Skip to main content

Matrix4

A class representing a 4x4 matrix.

The most common use of a 4x4 matrix in 3D computer graphics is as a Transformation Matrix. For an introduction to transformation matrices as used in WebGL, check out this tutorial.

This allows a Vector3 representing a point in 3D space to undergo transformations such as translation, rotation, shear, scale, reflection, orthogonal or perspective projection and so on, by being multiplied by the matrix. This is known as applying the matrix to the vector.

Every Object3D has three associated Matrix4s:

  • Object3D.matrix: This stores the local transform of the object. This is the object's transformation relative to its parent.
  • Object3D.matrixWorld: The global or world transform of the object. If the object has no parent, then this is identical to the local transform stored in matrix.
  • Object3D.modelViewMatrix: This represents the object's transformation relative to the camera's coordinate system. An object's modelViewMatrix is the object's matrixWorld pre-multiplied by the camera's matrixWorldInverse.

Cameras have three additional Matrix4s:

Note: Object3D.normalMatrix is not a Matrix4, but a Matrix3.

A Note on Row-Major and Column-Major Ordering​

The constructor and set() method take arguments in row-major order, while internally they are stored in the .elements array in column-major order.

This means that calling

const m = new THREE.Matrix4(); m.set( 11, 12, 13, 14, 21, 22, 23, 24, 31, 32,
33, 34, 41, 42, 43, 44 );

will result in the .elements array containing:

m.elements = [ 11, 21, 31, 41, 12, 22, 32, 42, 13, 23, 33, 43, 14, 24, 34, 44
];

and internally all calculations are performed using column-major ordering. However, as the actual ordering makes no difference mathematically and most people are used to thinking about matrices in row-major order, the three.js documentation shows matrices in row-major order. Just bear in mind that if you are reading the source code, you'll have to take the transpose of any matrices outlined here to make sense of the calculations.

Extracting position, rotation and scale​

There are several options available for extracting position, rotation and scale from a Matrix4.

Constructor​

Matrix4​

function Matrix4( n11: Number, n12: Number, n13: Number, n14: Number, n21:
Number, n22: Number, n23: Number, n24: Number, n31: Number, n32: Number, n33:
Number, n34: Number, n41: Number, n42: Number, n43: Number, n44: Number ):
void;

Creates a 4x4 matrix with the given arguments in row-major order. If no arguments are provided, the constructor initializes the Matrix4 to the 4x4 identity matrix.

Properties​

elements​

elements: Array;

A column-major list of matrix values.

Methods​

clone​

function clone( ): Matrix4;

Creates a new Matrix4 with identical .elements to this one.

compose​

function compose( position: Vector3, quaternion: Quaternion, scale: Vector3 ):
this;

Sets this matrix to the transformation composed of position, quaternion and scale.

copy​

function copy( m: Matrix4 ): this;

Copies the .elements of matrix .atrix4 into this matrix.

copyPosition​

function copyPosition( m: Matrix4 ): this;

Copies the translation component of the supplied matrix m into this matrix's translation component.

decompose​

function decompose( position: Vector3, quaternion: Quaternion, scale: Vector3
): this;

Decomposes this matrix into its position, quaternion and scale components.

Note: Not all matrices are decomposable in this way. For example, if an object has a non-uniformly scaled parent, then the object's world matrix may not be decomposable, and this method may not be appropriate.

determinant​

function determinant( ): Float;

Computes and returns the determinant of this matrix.

Based on the method outlined here.

equals​

function equals( m: Matrix4 ): Boolean;

Return true if this matrix and m are equal.

extractBasis​

function extractBasis( xAxis: Vector3, yAxis: Vector3, zAxis: Vector3 ): this;

Extracts the basis of this matrix into the three axis vectors provided. If this matrix is:

a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p

then the xAxis, yAxis, zAxis will be set to:

xAxis = (a, e, i) yAxis = (b, f, j) zAxis = (c, g, k)

extractRotation​

function extractRotation( m: Matrix4 ): this;

Extracts the rotation component of the supplied matrix m into this matrix's rotation component.

fromArray​

function fromArray( array: Array, offset: Integer ): this;

array - the array to read the elements from.
offset - ( optional ) offset into the array. Default is 0.

Sets the elements of this matrix based on an array in column-major format.

invert​

function invert( ): this;

Inverts this matrix, using the analytic method. You can not invert with a determinant of zero. If you attempt this, the method produces a zero matrix instead.

getMaxScaleOnAxis​

function getMaxScaleOnAxis( ): Float;

Gets the maximum scale value of the 3 axes.

identity​

function identity( ): this;

Resets this matrix to the identity matrix.

lookAt​

function lookAt( eye: Vector3, target: Vector3, up: Vector3 ): this;

Constructs a rotation matrix, looking from eye towards target oriented by the up vector.

makeRotationAxis​

function makeRotationAxis( axis: Vector3, theta: Float ): this;

axis — Rotation axis, should be normalized.
theta — Rotation angle in radians.

Sets this matrix as rotation transform around axis by theta radians.
This is a somewhat controversial but mathematically sound alternative to rotating via Quaternions. See the discussion here.

makeBasis​

function makeBasis( xAxis: Vector3, yAxis: Vector3, zAxis: Vector3 ): this;

Set this to the basis matrix consisting of the three provided basis vectors:

xAxis.x, yAxis.x, zAxis.x, 0, xAxis.y, yAxis.y, zAxis.y, 0, xAxis.z, yAxis.z,
zAxis.z, 0, 0, 0, 0, 1

makePerspective​

function makePerspective( left: Float, right: Float, top: Float, bottom:
Float, near: Float, far: Float ): this;

Creates a perspective projection matrix. This is used internally by PerspectiveCamera.updateProjectionMatrix()

makeOrthographic​

function makeOrthographic( left: Float, right: Float, top: Float, bottom:
Float, near: Float, far: Float ): this;

Creates an orthographic projection matrix. This is used internally by OrthographicCamera.updateProjectionMatrix().

makeRotationFromEuler​

function makeRotationFromEuler( euler: Euler ): this;

Sets the rotation component (the upper left 3x3 matrix) of this matrix to the rotation specified by the given Euler Angle. The rest of the matrix is set to the identity. Depending on the order of the euler, there are six possible outcomes. See this page for a complete list.

makeRotationFromQuaternion​

function makeRotationFromQuaternion( q: Quaternion ): this;

Sets the rotation component of this matrix to the rotation specified by q, as outlined here. The rest of the matrix is set to the identity. So, given q = w + xi + yj + zk, the resulting matrix will be:

1-2y²-2z² 2xy-2zw 2xz+2yw 0 2xy+2zw 1-2x²-2z² 2yz-2xw 0 2xz-2yw 2yz+2xw
1-2x²-2y² 0 0 0 0 1

makeRotationX​

function makeRotationX( theta: Float ): this;

theta — Rotation angle in radians.

Sets this matrix as a rotational transformation around the X axis by theta (θ) radians. The resulting matrix will be:

1 0 0 0 0 cos(θ) -sin(θ) 0 0 sin(θ) cos(θ) 0 0 0 0 1

makeRotationY​

function makeRotationY( theta: Float ): this;

theta — Rotation angle in radians.

Sets this matrix as a rotational transformation around the Y axis by theta (θ) radians. The resulting matrix will be:

cos(θ) 0 sin(θ) 0 0 1 0 0 -sin(θ) 0 cos(θ) 0 0 0 0 1

makeRotationZ​

function makeRotationZ( theta: Float ): this;

theta — Rotation angle in radians.

Sets this matrix as a rotational transformation around the Z axis by theta (θ) radians. The resulting matrix will be:

cos(θ) -sin(θ) 0 0 sin(θ) cos(θ) 0 0 0 0 1 0 0 0 0 1

makeScale​

function makeScale( x: Float, y: Float, z: Float ): this;

x - the amount to scale in the X axis.
y - the amount to scale in the Y axis.
z - the amount to scale in the Z axis.

Sets this matrix as scale transform:

x, 0, 0, 0, 0, y, 0, 0, 0, 0, z, 0, 0, 0, 0, 1

makeShear​

function makeShear( xy: Float, xz: Float, yx: Float, yz: Float, zx: Float, zy:
Float ): this;

xy - the amount to shear X by Y.
xz - the amount to shear X by Z.
yx - the amount to shear Y by X.
yz - the amount to shear Y by Z.
zx - the amount to shear Z by X.
zy - the amount to shear Z by Y.

Sets this matrix as a shear transform:

1, yx, zx, 0, xy, 1, zy, 0, xz, yz, 1, 0, 0, 0, 0, 1

makeTranslation​

function makeTranslation( v: Vector3 ): this;

makeTranslation​

function makeTranslation( x: Float, y: Float, z: Float ): this;

Sets this matrix as a translation transform from vector v, or numbers x, y and z:

1, 0, 0, x, 0, 1, 0, y, 0, 0, 1, z, 0, 0, 0, 1

multiply​

function multiply( m: Matrix4 ): this;

Post-multiplies this matrix by m.

multiplyMatrices​

function multiplyMatrices( a: Matrix4, b: Matrix4 ): this;

Sets this matrix to a x b.

multiplyScalar​

function multiplyScalar( s: Float ): this;

Multiplies every component of the matrix by a scalar value s.

premultiply​

function premultiply( m: Matrix4 ): this;

Pre-multiplies this matrix by m.

scale​

function scale( v: Vector3 ): this;

Multiplies the columns of this matrix by vector v.

set​

function set( n11: Float, n12: Float, n13: Float, n14: Float, n21: Float, n22:
Float, n23: Float, n24: Float, n31: Float, n32: Float, n33: Float, n34: Float,
n41: Float, n42: Float, n43: Float, n44: Float ): this;

Set the .elements of this matrix to the supplied row-major values .loat, .loat, ... .loat.

setFromMatrix3​

function setFromMatrix3( m: Matrix3 ): this;

Set the upper 3x3 elements of this matrix to the values of the Matrix3 m.

setPosition​

function setPosition( v: Vector3 ): this;

setPosition​

function setPosition( x: Float, y: Float, z: Float ): this;

Sets the position component for this matrix from vector v, without affecting the rest of the matrix - i.e. if the matrix is currently:

a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p

This becomes:

a, b, c, v.x, e, f, g, v.y, i, j, k, v.z, m, n, o, p

toArray​

function toArray( array: Array, offset: Integer ): Array;

array - (optional) array to store the resulting vector in.
offset - (optional) offset in the array at which to put the result.

Writes the elements of this matrix to an array in column-major format.

transpose​

function transpose( ): this;

Transposes this matrix.

Source​

src/math/Matrix4.js