# 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 | | 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

### Methods

##### Parameters:
Name Type Description
`rhs`

Matrix or scalar on the right-hand side.

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`

orthogonal 3x3 matrix

`scale`

NOTE: the component in scale cannot be 0

`scaleRotation`

orthogonal 3x3 matrix

#### copy(rhs) → {Matrix3}

Copies component values and stores them locally.

##### Parameters:
Name Type Description
`rhs`

Source matrix.

#### copyMatrix4(rhs) → {Matrix3}

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

##### Parameters:
Name Type Description
`rhs`

Source matrix.

#### copyQuaternion(quaternion) → {Matrix3}

Sets the matrix from a quaternion.

##### Parameters:
Name Type Description
`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`

matrix store

`scale`

vector store

`scaleRotation`

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`

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

`theta` number

`phi` number

##### 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`

Direction vector.

`up`

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`

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`

Matrix on the left-hand side

`rhs`

Matrix on the right-hand side

#### multiplyDiagonalPost(vec, result) → {Matrix3}

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

##### Parameters:
Name Type Description
`vec`

Vector on the right-hand side.

`result`

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>

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` <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);``

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` <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);``

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` <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`

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 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`

Source matrix.

`target` <optional>

Target matrix.