Math

@ripl/3d

3D math utilities: vectors, matrices, and projections.

Overview

Interfaces: Viewport

Type Aliases: Vector3 · Matrix4 · ProjectedPoint

Functions: vec3Add · vec3Sub · vec3Scale · vec3Dot · vec3Cross · vec3Length · vec3Normalize · vec3Lerp · vec3Negate · vec3Distance · typeIsVector3 · mat4Create · mat4Identity · mat4Clone · mat4Multiply · mat4Translate · mat4Scale · mat4RotateX · mat4RotateY · mat4RotateZ · mat4LookAt · mat4Perspective · mat4Orthographic · mat4TransformDirection · mat4TransformPoint · projectPoint

Viewport interface

Viewport dimensions used for projection.

interface Viewport {
    width: number;
    height: number;
}

Properties:

Property	Type	Description
width	number
height	number

---

Vector3 type

A 3-component vector represented as a labeled tuple [x, y, z].

type Vector3 = [x: number, y: number, z: number];

---

Matrix4 type

A column-major 4×4 matrix stored as a 16-element Float64Array.

type Matrix4 = Float64Array;

---

ProjectedPoint type

A 2D screen-space point with a depth component for z-ordering.

type ProjectedPoint = [x: number, y: number, depth: number];

---

vec3Add function

Returns the component-wise sum of two vectors.

function vec3Add(a: Vector3, b: Vector3): Vector3

Parameters:

Name	Type	Description
a	Vector3
b	Vector3

Returns: Vector3

---

vec3Sub function

Returns the component-wise difference of two vectors.

function vec3Sub(a: Vector3, b: Vector3): Vector3

Parameters:

Name	Type	Description
a	Vector3
b	Vector3

Returns: Vector3

---

vec3Scale function

Scales a vector by a scalar.

function vec3Scale(v: Vector3, s: number): Vector3

Parameters:

Name	Type	Description
v	Vector3
s	number

Returns: Vector3

---

vec3Dot function

Computes the dot product of two vectors.

function vec3Dot(a: Vector3, b: Vector3): number

Parameters:

Name	Type	Description
a	Vector3
b	Vector3

Returns: number

---

vec3Cross function

Computes the cross product of two vectors.

function vec3Cross(a: Vector3, b: Vector3): Vector3

Parameters:

Name	Type	Description
a	Vector3
b	Vector3

Returns: Vector3

---

vec3Length function

Returns the Euclidean length of a vector.

function vec3Length(v: Vector3): number

Parameters:

Name	Type	Description
v	Vector3

Returns: number

---

vec3Normalize function

Returns the unit-length direction of a vector, or the zero vector if length is 0.

function vec3Normalize(v: Vector3): Vector3

Parameters:

Name	Type	Description
v	Vector3

Returns: Vector3

---

vec3Lerp function

Linearly interpolates between two vectors by factor t.

function vec3Lerp(a: Vector3, b: Vector3, t: number): Vector3

Parameters:

Name	Type	Description
a	Vector3
b	Vector3
t	number

Returns: Vector3

---

vec3Negate function

Negates all components of a vector.

function vec3Negate(v: Vector3): Vector3

Parameters:

Name	Type	Description
v	Vector3

Returns: Vector3

---

vec3Distance function

Returns the Euclidean distance between two points.

function vec3Distance(a: Vector3, b: Vector3): number

Parameters:

Name	Type	Description
a	Vector3
b	Vector3

Returns: number

---

typeIsVector3 function

Type guard that checks whether a value is a Vector3 tuple.

function typeIsVector3(value: unknown): value is Vector3

Parameters:

Name	Type	Description
value	unknown

Returns: boolean

---

mat4Create function

Creates a zeroed 4×4 matrix.

function mat4Create(): Matrix4

Returns: Matrix4

---

mat4Identity function

Creates a 4×4 identity matrix.

function mat4Identity(): Matrix4

Returns: Matrix4

---

mat4Clone function

Returns a copy of the given matrix.

function mat4Clone(m: Matrix4): Matrix4

Parameters:

Name	Type	Description
m	Matrix4

Returns: Matrix4

---

mat4Multiply function

Multiplies two 4×4 matrices.

function mat4Multiply(a: Matrix4, b: Matrix4): Matrix4

Parameters:

Name	Type	Description
a	Matrix4
b	Matrix4

Returns: Matrix4

---

mat4Translate function

Applies a translation to a matrix.

function mat4Translate(m: Matrix4, v: Vector3): Matrix4

Parameters:

Name	Type	Description
m	Matrix4
v	Vector3

Returns: Matrix4

---

mat4Scale function

Applies a scale transform to a matrix.

function mat4Scale(m: Matrix4, v: Vector3): Matrix4

Parameters:

Name	Type	Description
m	Matrix4
v	Vector3

Returns: Matrix4

---

mat4RotateX function

Applies a rotation around the X axis to a matrix.

function mat4RotateX(m: Matrix4, angle: number): Matrix4

Parameters:

Name	Type	Description
m	Matrix4
angle	number

Returns: Matrix4

---

mat4RotateY function

Applies a rotation around the Y axis to a matrix.

function mat4RotateY(m: Matrix4, angle: number): Matrix4

Parameters:

Name	Type	Description
m	Matrix4
angle	number

Returns: Matrix4

---

mat4RotateZ function

Applies a rotation around the Z axis to a matrix.

function mat4RotateZ(m: Matrix4, angle: number): Matrix4

Parameters:

Name	Type	Description
m	Matrix4
angle	number

Returns: Matrix4

---

mat4LookAt function

Constructs a view matrix looking from eye toward target with the given up direction.

function mat4LookAt(eye: Vector3, target: Vector3, up: Vector3): Matrix4

Parameters:

Name	Type	Description
eye	Vector3
target	Vector3
up	Vector3

Returns: Matrix4

---

mat4Perspective function

Constructs a perspective projection matrix.

function mat4Perspective(fovRadians: number, aspect: number, near: number, far: number): Matrix4

Parameters:

Name	Type	Description
fovRadians	number
aspect	number
near	number
far	number

Returns: Matrix4

---

mat4Orthographic function

Constructs an orthographic projection matrix.

function mat4Orthographic(
    left: number,
    right: number,
    bottom: number,
    top: number,
    near: number,
    far: number
): Matrix4

Parameters:

Name	Type	Description
left	number
right	number
bottom	number
top	number
near	number
far	number

Returns: Matrix4

---

mat4TransformDirection function

Transforms a direction vector by the upper-3×3 of a 4×4 matrix, ignoring translation.

function mat4TransformDirection(m: Matrix4, v: Vector3): Vector3

Parameters:

Name	Type	Description
m	Matrix4
v	Vector3

Returns: Vector3

---

mat4TransformPoint function

Transforms a 3D point by a 4×4 matrix, performing the perspective divide.

function mat4TransformPoint(m: Matrix4, v: Vector3): Vector3

Parameters:

Name	Type	Description
m	Matrix4
v	Vector3

Returns: Vector3

---

projectPoint function

Projects a 3D world-space point onto 2D screen-space via a view-projection matrix and viewport.

function projectPoint(point: Vector3, viewProjection: Matrix4, viewport: Viewport): ProjectedPoint

Parameters:

Name	Type	Description
point	Vector3
viewProjection	Matrix4
viewport	Viewport

Returns: ProjectedPoint

---