Web Engine Dev

Appearance

@web-engine-dev/math

@web-engine-dev/math / Quat

Class: Quat ​

A quaternion for representing rotations. Stored as (x, y, z, w) where w is the scalar component.

Default operations are immutable and return new instances. For performance-critical code paths (game loops, hot paths), use the mutable variants (suffix Mut) or static out-parameter methods (suffix Out) to avoid allocations.

Example ​

ts
// Immutable (allocates new Quat)
const result = a.mulQuat(b);

// Mutable (modifies a in place, no allocation)
a.multiplyMut(b);

// Out-parameter (writes to existing Quat)
Quat.multiplyOut(a, b, result);

Constructors ​

Constructor ​

new Quat(x?, y?, z?, w?): Quat

Parameters ​

x? ​

number = 0

y? ​

number = 0

z? ​

number = 0

w? ​

number = 1

Returns ​

Quat

Properties ​

w ​

w: number

x ​

x: number

y ​

y: number

z ​

z: number

Methods ​

add() ​

add(q): Quat

Parameters ​

q ​

Quat

Returns ​

Quat

conjugate() ​

conjugate(): Quat

Returns the conjugate (inverse for unit quaternions).

Returns ​

Quat

copyMut() ​

copyMut(q): this

Copies components from another quaternion.

Parameters ​

q ​

Quat

Source quaternion

Returns ​

this

this for chaining

copyToArray() ​

copyToArray(arr, offset?): void

Parameters ​

arr ​

number[] | Float32Array<ArrayBufferLike>

offset? ​

number = 0

Returns ​

void

dot() ​

dot(q): number

Parameters ​

q ​

Quat

Returns ​

number

equals() ​

equals(q, epsilon?): boolean

Parameters ​

q ​

Quat

epsilon? ​

number = 0

Returns ​

boolean

forward() ​

forward(): Vec3

Returns ​

Vec3

invert() ​

invert(): Quat

Returns the inverse quaternion.

Returns ​

Quat

invertMut() ​

invertMut(): this

Inverts this quaternion in place.

Returns ​

this

this for chaining

length() ​

length(): number

Returns ​

number

lengthSq() ​

lengthSq(): number

Returns ​

number

lerp() ​

lerp(q, t): Quat

Linear interpolation (faster but doesn't preserve constant angular velocity).

Parameters ​

q ​

Quat

t ​

number

Returns ​

Quat

mul() ​

mul(s): Quat

Parameters ​

s ​

number

Returns ​

Quat

mulQuat() ​

mulQuat(q): Quat

Quaternion multiplication (this * q). Represents the composition of rotations: first q, then this.

Parameters ​

q ​

Quat

Returns ​

Quat

Example ​

ts
const rotX = Quat.fromAxisAngle(Vec3.right(), Math.PI / 4);
const rotY = Quat.fromAxisAngle(Vec3.up(), Math.PI / 4);
const combined = rotY.mulQuat(rotX);  // First X, then Y rotation

multiplyMut() ​

multiplyMut(q): this

Multiplies this quaternion by another in place (this = this * q).

Parameters ​

q ​

Quat

Quaternion to multiply with

Returns ​

this

this for chaining

mulVec3() ​

mulVec3(v): Vec3

Rotate a vector by this quaternion.

Parameters ​

v ​

Vec3

Vector to rotate

Returns ​

Vec3

Rotated vector

Example ​

ts
const rotation = Quat.fromAxisAngle(Vec3.up(), Math.PI / 2);
const forward = Vec3.forward();
const rotated = rotation.mulVec3(forward);  // Now points right

negate() ​

negate(): Quat

Returns ​

Quat

normalize() ​

normalize(): Quat

Returns ​

Quat

normalizeMut() ​

normalizeMut(): this

Normalizes this quaternion in place.

Returns ​

this

this for chaining

right(): Vec3

Returns ​

Vec3

rotateVec3Mut() ​

rotateVec3Mut(v): Vec3

Rotates a vector by this quaternion in place.

Parameters ​

v ​

Vec3

Vector to rotate (modified in place)

Returns ​

Vec3

v for chaining

rotateVec3Out() ​

rotateVec3Out(v, out): Vec3

Rotates a vector by this quaternion, writing result to out. Avoids allocation compared to mulVec3.

Parameters ​

v ​

Vec3

Vector to rotate

out ​

Vec3

Output vector

Returns ​

Vec3

out for chaining

setFromAxisAngleMut() ​

setFromAxisAngleMut(axis, angle): this

Sets this quaternion from an axis and angle in place.

Parameters ​

axis ​

Vec3

Normalized rotation axis

angle ​

number

Rotation angle in radians

Returns ​

this

this for chaining

setFromEulerMut() ​

setFromEulerMut(pitch, yaw, roll): this

Sets this quaternion from Euler angles in place.

Parameters ​

pitch ​

number

Rotation around X axis in radians

yaw ​

number

Rotation around Y axis in radians

roll ​

number

Rotation around Z axis in radians

Returns ​

this

this for chaining

setIdentityMut() ​

setIdentityMut(): this

Sets this quaternion to identity.

Returns ​

this

this for chaining

setMut() ​

setMut(x, y, z, w): this

Sets the components of this quaternion directly.

Parameters ​

x ​

number

X component

y ​

number

Y component

z ​

number

Z component

w ​

number

W (scalar) component

Returns ​

this

this for chaining

slerp() ​

slerp(q, t): Quat

Spherical linear interpolation (constant angular velocity).

Parameters ​

q ​

Quat

Target quaternion

t ​

number

Interpolation factor (0 = this, 1 = q)

Returns ​

Quat

Interpolated quaternion

Example ​

ts
const start = Quat.identity();
const end = Quat.fromAxisAngle(Vec3.up(), Math.PI);  // 180° turn
const halfway = start.slerp(end, 0.5);  // 90° turn

slerpFast() ​

slerpFast(q, t): Quat

Fast slerp instance method. Uses optimized paths for nearly-parallel quaternions.

Parameters ​

q ​

Quat

Target quaternion

t ​

number

Interpolation factor (0 = this, 1 = q)

Returns ​

Quat

New interpolated quaternion

slerpFastMut() ​

slerpFastMut(q, t): this

Fast slerp in place. Uses optimized paths for nearly-parallel quaternions.

Parameters ​

q ​

Quat

Target quaternion

t ​

number

Interpolation factor (0 = this, 1 = q)

Returns ​

this

this for chaining

slerpMut() ​

slerpMut(q, t): this

Spherical linear interpolation towards another quaternion in place.

Parameters ​

q ​

Quat

Target quaternion

t ​

number

Interpolation factor (0 = this, 1 = q)

Returns ​

this

this for chaining

sub() ​

sub(q): Quat

Parameters ​

q ​

Quat

Returns ​

Quat

toArray() ​

toArray(): [number, number, number, number]

Returns ​

[number, number, number, number]

toAxisAngle() ​

toAxisAngle(): object

Extract axis and angle from the quaternion.

Returns ​

object

angle ​

angle: number

axis ​

axis: Vec3

toEuler() ​

toEuler(): Vec3

Convert to Euler angles (ZYX order, yaw-pitch-roll). Returns [pitch, yaw, roll] in radians.

Returns ​

Vec3

toFloat32Array() ​

toFloat32Array(): Float32Array

Returns ​

Float32Array

toMat3() ​

toMat3(): Mat3

Convert to a 3x3 rotation matrix.

Returns ​

Mat3

toMat4() ​

toMat4(): Mat4

Convert to a 4x4 rotation matrix.

Returns ​

Mat4

toString() ​

toString(): string

Returns ​

string

up() ​

up(): Vec3

Returns ​

Vec3

fromArray() ​

static fromArray(arr, offset?): Quat

Parameters ​

arr ​

ArrayLike<number>

offset? ​

number = 0

Returns ​

Quat

fromAxes() ​

static fromAxes(xAxis, yAxis, zAxis): Quat

Creates a quaternion from three orthonormal basis vectors. The vectors define the X, Y, and Z axes of the rotation.

Parameters ​

xAxis ​

Vec3

The X axis of the rotation (right).

yAxis ​

Vec3

The Y axis of the rotation (up).

zAxis ​

Vec3

The Z axis of the rotation (forward).

Returns ​

Quat

fromAxisAngle() ​

static fromAxisAngle(axis, angle): Quat

Creates a quaternion from an axis and angle.

Parameters ​

axis ​

Vec3

Normalized rotation axis.

angle ​

number

Rotation angle in radians.

Returns ​

Quat

Example ​

ts
// Rotate 90 degrees around the Y axis
const rotation = Quat.fromAxisAngle(Vec3.up(), Math.PI / 2);

fromEuler() ​

static fromEuler(pitch, yaw, roll): Quat

Creates a quaternion from Euler angles (ZYX order, yaw-pitch-roll).

Parameters ​

pitch ​

number

Rotation around X axis in radians.

yaw ​

number

Rotation around Y axis in radians.

roll ​

number

Rotation around Z axis in radians.

Returns ​

Quat

Example ​

ts
// Look slightly down (pitch) and turn right (yaw)
const rotation = Quat.fromEuler(-0.2, Math.PI / 4, 0);

fromMat3() ​

static fromMat3(m): Quat

Creates a quaternion from a rotation matrix. Normalizes columns to handle scaled matrices correctly. Returns identity quaternion for degenerate matrices.

Parameters ​

m ​

Mat3

Returns ​

Quat

fromMat4() ​

static fromMat4(m): Quat

Creates a quaternion from a 4x4 transformation matrix. Extracts the rotation component (ignores translation and scale). Normalizes columns to handle scaled matrices correctly. Returns identity quaternion for degenerate matrices.

Parameters ​

m ​

Mat4

Returns ​

Quat

fromMat4Out() ​

static fromMat4Out(m, out): Quat

Writes a quaternion from a 4x4 transformation matrix into out. Extracts the rotation component (ignores translation and scale). Normalizes columns to handle scaled matrices correctly.

Parameters ​

m ​

Mat4

out ​

Quat

Returns ​

Quat

fromToRotation() ​

static fromToRotation(from, to): Quat

Creates a quaternion that rotates from one direction to another. Both vectors should be normalized.

Parameters ​

from ​

Vec3

to ​

Vec3

Returns ​

Quat

identity() ​

static identity(): Quat

Returns ​

Quat

invertOut() ​

static invertOut(q, out): Quat

Inverts a quaternion and writes the result to out.

Parameters ​

q ​

Quat

Quaternion to invert

out ​

Quat

Output quaternion

Returns ​

Quat

out for chaining

lookRotation() ​

static lookRotation(forward, up?): Quat

Creates a quaternion looking in the given direction.

Parameters ​

forward ​

Vec3

Forward direction (normalized).

up? ​

Vec3 = ...

Up vector (normalized).

Returns ​

Quat

multiplyOut() ​

static multiplyOut(a, b, out): Quat

Multiplies two quaternions and writes the result to out.

Parameters ​

a ​

Quat

First quaternion

b ​

Quat

Second quaternion

out ​

Quat

Output quaternion

Returns ​

Quat

out for chaining

normalizeOut() ​

static normalizeOut(q, out): Quat

Normalizes a quaternion and writes the result to out.

Parameters ​

q ​

Quat

Quaternion to normalize

out ​

Quat

Output quaternion

Returns ​

Quat

out for chaining

slerpFastOut() ​

static slerpFastOut(a, b, t, out): Quat

Fast spherical linear interpolation with optimized paths for common cases. Uses lerp for nearly-parallel quaternions and nlerp for moderately close ones. Best for animation blending where quaternions are typically close together.

Parameters ​

a ​

Quat

Start quaternion

b ​

Quat

End quaternion

t ​

number

Interpolation factor (0 = a, 1 = b)

out ​

Quat

Output quaternion

Returns ​

Quat

out for chaining

slerpOut() ​

static slerpOut(a, b, t, out): Quat

Spherical linear interpolation between two quaternions.

Parameters ​

a ​

Quat

Start quaternion

b ​

Quat

End quaternion

t ​

number

Interpolation factor (0 = a, 1 = b)

out ​

Quat

Output quaternion

Returns ​

Quat

out for chaining

Proprietary software. All rights reserved.

Copyright 2025-present Web Engine Dev