Main Page   Modules   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Spacial Transformers: xform( ... ), operator( ... ).

Transform points and vectors by Matrices and Quaternions. More...

Vector Transform (Quaternion)

template<typename DATA_TYPE> VecBase< DATA_TYPE, 3 > & xform (VecBase< DATA_TYPE, 3 > &result, const Quat< DATA_TYPE > &rot, const VecBase< DATA_TYPE, 3 > &vector)
 transform a vector by a rotation quaternion. More...

template<typename DATA_TYPE> VecBase< DATA_TYPE, 3 > operator * (const Quat< DATA_TYPE > &rot, const VecBase< DATA_TYPE, 3 > &vector)
 transform a vector by a rotation quaternion. More...

template<typename DATA_TYPE> VecBase< DATA_TYPE, 3 > operator *= (VecBase< DATA_TYPE, 3 > &vector, const Quat< DATA_TYPE > &rot)
 transform a vector by a rotation quaternion. More...


Vector Transform (Matrix)

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Vec< DATA_TYPE, COLS > & xform (Vec< DATA_TYPE, COLS > &result, const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Vec< DATA_TYPE, COLS > &vector)
 xform a vector by a matrix. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Vec< DATA_TYPE, COLS > operator * (const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Vec< DATA_TYPE, COLS > &vector)
 matrix * vector xform. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned VEC_SIZE> Vec< DATA_TYPE, VEC_SIZE > & xform (Vec< DATA_TYPE, VEC_SIZE > &result, const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Vec< DATA_TYPE, VEC_SIZE > &vector)
 partially transform a partially specified vector by a matrix, assumes last elt of vector is 0 (the 0 makes it only partially transformed). More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE> Vec< DATA_TYPE, COLS_MINUS_ONE > operator * (const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Vec< DATA_TYPE, COLS_MINUS_ONE > &vector)
 matrix * partial vector, assumes last elt of vector is 0 (partial transform). More...


Point Transform (Matrix)

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Point< DATA_TYPE, COLS > & xform (Point< DATA_TYPE, COLS > &result, const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Point< DATA_TYPE, COLS > &point)
 transform point by a matrix. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Point< DATA_TYPE, COLS > operator * (const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Point< DATA_TYPE, COLS > &point)
 matrix * point. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned PNT_SIZE> Point< DATA_TYPE, PNT_SIZE > & xform (Point< DATA_TYPE, PNT_SIZE > &result, const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Point< DATA_TYPE, PNT_SIZE > &point)
 transform a partially specified point by a matrix, assumes last elt of point is 1. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE> Point< DATA_TYPE, COLS_MINUS_ONE > operator * (const Matrix< DATA_TYPE, ROWS, COLS > &matrix, const Point< DATA_TYPE, COLS_MINUS_ONE > &point)
 matrix * partially specified point. More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Point< DATA_TYPE, COLS > operator * (const Point< DATA_TYPE, COLS > &point, const Matrix< DATA_TYPE, ROWS, COLS > &matrix)
 point * a matrix multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point [with w == 1 for points by definition] ). More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS> Point< DATA_TYPE, COLS > operator *= (Point< DATA_TYPE, COLS > &point, const Matrix< DATA_TYPE, ROWS, COLS > &matrix)
 point *= a matrix multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point [with w == 1 for points by definition] ). More...

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE> Point< DATA_TYPE, COLS_MINUS_ONE > operator *= (Point< DATA_TYPE, COLS_MINUS_ONE > &point, const Matrix< DATA_TYPE, ROWS, COLS > &matrix)
 partial point *= a matrix multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Point [with w == 1 for points by definition] ). More...

Detailed Description

Transform points and vectors by Matrices and Quaternions.

Note that xform is defined differently for Point and Vec. By Point is a full xform, by Vec is only a rotation.

Function Documentation

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Point<DATA_TYPE, COLS> operator * (  const Point< DATA_TYPE, COLS > &    point,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix
)  [inline]
 

point * a matrix multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point [with w == 1 for points by definition] ).

Parameters:
matrix  the transform matrix
point  the original point
Returns:
the point transformed by the matrix
Postcondition:
This results in a full matrix xform of the point.

Definition at line 345 of file Xforms.h. 

00346    {
00347       Point<DATA_TYPE, COLS> temporary;
00348       return xform( temporary, matrix, point );
00349    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE>
Point<DATA_TYPE, COLS_MINUS_ONE> operator * (  const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Point< DATA_TYPE, COLS_MINUS_ONE > &    point
)  [inline]
 

matrix * partially specified point.

multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Point [with w == 1 for points by definition] ).

Parameters:
matrix  the transform matrix
point  the original point
Returns:
the point transformed by the matrix
Postcondition:
the [k-1 x 1] vector you pass in is treated as a [point, 1.0]
This results in a full matrix xform of the point.

Definition at line 331 of file Xforms.h. 

00332    {
00333       Point<DATA_TYPE, COLS_MINUS_ONE> temporary;
00334       return xform( temporary, matrix, point );
00335    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Point<DATA_TYPE, COLS> operator * (  const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Point< DATA_TYPE, COLS > &    point
)  [inline]
 

matrix * point.

multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point...).

Parameters:
matrix  the transform matrix
point  the original point
Returns:
the point transformed by the matrix
Postcondition:
This results in a full matrix xform of the point.
returns a point same size as the matrix rows... (p[r][1] = m[r][k] * p[k][1])

Definition at line 272 of file Xforms.h. 

00273    {
00274       Point<DATA_TYPE, COLS> temporary;
00275       return xform( temporary, matrix, point );
00276    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE>
Vec<DATA_TYPE, COLS_MINUS_ONE> operator * (  const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Vec< DATA_TYPE, COLS_MINUS_ONE > &    vector
)  [inline]
 

matrix * partial vector, assumes last elt of vector is 0 (partial transform).

Parameters:
matrix  the transform matrix
vector  the original vector
Returns:
the vector transformed by the matrix multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Vector [with w == 0 for vectors by definition] ).
Postcondition:
the [k-1 x 1] vector you pass in is treated as a [vector, 0.0]
This ends up being a partial xform using only the rotation from the matrix (vector xformed result is untranslated).

Definition at line 226 of file Xforms.h. 

00227    {
00228       Vec<DATA_TYPE, COLS_MINUS_ONE> temporary;
00229       return xform( temporary, matrix, vector );
00230    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Vec<DATA_TYPE, COLS> operator * (  const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Vec< DATA_TYPE, COLS > &    vector
)  [inline]
 

matrix * vector xform.

multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Vector...).

Parameters:
matrix  the transform matrix
vector  the original vector
Returns:
the vector transformed by the matrix
Postcondition:
This results in a full matrix xform of the vector (assumes you know what you are doing - i.e. that you know that the last component of a vector by definition is 0.0, and changing this might make the xform different that what you may expect).
returns a vec same size as the matrix rows... (v[r][1] = m[r][k] * v[k][1])

Definition at line 166 of file Xforms.h. 

00167    {
00168       // do a standard [m x k] by [k x n] matrix multiplication (where n == 0).
00169       Vec<DATA_TYPE, COLS> temporary;
00170       return xform( temporary, matrix, vector );
00171    }

template<typename DATA_TYPE>
VecBase<DATA_TYPE, 3> operator * (  const Quat< DATA_TYPE > &    rot,
const VecBase< DATA_TYPE, 3 > &    vector
)  [inline]
 

transform a vector by a rotation quaternion.

Precondition:
give a vector, and a rotation quaternion (by definition, a rotation quaternion is normalized).
Parameters:
rot  The quaternion
vector  The original vector to transform
Returns:
the resulting vector transformed by the quaternion
Postcondition:
v' = q P(v) q* (where result is v', rot is q, and vector is v. q* is conj(q), and P(v) is pure quaternion made from v)

Definition at line 101 of file Xforms.h. 

00102    {
00103       VecBase<DATA_TYPE, 3> temporary;
00104       return xform( temporary, rot, vector );
00105    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned COLS_MINUS_ONE>
Point<DATA_TYPE, COLS_MINUS_ONE> operator *= (  Point< DATA_TYPE, COLS_MINUS_ONE > &    point,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix
)  [inline]
 

partial point *= a matrix multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Point [with w == 1 for points by definition] ).

Parameters:
matrix  the transform matrix
point  the original point
Returns:
the point transformed by the matrix
Postcondition:
the [k-1 x 1] vector you pass in is treated as a [point, 1.0]
This results in a full matrix xform of the point.

Definition at line 375 of file Xforms.h. 

00376    {
00377       Point<DATA_TYPE, COLS_MINUS_ONE> temporary = point;
00378       return xform( point, matrix, temporary);
00379    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Point<DATA_TYPE, COLS> operator *= (  Point< DATA_TYPE, COLS > &    point,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix
)  [inline]
 

point *= a matrix multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point [with w == 1 for points by definition] ).

Parameters:
matrix  the transform matrix
point  the original point
Returns:
the point transformed by the matrix
Postcondition:
This results in a full matrix xform of the point.

Definition at line 360 of file Xforms.h. 

00361    {
00362       Point<DATA_TYPE, COLS> temporary = point;
00363       return xform( point, matrix, temporary);
00364    }

template<typename DATA_TYPE>
VecBase<DATA_TYPE, 3> operator *= (  VecBase< DATA_TYPE, 3 > &    vector,
const Quat< DATA_TYPE > &    rot
)  [inline]
 

transform a vector by a rotation quaternion.

Precondition:
give a vector, and a rotation quaternion (by definition, a rotation quaternion is normalized).
Parameters:
rot  The quaternion
vector  The original vector to transform
Postcondition:
v' = q P(v) q* (where result is v', rot is q, and vector is v. q* is conj(q), and P(v) is pure quaternion made from v)

Definition at line 115 of file Xforms.h. 

00116    {
00117       VecBase<DATA_TYPE, 3> temporary = vector;
00118       return xform( vector, rot, temporary);
00119    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned PNT_SIZE>
Point<DATA_TYPE, PNT_SIZE>& xform (  Point< DATA_TYPE, PNT_SIZE > &    result,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Point< DATA_TYPE, PNT_SIZE > &    point
)  [inline]
 

transform a partially specified point by a matrix, assumes last elt of point is 1.

Transforms a point with a matrix, uses multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Point [with w == 1 for points by definition] ).

Parameters:
result  the point to write the result in
matrix  the transform matrix
point  the original point
Postcondition:
the [k-1 x 1] point you pass in is treated as [point, 1.0]
This results in a full matrix xform of the point.
Todo:
we need a PointOps.h operator *=(scalar) function

Definition at line 291 of file Xforms.h. 

00292    {
00293       gmtlASSERT( PNT_SIZE == COLS - 1 && "The precondition of this method is that the vector size must be one less than the number of columns in the matrix.  eg. if Mat<n,k>, then Vec<k-1>." );
00294 
00295       // copy the point to the correct size.
00296       Point<DATA_TYPE, PNT_SIZE+1> temp_point, temp_result;
00297       for (unsigned x = 0; x < PNT_SIZE; ++x)
00298          temp_point[x] = point[x];
00299       temp_point[PNT_SIZE] = (DATA_TYPE)1.0; // by definition of a point, set the last unspecified elt to 1.0
00300 
00301       // transform it.
00302       xform<DATA_TYPE, ROWS, COLS>( temp_result, matrix, temp_point );
00303 
00304       // convert result back to pnt<DATA_TYPE, PNT_SIZE>
00305       // some matrices will make the W param large even if this is a true vector,
00306       // we'll need to redistribute it to the other elts if W param is non-zero
00307       if (Math::isEqual( temp_result[PNT_SIZE], (DATA_TYPE)0, (DATA_TYPE)0.0001 ) == false)
00308       {
00309          DATA_TYPE w_coord_div = DATA_TYPE( 1.0 ) / temp_result[PNT_SIZE];
00310          for (unsigned x = 0; x < PNT_SIZE; ++x)
00311             result[x] = temp_result[x] * w_coord_div;
00312       }
00313       else
00314       {
00315          for (unsigned x = 0; x < PNT_SIZE; ++x)
00316             result[x] = temp_result[x];
00317       }
00318 
00319       return result;
00320    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS, unsigned VEC_SIZE>
Vec<DATA_TYPE, VEC_SIZE>& xform (  Vec< DATA_TYPE, VEC_SIZE > &    result,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Vec< DATA_TYPE, VEC_SIZE > &    vector
)  [inline]
 

partially transform a partially specified vector by a matrix, assumes last elt of vector is 0 (the 0 makes it only partially transformed).

Transforms a vector with a matrix, uses multiplication of [m x k] matrix by a [k-1 x 1] matrix (also known as a Vector [with w == 0 for vectors by definition] ).

Parameters:
result  the vector to write the result in
matrix  the transform matrix
vector  the original vector
Postcondition:
the [k-1 x 1] vector you pass in is treated as a [vector, 0.0]
This ends up being a partial xform using only the rotation from the matrix (vector xformed result is untranslated).

Definition at line 185 of file Xforms.h. 

00186    {
00187       gmtlASSERT( VEC_SIZE == COLS - 1 );
00188       // do a standard [m x k] by [k x n] matrix multiplication (where n == 0).
00189 
00190       // copy the point to the correct size.
00191       Vec<DATA_TYPE, COLS> temp_vector, temp_result;
00192       for (unsigned x = 0; x < VEC_SIZE; ++x)
00193          temp_vector[x] = vector[x];
00194       temp_vector[COLS-1] = (DATA_TYPE)0.0; // by definition of a vector, set the last unspecified elt to 0.0
00195 
00196       // transform it.
00197       xform<DATA_TYPE, ROWS, COLS>( temp_result, matrix, temp_vector );
00198 
00199       // convert result back to vec<DATA_TYPE, VEC_SIZE>
00200       // some matrices will make the W param large even if this is a true vector,
00201       // we'll need to redistribute it to the other elts if W param is non-zero
00202       if (Math::isEqual( temp_result[VEC_SIZE], (DATA_TYPE)0, (DATA_TYPE)0.0001 ) == false)
00203       {
00204          DATA_TYPE w_coord_div = DATA_TYPE( 1.0 ) / temp_result[VEC_SIZE];
00205          for (unsigned x = 0; x < VEC_SIZE; ++x)
00206             result[x] = temp_result[x] * w_coord_div;
00207       }
00208       else
00209       {
00210          for (unsigned x = 0; x < VEC_SIZE; ++x)
00211             result[x] = temp_result[x];
00212       }
00213 
00214       return result;
00215    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Point<DATA_TYPE, COLS>& xform (  Point< DATA_TYPE, COLS > &    result,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Point< DATA_TYPE, COLS > &    point
)  [inline]
 

transform point by a matrix.

multiplication of [m x k] matrix by a [k x 1] matrix (also known as a Point...).

Parameters:
result  the point to write the result in
matrix  the transform matrix
point  the original point
Postcondition:
This results in a full matrix xform of the point.
returns a point same size as the matrix rows... (p[r][1] = m[r][k] * p[k][1])

Definition at line 249 of file Xforms.h. 

00250    {
00251       // do a standard [m x k] by [k x n] matrix multiplication (n == 1).
00252 
00253       // reset point to zero...
00254       result = Point<DATA_TYPE, COLS>();
00255 
00256       for (unsigned iRow = 0; iRow < ROWS; ++iRow)
00257       for (unsigned iCol = 0; iCol < COLS; ++iCol)
00258          result[iRow] += matrix( iRow, iCol ) * point[iCol];
00259 
00260       return result;
00261    }

template<typename DATA_TYPE, unsigned ROWS, unsigned COLS>
Vec<DATA_TYPE, COLS>& xform (  Vec< DATA_TYPE, COLS > &    result,
const Matrix< DATA_TYPE, ROWS, COLS > &    matrix,
const Vec< DATA_TYPE, COLS > &    vector
)  [inline]
 

xform a vector by a matrix.

Transforms a vector with a matrix, uses multiplication of [m x k] matrix by a [k x 1] matrix (the later also known as a Vector...).

Parameters:
result  the vector to write the result in
matrix  the transform matrix
vector  the original vector
Postcondition:
This results in a rotational xform of the vector (assumes you know what you are doing - i.e. that you know that the last component of a vector by definition is 0.0, and changing this might make the xform different than what you may expect).
returns a point same size as the matrix rows... (v[r][1] = m[r][k] * v[k][1])

Definition at line 140 of file Xforms.h. 

00141    {
00142       // do a standard [m x k] by [k x n] matrix multiplication (where n == 0).
00143 
00144       // reset vec to zero...
00145       result = Vec<DATA_TYPE, COLS>();
00146 
00147       for (unsigned iRow = 0; iRow < ROWS; ++iRow)
00148       for (unsigned iCol = 0; iCol < COLS; ++iCol)
00149          result[iRow] += matrix( iRow, iCol ) * vector[iCol];
00150 
00151       return result;
00152    }

template<typename DATA_TYPE>
VecBase<DATA_TYPE, 3>& xform (  VecBase< DATA_TYPE, 3 > &    result,
const Quat< DATA_TYPE > &    rot,
const VecBase< DATA_TYPE, 3 > &    vector
)  [inline]
 

transform a vector by a rotation quaternion.

Precondition:
give a vector, and a rotation quaternion (by definition, a rotation quaternion is normalized).
Parameters:
result  The vector to write the result into
rot  The quaternion
vector  The original vector to transform
Postcondition:
v' = q P(v) q* (where result is v', rot is q, and vector is v. q* is conj(q), and P(v) is pure quaternion made from v)
See also:
game programming gems #1 p199 , shoemake siggraph notes
Note:
for the implementation, inv and conj should both work for the "q*" in "Rv = q P(v) q*" but conj is actually faster so we usually choose that.
also note, that if the input quat wasn't normalized (and thus isn't a rotation quat), then this might not give the correct result, since conj and invert is only equiv when normalized...

Definition at line 67 of file Xforms.h. 

00068    {
00069       // check preconditions...
00070       gmtlASSERT( Math::isEqual( length( rot ), (DATA_TYPE)1.0, (DATA_TYPE)0.0001 ) && "must pass a rotation quaternion to xform(result,quat,vec) - by definition, a rotation quaternion is normalized).  if you need non-rotation quaternion support, let us know." );
00071 
00072       // easiest to write and understand (slowest too)
00073       //return result_vec = makeVec( rot * makePure( vector ) * makeConj( rot ) );
00074 
00075       // completely hand expanded
00076       // (faster by 28% in gcc 2.96 debug mode.)
00077       // (faster by 35% in gcc 2.96 opt3 mode (78% for doubles))
00078       Quat<DATA_TYPE> rot_conj( -rot[Xelt], -rot[Yelt], -rot[Zelt], rot[Welt] );
00079       Quat<DATA_TYPE> pure( vector[0], vector[1], vector[2], (DATA_TYPE)0.0 );
00080       Quat<DATA_TYPE> temp(
00081          pure[Welt]*rot_conj[Xelt] + pure[Xelt]*rot_conj[Welt] + pure[Yelt]*rot_conj[Zelt] - pure[Zelt]*rot_conj[Yelt],
00082          pure[Welt]*rot_conj[Yelt] + pure[Yelt]*rot_conj[Welt] + pure[Zelt]*rot_conj[Xelt] - pure[Xelt]*rot_conj[Zelt],
00083          pure[Welt]*rot_conj[Zelt] + pure[Zelt]*rot_conj[Welt] + pure[Xelt]*rot_conj[Yelt] - pure[Yelt]*rot_conj[Xelt],
00084          pure[Welt]*rot_conj[Welt] - pure[Xelt]*rot_conj[Xelt] - pure[Yelt]*rot_conj[Yelt] - pure[Zelt]*rot_conj[Zelt] );
00085 
00086       result.set(
00087          rot[Welt]*temp[Xelt] + rot[Xelt]*temp[Welt] + rot[Yelt]*temp[Zelt] - rot[Zelt]*temp[Yelt],
00088          rot[Welt]*temp[Yelt] + rot[Yelt]*temp[Welt] + rot[Zelt]*temp[Xelt] - rot[Xelt]*temp[Zelt],
00089          rot[Welt]*temp[Zelt] + rot[Zelt]*temp[Welt] + rot[Xelt]*temp[Yelt] - rot[Yelt]*temp[Xelt] );
00090       return result;
00091    }

Generated on Mon Apr 7 15:29:24 2003 for GenericMathTemplateLibrary by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002