@basementuniverse/vec

vec

A small vector and matrix library.

Includes 2d vectors, 3d vectors, and matrices of any size.

Vectors and matrices are generally immutable; operations will return new instances.

Installation

npm i @basementuniverse/vec

Usage

Node:

const { vec2, vec3, mat } = require('@basementuniverse/vec');

Browser:

<script src="vec.js"></script>

Typescript:

import { vec2, vec3, mat } from '@basementuniverse/vec';

Contents

• vec2
• vec3
• mat

Functions

vec2([x], [y]) ⇒ vec2

Create a new 2d vector

vec3([x], [y], [z]) ⇒ vec3

Create a new 3d vector

mat([m], [n], [entries]) ⇒ mat

Create a new matrix

Typedefs

vec2 : Object

A 2d vector

vec2MapCallback ⇒ number

A function to call on each component of a 2d vector

polarCoordinates2d : Object

Polar coordinates for a 2d vector

vec3 : Object

A 3d vector

vec3MapCallback ⇒ number

A function to call on each component of a 3d vector

polarCoordinates3d : Object

Polar coordinates for a 3d vector

mat : Object

A matrix

matrixMapCallback ⇒ number

A function to call on each entry of a matrix

vec2([x], [y]) ⇒ vec2

Create a new 2d vector

Kind: global function
Returns: vec2 - A new 2d vector

Param	Type	Description
[x]	number | vec2	The x component of the vector, or a vector to copy
[y]	number	The y component of the vector

Example (various ways to initialise a vector)

let a = vec2(3, 2); // (3, 2)
let b = vec2(4);    // (4, 4)
let c = vec2(a);    // (3, 2)
let d = vec2();     // (0, 0)

• vec2([x], [y]) ⇒ vec2
  • .components(a) ⇒ Array.<number>
  • .fromComponents(components) ⇒ vec2
  • .ux() ⇒ vec2
  • .uy() ⇒ vec2
  • .add(a, b) ⇒ vec2
  • .sub(a, b) ⇒ vec2
  • .mul(a, b) ⇒ vec2
  • .scale(a, b) ⇒ vec2
  • .div(a, b) ⇒ vec2
  • .len(a) ⇒ number
  • .manhattan(a) ⇒ number
  • .nor(a) ⇒ vec2
  • .dot(a, b) ⇒ number
  • .rot(a, r) ⇒ vec2
  • .rotf(a, r) ⇒ vec2
  • .eq(a, b) ⇒ boolean
  • .rad(a) ⇒ number
  • .cpy(a) ⇒ vec2
  • .map(a, f) ⇒ vec2
  • .str(a, [s]) ⇒ string
  • .swiz(a, [s]) ⇒ Array.<number>
  • .polar(a) ⇒ polarCoordinates2d
  • .fromPolar(r, theta) ⇒ vec2

vec2.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec2
Returns: Array.<number> - The vector components as an array

Param	Type	Description
a	vec2	The vector to get components from

vec2.fromComponents(components) ⇒ vec2

Create a vector from an array of components

Kind: static method of vec2
Returns: vec2 - A new vector

Param	Type	Description
components	Array.<number>	The components of the vector

vec2.ux() ⇒ vec2

Return a unit vector (1, 0)

Kind: static method of vec2
Returns: vec2 - A unit vector (1, 0)

vec2.uy() ⇒ vec2

Return a unit vector (0, 1)

Kind: static method of vec2
Returns: vec2 - A unit vector (0, 1)

vec2.add(a, b) ⇒ vec2

Add vectors

Kind: static method of vec2
Returns: vec2 - a + b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.sub(a, b) ⇒ vec2

Subtract vectors

Kind: static method of vec2
Returns: vec2 - a - b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.mul(a, b) ⇒ vec2

Scale a vector

Kind: static method of vec2
Returns: vec2 - a * b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.scale(a, b) ⇒ vec2

Scale a vector by a scalar, alias for vec2.mul

Kind: static method of vec2
Returns: vec2 - a * b

Param	Type	Description
a	vec2	Vector a
b	number	Scalar b

vec2.div(a, b) ⇒ vec2

Divide a vector

Kind: static method of vec2
Returns: vec2 - a / b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec2
Returns: number - |a|

Param	Type	Description
a	vec2	Vector a

vec2.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec2
Returns: number - |a|

Param	Type	Description
a	vec2	Vector a

vec2.nor(a) ⇒ vec2

Normalise a vector

Kind: static method of vec2
Returns: vec2 - ^a

Param	Type	Description
a	vec2	The vector to normalise

vec2.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec2
Returns: number - a ∙ b

Param	Type	Description
a	vec2	Vector a
b	vec2	Vector b

vec2.rot(a, r) ⇒ vec2

Rotate a vector by r radians

Kind: static method of vec2
Returns: vec2 - A rotated vector

Param	Type	Description
a	vec2	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec2.rotf(a, r) ⇒ vec2

Fast method to rotate a vector by -90, 90 or 180 degrees

Kind: static method of vec2
Returns: vec2 - A rotated vector

Param	Type	Description
a	vec2	The vector to rotate
r	number	1 for 90 degrees (cw), -1 for -90 degrees (ccw), 2 or -2 for 180 degrees

vec2.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec2
Returns: boolean - True if vectors a and b are equal, false otherwise

Param	Type	Description
a	vec2	Vector a
b	vec2	Vector b

vec2.rad(a) ⇒ number

Get the angle of a vector

Kind: static method of vec2
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec2	Vector a

vec2.cpy(a) ⇒ vec2

Copy a vector

Kind: static method of vec2
Returns: vec2 - A copy of vector a

Param	Type	Description
a	vec2	The vector to copy

vec2.map(a, f) ⇒ vec2

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec2
Returns: vec2 - Vector a mapped through f

Param	Type	Description
a	vec2	Vector a
f	vec2MapCallback	The function to call on each component of the vector

vec2.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec2
Returns: string - A string representation of the vector

Param	Type	Default	Description
a	vec2		The vector to convert
[s]	string	"', '"	The separator string

vec2.swiz(a, [s]) ⇒ Array.<number>

Swizzle a vector with a string of component labels

The string can contain:

• x or y
• u or v (aliases for x and y, respectively)
• X, Y, U, V (negated versions of the above)
• 0 or 1 (these will be passed through unchanged)
• . to return the component that would normally be at this position (or 0)

Any other characters will default to 0

Kind: static method of vec2
Returns: Array.<number> - The swizzled components

Param	Type	Default	Description
a	vec2		The vector to swizzle
[s]	string	"'..'"	The swizzle string

Example (swizzling a vector)

let a = vec2(3, -2);
vec2.swiz(a, 'x');    // [3]
vec2.swiz(a, 'yx');   // [-2, 3]
vec2.swiz(a, 'xY');   // [3, 2]
vec2.swiz(a, 'Yy');   // [2, -2]
vec2.swiz(a, 'x.x');  // [3, -2, 3]
vec2.swiz(a, 'y01x'); // [-2, 0, 1, 3]

vec2.polar(a) ⇒ polarCoordinates2d

Convert a vector into polar coordinates

Kind: static method of vec2
Returns: polarCoordinates2d - The magnitude and angle of the vector

Param	Type	Description
a	vec2	The vector to convert

vec2.fromPolar(r, theta) ⇒ vec2

Convert polar coordinates into a vector

Kind: static method of vec2
Returns: vec2 - A vector with the given angle and magnitude

Param	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The angle of the vector

vec3([x], [y], [z]) ⇒ vec3

Create a new 3d vector

Kind: global function
Returns: vec3 - A new 3d vector

Param	Type	Description
[x]	number | vec3 | vec2	The x component of the vector, or a vector to copy
[y]	number	The y component of the vector, or the z component if x is a vec2
[z]	number	The z component of the vector

Example (various ways to initialise a vector)

let a = vec3(3, 2, 1);       // (3, 2, 1)
let b = vec3(4, 5);          // (4, 5, 0)
let c = vec3(6);             // (6, 6, 6)
let d = vec3(a);             // (3, 2, 1)
let e = vec3();              // (0, 0, 0)
let f = vec3(vec2(1, 2), 3); // (1, 2, 3)
let g = vec3(vec2(4, 5));    // (4, 5, 0)

• vec3([x], [y], [z]) ⇒ vec3
  • .components(a) ⇒ Array.<number>
  • .fromComponents(components) ⇒ vec3
  • .ux() ⇒ vec3
  • .uy() ⇒ vec3
  • .uz() ⇒ vec3
  • .add(a, b) ⇒ vec3
  • .sub(a, b) ⇒ vec3
  • .mul(a, b) ⇒ vec3
  • .scale(a, b) ⇒ vec3
  • .div(a, b) ⇒ vec3
  • .len(a) ⇒ number
  • .manhattan(a) ⇒ number
  • .nor(a) ⇒ vec3
  • .dot(a, b) ⇒ number
  • .rot(a, m) ⇒ vec3
  • .rotx(a, r) ⇒ vec3
  • .roty(a, r) ⇒ vec3
  • .rotz(a, r) ⇒ vec3
  • .rotq(a, q) ⇒ vec3
  • .rota(a, e) ⇒ vec3
  • .cross(a, b) ⇒ vec3
  • .eq(a, b) ⇒ boolean
  • .radx(a) ⇒ number
  • .rady(a) ⇒ number
  • .radz(a) ⇒ number
  • .cpy(a) ⇒ vec3
  • .map(a, f) ⇒ vec3
  • .str(a, [s]) ⇒ string
  • .swiz(a, [s]) ⇒ Array.<number>
  • .polar(a) ⇒ polarCoordinates3d
  • .fromPolar(r, theta, phi) ⇒ vec3

vec3.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec3
Returns: Array.<number> - The vector components as an array

Param	Type	Description
a	vec3	The vector to get components from

vec3.fromComponents(components) ⇒ vec3

Create a vector from an array of components

Kind: static method of vec3
Returns: vec3 - A new vector

Param	Type	Description
components	Array.<number>	The components of the vector

vec3.ux() ⇒ vec3

Return a unit vector (1, 0, 0)

Kind: static method of vec3
Returns: vec3 - A unit vector (1, 0, 0)

vec3.uy() ⇒ vec3

Return a unit vector (0, 1, 0)

Kind: static method of vec3
Returns: vec3 - A unit vector (0, 1, 0)

vec3.uz() ⇒ vec3

Return a unit vector (0, 0, 1)

Kind: static method of vec3
Returns: vec3 - A unit vector (0, 0, 1)

vec3.add(a, b) ⇒ vec3

Add vectors

Kind: static method of vec3
Returns: vec3 - a + b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.sub(a, b) ⇒ vec3

Subtract vectors

Kind: static method of vec3
Returns: vec3 - a - b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.mul(a, b) ⇒ vec3

Scale a vector

Kind: static method of vec3
Returns: vec3 - a * b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.scale(a, b) ⇒ vec3

Scale a vector by a scalar, alias for vec3.mul

Kind: static method of vec3
Returns: vec3 - a * b

Param	Type	Description
a	vec3	Vector a
b	number	Scalar b

vec3.div(a, b) ⇒ vec3

Divide a vector

Kind: static method of vec3
Returns: vec3 - a / b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec3
Returns: number - |a|

Param	Type	Description
a	vec3	Vector a

vec3.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec3
Returns: number - |a|

Param	Type	Description
a	vec3	Vector a

vec3.nor(a) ⇒ vec3

Normalise a vector

Kind: static method of vec3
Returns: vec3 - ^a

Param	Type	Description
a	vec3	The vector to normalise

vec3.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec3
Returns: number - a ∙ b

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.rot(a, m) ⇒ vec3

Rotate a vector using a rotation matrix

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
m	mat	The rotation matrix

vec3.rotx(a, r) ⇒ vec3

Rotate a vector by r radians around the x axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.roty(a, r) ⇒ vec3

Rotate a vector by r radians around the y axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.rotz(a, r) ⇒ vec3

Rotate a vector by r radians around the z axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.rotq(a, q) ⇒ vec3

Rotate a vector using a quaternion

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
q	Array.<number>	The quaternion to rotate by

vec3.rota(a, e) ⇒ vec3

Rotate a vector using Euler angles

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
e	vec3	The Euler angles to rotate by

vec3.cross(a, b) ⇒ vec3

Get the cross product of vectors

Kind: static method of vec3
Returns: vec3 - a × b

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec3
Returns: boolean - True if vectors a and b are equal, false otherwise

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.radx(a) ⇒ number

Get the angle of a vector from the x axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.rady(a) ⇒ number

Get the angle of a vector from the y axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.radz(a) ⇒ number

Get the angle of a vector from the z axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.cpy(a) ⇒ vec3

Copy a vector

Kind: static method of vec3
Returns: vec3 - A copy of vector a

Param	Type	Description
a	vec3	The vector to copy

vec3.map(a, f) ⇒ vec3

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec3
Returns: vec3 - Vector a mapped through f

Param	Type	Description
a	vec3	Vector a
f	vec3MapCallback	The function to call on each component of the vector

vec3.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec3
Returns: string - A string representation of the vector

Param	Type	Default	Description
a	vec3		The vector to convert
[s]	string	"', '"	The separator string

vec3.swiz(a, [s]) ⇒ Array.<number>

Swizzle a vector with a string of component labels

The string can contain:

• x, y or z
• u, v or w (aliases for x, y and z, respectively)
• r, g or b (aliases for x, y and z, respectively)
• X, Y, Z, U, V, W, R, G, B (negated versions of the above)
• 0 or 1 (these will be passed through unchanged)
• . to return the component that would normally be at this position (or 0)

Any other characters will default to 0

Kind: static method of vec3
Returns: Array.<number> - The swizzled components

Param	Type	Default	Description
a	vec3		The vector to swizzle
[s]	string	"'...'"	The swizzle string

Example (swizzling a vector)

let a = vec3(3, -2, 1);
vec3.swiz(a, 'x');     // [3]
vec3.swiz(a, 'zyx');   // [1, -2, 3]
vec3.swiz(a, 'xYZ');   // [3, 2, -1]
vec3.swiz(a, 'Zzx');   // [-1, 1, 3]
vec3.swiz(a, 'x.x');   // [3, -2, 3]
vec3.swiz(a, 'y01zx'); // [-2, 0, 1, 1, 3]

vec3.polar(a) ⇒ polarCoordinates3d

Convert a vector into polar coordinates

Kind: static method of vec3
Returns: polarCoordinates3d - The magnitude, tilt and pan of the vector

Param	Type	Description
a	vec3	The vector to convert

vec3.fromPolar(r, theta, phi) ⇒ vec3

Convert polar coordinates into a vector

Kind: static method of vec3
Returns: vec3 - A vector with the given angle and magnitude

Param	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The tilt of the vector
phi	number	The pan of the vector

mat([m], [n], [entries]) ⇒ mat

Create a new matrix

Kind: global function
Returns: mat - A new matrix

Param	Type	Default	Description
[m]	number	4	The number of rows
[n]	number	4	The number of columns
[entries]	Array.<number>	[]	Matrix values in reading order

• mat([m], [n], [entries]) ⇒ mat
  • .identity(n) ⇒ mat
  • .get(a, i, j) ⇒ number
  • .set(a, i, j, v)
  • .row(a, m) ⇒ Array.<number>
  • .col(a, n) ⇒ Array.<number>
  • .add(a, b) ⇒ mat
  • .sub(a, b) ⇒ mat
  • .mul(a, b) ⇒ mat | boolean
  • .scale(a, b) ⇒ mat
  • .trans(a) ⇒ mat
  • .minor(a, i, j) ⇒ mat | boolean
  • .det(a) ⇒ number | boolean
  • .nor(a) ⇒ mat | boolean
  • .adj(a) ⇒ mat
  • .inv(a) ⇒ mat | boolean
  • .eq(a, b) ⇒ boolean
  • .cpy(a) ⇒ mat
  • .map(a, f) ⇒ mat
  • .str(a, [ms], [ns]) ⇒ string

mat.identity(n) ⇒ mat

Get an identity matrix of size n

Kind: static method of mat
Returns: mat - An identity matrix

Param	Type	Description
n	number	The size of the matrix

mat.get(a, i, j) ⇒ number

Get an entry from a matrix

Kind: static method of mat
Returns: number - The value at position (i, j) in matrix a

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset

mat.set(a, i, j, v)

Set an entry of a matrix

Kind: static method of mat

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset
v	number	The value to set in matrix a

mat.row(a, m) ⇒ Array.<number>

Get a row from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Row m from matrix a

Param	Type	Description
a	mat	Matrix a
m	number	The row offset

mat.col(a, n) ⇒ Array.<number>

Get a column from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Column n from matrix a

Param	Type	Description
a	mat	Matrix a
n	number	The column offset

mat.add(a, b) ⇒ mat

Add matrices

Kind: static method of mat
Returns: mat - a + b

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.sub(a, b) ⇒ mat

Subtract matrices

Kind: static method of mat
Returns: mat - a - b

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.mul(a, b) ⇒ mat | boolean

Multiply matrices

Kind: static method of mat
Returns: mat | boolean - ab or false if the matrices cannot be multiplied

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.scale(a, b) ⇒ mat

Scale a matrix

Kind: static method of mat
Returns: mat - a * b

Param	Type	Description
a	mat	Matrix a
b	number	Scalar b

mat.trans(a) ⇒ mat

Transpose a matrix

Kind: static method of mat
Returns: mat - A transposed matrix

Param	Type	Description
a	mat	The matrix to transpose

mat.minor(a, i, j) ⇒ mat | boolean

Get the minor of a matrix

Kind: static method of mat
Returns: mat | boolean - The (i, j) minor of matrix a or false if the matrix is not square

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset

mat.det(a) ⇒ number | boolean

Get the determinant of a matrix

Kind: static method of mat
Returns: number | boolean - |a| or false if the matrix is not square

Param	Type	Description
a	mat	Matrix a

mat.nor(a) ⇒ mat | boolean

Normalise a matrix

Kind: static method of mat
Returns: mat | boolean - ^a or false if the matrix is not square

Param	Type	Description
a	mat	The matrix to normalise

mat.adj(a) ⇒ mat

Get the adjugate of a matrix

Kind: static method of mat
Returns: mat - The adjugate of a

Param	Type	Description
a	mat	The matrix from which to get the adjugate

mat.inv(a) ⇒ mat | boolean

Get the inverse of a matrix

Kind: static method of mat
Returns: mat | boolean - a^-1 or false if the matrix has no inverse

Param	Type	Description
a	mat	The matrix to invert

mat.eq(a, b) ⇒ boolean

Check if two matrices are equal

Kind: static method of mat
Returns: boolean - True if matrices a and b are identical, false otherwise

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.cpy(a) ⇒ mat

Copy a matrix

Kind: static method of mat
Returns: mat - A copy of matrix a

Param	Type	Description
a	mat	The matrix to copy

mat.map(a, f) ⇒ mat

Call a function on each entry of a matrix and build a new matrix from the results

Kind: static method of mat
Returns: mat - Matrix a mapped through f

Param	Type	Description
a	mat	Matrix a
f	matrixMapCallback	The function to call on each entry of the matrix

mat.str(a, [ms], [ns]) ⇒ string

Convert a matrix into a string

Kind: static method of mat
Returns: string - A string representation of the matrix

Param	Type	Default	Description
a	mat		The matrix to convert
[ms]	string	"', '"	The separator string for columns
[ns]	string	"'\n'"	The separator string for rows

vec2 : Object

A 2d vector

Kind: global typedef
Properties

Name	Type	Description
x	number	The x component of the vector
y	number	The y component of the vector

• vec2 : Object
  • .components(a) ⇒ Array.<number>
  • .fromComponents(components) ⇒ vec2
  • .ux() ⇒ vec2
  • .uy() ⇒ vec2
  • .add(a, b) ⇒ vec2
  • .sub(a, b) ⇒ vec2
  • .mul(a, b) ⇒ vec2
  • .scale(a, b) ⇒ vec2
  • .div(a, b) ⇒ vec2
  • .len(a) ⇒ number
  • .manhattan(a) ⇒ number
  • .nor(a) ⇒ vec2
  • .dot(a, b) ⇒ number
  • .rot(a, r) ⇒ vec2
  • .rotf(a, r) ⇒ vec2
  • .eq(a, b) ⇒ boolean
  • .rad(a) ⇒ number
  • .cpy(a) ⇒ vec2
  • .map(a, f) ⇒ vec2
  • .str(a, [s]) ⇒ string
  • .swiz(a, [s]) ⇒ Array.<number>
  • .polar(a) ⇒ polarCoordinates2d
  • .fromPolar(r, theta) ⇒ vec2

vec2.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec2
Returns: Array.<number> - The vector components as an array

Param	Type	Description
a	vec2	The vector to get components from

vec2.fromComponents(components) ⇒ vec2

Create a vector from an array of components

Kind: static method of vec2
Returns: vec2 - A new vector

Param	Type	Description
components	Array.<number>	The components of the vector

vec2.ux() ⇒ vec2

Return a unit vector (1, 0)

Kind: static method of vec2
Returns: vec2 - A unit vector (1, 0)

vec2.uy() ⇒ vec2

Return a unit vector (0, 1)

Kind: static method of vec2
Returns: vec2 - A unit vector (0, 1)

vec2.add(a, b) ⇒ vec2

Add vectors

Kind: static method of vec2
Returns: vec2 - a + b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.sub(a, b) ⇒ vec2

Subtract vectors

Kind: static method of vec2
Returns: vec2 - a - b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.mul(a, b) ⇒ vec2

Scale a vector

Kind: static method of vec2
Returns: vec2 - a * b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.scale(a, b) ⇒ vec2

Scale a vector by a scalar, alias for vec2.mul

Kind: static method of vec2
Returns: vec2 - a * b

Param	Type	Description
a	vec2	Vector a
b	number	Scalar b

vec2.div(a, b) ⇒ vec2

Divide a vector

Kind: static method of vec2
Returns: vec2 - a / b

Param	Type	Description
a	vec2	Vector a
b	vec2 | number	Vector or scalar b

vec2.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec2
Returns: number - |a|

Param	Type	Description
a	vec2	Vector a

vec2.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec2
Returns: number - |a|

Param	Type	Description
a	vec2	Vector a

vec2.nor(a) ⇒ vec2

Normalise a vector

Kind: static method of vec2
Returns: vec2 - ^a

Param	Type	Description
a	vec2	The vector to normalise

vec2.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec2
Returns: number - a ∙ b

Param	Type	Description
a	vec2	Vector a
b	vec2	Vector b

vec2.rot(a, r) ⇒ vec2

Rotate a vector by r radians

Kind: static method of vec2
Returns: vec2 - A rotated vector

Param	Type	Description
a	vec2	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec2.rotf(a, r) ⇒ vec2

Fast method to rotate a vector by -90, 90 or 180 degrees

Kind: static method of vec2
Returns: vec2 - A rotated vector

Param	Type	Description
a	vec2	The vector to rotate
r	number	1 for 90 degrees (cw), -1 for -90 degrees (ccw), 2 or -2 for 180 degrees

vec2.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec2
Returns: boolean - True if vectors a and b are equal, false otherwise

Param	Type	Description
a	vec2	Vector a
b	vec2	Vector b

vec2.rad(a) ⇒ number

Get the angle of a vector

Kind: static method of vec2
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec2	Vector a

vec2.cpy(a) ⇒ vec2

Copy a vector

Kind: static method of vec2
Returns: vec2 - A copy of vector a

Param	Type	Description
a	vec2	The vector to copy

vec2.map(a, f) ⇒ vec2

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec2
Returns: vec2 - Vector a mapped through f

Param	Type	Description
a	vec2	Vector a
f	vec2MapCallback	The function to call on each component of the vector

vec2.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec2
Returns: string - A string representation of the vector

Param	Type	Default	Description
a	vec2		The vector to convert
[s]	string	"', '"	The separator string

vec2.swiz(a, [s]) ⇒ Array.<number>

Swizzle a vector with a string of component labels

The string can contain:

• x or y
• u or v (aliases for x and y, respectively)
• X, Y, U, V (negated versions of the above)
• 0 or 1 (these will be passed through unchanged)
• . to return the component that would normally be at this position (or 0)

Any other characters will default to 0

Kind: static method of vec2
Returns: Array.<number> - The swizzled components

Param	Type	Default	Description
a	vec2		The vector to swizzle
[s]	string	"'..'"	The swizzle string

Example (swizzling a vector)

let a = vec2(3, -2);
vec2.swiz(a, 'x');    // [3]
vec2.swiz(a, 'yx');   // [-2, 3]
vec2.swiz(a, 'xY');   // [3, 2]
vec2.swiz(a, 'Yy');   // [2, -2]
vec2.swiz(a, 'x.x');  // [3, -2, 3]
vec2.swiz(a, 'y01x'); // [-2, 0, 1, 3]

vec2.polar(a) ⇒ polarCoordinates2d

Convert a vector into polar coordinates

Kind: static method of vec2
Returns: polarCoordinates2d - The magnitude and angle of the vector

Param	Type	Description
a	vec2	The vector to convert

vec2.fromPolar(r, theta) ⇒ vec2

Convert polar coordinates into a vector

Kind: static method of vec2
Returns: vec2 - A vector with the given angle and magnitude

Param	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The angle of the vector

vec2MapCallback ⇒ number

A function to call on each component of a 2d vector

Kind: global typedef
Returns: number - The mapped component

Param	Type	Description
value	number	The component value
label	'x' | 'y'	The component label (x or y)

polarCoordinates2d : Object

Polar coordinates for a 2d vector

Kind: global typedef
Properties

Name	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The angle of the vector

vec3 : Object

A 3d vector

Kind: global typedef
Properties

Name	Type	Description
x	number	The x component of the vector
y	number	The y component of the vector
z	number	The z component of the vector

• vec3 : Object
  • .components(a) ⇒ Array.<number>
  • .fromComponents(components) ⇒ vec3
  • .ux() ⇒ vec3
  • .uy() ⇒ vec3
  • .uz() ⇒ vec3
  • .add(a, b) ⇒ vec3
  • .sub(a, b) ⇒ vec3
  • .mul(a, b) ⇒ vec3
  • .scale(a, b) ⇒ vec3
  • .div(a, b) ⇒ vec3
  • .len(a) ⇒ number
  • .manhattan(a) ⇒ number
  • .nor(a) ⇒ vec3
  • .dot(a, b) ⇒ number
  • .rot(a, m) ⇒ vec3
  • .rotx(a, r) ⇒ vec3
  • .roty(a, r) ⇒ vec3
  • .rotz(a, r) ⇒ vec3
  • .rotq(a, q) ⇒ vec3
  • .rota(a, e) ⇒ vec3
  • .cross(a, b) ⇒ vec3
  • .eq(a, b) ⇒ boolean
  • .radx(a) ⇒ number
  • .rady(a) ⇒ number
  • .radz(a) ⇒ number
  • .cpy(a) ⇒ vec3
  • .map(a, f) ⇒ vec3
  • .str(a, [s]) ⇒ string
  • .swiz(a, [s]) ⇒ Array.<number>
  • .polar(a) ⇒ polarCoordinates3d
  • .fromPolar(r, theta, phi) ⇒ vec3

vec3.components(a) ⇒ Array.<number>

Get the components of a vector as an array

Kind: static method of vec3
Returns: Array.<number> - The vector components as an array

Param	Type	Description
a	vec3	The vector to get components from

vec3.fromComponents(components) ⇒ vec3

Create a vector from an array of components

Kind: static method of vec3
Returns: vec3 - A new vector

Param	Type	Description
components	Array.<number>	The components of the vector

vec3.ux() ⇒ vec3

Return a unit vector (1, 0, 0)

Kind: static method of vec3
Returns: vec3 - A unit vector (1, 0, 0)

vec3.uy() ⇒ vec3

Return a unit vector (0, 1, 0)

Kind: static method of vec3
Returns: vec3 - A unit vector (0, 1, 0)

vec3.uz() ⇒ vec3

Return a unit vector (0, 0, 1)

Kind: static method of vec3
Returns: vec3 - A unit vector (0, 0, 1)

vec3.add(a, b) ⇒ vec3

Add vectors

Kind: static method of vec3
Returns: vec3 - a + b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.sub(a, b) ⇒ vec3

Subtract vectors

Kind: static method of vec3
Returns: vec3 - a - b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.mul(a, b) ⇒ vec3

Scale a vector

Kind: static method of vec3
Returns: vec3 - a * b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.scale(a, b) ⇒ vec3

Scale a vector by a scalar, alias for vec3.mul

Kind: static method of vec3
Returns: vec3 - a * b

Param	Type	Description
a	vec3	Vector a
b	number	Scalar b

vec3.div(a, b) ⇒ vec3

Divide a vector

Kind: static method of vec3
Returns: vec3 - a / b

Param	Type	Description
a	vec3	Vector a
b	vec3 | number	Vector or scalar b

vec3.len(a) ⇒ number

Get the length of a vector

Kind: static method of vec3
Returns: number - |a|

Param	Type	Description
a	vec3	Vector a

vec3.manhattan(a) ⇒ number

Get the length of a vector using taxicab geometry

Kind: static method of vec3
Returns: number - |a|

Param	Type	Description
a	vec3	Vector a

vec3.nor(a) ⇒ vec3

Normalise a vector

Kind: static method of vec3
Returns: vec3 - ^a

Param	Type	Description
a	vec3	The vector to normalise

vec3.dot(a, b) ⇒ number

Get a dot product of vectors

Kind: static method of vec3
Returns: number - a ∙ b

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.rot(a, m) ⇒ vec3

Rotate a vector using a rotation matrix

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
m	mat	The rotation matrix

vec3.rotx(a, r) ⇒ vec3

Rotate a vector by r radians around the x axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.roty(a, r) ⇒ vec3

Rotate a vector by r radians around the y axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.rotz(a, r) ⇒ vec3

Rotate a vector by r radians around the z axis

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
r	number	The angle to rotate by, measured in radians

vec3.rotq(a, q) ⇒ vec3

Rotate a vector using a quaternion

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
q	Array.<number>	The quaternion to rotate by

vec3.rota(a, e) ⇒ vec3

Rotate a vector using Euler angles

Kind: static method of vec3
Returns: vec3 - A rotated vector

Param	Type	Description
a	vec3	The vector to rotate
e	vec3	The Euler angles to rotate by

vec3.cross(a, b) ⇒ vec3

Get the cross product of vectors

Kind: static method of vec3
Returns: vec3 - a × b

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.eq(a, b) ⇒ boolean

Check if two vectors are equal

Kind: static method of vec3
Returns: boolean - True if vectors a and b are equal, false otherwise

Param	Type	Description
a	vec3	Vector a
b	vec3	Vector b

vec3.radx(a) ⇒ number

Get the angle of a vector from the x axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.rady(a) ⇒ number

Get the angle of a vector from the y axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.radz(a) ⇒ number

Get the angle of a vector from the z axis

Kind: static method of vec3
Returns: number - The angle of vector a in radians

Param	Type	Description
a	vec3	Vector a

vec3.cpy(a) ⇒ vec3

Copy a vector

Kind: static method of vec3
Returns: vec3 - A copy of vector a

Param	Type	Description
a	vec3	The vector to copy

vec3.map(a, f) ⇒ vec3

Call a function on each component of a vector and build a new vector from the results

Kind: static method of vec3
Returns: vec3 - Vector a mapped through f

Param	Type	Description
a	vec3	Vector a
f	vec3MapCallback	The function to call on each component of the vector

vec3.str(a, [s]) ⇒ string

Convert a vector into a string

Kind: static method of vec3
Returns: string - A string representation of the vector

Param	Type	Default	Description
a	vec3		The vector to convert
[s]	string	"', '"	The separator string

vec3.swiz(a, [s]) ⇒ Array.<number>

Swizzle a vector with a string of component labels

The string can contain:

• x, y or z
• u, v or w (aliases for x, y and z, respectively)
• r, g or b (aliases for x, y and z, respectively)
• X, Y, Z, U, V, W, R, G, B (negated versions of the above)
• 0 or 1 (these will be passed through unchanged)
• . to return the component that would normally be at this position (or 0)

Any other characters will default to 0

Kind: static method of vec3
Returns: Array.<number> - The swizzled components

Param	Type	Default	Description
a	vec3		The vector to swizzle
[s]	string	"'...'"	The swizzle string

Example (swizzling a vector)

let a = vec3(3, -2, 1);
vec3.swiz(a, 'x');     // [3]
vec3.swiz(a, 'zyx');   // [1, -2, 3]
vec3.swiz(a, 'xYZ');   // [3, 2, -1]
vec3.swiz(a, 'Zzx');   // [-1, 1, 3]
vec3.swiz(a, 'x.x');   // [3, -2, 3]
vec3.swiz(a, 'y01zx'); // [-2, 0, 1, 1, 3]

vec3.polar(a) ⇒ polarCoordinates3d

Convert a vector into polar coordinates

Kind: static method of vec3
Returns: polarCoordinates3d - The magnitude, tilt and pan of the vector

Param	Type	Description
a	vec3	The vector to convert

vec3.fromPolar(r, theta, phi) ⇒ vec3

Convert polar coordinates into a vector

Kind: static method of vec3
Returns: vec3 - A vector with the given angle and magnitude

Param	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The tilt of the vector
phi	number	The pan of the vector

vec3MapCallback ⇒ number

A function to call on each component of a 3d vector

Kind: global typedef
Returns: number - The mapped component

Param	Type	Description
value	number	The component value
label	'x' | 'y' | 'z'	The component label (x, y or z)

polarCoordinates3d : Object

Polar coordinates for a 3d vector

Kind: global typedef
Properties

Name	Type	Description
r	number	The magnitude (radius) of the vector
theta	number	The tilt angle of the vector
phi	number	The pan angle of the vector

mat : Object

A matrix

Kind: global typedef
Properties

Name	Type	Description
m	number	The number of rows in the matrix
n	number	The number of columns in the matrix
entries	Array.<number>	The matrix values

• mat : Object
  • .identity(n) ⇒ mat
  • .get(a, i, j) ⇒ number
  • .set(a, i, j, v)
  • .row(a, m) ⇒ Array.<number>
  • .col(a, n) ⇒ Array.<number>
  • .add(a, b) ⇒ mat
  • .sub(a, b) ⇒ mat
  • .mul(a, b) ⇒ mat | boolean
  • .scale(a, b) ⇒ mat
  • .trans(a) ⇒ mat
  • .minor(a, i, j) ⇒ mat | boolean
  • .det(a) ⇒ number | boolean
  • .nor(a) ⇒ mat | boolean
  • .adj(a) ⇒ mat
  • .inv(a) ⇒ mat | boolean
  • .eq(a, b) ⇒ boolean
  • .cpy(a) ⇒ mat
  • .map(a, f) ⇒ mat
  • .str(a, [ms], [ns]) ⇒ string

mat.identity(n) ⇒ mat

Get an identity matrix of size n

Kind: static method of mat
Returns: mat - An identity matrix

Param	Type	Description
n	number	The size of the matrix

mat.get(a, i, j) ⇒ number

Get an entry from a matrix

Kind: static method of mat
Returns: number - The value at position (i, j) in matrix a

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset

mat.set(a, i, j, v)

Set an entry of a matrix

Kind: static method of mat

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset
v	number	The value to set in matrix a

mat.row(a, m) ⇒ Array.<number>

Get a row from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Row m from matrix a

Param	Type	Description
a	mat	Matrix a
m	number	The row offset

mat.col(a, n) ⇒ Array.<number>

Get a column from a matrix as an array

Kind: static method of mat
Returns: Array.<number> - Column n from matrix a

Param	Type	Description
a	mat	Matrix a
n	number	The column offset

mat.add(a, b) ⇒ mat

Add matrices

Kind: static method of mat
Returns: mat - a + b

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.sub(a, b) ⇒ mat

Subtract matrices

Kind: static method of mat
Returns: mat - a - b

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.mul(a, b) ⇒ mat | boolean

Multiply matrices

Kind: static method of mat
Returns: mat | boolean - ab or false if the matrices cannot be multiplied

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.scale(a, b) ⇒ mat

Scale a matrix

Kind: static method of mat
Returns: mat - a * b

Param	Type	Description
a	mat	Matrix a
b	number	Scalar b

mat.trans(a) ⇒ mat

Transpose a matrix

Kind: static method of mat
Returns: mat - A transposed matrix

Param	Type	Description
a	mat	The matrix to transpose

mat.minor(a, i, j) ⇒ mat | boolean

Get the minor of a matrix

Kind: static method of mat
Returns: mat | boolean - The (i, j) minor of matrix a or false if the matrix is not square

Param	Type	Description
a	mat	Matrix a
i	number	The row offset
j	number	The column offset

mat.det(a) ⇒ number | boolean

Get the determinant of a matrix

Kind: static method of mat
Returns: number | boolean - |a| or false if the matrix is not square

Param	Type	Description
a	mat	Matrix a

mat.nor(a) ⇒ mat | boolean

Normalise a matrix

Kind: static method of mat
Returns: mat | boolean - ^a or false if the matrix is not square

Param	Type	Description
a	mat	The matrix to normalise

mat.adj(a) ⇒ mat

Get the adjugate of a matrix

Kind: static method of mat
Returns: mat - The adjugate of a

Param	Type	Description
a	mat	The matrix from which to get the adjugate

mat.inv(a) ⇒ mat | boolean

Get the inverse of a matrix

Kind: static method of mat
Returns: mat | boolean - a^-1 or false if the matrix has no inverse

Param	Type	Description
a	mat	The matrix to invert

mat.eq(a, b) ⇒ boolean

Check if two matrices are equal

Kind: static method of mat
Returns: boolean - True if matrices a and b are identical, false otherwise

Param	Type	Description
a	mat	Matrix a
b	mat	Matrix b

mat.cpy(a) ⇒ mat

Copy a matrix

Kind: static method of mat
Returns: mat - A copy of matrix a

Param	Type	Description
a	mat	The matrix to copy

mat.map(a, f) ⇒ mat

Call a function on each entry of a matrix and build a new matrix from the results

Kind: static method of mat
Returns: mat - Matrix a mapped through f

Param	Type	Description
a	mat	Matrix a
f	matrixMapCallback	The function to call on each entry of the matrix

mat.str(a, [ms], [ns]) ⇒ string

Convert a matrix into a string

Kind: static method of mat
Returns: string - A string representation of the matrix

Param	Type	Default	Description
a	mat		The matrix to convert
[ms]	string	"', '"	The separator string for columns
[ns]	string	"'\n'"	The separator string for rows

matrixMapCallback ⇒ number

A function to call on each entry of a matrix

Kind: global typedef
Returns: number - The mapped entry

Param	Type	Description
value	number	The entry value
index	number	The entry index
entries	Array.<number>	The array of matrix entries