1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
4 // Digital Ltd. LLC
5 //
6 // All rights reserved.
7 //
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
10 // met:
11 // * Redistributions of source code must retain the above copyright
12 // notice, this list of conditions and the following disclaimer.
13 // * Redistributions in binary form must reproduce the above
14 // copyright notice, this list of conditions and the following disclaimer
15 // in the documentation and/or other materials provided with the
16 // distribution.
17 // * Neither the name of Industrial Light & Magic nor the names of
18 // its contributors may be used to endorse or promote products derived
19 // from this software without specific prior written permission.
20 //
21 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 //
33 ///////////////////////////////////////////////////////////////////////////
34
35
36
37 #ifndef INCLUDED_IMATHFRAME_H
38 #define INCLUDED_IMATHFRAME_H
39
40 namespace Imath {
41
42 template<class T> class Vec3;
43 template<class T> class Matrix44;
44
45 //
46 // These methods compute a set of reference frames, defined by their
47 // transformation matrix, along a curve. It is designed so that the
48 // array of points and the array of matrices used to fetch these routines
49 // don't need to be ordered as the curve.
50 //
51 // A typical usage would be :
52 //
53 // m[0] = Imath::firstFrame( p[0], p[1], p[2] );
54 // for( int i = 1; i < n - 1; i++ )
55 // {
56 // m[i] = Imath::nextFrame( m[i-1], p[i-1], p[i], t[i-1], t[i] );
57 // }
58 // m[n-1] = Imath::lastFrame( m[n-2], p[n-2], p[n-1] );
59 //
60 // See Graphics Gems I for the underlying algorithm.
61 //
62
63 template<class T> Matrix44<T> firstFrame( const Vec3<T>&, // First point
64 const Vec3<T>&, // Second point
65 const Vec3<T>& ); // Third point
66
67 template<class T> Matrix44<T> nextFrame( const Matrix44<T>&, // Previous matrix
68 const Vec3<T>&, // Previous point
69 const Vec3<T>&, // Current point
70 Vec3<T>&, // Previous tangent
71 Vec3<T>& ); // Current tangent
72
73 template<class T> Matrix44<T> lastFrame( const Matrix44<T>&, // Previous matrix
74 const Vec3<T>&, // Previous point
75 const Vec3<T>& ); // Last point
76
77 //
78 // firstFrame - Compute the first reference frame along a curve.
79 //
80 // This function returns the transformation matrix to the reference frame
81 // defined by the three points 'pi', 'pj' and 'pk'. Note that if the two
82 // vectors <pi,pj> and <pi,pk> are colinears, an arbitrary twist value will
83 // be choosen.
84 //
85 // Throw 'NullVecExc' if 'pi' and 'pj' are equals.
86 //
87
firstFrame(const Vec3<T> & pi,const Vec3<T> & pj,const Vec3<T> & pk)88 template<class T> Matrix44<T> firstFrame
89 (
90 const Vec3<T>& pi, // First point
91 const Vec3<T>& pj, // Second point
92 const Vec3<T>& pk ) // Third point
93 {
94 Vec3<T> t = pj - pi; t.normalizeExc();
95
96 Vec3<T> n = t.cross( pk - pi ); n.normalize();
97 if( n.length() == 0.0f )
98 {
99 int i = fabs( t[0] ) < fabs( t[1] ) ? 0 : 1;
100 if( fabs( t[2] ) < fabs( t[i] )) i = 2;
101
102 Vec3<T> v( 0.0, 0.0, 0.0 ); v[i] = 1.0;
103 n = t.cross( v ); n.normalize();
104 }
105
106 Vec3<T> b = t.cross( n );
107
108 Matrix44<T> M;
109
110 M[0][0] = t[0]; M[0][1] = t[1]; M[0][2] = t[2]; M[0][3] = 0.0,
111 M[1][0] = n[0]; M[1][1] = n[1]; M[1][2] = n[2]; M[1][3] = 0.0,
112 M[2][0] = b[0]; M[2][1] = b[1]; M[2][2] = b[2]; M[2][3] = 0.0,
113 M[3][0] = pi[0]; M[3][1] = pi[1]; M[3][2] = pi[2]; M[3][3] = 1.0;
114
115 return M;
116 }
117
118 //
119 // nextFrame - Compute the next reference frame along a curve.
120 //
121 // This function returns the transformation matrix to the next reference
122 // frame defined by the previously computed transformation matrix and the
123 // new point and tangent vector along the curve.
124 //
125
nextFrame(const Matrix44<T> & Mi,const Vec3<T> & pi,const Vec3<T> & pj,Vec3<T> & ti,Vec3<T> & tj)126 template<class T> Matrix44<T> nextFrame
127 (
128 const Matrix44<T>& Mi, // Previous matrix
129 const Vec3<T>& pi, // Previous point
130 const Vec3<T>& pj, // Current point
131 Vec3<T>& ti, // Previous tangent vector
132 Vec3<T>& tj ) // Current tangent vector
133 {
134 Vec3<T> a(0.0, 0.0, 0.0); // Rotation axis.
135 T r = 0.0; // Rotation angle.
136
137 if( ti.length() != 0.0 && tj.length() != 0.0 )
138 {
139 ti.normalize(); tj.normalize();
140 T dot = ti.dot( tj );
141
142 //
143 // This is *really* necessary :
144 //
145
146 if( dot > 1.0 ) dot = 1.0;
147 else if( dot < -1.0 ) dot = -1.0;
148
149 r = acosf( dot );
150 a = ti.cross( tj );
151 }
152
153 if( a.length() != 0.0 && r != 0.0 )
154 {
155 Matrix44<T> R; R.setAxisAngle( a, r );
156 Matrix44<T> Tj; Tj.translate( pj );
157 Matrix44<T> Ti; Ti.translate( -pi );
158
159 return Mi * Ti * R * Tj;
160 }
161 else
162 {
163 Matrix44<T> Tr; Tr.translate( pj - pi );
164
165 return Mi * Tr;
166 }
167 }
168
169 //
170 // lastFrame - Compute the last reference frame along a curve.
171 //
172 // This function returns the transformation matrix to the last reference
173 // frame defined by the previously computed transformation matrix and the
174 // last point along the curve.
175 //
176
lastFrame(const Matrix44<T> & Mi,const Vec3<T> & pi,const Vec3<T> & pj)177 template<class T> Matrix44<T> lastFrame
178 (
179 const Matrix44<T>& Mi, // Previous matrix
180 const Vec3<T>& pi, // Previous point
181 const Vec3<T>& pj ) // Last point
182 {
183 Matrix44<T> Tr; Tr.translate( pj - pi );
184
185 return Mi * Tr;
186 }
187
188 } // namespace Imath
189
190 #endif
191