| 1 |
h1. Dealing with two Dimensions: *D2* |
| 2 |
|
| 3 |
After writing a few classes for two dimensional objects, we realized |
| 4 |
that there is a lot of boilerplate associated with what is essentially |
| 5 |
lifting one dimensional concepts into two. Instead of frequently |
| 6 |
rewriting this code, we instead created the *D2* template class. |
| 7 |
|
| 8 |
For example, a point in space might be represented by *D2<double>*. |
| 9 |
This may, in fact, become the actual representation for Point. |
| 10 |
We have not yet replaced Point with this, as not all of Points |
| 11 |
operations have been ported (or are applicable), and we are not |
| 12 |
yet sure if there is 0 performance loss. |
| 13 |
|
| 14 |
(TODO remove previous stuff if D2<double> becomes point repr) |
| 15 |
|
| 16 |
h2. Component Access |
| 17 |
|
| 18 |
One might expect such an object to have @.x@ and @.y@ fields, however, |
| 19 |
it instead consists of 2 element array. With LibNR, it was found that |
| 20 |
the availability of @.x@ and @.y@ encouraged people to attempt to |
| 21 |
inline operations rather than using the operators, perhaps in (vain) |
| 22 |
pursuit of a performance enhancement. By using an array, we encourage |
| 23 |
people to think about points as symmetric objects and discourage |
| 24 |
direct use of the components. However, we still provide direct access |
| 25 |
for the rare occasion that it is needed. Even in these cases, the array |
| 26 |
method reduces bugs by encouraging iteration over the array rather than |
| 27 |
explicit element reference. |
| 28 |
|
| 29 |
The components of a *D2* are accessed through the indexing operator, []. |
| 30 |
The input value to the index operator is the @enum@ *Dim2*, which |
| 31 |
defines *X* = 0 and *Y* = 1. This is to encourage using the |
| 32 |
@for(int d=0; i<2; i++)@ idiom when normal operations do not suffice. |
| 33 |
|
| 34 |
h2. Arithmetic Operators |
| 35 |
|
| 36 |
@D2<T>@ implements the *AddableConcept*, *OffsetableConcept*, and |
| 37 |
*ScalableConcept* (if @T@ implements them as well) yielding the |
| 38 |
following operators: |
| 39 |
|
| 40 |
<pre><code> |
| 41 |
AddableConcept: x + y, x - y, x += y, x -= y |
| 42 |
OffsetableConcept: x + p, x - p, x += p, x -= p |
| 43 |
ScalableConcept: x * p, x / p, x *= p, x /= p, -x |
| 44 |
x * d, x / d, x *= d, x /= d |
| 45 |
</code></pre> |
| 46 |
|
| 47 |
(where @x@ and @y@ are *D2*, d is *Coord*, and @p@ is a *Point* and all |
| 48 |
return @D2<T>@) |
| 49 |
|
| 50 |
These operators all just apply the operation on @T@ to the components. |
| 51 |
So, @a + b@ just returns @D2<T>(a[X] + b[X], a[Y] + b[Y])@, though the |
| 52 |
actual code uses a loop (which is unrolled) in order to avoid |
| 53 |
bugs. |
| 54 |
|
| 55 |
h2. Geometric Operations |
| 56 |
|
| 57 |
<pre><code> |
| 58 |
T dot(D2<T> const &, D2<T> const &); |
| 59 |
T cross(D2<T> const &, D2<T> const &); |
| 60 |
</code></pre> |
| 61 |
|
| 62 |
The *dot*:http://en.wikipedia.org/wiki/Dot@product and |
| 63 |
*cross*:http://en.wikipedia.org/wiki/Cross@product products are defined |
| 64 |
on D2<T> when T implements *AddableConcept* and *MultiplicableConcept. |
| 65 |
The cross function returns the length of the resultant 3d vector |
| 66 |
perpendicular to the 2d plane. |
| 67 |
|
| 68 |
@ D2<T> operator*(D2<T> const &, Matrix const &)@ |
| 69 |
|
| 70 |
This operation applies an affine transformation to the 2d object. |
| 71 |
|
| 72 |
h2. Fragment Lifting |
| 73 |
|
| 74 |
*D2<T>* also implements FragmentConcept if T implements it as well, |
| 75 |
allowing *D2* to lift one dimensional functions into two-dimensional |
| 76 |
parametric curves. As a fragment, a *D2* will represent a function |
| 77 |
from a double to a Point. |
| 78 |
|
| 79 |
h3. Fragment Operations |
| 80 |
|
| 81 |
In addition to the normal set of Fragment methods, D2 has the following |
| 82 |
functions: |
| 83 |
|
| 84 |
h4. @ D2<T> compose(D2<T> const &a, T const &b); @ |
| 85 |
|
| 86 |
The *compose* function is defined when @T@ is a function representation which |
| 87 |
supports composition. The only forms in 2geom are *SBasis* and *SBasis2d*. |
| 88 |
The *D2* *compose* function composes @b@ on both components of @a@. This |
| 89 |
makes sense, as a D2<SBasis> is double -> D2<double> and the function for |
| 90 |
composition is double -> double. One way to think of composition is that |
| 91 |
the output is equivalent to applying @b@ to the input, and then applying a |
| 92 |
to @b@'s output. |
| 93 |
|
| 94 |
h4. @ D2<T> compose_each(D2<T> const &a, D2<T> &b); @ |
| 95 |
|
| 96 |
The *compose_each* function is similar to the *compose* function, except that |
| 97 |
@b@ is also a *D2*, so instead of composing the same function on each component, |
| 98 |
the two functions in @b@ are used. |
| 99 |
|
| 100 |
|
| 101 |
h4. @ Point D2<T>::operator()(double x, double y) const @ |
| 102 |
|
| 103 |
*D2* wraps this operator for when @T@ is a function taking a 2 component input. |
| 104 |
The only case of this currently within 2geom is SBasis2d. |
| 105 |
|
| 106 |
(TODO: derivative/integral) |