Matrix3 Values

The Matrix3 class implements a 4x3 3D transformation matrix object. The transform matrix is a 3D homogeneous matrix typically used to hold object coordinate systems and transformations.

Constructors

matrix3 <row1_point3> <row2_point3> <row3_point3> <row4_point3>

matrix from row vectors

matrix3 0

zero matrix

matrix3 1

identity matrix

<quat> as matrix3

<angleaxis> as matrix3

<eulerangles> as matrix3

rotation matrices

rotateXMatrix <number> -- all angles in degrees

rotateYMatrix <number>

rotateZMatrix <number>

rotation matrices

transMatrix <point3>

translation matrix

scaleMatrix <point3>

scale matrix

rotateYPRMatrix <yaw_number> <pitch_number> <roll_number>

Returns a Matrix3 value for use as a rotation transformation by specifying yaw, pitch and roll angles. All angles are in degrees.

matrixFromNormal <point3>

Returns a Matrix3 value with the normal specified by the given point as the Z axis. The translation portion of the Matrix3 value will be [0,0,0]. The components of the scale portion are the inverse of the values required to normalize the point3 value.

For example,

MatrixFromNormal [0,0,1]

MatrixFromNormal [0,1,1]

will return

(matrix3 [1,0,0], [0,1,0], [0,0,1], [0,0,0])

(matrix3 [0,-0.707107,0.707107] [1.41421,0,0] [0,1,1] [0,0,0])

Operators

<matrix3> + <matrix3>

<matrix3> - <matrix3>

<matrix3> * <matrix3>

<matrix3> as <class>

Matrix3's can convert to Quat's, AngleAxis, EulerAngles using the matrix's rotation component

<matrix3>[<integer>]

Returns a row of the Matrix3 as a Point3. Valud range on this index is 1 to 4.

<matrix3>[<integer>] = <Point3>

Sets a row of the Matrix3 to the Point3. Valid range on the index is 1 to 4.

Properties

<matrix3>.row1 : Point3

<matrix3>.row2 : Point3

<matrix3>.row3 : Point3

<matrix3>.row4 : Point3

<matrix3>.translation : Point3

read/write access to rows. Row4 is the translation.

Note:

When working with object transformation matrix3 values, the rows and their sub-elements cannot be modified directly. To change a row or an element of the row, assign the matrix3 value to a user variable first, modify the matrix3 rows by assigning to the variable and then assign the variable back to the .transform property of the original object.

For Example:

--DOES NOTHING:

$Teapot01.transform.row4 = [10.0,20.0,30.0]

--WORKS:

myTransform = $Teapot01.transform

myTransform.row4 = [10.0,20.0,30.0]

$Teapot01.transform = myTransform

<matrix3>.rotationpart : Quat, read-only

<matrix3>.translationpart : Point3, read-only

<matrix3>.scalerotationpart : Quat, read-only

<matrix3>.scalepart : Point3, read-only

access to various transforms, with the remaining transforms zero-ed out.

<matrix3>.determinantsign : Integer, read-only

returns sign of the matrix's determinant

Methods

copy <matrix3>

Creates a new copy of the matrix3 value.

For example:

newMatrix3 = copy oldMatrix3

The new value contains a copy of the input matrix3 value, and is independent of the input matrix3 value.

isIdentity <matrix3>

Returns true if the matrix is equal to the identity matrix.

inverse <matrix3>

Returns the inverse of the matrix.

xformMat <transform_matrix3> <space_matrix3>

Returns the transform matrix transformed into a particular space. For example, say you have a rotation you want to apply, but you want to perform the rotation in another coordinate system. To do this, you typically transform into the space of the coordinate system, then apply the transformation, and then transform out of that coordinate system. This method transformats matrix transform_matrix3 into the space of matrix space_matrix3. The resulting matrix3 value is calculated as space_matrix3 * transform_matrix3 * inverse(space_matrix3).

identity <matrix3> -- mapped function

Sets the input matrix or matrices to the identity matrix. If the parameter is a single matrix, this function returns an identity matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the identity matrix.

zero <matrix3> -- mapped function

Sets the input matrix or matrices to the zero matrix. If the parameter is a single matrix, this function returns an zero matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 values are replaced with the zero matrix.

orthogonalize <matrix3> -- mapped function

Sets the input matrix or matrices to the an "unbiased" orthogonalization of the matrix. An orthogonal matrix has an axis system where each axis is 90 degrees from the others (it's not skewed). If the parameter is a single matrix, this function returns the orthogonalized matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the orthogonalized matrix value(s).

translate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

rotateX <matrix3> <number> -- mapped functions -- all angles in degrees

rotateY <matrix3> <number>

rotateZ <matrix3> <number>

rotate <matrix3> <quat>

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

scale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the RIGHT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. When 3ds Max was originally written there was a bug in the code for this method where the translation portion of the matrix was not being scaled. This meant that when a matrix was scaled the bottom row was not scaled. Thus it would always scale about the local origin of the object, but it would scale the world axes. When this bug was discovered, dependencies existed in the code upon this bug. Thus it could not simply be fixed because it would break the existing code that depended upon it working the incorrect way. To correct this boolean parameter was added. If it is set to true, the translation component will be scaled correctly. If not specified, the boolean defaults to false, and the code behaves the old way. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preTranslate <matrix3> <point3> -- mapped function

Applies an incremental translation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preRotateX <matrix3> <number> -- mapped functions -- all angles in degrees

preRotateY <matrix3> <number>

preRotateZ <matrix3> <number>

preRotate <matrix3> <quat>

Applies an incremental rotation transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

preScale <matrix3> <point3> [ <boolean> ] -- mapped function

Applies an incremental scale transformation to the input matrix or matrices. This is equivalent to multiplying on the LEFT by the transform. If <boolean> is true, the translation component is scaled. If <boolean> is false the translation component is unaffected. If not specified, the boolean defaults to false. If the matrix3 parameter is a single matrix, this function returns the transformed matrix. If the parameter is an array of matrices, this function returns the value OK. In both cases, the input matrix3 value(s) are replaced with the transformed matrix value(s).

Related Methods

getEulerMatAngleRatio <matrix3_1> <matrix3_2> <eulerAngles1> <eulerAngles2> [angle:<eulertype_integer>]

When converting a series of matrix3 values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single matrix3 value can be expressed through many different eulerAngles values. This flip can be detected by based on the eulerAngles/matrix3 ratio. The eulerAngles/matrix3 ratio is the relation of the angle difference in eulerAngles space to the angle difference in matrix3 space. If this ratio is bigger than PI the rotation between the two matrix3 to eulerAngles conversions. This method returns the eulerAngles/matrix3 Angle ratio between the two matrix3 to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

matrix3_1 and matrix3_2 are the previous and current transform matrix values.

eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

The optional eulertype_integer specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ

2 - XZY

3 - YZX

4 - YXZ

5 - ZXY

6 - ZYX

7 - XYX

8 - YZY

9 - ZXZ