1 ///////////////////////////////////////////////////////////////////////////
3 // Copyright (c) 2002, Industrial Light & Magic, a division of Lucas
6 // All rights reserved.
8 // Redistribution and use in source and binary forms, with or without
9 // modification, are permitted provided that the following conditions are
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
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.
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.
33 ///////////////////////////////////////////////////////////////////////////
37 #ifndef INCLUDED_IMATHFRAME_H
38 #define INCLUDED_IMATHFRAME_H
42 template<class T> class Vec3;
43 template<class T> class Matrix44;
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.
51 // A typical usage would be :
53 // m[0] = Imath::firstFrame( p[0], p[1], p[2] );
54 // for( int i = 1; i < n - 1; i++ )
56 // m[i] = Imath::nextFrame( m[i-1], p[i-1], p[i], t[i-1], t[i] );
58 // m[n-1] = Imath::lastFrame( m[n-2], p[n-2], p[n-1] );
60 // See Graphics Gems I for the underlying algorithm.
63 template<class T> Matrix44<T> firstFrame( const Vec3<T>&, // First point
64 const Vec3<T>&, // Second point
65 const Vec3<T>& ); // Third point
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
73 template<class T> Matrix44<T> lastFrame( const Matrix44<T>&, // Previous matrix
74 const Vec3<T>&, // Previous point
75 const Vec3<T>& ); // Last point
78 // firstFrame - Compute the first reference frame along a curve.
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
85 // Throw 'NullVecExc' if 'pi' and 'pj' are equals.
88 template<class T> Matrix44<T> firstFrame
90 const Vec3<T>& pi, // First point
91 const Vec3<T>& pj, // Second point
92 const Vec3<T>& pk ) // Third point
94 Vec3<T> t = pj - pi; t.normalizeExc();
96 Vec3<T> n = t.cross( pk - pi ); n.normalize();
97 if( n.length() == 0.0f )
99 int i = fabs( t[0] ) < fabs( t[1] ) ? 0 : 1;
100 if( fabs( t[2] ) < fabs( t[i] )) i = 2;
102 Vec3<T> v( 0.0, 0.0, 0.0 ); v[i] = 1.0;
103 n = t.cross( v ); n.normalize();
106 Vec3<T> b = t.cross( n );
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;
119 // nextFrame - Compute the next reference frame along a curve.
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.
126 template<class T> Matrix44<T> nextFrame
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
134 Vec3<T> a(0.0, 0.0, 0.0); // Rotation axis.
135 T r = 0.0; // Rotation angle.
137 if( ti.length() != 0.0 && tj.length() != 0.0 )
139 ti.normalize(); tj.normalize();
140 T dot = ti.dot( tj );
143 // This is *really* necessary :
146 if( dot > 1.0 ) dot = 1.0;
147 else if( dot < -1.0 ) dot = -1.0;
153 if( a.length() != 0.0 && r != 0.0 )
155 Matrix44<T> R; R.setAxisAngle( a, r );
156 Matrix44<T> Tj; Tj.translate( pj );
157 Matrix44<T> Ti; Ti.translate( -pi );
159 return Mi * Ti * R * Tj;
163 Matrix44<T> Tr; Tr.translate( pj - pi );
170 // lastFrame - Compute the last reference frame along a curve.
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.
177 template<class T> Matrix44<T> lastFrame
179 const Matrix44<T>& Mi, // Previous matrix
180 const Vec3<T>& pi, // Previous point
181 const Vec3<T>& pj ) // Last point
183 Matrix44<T> Tr; Tr.translate( pj - pi );