Matrix3 Values

Values and Collections - Quick Navigation

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>

Constructs a matrix from four row vectors.

matrix3 0

Constructs a zero matrix: (matrix3 [0,0,0] [0,0,0] [0,0,0] [0,0,0])

matrix3 1

Constructs an identity matrix: (matrix3 [1,0,0] [0,1,0] [0,0,1] [0,0,0])

<quat> as matrix3
<angleaxis> as matrix3
<eulerangles> as matrix3 

Construct and return rotation matrices from arbitrary rotation values.

rotateXMatrix <number> -- all angles in degrees rotateYMatrix <number>
rotateZMatrix <number>

Construct and return rotation matrices relatively to major world axes.

transMatrix <point3>

Constructs and returns a translation matrix.

scaleMatrix <point3>

Constructs and returns a scale matrix.

rotateYPRMatrix <yaw_number> <pitch_number> <roll_number>

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

matrixFromNormal <point3>

Constructs and 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.

MatrixFromNormal [0,0,1]
MatrixFromNormal [0,1,1]

(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. Valid 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.

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

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 the sign of the matrix' determinant.

Methods

copy <matrix3>

Creates a new copy of the matrix3 value.

newMatrix3 = copy oldMatrix3

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

Using the equality comparison expression on the original and the copy values will always return false.

To correctly compare two matrix3 values for equality, their four components have to be compared individually, the two values could be converted to strings and compared as strings instead, or the one matrix3 value could be multiplied by the inverse of the other and tested for identity:

a = matrix3 1 --create an identity matrix
(matrix3 [1,0,0] [0,1,0] [0,0,1] [0,0,0])
b = copy a --copy the value of a into variable b
(matrix3 [1,0,0] [0,1,0] [0,0,1] [0,0,0])
a == b --compare a and b - although their values are equal, result is false
false
 
--This is because the equality test of compound values like Matrix3 and Array
--is testing to see whether the two variables point at the same memory address
--and does not perform a per-component equality test.
--Thus:
c = a
(matrix3 [1,0,0] [0,1,0] [0,0,1] [0,0,0])
a == c --compare a and c - both point at the same memory and are considered equal:
true
 
--To compare a and b, we can either convert both to strings and compare them:
a as string == b as string
true
 
--or we can test their components in pairs,
a.row1 == b.row1 AND a.row2 == b.row2 AND a.row3 == b.row3 AND a.row4 == b.row4
true
 
--or we can multiply a with the inverse of b and test if the result is the identity matrix:
isIdentity (a * inverse b)
true

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 transforms 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 a 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).

-- all angles in degrees
--mapped functions
rotateX <matrix3> <number>  
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).

-- all angles in degrees
-- mapped functions 
preRotateX<matrix3> <number>
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

<float>GetEulerMatAngleRatio <mat1> <mat2> <array1> <array2>

<float>GetEulerMatAngleRatio <mat1> <mat1> <eulerAngle1> <eulerAngle2>  

<float>GetEulerMatAngleRatio <mat1> <mat1> &<var1> &<var2>

See topic EulerAngles Values for details.

 Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Please see the Autodesk Creative Commons FAQ for more information.