Math

2D Vectors

class vec2

This type represents a 2D vector. Most mathematical operators such as equality, addition, subtraction, multiplication and division are provided, so you can use vec2 data types similarly to how you use numerical types.

Parameters:

• x (number) – Initial x value of the vector

• y (number) – Initial y value of the vector

Syntax:

v = vec2(1, 2)
v = vec2(1) -- set both x and y to 1
v = vec2() -- set both x and y to 0

x: number

The x component of this vector

y: number

The y component of this vector

static min(v1, v2)

Return a vec2 containing the component-wise minimum of two vectors

Parameters:

• v1 (vec2) – The first vector

• v2 (vec2) – The second vector

Returns:

A new vec2 with the minimum of each component

Return type:

vec2

static max(v1, v2)

Return a vec2 containing the component-wise maximum of two vectors

Parameters:

• v1 (vec2) – The first vector

• v2 (vec2) – The second vector

Returns:

A new vec2 with the maximum of each component

Return type:

vec2

length: number

The length of this vector

length2: number

The squared length of this vector

normalize()

Normalize this vector in-place

normalized() → vec2

Return a normalized copy of this vector

Returns:

A normalized copy of this vector

Return type:

vec2

dot(v) → number

Perform a scalar dot product with another vector and return the result

Parameters:

v (vec2) – The other vector

Returns:

The scalar dot product

Return type:

number

distance(v) → number

Calculate the Euclidean distance to another vector

Parameters:

v (vec2) – The other vector

Returns:

The distance between the two vectors

Return type:

number

distance2(v) → number

Calculate the squared Euclidean distance to another vector

Parameters:

v (vec2) – The other vector

Returns:

The squared distance between the two vectors

Return type:

number

reflect(normal) → vec2

Reflect this vector about a normal

Parameters:

normal (vec2) – The normal vector to reflect about

Returns:

The reflected vector

Return type:

vec2

refract(normal, ior) → vec2

Refract this vector through a surface with a given index of refraction

Parameters:

• normal (vec2) – The surface normal

• ior (number) – The index of refraction

Returns:

The refracted vector

Return type:

vec2

lerp(v, t) → vec2

Interpolate this vector with another by a given factor

Parameters:

• v (vec2) – The target vector

• t (number) – The interpolation factor (typically between 0 and 1)

Returns:

The interpolated vector

Return type:

vec2

abs() → vec2

Return a copy of this vector with component-wise absolute values

Returns:

A copy with all components made positive

Return type:

vec2

unpack() → number, number

Unpack this vector as individual number values

Returns:

The x and y components as separate values

cross(v) → number

Compute the 2D cross product (perp dot product) with another vector

Parameters:

v (vec2) – The other vector

Returns:

The scalar cross product result

Return type:

number

rotate(angleRadians) → vec2

Rotate this vector by a given angle in radians

Parameters:

angleRadians (number) – The angle of rotation in radians

Returns:

The rotated vector

Return type:

vec2

rotate90() → vec2

Rotate this vector by 90 degrees

Returns:

The rotated vector

Return type:

vec2

angleBetween(v) → number

Calculate the oriented angle between this vector and another, between -pi and pi

Parameters:

v (vec2) – The other vector

Returns:

The oriented angle in radians between -pi and pi

Return type:

number

3D Vectors

class vec3

static vec3(x, y, z)

Create a new vec3 by setting each component individually

Parameters:

• x (number) – The x component

• y (number) – The y component

• z (number) – The z component

static vec3()

Create a new vec3 by setting all components to zero

static vec3(v)

Create a new vec3 by setting all components to the same value

Parameters:

v (number) – The x, y and z values

static min(v1, v2)

Return a vec3 containing the component-wise minimum of two vectors

Parameters:

• v1 (vec3) – The first vector

• v2 (vec3) – The second vector

Returns:

A new vec3 with the minimum of each component

Return type:

vec3

static max(v1, v2)

Return a vec3 containing the component-wise maximum of two vectors

Parameters:

• v1 (vec3) – The first vector

• v2 (vec3) – The second vector

Returns:

A new vec3 with the maximum of each component

Return type:

vec3

x: number

The x component of this vector

y: number

The y component of this vector

z: number

The z component of this vector

length: number

The length of this vector

length2: number

The squared length of this vector

normalize()

Normalize this vector in-place

normalized() → vec3

Return a normalized copy of this vector

Returns:

A normalized copy of this vector

Return type:

vec3

dot(v) → number

Perform a scalar dot product with another vector and return the result

Parameters:

v (vec3) – The other vector

Returns:

The scalar dot product

Return type:

number

cross(v) → vec3

Perform a cross product with another vec3 and return the result

Parameters:

v (vec3) – The other vector

Returns:

A vector perpendicular to both input vectors

Return type:

vec3

distance(v) → number

Calculate the Euclidean distance to another vector

Parameters:

v (vec3) – The other vector

Returns:

The distance between the two vectors

Return type:

number

distance2(v) → number

Calculate the squared Euclidean distance to another vector

Parameters:

v (vec3) – The other vector

Returns:

The squared distance between the two vectors

Return type:

number

reflect(normal) → vec3

Reflect this vector about a normal

Parameters:

normal (vec3) – The normal vector to reflect about

Returns:

The reflected vector

Return type:

vec3

refract(normal, ior) → vec3

Refract this vector through a surface with a given index of refraction

Parameters:

• normal (vec3) – The surface normal

• ior (number) – The index of refraction

Returns:

The refracted vector

Return type:

vec3

lerp(v, t) → vec3

Interpolate this vector with another by a given factor

Parameters:

• v (vec3) – The target vector

• t (number) – The interpolation factor (typically between 0 and 1)

Returns:

The interpolated vector

Return type:

vec3

abs() → vec3

Return a copy of this vector with component-wise absolute values

Returns:

A copy with all components made positive

Return type:

vec3

unpack() → number, number, number

Unpack this vector as individual number values

Returns:

The x, y and z components as separate values

4D Vectors

class vec4

static vec4(x)

static vec4(x, y, z, w)

Create a new vec4 by setting all components to the same value, or each one individually

Parameters:

• x (number) – The x component (also used for y, z and w when called with a single argument)

• y (number) – The y component

• z (number) – The z component

• w (number) – The w component

static min(v1, v2)

Return a vec4 containing the component-wise minimum of two vectors

Parameters:

• v1 (vec4) – The first vector

• v2 (vec4) – The second vector

Returns:

A new vec4 with the minimum of each component

Return type:

vec4

static max(v1, v2)

Return a vec4 containing the component-wise maximum of two vectors

Parameters:

• v1 (vec4) – The first vector

• v2 (vec4) – The second vector

Returns:

A new vec4 with the maximum of each component

Return type:

vec4

x: number

The x component of this vector

y: number

The y component of this vector

z: number

The z component of this vector

w: number

The w component of this vector

length: number

The length of this vector

length2: number

The squared length of this vector

normalize()

Normalize this vector in-place

normalized() → vec4

Return a normalized copy of this vector

Returns:

A normalized copy of this vector

Return type:

vec4

dot(v) → number

Perform a scalar dot product with another vector and return the result

Parameters:

v (vec4) – The other vector

Returns:

The scalar dot product

Return type:

number

distance(v) → number

Calculate the Euclidean distance to another vector

Parameters:

v (vec4) – The other vector

Returns:

The distance between the two vectors

Return type:

number

distance2(v) → number

Calculate the squared Euclidean distance to another vector

Parameters:

v (vec4) – The other vector

Returns:

The squared distance between the two vectors

Return type:

number

reflect(normal) → vec4

Reflect this vector about a normal

Parameters:

normal (vec4) – The normal vector to reflect about

Returns:

The reflected vector

Return type:

vec4

refract(normal, ior) → vec4

Refract this vector through a surface with a given index of refraction

Parameters:

• normal (vec4) – The surface normal

• ior (number) – The index of refraction

Returns:

The refracted vector

Return type:

vec4

lerp(v, t) → vec4

Interpolate this vector with another by a given factor

Parameters:

• v (vec4) – The target vector

• t (number) – The interpolation factor (typically between 0 and 1)

Returns:

The interpolated vector

Return type:

vec4

abs() → vec4

Return a copy of this vector with component-wise absolute values

Returns:

A copy with all components made positive

Return type:

vec4

unpack() → number, number, number, number

Unpack this vector as individual number values

Returns:

The x, y, z and w components as separate values

Quaternions

class quat

static quat()

static quat(w, x, y, z)

Create a new quat

Parameters:

• w (number) – The scalar (real) component

• x (number) – The x imaginary component

• y (number) – The y imaginary component

• z (number) – The z imaginary component

static lookRotation(forward, up)

Create a rotation that points in the forward direction, oriented using up

Parameters:

• forward (vec3) – The forward direction

• up (vec3) – The up direction used for orientation

Returns:

A quat that points in the forward direction

Return type:

quat

static fromToRotation(from, to)

Create a rotation that rotates from one direction to another

Parameters:

• from (vec3) – The direction to rotate from

• to (vec3) – The direction to rotate to

Returns:

A quat containing the relative rotation from from to to

Return type:

quat

static angleAxis(angle, axis)

Create a rotation of angle degrees around an axis

Parameters:

• angle (number) – The amount of rotation in degrees

• axis (vec3) – The axis of rotation

Returns:

A new quat representing the rotation

Return type:

quat

static eulerAngles(x, y, z)

Create a rotation from euler angles (yaw, pitch, roll) in degrees

Parameters:

• x (number) – The amount of rotation about the x axis (pitch) in degrees

• y (number) – The amount of rotation about the y axis (yaw) in degrees

• z (number) – The amount of rotation about the z axis (roll) in degrees

Returns:

A new quat representing the combined rotation

Return type:

quat

x: number

The x imaginary component

y: number

The y imaginary component

z: number

The z imaginary component

w: number

The scalar (real) component

angles: vec3

A set of euler angles (in degrees) that produces the same rotation as this quaternion

Note: euler angles derived from a quaternion are ambiguous and should not be relied upon for smooth interpolation

slerp(q, t) → quat

Spherically interpolate between this quaternion and another

Parameters:

• q (quat) – The target quaternion

• t (number) – The interpolation amount (between 0 and 1)

Returns:

A new quat spherically interpolated from this to q by t

Return type:

quat

conjugate() → quat

Return the conjugate of this quaternion

Returns:

A new quat containing the conjugate (inverse rotation)

Return type:

quat

normalize()

Normalize this quaternion in-place

normalized() → quat

Return a normalized copy of this quaternion

Returns:

A normalized copy of this quaternion

Return type:

quat

2x2 Matrix

class mat2

A simple 2x2 matrix. Individual entries can be accessed via a 1-based index

m = mat2(1) -- init with diagonals set to 1
print(m[1]) -- prints '1.0'

static mat2()

static mat2(s)

static mat2(v1, v2)

static mat2(m11, m12, m21, m22)

Create a new mat2: default (identity), diagonal scalar, two vec2 columns, or all 4 entries

Parameters:

• s (number) – Diagonal scalar value

• v1 (vec2) – First column vector

• v2 (vec2) – Second column vector

inverse() → mat2

Return the inverse of this matrix

Returns:

The inverse of this matrix

Return type:

mat2

transpose() → mat2

Return the transpose of this matrix

Returns:

The transpose of this matrix

Return type:

mat2

determinant() → number

Return the determinant of this matrix

Returns:

The determinant

Return type:

number

row(index) → vec2

Return the row at a given index

Parameters:

index (number) – The 1-based row index

Returns:

The row at the given index

Return type:

vec2

column(index) → vec2

Return the column at a given index

Parameters:

index (number) – The 1-based column index

Returns:

The column at the given index

Return type:

vec2

3x3 Matrix

class mat3

A simple 3x3 matrix. Individual entries can be accessed via a 1-based index

m = mat3(1) -- init with diagonals set to 1
print(m[1]) -- prints '1.0'

static mat3()

static mat3(s)

static mat3(v1, v2, v3)

static mat3(m11, m12, m31, ..., m33)

Create a new mat3: default (identity), diagonal scalar, three vec3 columns, or all 9 entries

Parameters:

• s (number) – Diagonal scalar value

• v1 (vec3) – First column vector

• v2 (vec3) – Second column vector

• v3 (vec3) – Third column vector

inverse() → mat3

Return the inverse of this matrix

Returns:

The inverse of this matrix

Return type:

mat3

transpose() → mat3

Return the transpose of this matrix

Returns:

The transpose of this matrix

Return type:

mat3

determinant() → number

Return the determinant of this matrix

Returns:

The determinant

Return type:

number

row(index) → vec3

Return the row at a given index

Parameters:

index (number) – The 1-based row index

Returns:

The row at the given index

Return type:

vec3

column(index) → vec3

Return the column at a given index

Parameters:

index (number) – The 1-based column index

Returns:

The column at the given index

Return type:

vec3

4x4 Matrix

class mat4

A 4x4 matrix typically used for 3D homogeneous transformations. Individual entries can be accessed via a 1-based index

m = mat4(1) -- init with diagonals set to 1
print(m[1]) -- prints '1.0'

static mat4()

static mat4(s)

static mat4(v1, v2, v3, v4)

static mat4(m11, m12, m31, m41, ..., m44)

Create a new mat4: default (identity), diagonal scalar, four vec4 columns, or all 16 entries

Parameters:

• s (number) – Diagonal scalar value

• v1 (vec4) – First column vector

• v2 (vec4) – Second column vector

• v3 (vec4) – Third column vector

• v4 (vec4) – Fourth column vector

static lookAt(eye, center, up)

Create a look-at view matrix

Parameters:

• eye (vec3) – The position of the camera

• center (vec3) – The point to look at

• up (vec3) – The up direction

Returns:

A view matrix looking from eye toward center

Return type:

mat4

static lookAt(matrix, eye, center, up)

Apply a look-at transform to an existing matrix

Parameters:

• matrix (mat4) – The matrix to apply the transform to

• eye (vec3) – The position of the camera

• center (vec3) – The point to look at

• up (vec3) – The up direction

Returns:

The transformed matrix

Return type:

mat4

static orbit(origin, distance, x, y)

Create an orbit view matrix centered on a point

Parameters:

• origin (vec3) – The point to orbit around

• distance (number) – The distance from the origin

• x (number) – The horizontal orbit angle in degrees

• y (number) – The vertical orbit angle in degrees

Returns:

An orbit view matrix

Return type:

mat4

static orbit(matrix, origin, distance, x, y)

Apply an orbit transform to an existing matrix

Parameters:

• matrix (mat4) – The matrix to apply the transform to

• origin (vec3) – The point to orbit around

• distance (number) – The distance from the origin

• x (number) – The horizontal orbit angle in degrees

• y (number) – The vertical orbit angle in degrees

Returns:

The transformed matrix

Return type:

mat4

static ortho(left, right, top, bottom[, near, far])

Create an orthographic projection matrix

Parameters:

• left (number) – The left clipping plane

• right (number) – The right clipping plane

• top (number) – The top clipping plane

• bottom (number) – The bottom clipping plane

• near (number) – The near clipping plane (optional)

• far (number) – The far clipping plane (optional)

Returns:

An orthographic projection matrix

Return type:

mat4

static perspective(fovy, aspect, near, far)

Create a perspective projection matrix

Parameters:

• fovy (number) – The vertical field of view in degrees

• aspect (number) – The aspect ratio (width / height)

• near (number) – The near clipping plane distance

• far (number) – The far clipping plane distance

Returns:

A perspective projection matrix

Return type:

mat4

static rotate(angle, axis)

Create a rotation matrix

Parameters:

• angle (number) – The rotation angle in degrees

• axis (vec3) – The axis of rotation

Returns:

A rotation matrix

Return type:

mat4

static rotate(matrix, angle, axis)

Apply a rotation transform to an existing matrix

Parameters:

• matrix (mat4) – The matrix to rotate

• angle (number) – The rotation angle in degrees

• axis (vec3) – The axis of rotation

Returns:

The rotated matrix

Return type:

mat4

inverse() → mat4

Return the inverse of this matrix

Returns:

The inverse of this matrix

Return type:

mat4

transpose() → mat4

Return the transpose of this matrix

Returns:

The transpose of this matrix

Return type:

mat4

determinant() → number

Return the determinant of this matrix

Returns:

The determinant

Return type:

number

row(index) → vec4

Return the row at a given index

Parameters:

index (number) – The 1-based row index

Returns:

The row at the given index

Return type:

vec4

column(index) → vec4

Return the column at a given index

Parameters:

index (number) – The 1-based column index

Returns:

The column at the given index

Return type:

vec4

Axis-Aligned Bounding Box (AABB)

class bounds.aabb

An axis-aligned bounding box defined by minimum and maximum corner points

Parameters:

• min (vec3) – The minimum corner of the bounding box

• max (vec3) – The maximum corner of the bounding box

Syntax:

b = bounds.aabb(vec3(-1, -1, -1), vec3(1, 1, 1))

min: vec3

The minimum corner of this bounding box

max: vec3

The maximum corner of this bounding box

size: vec3

The size (width, height, depth) of this bounding box

center: vec3

The center point of this bounding box

set(min, max)

Set the minimum and maximum corners of this bounding box

Parameters:

• min (vec3) – The new minimum corner

• max (vec3) – The new maximum corner

translate(offset)

Translate this bounding box by an offset

Parameters:

offset (vec3) – The translation offset