AlTM

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