Basic Interface to Alias transformation matrix.
Synopsis
#include <AlTM.h>
class AlTM
inline AlTM() ;
inline ~AlTM() ;
AlTM( const AlTM& );
AlTM( const double[4][4] );
AlTM( const double d0,const double d1,const double d2,const double d3 );
inline double* operator []( int row )
inline const double* operator []( int row ) const
statusCode getTM( double[4][4] ) const;
statusCode setTM( const double[4][4] );
AlTM& operator =( const AlTM& );
AlTM& operator =( const double d );
int operator ==( const AlTM& ) const;
int operator !=( const AlTM& ) const;
AlTM operator +( const AlTM& ) const;
AlTM operator -( const AlTM& ) const;
AlTM operator *( const AlTM& ) const;
AlTM operator *( const double ) const;
friend AlTM operator *( const double d, const AlTM& tm );
AlTM& operator +=( const AlTM& );
AlTM& operator -=( const AlTM& );
AlTM& operator *=( const AlTM& );
AlTM& operator *=( const double );
statusCode transPoint( double d[4] ) const;
statusCode transPoint( const double pt[4], double transPt[4] ) const;
statusCode transPoint( double& x, double &y, double &z, double &w ) const;
statusCode transPoint( double& x, double &y, double &z ) const; // assumes w = 1.0
statusCode transVector( double& x, double& y, double& z ) const;
statusCode transNormal( double& x, double& y, double& z ) const;
statusCode decompose ( double [3], double [3], double [3], double [3] ) const;
AlTM inverse( void ) const;
AlTM transpose( void ) const;
static AlTM identity( void );
static AlTM zero( void );
static AlTM diagonal( const double d0, const double d1, const double d2, const double d3 );
// standard transformations
static AlTM scale( const double );
static AlTM scale_nonp( const double, const double, const double );
static AlTM translate( const double, const double, const double );
static AlTM rotateX( const double );
static AlTM rotateY( const double );
static AlTM rotateZ( const double );
static AlTM rotate( double x, double y, double z, double angle );
Description
This class encapsulates the functionality for creating, manipulating and deleting Alias 4x4 transformation matrices.
Transformation matrices are used to do linear transformations of a vector. Composite transformations are done by multiplying
the individual transformations together.
The matrix is ordered as AlTM[y][x]:
0,0 0,1 0,2 0,3
1,0 1,1 1,2 1,3
2,0 2,1 2,2 2,3
3,0 3,1 3,2 3,3
The transformation matrix usually takes the form:
TM = | r00 r01 r02 0 |
| r10 r11 r12 0 |
| r20 r21 r22 0 |
| tx0 ty0 tz0 1 |
where tx0, ty0, tz0 are the aggregate translations and r(xy) is the aggregate product of rotations, scales and shears.
A point is transformed by considering the point to be a row vector of 4 elements and then post multiplying by the transformation
matrix.
[x’ y’ z’ w’]
= [x y z w] | 00 01 02 03 |
| 10 11 12 13 |
| 20 21 22 23 |
| 30 31 32 33 |
If the w component is not specified, it is assumed to have a value of 1.
The static functions at the end of the class are used to create typical transformation matrices.
Note: the [] operator has been defined for the AlTM class. This means that the individual matrix elements can be addressed
as if the AlTM were a standard 4x4 array of doubles. This eliminates the need to create a temporary 4x4 array to retrieve
the values.
for example, AlTM matrix; matrix[3][2] = 10.0;
AlTM::AlTM( const double d0, const double d1, const double d2, const double d3 )
Description
Constructor for the AlTM. This initializes the matrix by setting the diagonal to (d0,d1,d2,d3)
Warning: for efficiency reasons, the matrix is NOT initialized by the default constructor.
Use the AlTM(1,1,1,1) constructor to initialize the identity matrix (that is, this sets the diagonal to 1’s, and the rest
of the matrix to 0)
Similarly, to initialize the matrix with all 0, use the constructor AlTM(0) or AlTM(0,0,0,0)
AlTM::AlTM( const AlTM& tm )
Description
Constructor for the AlTM.
This initializes the matrix by making a copy of the given AlTM matrix ’tm’.
AlTM::AlTM( const double tm[4][4] )
Description
Constructor for the AlTM.
This initializes the matrix by making a copy of the given 4x4 array ’tm’.
statusCode AlTM::getTM( double tm[4][4] ) const
Description
Copies the contents of the AlTM into a 4x4 array ’tm’.
Arguments
< tm - where to copy the transformation matrix to
Return Codes
sSuccess - the matrix was successfully copied
sInvalidArgument - the pointer is NULL
statusCode AlTM::setTM( const double tm[4][4] )
Description
Copies the given matrix into the AlTM.
Return Codes
sSuccess - the matrix was successfully copied
sInvalidArgument - the pointer is NULL
AlTM& AlTM::operator =( const AlTM& tm )
Description
A = B
This copies matrix B to matrix A.
AlTM& AlTM::operator =( const double d )
Description
A = d
Every entry in matrix A is set to the scalar value in ’d’.
int AlTM::operator ==( const AlTM& tm ) const
Description
A == B
Returns 1 if matrix A and B are equal, 0 otherwise.
int AlTM::operator !=( const AlTM& tm ) const
Description
A != B
Returns 1 if matrix A and B are not equal, 0 otherwise.
AlTM AlTM::operator +( const AlTM& tm ) const
Description
result = A + B
Returns the result of matrix B added to matrix A.
AlTM AlTM::operator -( const AlTM& tm ) const
Description
result = A - B
Returns the result of matrix B subtracted from matrix A.
AlTM AlTM::operator *( const AlTM& tm ) const
Description
result = A * B
Returns the result of matrix A post multiplied by matrix B.
AlTM operator *( const double d, const AlTM& tm )const
Description
result = d * A
Returns the result of matrix A multiplied by the scalar value in ’d’.
AlTM AlTM::operator *( const double d ) const
Description
result = A * d
Returns the result of matrix A multiplied by the scalar value in ’d’.
AlTM& AlTM::operator +=( const AlTM& tm )
Description
A = A + B
Adds matrix B to matrix A.
AlTM& AlTM::operator -=( const AlTM& tm )
Description
A = A - B
Subtracts matrix B from matrix A.
AlTM& AlTM::operator *=( const AlTM& tm )
Description
A = A * B
Post multiplies matrix A by matrix B.
AlTM& AlTM::operator *=( const double d )
Description
A = A * d
Multiplies every entry in matrix A by the scalar value in ’d’.
statusCode AlTM::decompose( double translate[3], double scale[3], double rotate[3], double shear[3] ) const
Description
Decomposes the transform into translate, rotate, scale, and shear components.
The shears are saved as XY, XZ, and YZ in the return vector "shear". They may be ignored, but only at your peril! Alias transformation nodes can contain a shear despite the fact that there is no explicit shear operation (a two level DAG with
rotate and scale will do it).
Arguments
> translate - vector to store translation in
> scale - vector to store scale in
> rotate - vector to store rotation in
> shear - vector to store shear in
Return Codes
sSuccess - the matrix decomposition worked
sFailure - the matrix decomposition failed
AlTM AlTM::inverse( void ) const
Description
result = A.inverse()
Returns the inverse of matrix A.
If A is not invertible, then a zero matrix is returned (the result can be compared to the zero matrix ).
AlTM AlTM::transpose( void ) const
Description
result = A.transpose()
Returns the transpose of matrix A.
AlTM AlTM::identity( void )
Description
AlTM::identity() returns the identity matrix.
AlTM AlTM::zero( void )
Description
AlTM::zero() returns a zero matrix.
AlTM AlTM::diagonal( const double d0, const double d1, const double d2, const double d3 )
Description
Returns a zero matrix with diagonal values of ’d’.
The following matrix is returned:
[ d0 0 0 0 ]
[ 0 d1 0 0 ]
[ 0 0 d2 0 ]
[ 0 0 0 d3 ]
Arguments
< d - value to set the diagonal to
AlTM AlTM::scale( const double d )
Description
Returns a transformation matrix to scale a point [ x y z ] by a constant with value of ’d’.
The following matrix is returned:
[ d 0 0 0 ]
[ 0 d 0 0 ]
[ 0 0 d 0 ]
[ 0 0 0 1 ]
Arguments
< d - value to scale a point by
AlTM AlTM::scale_nonp( const double sx, const double sy, const double sz )
Description
Returns a transformation matrix to nonproportionally scale a point [ x y z ] by sx in the x axis, sy in the y axis and sz
in the z axis.
The following matrix is returned:
[ sx 0 0 0 ]
[ 0 sy 0 0 ]
[ 0 0 sz 0 ]
[ 0 0 0 1 ]
Arguments
< sx - scale of the x axis
< sy - scale of the y axis
< sz - scale of the z axis
AlTM AlTM::translate( const double tx, const double ty, const double tz )
Description
Returns a transformation matrix to translate a point (x,y,z) by (tx, ty, tz).
Arguments
< tx, ty, tz - the vector (tx, ty, tz) to translate the point by
AlTM AlTM::rotateX( const double rx )
Description
Returns a transformation matrix to rotate about the X axis.
Arguments
< rx - angle in radians to rotate about the x axis
AlTM AlTM::rotateY( const double ry )
Description
Returns a transformation matrix to rotate about the Y axis.
Arguments
< ry - angle in radians to rotate about the y axis
AlTM AlTM::rotateZ( const double rz )
Description
Returns a transformation matrix to rotate about the Z axis.
Arguments
< rz - angle in radians to rotate about the z axis
AlTM AlTM::rotate( double x, double y, double z, double angle )
Description
Returns a transformation matrix to rotate counterclockwise about the axis (x,y,z).
Arguments
< angle - angle in radians to rotate counterclockwise by
< x,y,z - the axis to rotate about
statusCode AlTM::transNormal( double& x, double& y, double& z ) const
Description
Transforms a normal. sFailure is returned if the upper 3x3 matrix is not invertible n’ = n * trans(inv(M)).
NOTE: this function inverts the given matrix to do the operation. This operation may not be numerically accurate. It is suggested
that, for DAG traversals, you use AlDagNode::inverseGlobalTransform to get the inverse of the transformation. Then take the
transformation, then use transVector. for example,
double normX, normY, normZ;
AlTM invTM;
dagNode->inverseGlobalTransformMatrix( invTM );
invTM.transpose().transVector( normX, normY, normZ );
statusCode AlTM::transVector( double& x, double& y, double& z ) const
Description
Transforms a vector (assumes w=0).
statusCode AlTM::transPoint( const double pt[4], double transPt[4] ) const
Description
Using the matrix, transforms the point in pt[] to transPt[].
It does the operation
transPt[ x y z w ] = pt[ x y z w ] * matrix
Arguments
< pt - the point to transform
> transPt - where to place the result
Return Codes
sSuccess - the matrix was successfully copied
sInvalidArgument - one of the pointers was NULL
statusCode AlTM::transPoint( double pt[4] ) const
Description
Using the matrix, transforms the point in pt[] to pt[].
It does the operation
pt[ x y z w ] = pt[ x y z w ] * matrix
Arguments
<> pt - the point to transform
Return Codes
sSuccess - the vector was successfully transformed
sInvalidArgument - the pointer was NULL
statusCode AlTM::transPoint( double &x, double &y, double &z, double &w ) const
Description
Using the transformation matrix, transforms the point (x,y,z,w).
It does the operation
[ x y z w ] = [ x y z w ] * matrix
Arguments
<> &x, &y, &z, &w - the row vector to transform
Return Codes
sSuccess - the vector was successfully transformed
statusCode AlTM::transPoint( double &x, double &y, double &z ) const
Description
Using the matrix, transforms the point (x, y, z, 1).
It does the operation
[ x y z 1 ] = [ x y z 1 ] * matrix
Arguments
<> &x, &y, &z - the row vector to transform
Return Codes
sSuccess - the vector was successfully transformed
