A 4x4 matrix. Any arguments to Matrix4
methods can be plain JavaScript arrays or other math.gl
objects.
import {Matrix4} from `math.gl`;
Copy a matrix to a Matrix4
so that it can be manipulated (and mutated) with Matrix4
methods:
const IDENTITY = [1, 0, ..., 1];
const m = new Matrix4(IDENTITY).translate([1, 0, 0]);
Create a perspective projection matrix
const projectionMatrix = new Matrix4().perspective({fov, aspect, near, far});
Create an orthograhic projection matrix
Invert a matrix
const inverse = matrix.invert();
Transform a vector as a point (including translations)
const transform = new Matrix4();
const vector2 = transform.transformPoint([0, 0]);
const vector3 = transform.transformPoint([0, 1, 2]);
const vector4 = transform.transformPoint([0, 1, 2, 1]);
Transform a vector as a direction (NOT including translations)
const transform = new Matrix4();
const vector2 = transform.transformDirection([0, 0]);
const vector3 = transform.transformDirection([0, 1, 2]);
const vector4 = transform.transformDirection([0, 1, 2, 1]);
class Matrix4 extends
Matrix
extends
MathArray
extends
Array
`
Many basic methods are inherited:
matrix4.clone()
matrix4.copy(array)
matrix4.set(...args)
matrix4.fromArray(array, offset = 0)
matrix4.toString()
matrix4.toArray(array = [], offset = 0)
matrix4.equals(array)
matrix4.exactEquals(array)
matrix4.validate(array = this)
matrix4.check(array = this)
matrix4.normalize()
Since Matrix4
is a subclass of the built in JavaScript Array
it can be used directly as a parameter to any function expecting an Array
.
Creates an empty Matrix4
new Matrix4()
Sets the matrix to the multiplicative identity matrix.
matrix4.identity()
Sets the elements of the matrix.
matrix4.set(m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31, m32, m33)
Sets the matrix to a transformation corresponding to the rotations represented by the given quaternion.
matrix4.fromQuaternion(quaternion)
quaternion
(Quaternion
) - the quaternion to create matrix fromGenerates a frustum matrix with the given bounds. The frustum far plane can be infinite.
matrix4.frustum({left, right, bottom, top, near, far})
left
(number
) - Left bound of the frustumright
(number
) - Right bound of the frustumbottom
(number
) - Bottom bound of the frustumtop
(number
) - Top bound of the frustumnear
(number
) - Near bound of the frustumfar
(number
|Infinity
) - Far bound of the frustumGenerates a look-at matrix with the given eye position, focal point, and up axis
matrix4.lookAt({eye, center, up})
eye
(Vector3
|number[3]
) - Position of the viewercenter
(=
) - 0, 0, 0] vec3 Point the viewer is looking atup
(=
) - 0, 1, 0] vec3 vec3 pointing upGenerates a orthogonal projection matrix with the given bounds
matrix4.ortho({left, right, bottom, top, near = 0.1, far = 500})
left
(number
) - Left bound of the frustumright
(number
) - Right bound of the frustumbottom
(number
) - Bottom bound of the frustumtop
(number
) - Top bound of the frustumnear
(number
) - Near bound of the frustumfar
(number
) - Far bound of the frustumGenerates an orthogonal projection matrix with the same parameters
as a perspective matrix (plus focalDistance
).
Matrix4.orthographic({fovy, aspect, focalDistance, near, far})
fovy
(number
) - Vertical field of view in radians
aspect
(number
) - Aspect ratio. typically viewport width/height
focalDistance
(number
) - selects which plane in the perspective view frustum should be used to calculate the size of the orthographic view box.
near
=0.1
(number
) - Near bound of the frustum
far
=500
(Nmber
) - Far bound of the frustum
In applications it is not unusual to want to offer both perspective and orthographic views and this method is supplied to make this as simple as possible.
Generates a perspective projection matrix with the given bounds. The frustum far plane can be infinite.
matrix4.perspective({ fovy = 45 * Math.PI - / 180, aspect = 1, near = 0.1, far = 500 })
fovy
=45
(number
) - Vertical field of view in radians (default is 45 degrees specified in radians)aspect
=1
(number
) - Aspect ratio. typically viewport width/heightnear
=0.1
(number
) - Near bound of the frustumfar
=500
(number
|Infinity
) - Far bound of the frustumReturns the determinant of the matrix (does not modify the matrix).
const determinant = matrix4.determinant()
Returns (number
) - the determinant
Sets this matrix to its transpose matrix.
matrix4.transpose()
Sets this matrix to its inverse matrix.
matrix4.invert()
Multiplies in another matrix from the left
matrix4.multiplyLeft(matrix4)
Matrix4
to transform vectors, the vectors are multiplied in from the right. This means that the multiplying in a matrix from the left will cause it to be applied last during transformation (unless additional matrices are multiplied in from the left of course).matrix4.multiplyRight(matrix4)
Matrix4
to transform vectors, the vectors are multiplied in from the right. This means that the multiplying in a matrix from the left will cause it to be applied last during transformation (unless additional matrices are multiplied in from the left of course).Adds a rotation by the given angle around the X axis. Equivalent to right multiplying the new transform into the matrix but more performant.
matrix4.rotateX(radians)
Adds a rotation by the given angle around the Y axis.
rotateY(radians)
Adds a rotation by the given angle around the Z axis.
matrix4.rotateZ(radians)
Adds successive rotations by the given angles around the X, Y and Z axis.
rotateXYZ([rx, ry, rz])
Adds successive rotations by the given angles around the X, Y and Z axis.
rotateAxis(radians, axis)
Equivalent to right multiplying the new transform into the matrix but more performant.
Adds a scaling transform, each axis can be scaled independently.
matrix4.scale(factor)
factor
(number) - scale factor to be applied to each axis.matrix4.scale([x, y, z])
x
(number) - scale factor to be multiplied into x componenty
(number) - scale factor to be multiplied into y componentz
(number) - scale factor to be multiplied into z componentEquivalent to right multiplying the new transform into the matrix but more performant.
-1
will flip the coordinate system in that axis.0
will drop that component.Adds a translation to the matrix.
matrix4.translate([x, y, z])
x
(number) - translation to be added to the x componenty
(number) - translation to be added to the y componentz
(number) - translation to be added to the z componentEquivalent to right multiplying the new transform into the matrix but more performant.
During vector transformation the given translation values are added to each component of the vector being transformed.
Returns a 4x4 rotation matrix.
Returns a 3x3 rotation matrix.
Returns the 3-element translation vector component of the affine transform described by the matrix.
For performance, an existing vector can be provided, if not a new vector will be returned.
Returns the 3-element scale vector component of the affine transform described by the matrix.
For performance, an existing vector can be provided, if not a new vector will be returned.
Transforms any 2, 3 or 4 element vector as a "point" by multiplying it (from the right) with this matrix. Point
here means that the returned vector will include any translations in this matrix.
const vector = matrix4.transformPoint(vector, out=)
vector
(Array
|Vector2
|Vector3
|Vector4
)
out
- unless supplied, will be a Vector2, Vector3 or Vector4, matching the length of input vector.
Returns out
, or a newly minted Vector2
, Vector3
or Vector4
If vector
is specified in homogeneous coordinates, w
coordinate must NOT be 0
.
If vector
is specified in homogeneous coordinates the returned vector will be w
adjusted, (i.e. w
coordinate will be 1
, even if the supplied vector was not normalized).
Transforms any 2, 3 or 4 element vector interpreted as a direction (i.e. all vectors are based in the origin so the transformation not pick up any translations from the matrix).
const vector = matrix4.transformDirection(vector, out)
vector
is specified in homogeneous coordinates, w
coordinate must be 0
.Matrix4
is stored internally in column major format (per WebGL conventions). This only matters when you read out the matrix to use it with other software.