Namespace: matrix

matrix

Module ID: shellfish/core/matrix

This module provides the Shellfish matrix toolbox for linear algebra, which is useful when working with coordinates in a 2D or 3D space.

Examples

Importing in JavaScript

shRequire("shellfish/core/matrix", mat =>
{
    ...
});

Importing in Shui

require "shellfish/core/matrix" as mat;

Object {
    ...
}

Methods

matrix.add (a, b)matrix.Matrix static matrix.js:259

Returns the result of the addition of two matrices or of a matrix with a scalar.

Name	Type	Description
`a`	matrix.Matrix	The matrix.
`b`	matrix.Matrix \| number	A matrix or a scalar.

Throws:

Throws an error if the two matrices are of different dimensions.

Returns:

Type	Description
matrix.Matrix	The resulting matrix.

matrix.det (m)number static matrix.js:408

Returns the determinant of the given matrix. The determinant is only defined for square matrices.

Name	Type	Description
`m`	matrix.Matrix	The matrix.

Throws:

Throws an error if the matrix is not square.

Returns:

Type	Description
number	The determinant.

matrix.dot (u, v)number static matrix.js:312

Returns the dot product of two column-vectors. Both vectors must have the same dimensions.

Name	Type	Description
`u`	matrix.Matrix	The first vector.
`v`	matrix.Matrix	The second vector.

Throws:

Throws an error if the two vectors are no column-vectors or are of different dimensions.

Returns:

Type	Description
number	The dot product.

matrix.elementWise (m, n, op)matrix.Matrix static matrix.js:98

Performs an element-wise operator with a scalar on a matrix.

The element-wise operators PLUS, MINUS, and MULTIPLY are available as predefined functions in the matrix module.

Name	Type	Description
`m`	matrix.Matrix	The matrix.
`n`	number	The scalar.
`op`	function	The element-wise operator.

Returns:

Type	Description
matrix.Matrix	The resulting matrix.

matrix.flat (m)Array.<number> static matrix.js:188

Produces a flat representation of a matrix in row-major order.

Name	Type	Description
`m`	matrix.Matrix	The matrix to flatten.

Returns:

Type	Description
Array.<number>	The flat representation.

matrix.fromArray (arr, cols)matrix.Matrix static matrix.js:162

Creates a matrix from an array, given in row-major order.

Name	Type	Description
`arr`	Array.<number>	The array of values in row-major order.
`cols`	number	The amount of columns.

Returns:

Type	Description
matrix.Matrix	The matrix.

matrix.identityM (dim)matrix.Matrix static matrix.js:493

Creates the identity matrix for the given dimension.

Name	Type	Description
`dim`	number	The dimension of the matrix.

Returns:

Type	Description
matrix.Matrix	The identity matrix.

matrix.inv (m)matrix.Matrix static matrix.js:441

Returns the inverse of the given matrix. Only square matrices with a determinant != 0 have an inverse.

Name	Type	Description
`m`	matrix.Matrix	The matrix.

Throws:

Throws an error if the matrix has no inverse.

Returns:

Type	Description
matrix.Matrix	The inverse of the matrix.

matrix.length (v)number static matrix.js:212

Returns the length of the given column-vector.

Name	Type	Description
`v`	matrix.Matrix	The vector.

Throws:

Throws an error if the matrix is not a vector.

Returns:

Type	Description
number	The length of the vector.

matrix.minor (m, row, col)matrix.Matrix static matrix.js:383

Returns the minor of a matrix at the given row and column.

Name	Type	Description
`m`	matrix.Matrix	The matrix.
`row`	number	The row for computing the minor.
`col`	number	The column for computing the minor.

Returns:

Type	Description
matrix.Matrix	The minor.

matrix.mul (a, b)matrix.Matrix static matrix.js:341

Returns the result of the mulitplication of two matrices, or of a matrix with a scalar.

Name	Type	Description
`a`	matrix.Matrix	The first matrix.
`b`	matrix.Matrix \| number	The second matrix or a scalar.

Throws:

Throws an error if the two matrices are of different dimensions.

Returns:

Type	Description
matrix.Matrix	The resulting matrix.

matrix.perspectiveM (distance)matrix.Matrix static matrix.js:639

Creates a 3D to 2D perspective projection matrix.

Name	Type	Description
`distance`	number	The viewer's distance to the screen.

Returns:

Type	Description
matrix.Matrix	The perspective projection matrix.

matrix.rotationM (u, v, angle)matrix.Matrix static matrix.js:541

Creates the rotation matrix for rotating around two orthogonal vectors.

Name	Type	Description
`u`	matrix.Matrix	The first vector.
`v`	matrix.Matrix	The second vector.
`angle`	number	The rotation angle in degrees.

Returns:

Type	Description
matrix.Matrix	The rotation matrix.

matrix.rotationMByQuaternion (u, v, angle)matrix.Matrix static matrix.js:611

Creates the rotation matrix for rotating by a quaternion (a four-dimensional complex number expressing a rotation in 3D space). Quaternion-rotations do not induce a gimbal-lock.

Name	Type	Description
`u`	matrix.Matrix	The first vector.
`v`	matrix.Matrix	The second vector.
`angle`	number	The rotation angle in degrees.

Returns:

Type	Description
matrix.Matrix	The rotation matrix.

matrix.scalingM (vec)matrix.Matrix static matrix.js:587

Creates the scaling matrix for scaling by the given vector.

Name	Type	Description
`vec`	matrix.Matrix	The scaling vector.

Returns:

Type	Description
matrix.Matrix	The scaling matrix.

matrix.shape (m)object static matrix.js:77

Returns the shape as { rows, cols } of the given matrix.

Name	Type	Description
`m`	matrix.Matrix	The matrix.

Returns:

Type	Description
object	The object describing the shape.

matrix.sub (a, b)matrix.Matrix static matrix.js:295

Returns the result of the subtraction of two matrices or of a matrix with a scalar.

Name	Type	Description
`a`	matrix.Matrix	The matrix.
`b`	matrix.Matrix \| number	A matrix or a scalar.

Returns:

Type	Description
matrix.Matrix	The resulting matrix.

matrix.t (m)matrix.Matrix static matrix.js:233

Returns the transpose of the given matrix. Transposing a column-vector creates a row-vector and vice versa.

Name	Type	Description
`m`	matrix.Matrix	The matrix to transpose.

Returns:

Type	Description
matrix.Matrix	The transpose of the matrix.

matrix.translationM (vec)matrix.Matrix static matrix.js:518

Creates the translation matrix for the given translation vector. The dimension of the translation matrix is one higher than of the vector.

Name	Type	Description
`vec`	matrix.Matrix	The translation vector.

Returns:

Type	Description
matrix.Matrix	The translation matrix.

matrix.vec (values)matrix.Matrix static matrix.js:122

Creates a column-vector of the given values.

Name	Type	Description
`values`	number	repeatable The values.

Returns:

Type	Description
matrix.Matrix	The vector (a (n x 1) matrix).

Type Definitions

matrix.Matrix Array.<Array.<number>>

Type for a (n x m) matrix. A vector is a special form of the matrix with one column or one row.

The matrix is defined in row-major order:

| 1 2 3 |
| 4 5 6 | ~ [1, 2, 3, 4, 5, 6, 7, 8, 9]
| 7 8 9 |