Matrix3

Matrix3

Matrix with 3x3 components. Used to store 3D rotations. It also contains common 3D Rotation operations.

Constructor

new Matrix3(…args)

Creates a new Matrix3 by passing in either a current Matrix3, number Array, or a set of 9 numbers.

Parameters:
Name Type Attributes Description
args number | Matrix3 | Array.<number> <repeatable>

Initial values for the components.

Members

mul2

Deprecated:
  • Deprecated as of 0.23.x Multiplies the matrix's values with another matrix's values; an alias for .mult

set

Sets the matrix's values from another matrix's values; an alias for .copy

(static) IDENTITY :Matrix3

Methods

add(rhs) → {Matrix3}

Performs a component-wise addition.

Parameters:
Name Type Description
rhs Matrix3

Matrix or scalar on the right-hand side.

adjugateNormSquared() → {number}

Compute the adjugate L2 norm squared value of the matrix

clone() → {Matrix3}

Returns a new matrix with the same values as the existing one.

compose(rotation, scale, scaleRotation) → {Matrix3}

Compose 3x3 matrix from rotation, scale and scaleRotation
A = RS = RVD(V.transpose) = U(V.transpose())VD(V.transpose())
rotation = R = U(V.transpose())
symmetricMatrix = S = VD(V.transpose())
scaleMatrix = D
scaleRotation = V
NOTE: the component in scale cannot be 0 based on the current algorithm

Parameters:
Name Type Description
rotation Matrix3

orthogonal 3x3 matrix

scale Vector3

NOTE: the component in scale cannot be 0

scaleRotation Matrix3

orthogonal 3x3 matrix

copy(rhs) → {Matrix3}

Copies component values and stores them locally.

Parameters:
Name Type Description
rhs Matrix3

Source matrix.

copyMatrix4(rhs) → {Matrix3}

Copies component values from the upper-left submatrix of a Matrix4.

Parameters:
Name Type Description
rhs Matrix4

Source matrix.

copyQuaternion(quaternion) → {Matrix3}

Sets the matrix from a quaternion.

Parameters:
Name Type Description
quaternion Quaternion

Rotational quaternion.

decompose(rotation, scale, scaleRotation, sortScaleopt) → {Matrix3}

Decompose 3x3 matrix to rotation, scale and scaleRotation
Use Polar decomposition and SVD decomposition
Vt = V.transpose()
A = RS = RVD(Vt) = U(Vt)VD(Vt)

  • rotation(R) = U(Vt)
  • symmetricMatrix(S) = VD(Vt)
  • scaleMatrix(D)
  • scaleRotation(V)
    NOTE: the component in scale cannot be 0 based on the current algorithm
Parameters:
Name Type Attributes Default Description
rotation Matrix3

matrix store

scale Vector3

vector store

scaleRotation Matrix3

matrix store

sortScale boolean <optional>
false

Sort the scale vector or not. If sortScale = true, the scale will be sorted in descent order, as well as rotation and scaleRotation

determinant() → {number}

Computes the determinant of the matrix.

equals(rhs) → {boolean}

Compares two matrices for approximate equality

Parameters:
Name Type Description
rhs Matrix3

The matrix to compare against

fromAngleNormalAxis(angle, x, y, z) → {Matrix3}

Sets this matrix to the rotation indicated by the given angle and a unit-length axis of rotation.

Parameters:
Name Type Description
angle number

the angle to rotate (in radians).

x number

X component of the normalized axis of rotation

y number

Y component of the normalized axis of rotation

z number

Z component of the normalized axis of rotation

fromAngles(psi, theta, phi) → {Matrix3}

Sets the Matrix3 from rotational angles in radians.
Order: YZX

Parameters:
Name Type Description
psi number

Psi angle in radians (roll).

theta number

Theta angle in radians (yaw).

phi number

Phi angle in radians (pitch).

Example
// sets the rotation to Math.PI (180 degrees) on the Y axis
entity.transformComponent.transform.rotation.fromAngles(0, Math.PI, 0);

invert() → {Matrix3}

Computes the analytical inverse and stores the result locally.

isDecomposable() → {boolean}

Check if the matrix is decomposable

isNormal() → {boolean}

Tests if the matrix is normal.

isOrthogonal() → {boolean}

Tests if the matrix is orthogonal.

isOrthonormal() → {boolean}

Tests if the matrix is orthonormal.

isUniformScaled(scale3, det) → {boolean}

Check if this matrix can be decomposed to uniform scale (scale vector's components equal to each other)

Parameters:
Name Type Description
scale3 number

Optional,pre-calculate value

det number

Optional,pre-calculate value

lookAt(direction, up) → {Matrix3}

Sets the Matrix3 to look in a specific direction.

Parameters:
Name Type Description
direction Vector3

Direction vector.

up Vector3

Up vector.

Example
// get the direction from the current entity to the 'other' entity
var direction = Vector3.sub(other.transformComponent.transform.translation,
entity.transformComponent.transform.translation);
// pass in the direction, and use Vector3.UNIT_Y as 'up'
entity.lookAt(direction, Vector3.UNIT_Y);
// update the transform component with the new rotation
entity.transformComponent.setUpdated();

mul(lhs) → {Matrix3}

Parameters:
Name Type Description
lhs Matrix3

Matrix on the left-hand side

Deprecated:
  • Use Matrix3.mult instead. Multiplies this matrix with another matrix

mult(lhs, rhs) → {Matrix3}

Multiplies two matrices and stores the result in this matrix

Parameters:
Name Type Description
lhs Matrix3

Matrix on the left-hand side

rhs Matrix3

Matrix on the right-hand side

multiplyDiagonalPost(vec, result) → {Matrix3}

Post-multiplies the matrix ("before") with a scaling vector.

Parameters:
Name Type Description
vec Vector3

Vector on the right-hand side.

result Matrix3

Storage matrix.

normSquared() → {number}

Compute the Frobenius norm squared value of the matrix
http://mathworld.wolfram.com/FrobeniusNorm.html

orthogonalize(iterationsopt, epsilonopt)

Orthogonalize the matrix until it is orthogonal OR it exceed the precision requirement OR it reach the iteration limit
NOTE: if mat3 is too far from orthogonal and have scale that is too far away from 1 it will make things faster
if mat3 first brought up to a scale of 1 first.

Parameters:
Name Type Attributes Default Description
iterations Number <optional>
5

the max iteration the function may have.

epsilon Number <optional>
Matrix3.FLOAT32_EPSILON

the epsilon for the precision check

permutateColumn(order) → {Matrix3}

Permutate the column of the matrix based on the order provided
For ex, order = [2, 1, 0]
the matrix will be converted as below
row1: [d00, d01, d02] => [d02, d01, d00]
row2: [d10, d11, d12] => [d12, d11, d10]
row3: [d20, d21, d22] => [d22, d21, d20]

Parameters:
Name Type Description
order Array.<Number>

rotateX(rad, storeopt) → {Matrix3}

Rotates a Matrix3 by the given angle in radians, around the X axis.

Parameters:
Name Type Attributes Description
rad number

the angle in radians to rotate the Matrix3 by.

store Matrix3 <optional>

the target Matrix3 to store the result or 'this', if undefined.

Example

rotates the entity on the X axis, by the amount of time per frame (tpf)

entity.transformComponent.transform.rotation.rotateX(sumerian.world.tpf);

rotateY(rad, storeopt) → {Matrix3}

Rotates a Matrix3 by the given angle in radians, around the Y axis.

Parameters:
Name Type Attributes Description
rad number

the angle in radians to rotate the Matrix3 by.

store Matrix3 <optional>

the target Matrix3 to store the result or 'this', if undefined.

Example

rotates the entity on the Y axis, by Math.PI * 0.5 (90 degrees)

entity.transformComponent.transform.rotation.rotateY(Math.PI * 0.5);

rotateZ(rad, storeopt) → {Matrix3}

Rotates a Matrix3 by the given angle in radians, around the Z axis.

Parameters:
Name Type Attributes Description
rad number

the angle in radians to rotate the Matrix3 by.

store Matrix3 <optional>

the target Matrix3 to store the result or 'this', if undefined.

Example

rotates the entity on the Z axis, by 3.14 (180 degrees)

entity.transformComponent.transform.rotation.rotateZ(3.14);

scale(scalar) → {Matrix3}

Multiplies this matrix with a scalar

Parameters:
Name Type Description
scalar number

setArray(rhsData) → {Matrix3}

Sets matrix values from an array.

Parameters:
Name Type Description
rhsData Array.<number>

Array source

setIdentity() → {Matrix3}

Sets the matrix to identity: (1, 0, 0, 0, 1, 0, 0, 0, 1).

sub(rhs) → {Matrix3}

Performs a component-wise subtraction.

Parameters:
Name Type Description
rhs Matrix3

Matrix or scalar on the right-hand side.

toAngles(store) → {Vector3}

Converts the current Matrix3 to Euler rotation angles in radians: (X axis, Y axis, Z axis)
Order: YZX

Parameters:
Name Type Description
store Vector3

Vector3 to store the computed angles in (or undefined to create a new one).

Example
// Not passing in a Vector3 to store the result, one is created and returned
var rot = entity.transformComponent.transform.rotation.toAngles();

// Passing in an existing Vector3 to store the result
var angles = new Vector3();
entity.transformComponent.transform.rotation.toAngles(angles);

transpose() → {Matrix3}

Transposes a matrix (exchanges rows and columns) and stores the result in a separate matrix.

(static) invert(source, targetopt) → {Matrix3}

Computes the analytical inverse and stores the result in a separate matrix.

Parameters:
Name Type Attributes Description
source Matrix3

Source matrix.

target Matrix3 <optional>

Target matrix.