MPxTransformationMatrix Class Reference

#include <MPxTransformationMatrix.h>

Class Description

Base class of all user defined transformation matrices.

MPxTransformationMatrix is the parent class for all user defined transformation matrices. A transformation matrix is a class that holds the individual components (i.e. translate, rotate, scale, pivots, etc.) that are used to construct a 4x4 matrix. Given that different combinations of transform components may produce similar 4x4 matrices, it is not always possible to get a generic 4x4 matrix and decompose it into unique components. This class allows better control over which components are changed than a generic 4x4 MMatrix could offer.

The MPxTransformationMatrix class is designed for use as the mathematical brains behind the MPxTransform node. This separation is useful for class reuse (different types of MPxTransform nodes may still use the same MPxTransformationMatrix class) as well as simplifying the MPxTransform class.

The MPxTransformationMatrix class is registered using the MFnPlugin::registerTransform() method. Both the MPxTransform and the MPxTransformationMatrix classes are registered in the same method. This allows for a clear association between a MPxTransform and a MPxTransformationMatrix.

When registering the MPxTransformationMatrix, a MTypeId is required. For nodes using the default MPxTransformationMatrix, a statically defined MTypeId is provided by the MPxTransformationMatrix::baseTransformationMatrixId data member.

Since the MPxTransformationMatrix class gives extended functionality to a native Maya class, several methods are given that are needed by Maya for this class to properly function in different settings.

To create a transformation matrix, derive from this class and overload the creator() method and the assignment operator for the derived class. If any additional data items are added to this class, the copyValues() method should also be overloaded. This will ensure that the new values will get properly handed by Maya. The rest of the methods may be overloaded as needed.

Examples:

Public Member Functions
	MPxTransformationMatrix ()
	Class Constructor.
	MPxTransformationMatrix (const MTransformationMatrix &)
	Class constructor. More...
	MPxTransformationMatrix (const MPxTransformationMatrix &)
	A copy constructor. More...
	MPxTransformationMatrix (const MMatrix &)
	MMatrix copy constructor. More...
virtual	~MPxTransformationMatrix ()
	Class destructor.
virtual void	copyValues (MPxTransformationMatrix *)
	This method should be overridden for any transform that uses more then the default transform values. More...
virtual MTypeId	typeId () const
	Returns the MTypeId of this transformation matrix. More...
MPxTransformationMatrix &	operator= (const MPxTransformationMatrix &src)
	Assignment operator. More...
MPxTransformationMatrix &	operator= (const MMatrix &src)
	Assignment operator. More...
MPxTransformationMatrix &	operator= (const MTransformationMatrix &src)
	Assignment operator. More...
bool	operator== (const MPxTransformationMatrix &)
	Equality operator. More...
bool	operator!= (const MPxTransformationMatrix &)
	Inequality operator. More...
bool	operator== (const MTransformationMatrix &)
	Equality operator. More...
bool	operator!= (const MTransformationMatrix &)
	Inequality operator. More...
bool	operator== (const MMatrix &)
	Equality operator. More...
bool	operator!= (const MMatrix &)
	Equality operator. More...
virtual bool	isEquivalent (const MPxTransformationMatrix &, double tolerance=MMatrix_kTol) const
	Determine if the MPxTransformationMatrix is equivalent within a specified tolerance. More...
virtual bool	isEquivalent (const MTransformationMatrix &, double tolerance=MMatrix_kTol) const
	Determine if the MTransformationMatrix is equivalent within a specified tolerance. More...
virtual bool	isEquivalent (const MMatrix &, double tolerance=MMatrix_kTol) const
	Determine if the MMatrix is equivalent within a specified tolerance. More...
virtual MPxTransformationMatrix	reverse () const
	Returns the negated translate, rotate, and scale without taking the pivots into account. More...
virtual MPxTransformationMatrix &	transformBy (const MTransformationMatrix &)
	Transforms the transformation matrix by the passed MTransformationMatrix. More...
virtual MMatrix	asMatrix () const
	Returns the four by four matrix that describes this transformation. More...
virtual MMatrix	asMatrixInverse () const
	Returns the inverse of the four by four matrix that describes this transformation. More...
virtual MMatrix	asScaleMatrix () const
	Returns scale matrix. More...
virtual MMatrix	asScaleMatrixInverse () const
	Returns inverse of the scale matrix. More...
virtual MMatrix	asRotateMatrix () const
	Returns the rotate section of the transformation matrix. More...
virtual MMatrix	asRotateMatrixInverse () const
	Returns the inverse of the rotate matrix. More...
virtual MMatrix	asMatrix (double percent) const
	Returns a matrix that represents the specified percentage of this transformation matrix. More...
virtual MMatrix	asInterpolationMatrix (const MTransformationMatrix &toM, double percent, bool rot, int direction=0) const
	Returns a matrix that represents the specified percentage of this transformation matrix. More...
virtual MTransformationMatrix	asTransformationMatrix () const
	Returns the custom transformation matrix as a standard MTransformationMatrix. More...
virtual MVector	translation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the translation component of the transformation matrix as a MVector in centimeters (the internal Maya linear unit). More...
virtual MStatus	translateTo (const MVector &vector, MSpace::Space=MSpace::kTransform)
	Sets the translate component of the transformation matrix in centimeters. More...
virtual MStatus	translateBy (const MVector &vector, MSpace::Space=MSpace::kTransform)
	Add to the translate component by translating relative to the existing transformation. More...
virtual MQuaternion	rotation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the rotation component of the transformation matrix as a quaternion. More...
virtual MEulerRotation	eulerRotation (MSpace::Space space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the rotation component of the transformation matrix as a euler rotation. More...
virtual MStatus	rotateTo (const MQuaternion &q, MSpace::Space=MSpace::kTransform)
	Sets the rotation component of the transformation matrix using a quaternion. More...
virtual MStatus	rotateBy (const MQuaternion &q, MSpace::Space=MSpace::kTransform)
	Rotates relative to the current rotation value of the transformation matrix. More...
virtual MStatus	rotateTo (const MEulerRotation &e, MSpace::Space=MSpace::kTransform)
	Sets the rotation component of the transformation matrix using an euler rotation. More...
virtual MStatus	rotateBy (const MEulerRotation &e, MSpace::Space=MSpace::kTransform)
	Rotates relative to the current rotation value of the transformation matrix. More...
virtual MTransformationMatrix::RotationOrder	rotationOrder (MStatus *ReturnStatus=NULL) const
	Returns the rotation order used by the rotation component of the transformation matrix. More...
virtual MStatus	setRotationOrder (MTransformationMatrix::RotationOrder, bool preserve=true)
	Sets the rotation order used by the rotation component of the transformation matrix. More...
virtual MQuaternion	rotateOrientation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the rotate orientation for the transformation matrix as a quaternion. More...
virtual MStatus	setRotateOrientation (const MQuaternion &q, MSpace::Space=MSpace::kTransform, bool balance=true)
	Sets the rotate orientation for the transformation matrix to the passed quaternion. More...
virtual MEulerRotation	eulerRotateOrientation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the rotate orientation for the transformation matrix as an euler rotation. More...
virtual MStatus	setRotateOrientation (const MEulerRotation &euler, MSpace::Space=MSpace::kTransform, bool balance=true)
	Sets the rotate orientation for the transformation matrix to the passed euler rotation. More...
virtual MVector	scale (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the scale component of the transformation matrix. More...
virtual MStatus	scaleTo (const MVector &, MSpace::Space=MSpace::kTransform)
	Set the scale component of the transformation matrix. More...
virtual MStatus	scaleBy (const MVector &, MSpace::Space=MSpace::kTransform)
	Apply a relative scale to the existing scale. More...
virtual MVector	shear (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the shear component of the transformation matrix. More...
virtual MStatus	shearTo (const MVector &shear, MSpace::Space=MSpace::kTransform)
	Sets the shear component of the transformation matrix. More...
virtual MStatus	shearBy (const MVector &shear, MSpace::Space=MSpace::kTransform)
	Apply a new shear to the existing shear component of the transformation matrix. More...
virtual MPoint	scalePivot (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the pivot used by the scale. More...
virtual MStatus	setScalePivot (const MPoint &, MSpace::Space=MSpace::kTransform, bool balance=true)
	Set the pivot used by the scale. More...
virtual MVector	scalePivotTranslation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the scale pivot translation, which is used to compensate for changes of the scale pivot. More...
virtual MStatus	setScalePivotTranslation (const MVector &vector, MSpace::Space=MSpace::kTransform)
	Set the scale pivot translation. More...
virtual MPoint	rotatePivot (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the pivot used by the rotation. More...
virtual MStatus	setRotatePivot (const MPoint &, MSpace::Space=MSpace::kTransform, bool balance=true)
	Set the pivot used by the rotation. More...
virtual MVector	rotatePivotTranslation (MSpace::Space=MSpace::kTransform, MStatus *ReturnStatus=NULL) const
	Returns the rotate pivot translation, which is used to compensate for changes of the rotate pivot. More...
virtual MStatus	setRotatePivotTranslation (const MVector &vector, MSpace::Space=MSpace::kTransform)
	Set the rotate pivot translation. More...
virtual MStatus	unSquishIt ()
	Remove any shearing and any non-proportional scaling from this transform. More...
virtual MMatrix	unSquishMatrix () const
	Remove any shearing and any non-proportional scaling. More...

Static Public Member Functions
static MPxTransformationMatrix *	creator ()
	A method to use when registering a custom transform that uses a default MPxTransformationMatrix. More...
static MEulerRotation::RotationOrder	convertTransformationRotationOrder (MTransformationMatrix::RotationOrder, MStatus *ReturnStatus=NULL)
	Convert from MTransformationMatrix::RotationOrder to MEulerRotation::RotationOrder. More...
static MTransformationMatrix::RotationOrder	convertEulerRotationOrder (MEulerRotation::RotationOrder, MStatus *ReturnStatus=NULL)
	Convert from MEulerRotation::RotationOrder to MTransformationMatrix::RotationOrder. More...
static MEulerRotation::RotationOrder	convertRotationOrder (MTransformationMatrix::RotationOrder, MStatus *ReturnStatus=NULL)
	This method is obsolete. This method is not available in Python. More...
static MTransformationMatrix::RotationOrder	convertRotationOrder (MEulerRotation::RotationOrder, MStatus *ReturnStatus=NULL)
	This method is obsolete. This method is not available in Python. More...

Static Public Attributes
static const MPxTransformationMatrix	identity
	The identity transformation matrix.
static MTypeId	baseTransformationMatrixId = MTypeId(0x58A00001)
	Type id for the default MPxTransformationMatrix.

Protected Member Functions
virtual MStatus	decomposeMatrix (const MMatrix &)
	This method converts a passed MMatrix into individual transformation matrix components. More...

Static Protected Member Functions
static const char *	className ()
	Returns the name of this class. More...

Protected Attributes
MVector	scaleValue
	Scale component of transformation.
MEulerRotation	rotationValue
	Rotation component of transformation.
MVector	translationValue
	Translation component of transformation.
MVector	shearValue
	Shear component of transformation.
MPoint	scalePivotValue
	Position of pivot used for scaling.
MVector	scalePivotTranslationValue
	Translation to compensate for movement of the scale pivot.
MPoint	rotatePivotValue
	Position of pivot used for rotation.
MVector	rotatePivotTranslationValue
	Translation to compensate for movement of the rotate pivot.
MQuaternion	rotateOrientationValue
	Orientation of the local rotation space.

Friends
std::ostream &	operator<< (std::ostream &os, const MPxTransformationMatrix &m)
	This method is not available in Python. More...

Constructor & Destructor Documentation

MPxTransformationMatrix

(

const MTransformationMatrix &

src

)

Class constructor.

The contents of the passed MTransformationMatrix are used to initialize the new MPxTransformationMatrix.

Parameters

[in]

src

matrix to be copied.

MPxTransformationMatrix

(

const MPxTransformationMatrix &

src

)

A copy constructor.

The contents of the passed MPxTransformationMatrix are used to initialize this MPxTransformationMatrix.

Parameters

[in]

src

The transformation matrix to copy.

MPxTransformationMatrix

(

const MMatrix &

src

)

MMatrix copy constructor.

The contents of the passed MMatrix are used to initialize the new MPxTransformationMatrix. In order to fill the individual components of the transformation matrix, decomposeMatrix() is called with the passed MMatrix.

Parameters

[in]

src

The matrix used for transformation initialization.

Member Function Documentation

void copyValues ( MPxTransformationMatrix *  xform )

virtual

This method should be overridden for any transform that uses more then the default transform values.

The values from the passed class (which should be type checked and downcast to its appropriate value) should be copied to this class.

Without this method being overridden, only the default transform components will get copied.

Parameters

[in]

xform

The user defined transformation matrix that should be copied.

MTypeId typeId ( ) const

virtual

Returns the MTypeId of this transformation matrix.

The MTypeId is a four byte identifier that uniquely identifies this type of transformation matrix.

Returns

Type id of the transformation matrix.

MPxTransformationMatrix & operator=

(

const MPxTransformationMatrix &

src

)

Assignment operator.

Parameters

[in]

src

User defined transformation matrix to be copied.

MPxTransformationMatrix & operator=

(

const MMatrix &

src

)

Assignment operator.

In order to convert the MMatrix to a MPxTransformationMatrix, decomposeMatrix() will be called.

Parameters

[in]

src

The matrix to copy.

MPxTransformationMatrix & operator=

(

const MTransformationMatrix &

src

)

Assignment operator.

Parameters

[in]

src

Transformation matrix to be copied.

bool operator==

(

const MPxTransformationMatrix &

rhs

)

Equality operator.

Parameters

[in]

rhs

The user defined transformation matrix to compare.

Returns

Boolean value: true if the transformation matrices are identical, false otherwise.

bool operator!=

(

const MPxTransformationMatrix &

rhs

)

Inequality operator.

This method will compare the resulting 4x4 matrices for inequality.

Parameters

[in]

rhs

The user defined transformation matrix to compare.

Returns

Boolean value: true The transformation matrices are not identical false otherwise.

bool operator==

(

const MTransformationMatrix &

rhs

)

Equality operator.

This method will compare the resulting 4x4 matrices for equality.

Parameters

[in]

rhs

The user defined transformation matrix to compare.

Returns

Boolean value: true The transformation matrices are identical, false otherwise.

bool operator!=

(

const MTransformationMatrix &

rhs

)

Inequality operator.

This method will compare the resulting 4x4 matrices for inequality.

Parameters

[in]

rhs

The MTransformationMatrix to compare.

Returns

Boolean value: true The matrices are not identical, false otherwise.

bool operator==

(

const MMatrix &

rhs

)

Equality operator.

Parameters

[in]

rhs

the MMatrix to compare

Returns

Boolean value: true The matrices are identical, false otherwise.

bool operator!=

(

const MMatrix &

rhs

)

Equality operator.

This method will compare the resulting 4x4 matrices for equality.

Parameters

[in]

rhs

The MMatrix to compare.

Returns

Boolean value: true The matrices are not identical, false otherwise.

bool isEquivalent ( const MPxTransformationMatrix &  other, double  tolerance = MMatrix_kTol  ) const

virtual

Determine if the MPxTransformationMatrix is equivalent within a specified tolerance.

The comparison is done with the resulting 4x4 MMatrix and not on a component by component basis.

Parameters

[in]	other	The user defined transformation matrix to compare to.
[in]	tolerance	The tolerance used in the comparison.

Returns

Boolean value; true The matrices are identical within the specified tolerance, false otherwise.

bool isEquivalent ( const MTransformationMatrix &  other, double  tolerance = MMatrix_kTol  ) const

virtual

Determine if the MTransformationMatrix is equivalent within a specified tolerance.

The comparison is done with the resulting 4x4 MMatrix and not on a component by component basis.

Parameters

[in]	other	The transformation matrix to compare to
[in]	tolerance	The tolerance used in the comparison.

Returns

Boolean value; true The matrices are identical within the specified tolerance, false otherwise.

bool isEquivalent ( const MMatrix &  other, double  tolerance = MMatrix_kTol  ) const

virtual

Determine if the MMatrix is equivalent within a specified tolerance.

Parameters

[in]	other	The matrix to compare to.
[in]	tolerance	The tolerance used in the comparison.

Returns

Boolean value; true The matrices are identical within the specified tolerance, false otherwise.

MPxTransformationMatrix reverse ( ) const

virtual

Returns the negated translate, rotate, and scale without taking the pivots into account.

This method is provided only as a convenience: it is not called internally by Maya.

Note that the value returned by this method is an instance of MPxTransformationMatrix not an instance of your derived class. As such, caution must be exercised when using it with derived classes which provide their own data members as those members will not be preserved in the result.

Returns

The reversed transformation matrix

MPxTransformationMatrix & transformBy ( const MTransformationMatrix &  transMat )

virtual

Transforms the transformation matrix by the passed MTransformationMatrix.

The individual components are considered with the exception of the pivot translations.

Parameters

[in]

transMat

The transformation matrix to transform by.

Returns

This transformation matrix.

MMatrix asMatrix ( ) const

virtual

Returns the four by four matrix that describes this transformation.

The default matrix math is defined by:

   -1                     -1
[Sp]x[S]x[Sh]x[Sp]x[St]x[Rp]x[Ro]x[R]x[Rp]x[Rt]x[T]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, [St] is the scale pivot translation, [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, [Rt] is the rotate picot translation, and [T] is the translation.

Returns

The resulting matrix.

Examples:

MMatrix asMatrixInverse ( ) const

virtual

Returns the inverse of the four by four matrix that describes this transformation.

By default this is described as:

     -1                     -1                         -1
[ [Sp]x[S]x[Sh]x[Sp]x[St]x[Rp]x[Ro]x[R]x[Rp]x[Rt]x[T] ]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, [St] is the scale pivot translation, [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, [Rt] is the rotate picot translation, and [T] is the translation.

Returns

The inverse matrix.

MMatrix asScaleMatrix ( ) const

virtual

Returns scale matrix.

The scale matrix takes points from object space to the space immediately following scale and shear transformations.

For the default matrix, the scale matrix combines the space pivot [Sp], scale [S], shear [Sh], and scale translate [St] components as follows:

   -1
[Sp]x[S]x[Sh]x[Sp]x[St]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, and [St] is the scale pivot translation.

Returns

The scale matrix.

MMatrix asScaleMatrixInverse ( ) const

virtual

Returns inverse of the scale matrix.

The scale matrix takes points from object space to the space immediately following scale and shear transformations.

By default this value is described by:

     -1                    -1
[ [Sp]x[S]x[Sh]x[Sp]x[St] ]

Where [Sp] is the scale pivot, [S] is the scale matrix, [Sh] is the shear matrix, and [St] is the scale pivot translation.

Returns

The inverse space matrix.

MMatrix asRotateMatrix ( ) const

virtual

Returns the rotate section of the transformation matrix.

By default this is described as:

   -1
[Rp]x[Ro]x[R]x[Rp]

Where [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, and [Rt] is the rotate pivot translation.

Returns

The rotate matrix.

Examples:

MMatrix asRotateMatrixInverse ( ) const

virtual

Returns the inverse of the rotate matrix.

By default this is described as:

     -1                    -1
[ [Rp]x[Ro]x[R]x[Rp]x[Rt] ]

Where [Rp] is the rotate pivot, [Ro] is the rotate orientation, [R] is the rotate matrix, and [Rt] is the rotate picot translation.

Returns

The inverse rotate matrix.

MMatrix asMatrix ( double  percent ) const

virtual

Returns a matrix that represents the specified percentage of this transformation matrix.

This is performed on a per-component basis.

Parameters

[in]

percent

Returns

The resulting matrix.

MMatrix asInterpolationMatrix ( const MTransformationMatrix &  toM, double  percent, bool  rot, int  direction = 0  ) const

virtual

Returns a matrix that represents the specified percentage of this transformation matrix.

The two matrices involved in the interpolation are this transformation matrix and the passed transformation matrix, toMatrix.

This is used by clusters.

Parameters

[in]	toM	The matrix to interpolate to.
[in]	percent	The percentage of the interpolation (between 0 and 1)
[in]	rot	Should the rotation values be included?
[in]	direction	The desired direction of the interpolation.

• 0 Closest path between this matrix and toMatrix.
• 1 From this matrix to toMatrix.
• 2 From toMatrix to this matrix.

Returns

The interpolated matrix.

MTransformationMatrix asTransformationMatrix ( ) const

virtual

Returns the custom transformation matrix as a standard MTransformationMatrix.

Returns

The transformation matrix.

MVector translation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the translation component of the transformation matrix as a MVector in centimeters (the internal Maya linear unit).

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The translation vector in centimeters.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus translateTo ( const MVector &  t, MSpace::Space  space = MSpace::kTransform  )

virtual

Sets the translate component of the transformation matrix in centimeters.

Parameters

[in]	t	The new translate value in centimeters.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus translateBy ( const MVector &  t, MSpace::Space  space = MSpace::kTransform  )

virtual

Add to the translate component by translating relative to the existing transformation.

The relative translate should be in centimeters.

Parameters

[in]	t	The relative translate value in centimeters.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MQuaternion rotation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the rotation component of the transformation matrix as a quaternion.

If an invalid space is used, MQuaternion::identity will be returned.

Parameters

[in]	space	The space in which to get the rotation.
[out]	ReturnStatus	The status.

Returns

The quaternion that is the rotation component of the transformation matrix

Status Codes:

• MS::kSuccess Operation successful
• MS::kInvalidParameter Invalid space

MEulerRotation eulerRotation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the rotation component of the transformation matrix as a euler rotation.

If an invalid space is used, MEulerRotation::identity will be returned.

Parameters

[in]	space	The space in which to get the rotation.
[out]	ReturnStatus	Return status.

Returns

The euler angle that is the rotation component of the transformation matrix.

Status Codes:

• MS::kSuccess Operation successful
• MS::kInvalidParameter Invalid space

Examples:

MStatus rotateTo ( const MQuaternion &  quat, MSpace::Space  space = MSpace::kTransform  )

virtual

Sets the rotation component of the transformation matrix using a quaternion.

Parameters

[in]	quat	The quaternion used to set the rotation component of the transformation matrix.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

Examples:

MStatus rotateBy ( const MQuaternion &  quat, MSpace::Space  space = MSpace::kTransform  )

virtual

Rotates relative to the current rotation value of the transformation matrix.

By default, the only valid transformation spaces for this method are MSpace::kTransform and MSpace::kPreTransform. All other spaces are treated as being equivalent to MSpace::kTransform.

Parameters

[in]	quat	The relative rotation as a quaternion.
[in]	space	The space in which the rotation is performed.

Returns

Return status.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kInvalidParameter An invalid space was used.

MStatus rotateTo ( const MEulerRotation &  euler, MSpace::Space  space = MSpace::kTransform  )

virtual

Sets the rotation component of the transformation matrix using an euler rotation.

Parameters

[in]	euler	The euler rotation used to set the transformation matrix.
[in]	space	The space used to set the rotation.

Returns

Return status.

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus rotateBy ( const MEulerRotation &  euler, MSpace::Space  space = MSpace::kTransform  )

virtual

Rotates relative to the current rotation value of the transformation matrix.

By default, the only valid transformation spaces for this method are MSpace::kTransform and MSpace::kPreTransform. All other spaces are treated as being equivalent to MSpace::kTransform.

Parameters

[in]	euler	The relative rotation as an euler angle.
[in]	space	The space in which the rotation is performed.

Returns

Return status.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kInvalidParameter An invalid space was used.

MTransformationMatrix::RotationOrder rotationOrder ( MStatus *  ReturnStatus = NULL ) const

virtual

Returns the rotation order used by the rotation component of the transformation matrix.

Parameters

[out]

ReturnStatus

Return status.

Returns

The rotation order use by the rotation component of the transformation matrix.

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure The method failed.

MStatus setRotationOrder ( MTransformationMatrix::RotationOrder  rotOrder, bool  preserve = true  )

virtual

Sets the rotation order used by the rotation component of the transformation matrix.

Parameters

[in]	rotOrder	The rotation order to use
[in]	preserve	If true then the values will change to preserve the rotation.

Returns

The return status

Status Codes:

• MS::kSuccess The method was successful.
• MS::kFailure The method failed.

MQuaternion rotateOrientation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the rotate orientation for the transformation matrix as a quaternion.

The rotate orientation orients the local rotation space.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	The return status.

Returns

The rotate orientation.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed.

MStatus setRotateOrientation ( const MQuaternion &  q, MSpace::Space  space = MSpace::kTransform, bool  balance = true  )

virtual

Sets the rotate orientation for the transformation matrix to the passed quaternion.

The rotate orientation is the rotation that orients the local rotation space.

Parameters

[in]	q	The rotate orientation.
[in]	space	The space to use.
[in]	balance	If true, the overall rotation will be preserved by altering the rotation to compensate for the change in rotate orientation.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MEulerRotation eulerRotateOrientation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the rotate orientation for the transformation matrix as an euler rotation.

The rotate orientation orients the local rotation space.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The rotate orientation as an euler angle.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MStatus setRotateOrientation ( const MEulerRotation &  euler, MSpace::Space  space = MSpace::kTransform, bool  balance = true  )

virtual

Sets the rotate orientation for the transformation matrix to the passed euler rotation.

The rotate orientation is the rotation that orients the local rotation space.

Parameters

[in]	euler	The rotate orientation.
[in]	space	The space to use.
[in]	balance	If true, the overall rotation will be preserved by altering the rotation to compensate for the change in rotate orientation.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter An invalid space was used.

MVector scale ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the scale component of the transformation matrix.

If the space is invalid a MVector with all of its components being 1.0 is returned.

Only the scale is returned, without the scale pivot, scale pivot translate, or shear values applied.

Parameters

[in]	space	transform space in which to get the scale
[out]	ReturnStatus	return status

Returns

Vector holding the x, y, and z scale components

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus scaleTo ( const MVector &  newScale, MSpace::Space  space = MSpace::kTransform  )

virtual

Set the scale component of the transformation matrix.

If an invalid space is passed, the scale will not be changed.

Parameters

[in]	newScale	A vector holding the scale components.
[in]	space	The space in which to perform the scale.

Returns

Return status

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MStatus scaleBy ( const MVector &  scaleFactor, MSpace::Space  space = MSpace::kTransform  )

virtual

Apply a relative scale to the existing scale.

Parameters

[in]	scaleFactor	A MVector holding the scale components.
[in]	space	The space in which to perform the scale.

Returns

Return status.

Status Codes:

• MS::kSuccess Success
• MS::kInvalidParameter Invalid space

MVector shear ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the shear component of the transformation matrix.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

A MVector holding the xy, xz, yz values of shear.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus shearTo ( const MVector &  newShear, MSpace::Space  space = MSpace::kTransform  )

virtual

Sets the shear component of the transformation matrix.

Parameters

[in]	newShear	The new shear value.
[in]	space	The space to use for setting the shear.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus shearBy ( const MVector &  shearOffset, MSpace::Space  space = MSpace::kTransform  )

virtual

Apply a new shear to the existing shear component of the transformation matrix.

The shear values are added by multiplying the individual shear components with the offset values.

Parameters

[in]	shearOffset	The relative shear value.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MPoint scalePivot ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the pivot used by the scale.

The value is in centimeters.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The scale pivot point.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus setScalePivot ( const MPoint &  scalePivot, MSpace::Space  space = MSpace::kTransform, bool  balance = true  )

virtual

Set the pivot used by the scale.

If balance if true, then the overall transformation matrix will not change and a compensating translation will be added to the scale pivot transformation to achieve this.

If an invalid space is used, the scale pivot will not change.

Parameters

[in]	scalePivot	The new scale pivot value.
[in]	space	The space to use.
[in]	balance	Set true is the overall transform should remain unchanged after setting the new scale pivot value.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MVector scalePivotTranslation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the scale pivot translation, which is used to compensate for changes of the scale pivot.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The scale pivot translation.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus setScalePivotTranslation ( const MVector &  v, MSpace::Space  space = MSpace::kTransform  )

virtual

Set the scale pivot translation.

When the scale pivot is changed, there is an option to automatically compensate for the change so that the overall transformation is not altered. The compensating factor is the scale pivot translation.

This method will manually change the scale pivot translation.

Parameters

[in]	v	The new scale pivot translation.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MPoint rotatePivot ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the pivot used by the rotation.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The rotation pivot point.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MStatus setRotatePivot ( const MPoint &  rotatePivot, MSpace::Space  space = MSpace::kTransform, bool  balance = true  )

virtual

Set the pivot used by the rotation.

If balance if true, then the overall transformation will not change and a compensating translation will be added to the rotation transformation to achieve this.

For the default case, the balance calculation is as follows:

Let [Rp] be the previous rotate pivot and [Rt] be the previous
rotate pivot translation. The new rotate pivot will be marked as
[Rp'] and the new rotate pivot translation as [Rt']

If balance is true the entire rotate section of the transform
must be the same before and after the rotate pivot is changed:

   -1                         -1
[Rp]x[Ro]x[R]x[Rp]x[Rt] = [Rp']x[Ro]x[R]x[Rp']x[Rt']

solving for [Rt'] produces:
             -1               -1     -1
[Rt'] = [[Rp']x[Ro]x[R]x[Rp']]  x  [Rp]x[Ro]x[R]x[Rp]x[Rt]

Parameters

[in]	rotatePivot	The new rotate pivot.
[in]	space	The space to use.
[in]	balance	Set true is the overall transform should remain unchanged after setting the new rotate pivot value.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MVector rotatePivotTranslation ( MSpace::Space  space = MSpace::kTransform, MStatus *  ReturnStatus = NULL  ) const

virtual

Returns the rotate pivot translation, which is used to compensate for changes of the rotate pivot.

Parameters

[in]	space	The space to use.
[out]	ReturnStatus	Return status.

Returns

The rotate pivot translation.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MStatus setRotatePivotTranslation ( const MVector &  v, MSpace::Space  space = MSpace::kTransform  )

virtual

Set the rotate pivot translation.

When the scale pivot is changed, there is an option to automatically compensate for the change so that the overall transformation is not altered. The compensating factor is the rotate pivot translation.

See the documentation for setRotatePivot for an explanation of the compensating calculation.

Parameters

[in]	v	The new rotate pivot translation.
[in]	space	The space to use.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space being used.

MStatus unSquishIt ( )

virtual

Remove any shearing and any non-proportional scaling from this transform.

If the scaling is non-proportional, then the maximum scale of the three scale axes will be used on all of the scale axes.

If new scaling or shearing types are added to a derived class, this method should be overloaded.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MMatrix unSquishMatrix ( ) const

virtual

Remove any shearing and any non-proportional scaling.

If the scaling is non-proportional, then the maximum scale of the three scale axes will be used on all of the scale axes. The method creates a new 4x4 MMatrix and leaves this transformation matrix unchanged.

If new scaling or shearing types are added to a derived class, this method should be overloaded.

Returns

The unsquished 4x4 matrix.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kInvalidParameter The method failed due to an invalid space.

MPxTransformationMatrix * creator ( )

static

A method to use when registering a custom transform that uses a default MPxTransformationMatrix.

The caller is responsible for deleting the memory created by this method.

Returns

The new MPxTransformationMatrix

Examples:

MEulerRotation::RotationOrder convertTransformationRotationOrder ( MTransformationMatrix::RotationOrder  xformOrder, MStatus *  ReturnStatus = NULL  )

static

Convert from MTransformationMatrix::RotationOrder to MEulerRotation::RotationOrder.

If MTransformationMatrix::kLast or MTransformationMatrix::kInvalid is passed in, MEulerRotation::kXYZ will be returned along with a kInvalidParameter return status.

Parameters

[in]	xformOrder	The MTransformationMatrix::RotationOrder
[out]	ReturnStatus	return status

Returns

The corresponding MEulerRotation::RotationOrder.

Status Codes:

• MS::kInvalidParameter No matching enum was found.
• MS::kSuccess Operation successful

MTransformationMatrix::RotationOrder convertEulerRotationOrder ( MEulerRotation::RotationOrder  eulerOrder, MStatus *  ReturnStatus = NULL  )

static

Convert from MEulerRotation::RotationOrder to MTransformationMatrix::RotationOrder.

Parameters

[in]	eulerOrder	The MEulerRotation::RotationOrder
[out]	ReturnStatus	return status

Returns

The corresponding MTransformationMatrix::RotationOrder.

Status Codes:

• MS::kInvalidParameter No matching enum was found.
• MS::kSuccess Operation successful

MEulerRotation::RotationOrder convertRotationOrder ( MTransformationMatrix::RotationOrder  xformOrder, MStatus *  ReturnStatus = NULL  )

static

This method is obsolete. This method is not available in Python.

Deprecated:

Use the MPxTransformationMatrix::convertTransformationRotationOrder() method instead.

Parameters

[in]	xformOrder
[out]	ReturnStatus

MTransformationMatrix::RotationOrder convertRotationOrder ( MEulerRotation::RotationOrder  eulerOrder, MStatus *  ReturnStatus = NULL  )

static

This method is obsolete. This method is not available in Python.

Deprecated:

Use the MPxTransformationMatrix::convertEulerRotationOrder() method instead.

Parameters

[in]	eulerOrder
[out]	ReturnStatus

MStatus decomposeMatrix ( const MMatrix &  m )

protectedvirtual

This method converts a passed MMatrix into individual transformation matrix components.

The default algorithm will solve under the assumption that the pivots and pivot translates are all zero.

It is possible that multiple transformation matrices may produce identical 4x4 matrices. This means that taking a generic transformation matrix and converting it to a MMatrix and back to a transformation matrix may have different components, but the net transformation will still be the same.

Parameters

[in]

m

The matrix to break up into components.

Returns

Return status.

Status Codes:

• MS::kSuccess The method succeeded.
• MS::kFailure The method failed.

const char * className ( )

staticprotected

Returns the name of this class.

Returns

The name of this class.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  os, const MPxTransformationMatrix &  m  )

friend

This method is not available in Python.

A method to easily dump the contents of a transformation matrix.

Parameters

[in]	os	The ostream to use.
[in]	m	The transformation matrix to print.

Returns

Ostream

---

The documentation for this class was generated from the following files:

• MPxTransformationMatrix.h
• MPxTransformationMatrix.cpp