Skip to content

Latest commit

 

History

History
2177 lines (1562 loc) · 68.6 KB

README.md

File metadata and controls

2177 lines (1562 loc) · 68.6 KB
Raw

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

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.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 Vector 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 number 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 Vector 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.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 Vector 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 number 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 Vector 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.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.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 Vector 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 number 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 Vector 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.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 Vector 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 number 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 Vector 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.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