ts-matrix is a collection of vector, matrix and quaternion classes written in Typescript with no dependencies.
Using npm or yarn
npm install --save ts-matrix
yarn add ts-matrixOr add the unpkg cdn link to your html
<script src="https://unpkg.com/ts-matrix">The library is built as an ECMAScript module (.mjs file), but it also exports a UMD version if needed.
Import the module, from Typescript or ES6 javascript.
import { Vector, Matrix, Quat, EPSILON } from 'ts-matrix';Then use the methods as you want :)
const v1 = new Vector([1, 2]);
const v2 = new Vector([3, 1]);
v1.add(v2);
// ==> [4, 3]Vector, Matrix and Quat are all immutable: every arithmetic operation returns a new instance rather than mutating the receiver (the only exceptions are the explicitly in-place helpers reset(), setAsIdentity()/setIdentity()).
If you use typescript, the declarations files are available with self documentation.
Instance methods
| method | description |
|---|---|
| at(row: number) | Get the value of a cell |
| rows | Returns Vector's size |
| values | Returns Vector values as an array |
| indexOf(value: number) | Returns the index of the value within the Vector, or -1 if it's not found. |
| reset() | Sets all vector values to 0, in place |
| addValues(count?: number) | Add zero values to the Vector (default: 1). Returns a new instance. |
| copy() | Returns a new vector with the same values |
| equals(vector: Vector, threshold?: number) | Checks equality between two vectors, optionally within a threshold (default: 0, i.e. exact equality) |
| negate() | Negates the Vector (change all cells arithmetic sign). Returns a new instance. |
| length() | Returns the vectors length |
| squaredLength() | Returns the vectors squared length |
| add(vector: Vector) | Adds all given values to the current Vector instance. Both vectors must have the same dimension. Returns a new instance. |
| subtract(vector: Vector) | Subtracts all given values to the current Vector instance. Both vectors must have the same dimension. Returns a new instance. |
| multiply(vector: Vector) | Multiplies all given values to the current Vector instance. Both vectors must have the same dimension. Returns a new instance. |
| divide(vector: Vector) | Divides all given values to the current Vector instance. Both vectors must have the same dimension. Returns a new instance. |
| multiplyMatrix(matrix: Matrix) | Computes the product of this vector (as a row vector) with a matrix. Returns a new instance. |
| scale(scale: number) | Multiply all vector values by the given scale. |
| normalize() | Computes the normalized Vector. Returns a zero vector if this vector has a length of 0. |
| dot(vector: Vector) | Computes the dot product between two Vectors. |
| cross(vector: Vector) | Computes the cross product between two Vectors. Returns new instance |
| mix(vector: Vector, time: number) | Computes the mix product between two Vectors. Returns new instance |
| angle(vector: Vector) | Returns the angle between two Vectors between 0 and +π inclusive |
| distance(vector: Vector) | Returns the distance (absolute value) between two Vectors |
| min() | Returns the lowest value from the Vector |
| max() | Returns the highest value from the Vector |
| round() | Rounds all vector values to the nearest integer |
| toString() | Returns a visual representation of the Vector as a string |
Static methods
| method | description |
|---|---|
| signedAngle(VectorA: Vector, VectorB: Vector) | Compute the signed angle in radians between two 3D Vectors, in the range -π to +π |
Instance methods
| method | description |
|---|---|
| at(row: number, col: number) | Get the value of a cell |
| rows | Returns the number of rows |
| columns | Returns the number of columns |
| values | Returns matrix values as a bi-dimentional array |
| indexOf(value: number) | Returns the position - as a tuple - of the value within the Matrix, or [-1, -1] if it's not found. |
| reset() | Sets all matrix values to 0, in place |
| copy() | Returns a new matrix with the same values |
| addColumns(count?: number) | Add empty columns to the Matrix (default: 1). Returns a new instance. |
| addRows(count?: number) | Add empty rows to the Matrix (default: 1). Returns a new instance. |
| equals(matrix: Matrix, threshold?: number) | Checks equality between two matrices, optionally within a threshold (default: 0, i.e. exact equality) |
| setIdentity() | Fills a squared matrix with the identity values (diagonal 1), in place |
| add(matrix: Matrix) | Adds two matrices. Both must have the same dimensions. Returns a new instance. |
| subtract(matrix: Matrix) | Subtracts two matrices. Both must have the same dimensions. Returns a new instance. |
| scale(scale: number) | Multiply all matrix values by the given scale. Returns a new instance. |
| multiply(matrix: Matrix) | Multiply two matrices. Returns a new instance. |
| multiplyVector(vector: Vector) | Computes the product of this matrix with a vector. Returns a new instance. |
| determinant() | Compute the determinant of the matrix. |
| trace() | Compute the sum of the diagonal values. Throws if the matrix isn't squared. |
| cofactor(row: number, col: number) | Compute the cofactor of the matrix. Returns a new instance. |
| transpose() | Transpose the matrix. Returns a new instance. |
| inverse() | Inverse the matrix. Returns a new instance. Throws if the matrix isn't squared, or is singular. |
| min() | Returns the lowest value from the Matrix |
| max() | Returns the highest value from the Matrix |
| round() | Rounds all matrix values to the nearest integer |
| toString() | Returns a visual representation of the Matrix as a string |
Static methods
| method | description |
|---|---|
| identity(dimension: number) | Returns a new squared identity Matrix |
| fromArray(values: number[], rows: number, columns: number) | Builds a new Matrix from a flat, row-major array of values |
Quat represents a rotation in 3D space as [x, y, z, w], and follows the same immutability convention as Vector and Matrix.
Instance methods
| method | description |
|---|---|
| at(index: number) | Get the value at index 0-3 |
| values | Returns the quaternion values as an array [x, y, z, w] |
| x, y, z, w | The individual components |
| xy, xyz, xyzw | Tuples of the first 2, 3, or all 4 components |
| reset() | Sets all quaternion values to 0, in place |
| copy() | Returns a new quaternion with the same values |
| equals(quat: Quat, threshold?: number) | Checks equality between two quaternions within a threshold (defaults to EPSILON) |
| setIdentity() | Sets this quaternion to the identity rotation, in place |
| calculateW() | Computes w from x, y, z, assuming a unit quaternion. Returns a new instance. |
| inverse() | Computes the inverse of the quaternion. Returns a new instance. |
| conjugate() | Computes the conjugate of the quaternion. Returns a new instance. |
| length() | Returns the magnitude of the quaternion |
| normalize() | Computes the normalized quaternion. Returns a zero quaternion if this quaternion has a length of 0. |
| add(other: Quat) | Adds two quaternions. Returns a new instance. |
| multiply(other: Quat) | Computes the Hamilton product of two quaternions. Returns a new instance. |
| roll() | Rotation angle around the x-axis, in radians |
| pitch() | Rotation angle around the y-axis, in radians |
| yaw() | Rotation angle around the z-axis, in radians |
| toString() | Returns a visual representation of the quaternion as a string |
Static methods
| method | description |
|---|---|
| identity() | Returns a new identity quaternion |
| dot(q1: Quat, q2: Quat) | Computes the dot product of two quaternions |
| sum(q1: Quat, q2: Quat) | Computes the sum of two quaternions |
| product(q1: Quat, q2: Quat) | Computes the Hamilton product of two quaternions |
| cross(q1: Quat, q2: Quat) | Computes (q1 * q2 - q2 * q1) / 2, which reduces to the vector cross product of q1 and q2's [x, y, z] parts when both have a 0 w |
| mix(q1: Quat, q2: Quat, time: number) | Spherical linear interpolation (slerp) between two quaternions |
| shortMix(q1: Quat, q2: Quat, time: number) | Slerp between two quaternions, always taking the shortest path around the hypersphere |
| fromAxisAngle(axis: Vector, angle: number) | Builds a quaternion representing a rotation of angle radians around a 3D axis |
Any contribution is welcome, whether it is an issue, PullRequest, or just a comment!
Made with love by Florent Catiau-Tristant (@kapcash)
