/src/FreeImage/Source/OpenEXR/Imath/ImathFrame.h

  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
 40namespace Imath {
 41
 42template<class T> class Vec3;
 43template<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
 63template<class T> Matrix44<T> firstFrame( const Vec3<T>&,    // First point
 64                                          const Vec3<T>&,    // Second point 
 65                                          const Vec3<T>& );  // Third point
 66
 67template<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
 73template<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
 88template<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
126template<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
177template<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