Debian Codegraph @

src/python/PyImath/varraySemantics.txt

raw
1 //
2 // SPDX-License-Identifier: BSD-3-Clause
3 // Copyright Contributors to the OpenEXR Project.
4 //
5
6 -----------
7 Terminology
8 -----------
9
10 Items - Similar to 'list items'. Can think of as the 'vertical'
11 dimension similar to the other FixedArray dimension. Each item
12 contains an array of varying length.
13
14 Elements - The 'variable-length' array members of each item. In this
15 case, each 'element' is an int. For a FloatVArray, the
16 elements would be floats.
17
18
19 ------------
20 Construction
21 ------------
22
23 v = IntVArray()
24 : Do not support; FixedArrays generally don't have empty construction.
25
26 v = IntVArray(10)
27 : Creates 10 items, each item has zero elements (i.e. empty).
28
29 v = IntVArray(int initialValue , 10, 5)
30 : Creates 10 items, each item has 5 elements that are initialized
31 to the initialValue.
32
33 v = IntVArray(IntArray initialValue, 10)
34 : Creates 10 items, each initialized with a copy of the elements of
35 the provided initialValue IntArray.
36
37 v = IntVArray([1, 2, 3], 10)
38 : Creates 10 items, each initialized with the elements of the provided
39 list. This would be similar to the previous constructor, but with
40 a different initialValue type. We probably don't want to support
41 this right away, but possibly at some point in the future.
42
43 v = IntVArray(int intialValue, IntArray() initialLengths)
44 : Creates initialLengths.len() items each with a number of elements
45 matching the values provided by the initialLengths array. The
46 initial value for all elements is 'initalValue'.
47
48 v = IntVArray(IntVArray clone)
49 : Created as a copy of 'clone'.
50
51
52 Usage (Accessing)
53 -----------------
54
55 int = v.len() (number of items)
56
57 IntArray = v[4] (reference of v's data)
58 IntArray = v[-1] (same as previous)
59 IntVArray = v[3:9] (reference of v's data; stride provides indexing)
60 IntVArray = v[:] (same as previous, stride probably not needed)
61
62 IntVArray = v[IntArray mask]
63 : Returns a reference of v's data; uses mask variable internally
64 IntVArray = v[BoolArray mask]
65 : Not currently supported, but would provide the same as previous.
66 This 'BoolArray' mask should be implemented sometime soon (for
67 this and all other FixedArrays).
68
69 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
70 Question: Support v[5][2] semantics. This might work out-of-the-box since
71 v[5] would return an IntArray, which supports [] also. In this
72 case it would be fine and a single 'int' would be returned.
73 But for v[5][1:3], we would return another IntArray
74 instead of a regular int, so the levels of indirection
75 for original internal IntVArray data might get too complicated. Do
76 we support this semantic or not. The problem is that if we don't
77 want to support it, we'll have to specifically disable it somehow
78 since we'll get it by default (v[5] returns IntArray, which would
79 automatically support [1:3]).
80
81 Question: To avoid the previous issue, we'll probably want a special element
82 accessor method (probably called 'element'). That'll have to have
83 the ability to take in a 'slice' as an argument. Would that all
84 work?
85
86 In the continuing text, we'll assume we support an 'element' accessor
87 method and not the [5][6] double-box notation.
88 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
89
90 int = v[4].element(1) (returns a single integer)
91 int = v[4].element(-1) (same as previous)
92 IntArray = v[4].element(2:7) (return IntArray referencing original data)
93 IntArray = v[4].element(:) (same as previous; no 'stride' needed)
94 int = v[4].len() (would not work; int doesn't support 'len')
95 int = v[4].element(:).len() (the number of elements for item 4 ???)
96
97 IntArray = v[3:9].element(1) (All of the element-1 members for items 3 - 9)
98 IntArray = v.element(1) (All of the element-1 members for each item)
99 IntArray = v[3:9].element(-1) (same as previous, but returns last elements)
100 IntVArray = v[3:9].element(2:7) (subset of the original ?????)
101 IntVArray = v[3:9].element(:) (subset of the original v; only items 3 - 9)
102 int 6 = v[3:9].len()
103
104 IntArray = v[:].element(1) (List of all element-1s from all items ???)
105 IntArray = v[:].element(-1) (List of all last elements ???)
106 IntVArray = v[:].element(2:7) (subset of the original ????)
107 IntVArray = v[:].element(:) (basically a reference of the original)
108 int = v[:].len() (number of items in v)
109
110 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
111 Question: We want to support easy indexing right into a 'X' V3fArray
112 or something similar. Lets say we want to add a V3f to all
113 coordinates of the entire system. We'd want to be able to
114 write expressions like:
115
116 x[ v[:].element(:) ] += imath.V3f(1,2,3)
117 x[ v[:].element(0) ] += imath.V3f(1,2,3) (the 'root' point)
118 x[ v[3].element(:) ] += ...
119 x[ v[1:10].element(:) ] += ...
120 x[ v[1:10].element(1:4) ] += ...
121
122 But in many cases, the expression returns another IntVArray.
123 Should/can we provide indexing into V3fArray from an IntVArray?
124 Do we currently support indexing into a V3fArray from IntArray?
125 What other ways can we make this convenient.
126 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
127
128 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
129 Question: What about cases where not all items support the same number
130 of elements. What happens in these cases:
131
132 IntArray = v[:].element(7)
133
134 for cases where some or all of the items don't have an element-7.
135 Would the IntArray be a subset of v's items (i.e. if only 3 items
136 could return an element-7, the IntArray would be 3 long). Or
137 would the IntArray contain invalid/None/undefined integers within
138 it.
139 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
140
141 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
142 Question: What other accessor/modification methods do we want to support.
143 append, remove, pop, push, etc?
144 <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
145