The Matrix3D object represents a transformation matrix that determines the position and orientation of a three-dimensional (3D) display object. The matrix can perform transformation functions including translation (repositioning along the x, y, and z axes), rotation, and scaling (resizing). The Matrix3D class can also perform perspective projection, which maps points from the 3D coordinate space to a two-dimensional (2D) view.

A single matrix can combine multiple transformations and apply them at once to a 3D display object. For example, a matrix can be applied to 3D coordinates to perform a rotation followed by a translation.


When you explicitly set the z property or any of the rotation or scaling properties of a display object, a corresponding Matrix3D object is automatically created.


You can access a 3D display object's Matrix3D object through the transform.matrix3d property. 2D objects do not have a Matrix3D object.


The value of the z property of a 2D object is zero and the value of its matrix3D property is nil.


Note: If the same Matrix3D object is assigned to two different display objects, a runtime error is thrown.


The Matrix3D object uses a 4x4 square matrix: a table of four rows and columns of numbers that hold the data for the transformation. The first three rows of the matrix hold data for each 3D axis (x,y,z). The translation information is in the last column. The orientation and scaling data are in the first three columns. The scaling factors are the diagonal numbers in the first three columns. 


You don't need to understand matrix mathematics to use the Matrix3D object. It offers specific methods that simplify the task of transformation and projection, such as the appendTranslation(), appendRotation(), or interpolateTo() methods. You also can use the decompose() and recompose() methods or the rawData property to access the underlying matrix elements.


Display objects cache their axis rotation properties to have separate rotation for each axis and to manage the different combinations of rotations. When a method of a Matrix3D object is called to transform a display object, the rotation cache of the object is invalidated.


Can be created with method new:

Lib.Media.Geom.Matrix3D.new(v)

Creates a Matrix3D object

v - (default = nil) - A Vector array of 16 Numbers, where each four elements is a column of a 4x4 matrix.


Created Matrix3D object has properties:

determinant

[read-only] A Number that determines whether a matrix is invertible.

position

A Vector3D object that holds the position, the 3D coordinate (x,y,z) of a display object within the transformation's frame of reference.

rawData

A Vector array of 16 Numbers, where every four elements is a column of a 4x4 matrix.


methods:

append(lhs)

Appends the matrix by multiplying another Matrix3D object by the current Matrix3D object.

lhs - A left-hand-side matrix that is multiplied by the current Matrix3D object.

appendRotation(degrees, axis, pivotPoint)

Appends an incremental rotation to a Matrix3D object.

degrees - The degree of the rotation.

axis - The axis or direction of rotation. The usual axes are the X_AXIS (Vector3D(1,0,0)), Y_AXIS (Vector3D(0,1,0)), and Z_AXIS (Vector3D(0,0,1)). This vector should have a length of one.

pivotPoint - (default = nil) - A Vector3D point that determines the center of an object's rotation. The default pivot point for an object is its registration point.

appendScale(xScale, yScale, zScale)

Appends an incremental scale change along the x, y, and z axes to a Matrix3D object.

xScale - A multiplier used to scale the object along the x axis.

yScale - A multiplier used to scale the object along the y axis.

zScale - A multiplier used to scale the object along the z axis.

appendTranslation(x, y, z)

Appends an incremental translation, a repositioning along the x, y, and z axes, to a Matrix3D object.

x - An incremental translation along the x axis.

y - An incremental translation along the y axis.

z - An incremental translation along the z axis.

clone()

Returns a new Matrix3D object that is an exact copy of the current Matrix3D object.

copyColumnFrom(column, vector3D)

Copies a Vector3D object into specific column of the calling Matrix3D object.

column - The destination column of the copy.

vector3D - The Vector3D object from which to copy the data.

copyColumnTo(column, vector3D)

Copies specific column of the calling Matrix3D object into the Vector3D object.

column - The column from which to copy the data.

vector3D - The destination Vector3D object of the copy.

copyFrom(sourceMatrix3D)

Copies all of the matrix data from the source Matrix3D object into the calling Matrix3D object.

sourceMatrix3D - The Matrix3D object from which to copy the data.

copyRawDataFrom(vector, index, transpose)

Copies all of the vector data from the source vector object into the calling Matrix3D object.

vector - The vector array object from which to copy the data.

index - (default = 0)

transpose - (default = false)

copyRawDataTo(vector, index, transpose)

Copies all of the matrix data from the calling Matrix3D object into the provided vector.

vector - The vector array object to which to copy the data.

index - (default = 0)

transpose - (default = false)

copyRowFrom(row, vector3D)

Copies a Vector3D object into specific row of the calling Matrix3D object.

row - The row from which to copy the data to.

vector3D - The Vector3D object from which to copy the data.

copyRowTo(row, vector3D)

Copies specific row of the calling Matrix3D object into the Vector3D object.

row - The row from which to copy the data from. 

vector3D - The Vector3D object to copy the data into.

copyToMatrix3D(dest)

Copies matrix to destination Matrix3D

dest - destination Matrix3D

decompose(orientationStyle)

Returns the transformation matrix's translation, rotation, and scale settings as a Vector of three Vector3D objects.

orientationStyle - (default = "eulerAngles") - parameter that determines the orientation style used for the matrix transformation. The three types of orientation style are eulerAngles (constant EULER_ANGLES), axisAngle (constant AXIS_ANGLE), and quaternion (constant QUATERNION). For additional information on the different orientation style, see the Orientation3D object.

deltaTransformVector(v)

Uses the transformation matrix without its translation elements to transform a Vector3D object from one space coordinate to another.

v - A Vector3D object holding the coordinates that are going to be transformed.

identity()

Converts the current matrix to an identity or unit matrix.

interpolate(thisMat, toMat, percent)

[static] Interpolates the translation, rotation, and scale transformation of one matrix toward those of the target matrix.

thisMat - The Matrix3D object that is to be interpolated.

toMat - The target Matrix3D object.

percent - A value between 0 and 1 that determines the percent the thisMat Matrix3D object is interpolated toward the target Matrix3D object.

interpolateTo(toMat, percent)

Interpolates this matrix towards the translation, rotation, and scale transformations of the target matrix.

toMat - The target Matrix3D object.

percent - A value between 0 and 1 that determines the location of the display object relative to the target. The closer the value is to 1.0, the closer the display object is to its current position. The closer the value is to 0, the closer the display object is to the target.

invert()

Inverts the current matrix.

pointAt(pos, at, up)

Rotates the display object so that it faces a specified position.

pos - The world-relative Vector3D position of the target object. World-relative defines the object's transformation relative to the world space and coordinates, where all objects are positioned.

at - (default = nil) - The object-relative vector that defines where the display object is pointing Vector3D. Object-relative defines the object's transformation relative to the object space, the object's own frame of reference and coordinate system. Default value is the +y axis (0,1,0).

up - (default = nil) - The object-relative vector that defines "up" for the display object Vector3D. If the object is drawn looking down from above, the +z axis is its "up" vector. Object-relative defines the object's transformation relative to the object space, the object's own frame of reference and coordinate system. Default value is the +z-axis (0,0,1).

prepend(rhs)

Prepends a matrix by multiplying the current Matrix3D object by another Matrix3D object.

rhs - A right-hand-side of the matrix by which the current Matrix3D is multiplied.

prependRotation(degrees, axis, pivotPoint)

Prepends an incremental rotation to a Matrix3D object.

degrees - The degree of rotation.

axis - The axis or direction of rotation Vector3D. The usual axes are the X_AXIS (Vector3D(1,0,0)), Y_AXIS (Vector3D(0,1,0)), and Z_AXIS (Vector3D(0,0,1)). This vector should have a length of one.

pivotPoint - (default = nil) - A point that determines the center of rotation Vector3D. The default pivot point for an object is its registration point.

prependScale(xScale, yScale, zScale)

Prepends an incremental scale change along the x, y, and z axes to a Matrix3D object.

xScale - A multiplier used to scale the object along the x axis.

yScale - A multiplier used to scale the object along the y axis.

zScale - A multiplier used to scale the object along the z axis.

prependTranslation(x, y, z)

Prepends an incremental translation, a repositioning along the x, y, and z axes, to a Matrix3D object.

x - An incremental translation along the x axis.

y - An incremental translation along the y axis.

z - An incremental translation along the z axis.

recompose(components, orientationStyle)

Sets the transformation matrix's translation, rotation, and scale settings.

components - A Vector array of three Vector3D objects that replace the Matrix3D object's translation, rotation, and scale elements.

orientationStyle - (default = "eulerAngles") - parameter that determines the orientation style used for the matrix transformation. The three types of orientation styles are eulerAngles (constant EULER_ANGLES), axisAngle (constant AXIS_ANGLE), and quaternion (constant QUATERNION). For additional information on the different orientation style, see the geom.Orientation3D object.

transformVector(v)

Uses the transformation matrix to transform a Vector3D object from one space coordinate to another.

v - A Vector3D object holding the coordinates that are going to be transformed.

transformVectors(vin, vout)

Uses the transformation matrix to transform a Vector of Numbers from one coordinate space to another.

vin - A Vector array of Numbers, where every three Numbers are a 3D coordinate (x,y,z) that is going to be transformed.

vout - A Vector array of Numbers, where every three Numbers are a 3D transformed coordinate (x,y,z).

transpose()

Converts the current Matrix3D object to a matrix where the rows and columns are swapped.

Created with the Personal Edition of HelpNDoc: Easily create EPub books