or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

common.md index.md matrices.md quaternions.md vectors.md

tile.json

Quaternion Operations

Comprehensive quaternion and dual quaternion operations for efficient 3D rotations and transformations. Quaternions provide a compact, singularity-free representation of 3D rotations that avoid gimbal lock and enable smooth interpolation.

Capabilities

Quaternion Operations (quat)

Operations for 4-component quaternions representing 3D rotations. Quaternions are represented as [x, y, z, w] where w is the scalar component.

Core Functions

/**
 * Creates a new identity quaternion
 * @returns New identity quaternion [0, 0, 0, 1]
 */
function create(): quat;

/**
 * Set a quaternion to the identity quaternion
 * @param out - Receiving quaternion
 * @returns out parameter
 */
function identity(out: quat): quat;

/**
 * Creates a new quaternion from an existing quaternion
 * @param a - Quaternion to clone
 * @returns New quaternion with copied values
 */
function clone(a: ReadonlyQuat): quat;

/**
 * Creates a new quaternion initialized with the given values
 * @param x - X component
 * @param y - Y component
 * @param z - Z component
 * @param w - W component
 * @returns New quaternion with specified values
 */
function fromValues(x: number, y: number, z: number, w: number): quat;

/**
 * Copy values from one quaternion to another
 * @param out - Receiving quaternion
 * @param a - Source quaternion
 * @returns out parameter
 */
function copy(out: quat, a: ReadonlyQuat): quat;

/**
 * Set the components of a quaternion to the given values
 * @param out - Receiving quaternion
 * @param x - X component
 * @param y - Y component
 * @param z - Z component
 * @param w - W component
 * @returns out parameter
 */
function set(out: quat, x: number, y: number, z: number, w: number): quat;

Axis-Angle Operations

/**
 * Sets a quaternion from the given angle and rotation axis
 * @param out - Receiving quaternion
 * @param axis - Axis of rotation
 * @param rad - Angle in radians
 * @returns out parameter
 */
function setAxisAngle(out: quat, axis: ReadonlyVec3, rad: number): quat;

/**
 * Gets the rotation axis and angle for a given quaternion
 * @param out_axis - Receiving rotation axis
 * @param q - Quaternion to be decomposed
 * @returns Rotation angle in radians
 */
function getAxisAngle(out_axis: vec3, q: ReadonlyQuat): number;

/**
 * Gets the angular distance between two unit quaternions
 * @param a - Origin quaternion
 * @param b - Destination quaternion
 * @returns Angular distance in radians
 */
function getAngle(a: ReadonlyQuat, b: ReadonlyQuat): number;

Quaternion Math Operations

/**
 * Multiplies two quaternions
 * @param out - Receiving quaternion
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function multiply(out: quat, a: ReadonlyQuat, b: ReadonlyQuat): quat;

/**
 * Rotates a quaternion by the given angle around the X axis
 * @param out - Receiving quaternion
 * @param a - Quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateX(out: quat, a: ReadonlyQuat, rad: number): quat;

/**
 * Rotates a quaternion by the given angle around the Y axis
 * @param out - Receiving quaternion
 * @param a - Quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateY(out: quat, a: ReadonlyQuat, rad: number): quat;

/**
 * Rotates a quaternion by the given angle around the Z axis
 * @param out - Receiving quaternion
 * @param a - Quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateZ(out: quat, a: ReadonlyQuat, rad: number): quat;

/**
 * Calculates the W component of a quaternion from the X, Y, and Z components
 * @param out - Receiving quaternion
 * @param a - Quaternion to calculate W for
 * @returns out parameter
 */
function calculateW(out: quat, a: ReadonlyQuat): quat;

/**
 * Calculate the exponential of a unit quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to calculate exponential of
 * @returns out parameter
 */
function exp(out: quat, a: ReadonlyQuat): quat;

/**
 * Calculate the natural logarithm of a unit quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to calculate logarithm of
 * @returns out parameter
 */
function ln(out: quat, a: ReadonlyQuat): quat;

/**
 * Calculate the scalar power of a unit quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to raise to power
 * @param b - Scalar power
 * @returns out parameter
 */
function pow(out: quat, a: ReadonlyQuat, b: number): quat;

/**
 * Calculates the inverse of a quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to calculate inverse of
 * @returns out parameter
 */
function invert(out: quat, a: ReadonlyQuat): quat;

/**
 * Calculates the conjugate of a quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to calculate conjugate of
 * @returns out parameter
 */
function conjugate(out: quat, a: ReadonlyQuat): quat;

Interpolation

/**
 * Performs a spherical linear interpolation between two quaternions
 * @param out - Receiving quaternion
 * @param a - First operand
 * @param b - Second operand
 * @param t - Interpolation amount (0.0 - 1.0)
 * @returns out parameter
 */
function slerp(out: quat, a: ReadonlyQuat, b: ReadonlyQuat, t: number): quat;

/**
 * Performs a linear interpolation between two quaternions
 * @param out - Receiving quaternion
 * @param a - First operand
 * @param b - Second operand
 * @param t - Interpolation amount (0.0 - 1.0)
 * @returns out parameter
 */
function lerp(out: quat, a: ReadonlyQuat, b: ReadonlyQuat, t: number): quat;

/**
 * Performs a spherical linear interpolation with two control points
 * @param out - Receiving quaternion
 * @param a - First operand
 * @param b - Second operand
 * @param c - Third operand
 * @param d - Fourth operand
 * @param t - Interpolation amount (0.0 - 1.0)
 * @returns out parameter
 */
function sqlerp(out: quat, a: ReadonlyQuat, b: ReadonlyQuat, c: ReadonlyQuat, d: ReadonlyQuat, t: number): quat;

Conversion Functions

/**
 * Creates a quaternion from the given 3x3 rotation matrix
 * @param out - Receiving quaternion
 * @param m - Rotation matrix
 * @returns out parameter
 */
function fromMat3(out: quat, m: ReadonlyMat3): quat;

/**
 * Creates a quaternion from the given Euler angles
 * @param out - Receiving quaternion
 * @param x - Rotation around X axis in radians
 * @param y - Rotation around Y axis in radians
 * @param z - Rotation around Z axis in radians
 * @param order - Rotation order (default: "xyz")
 * @returns out parameter
 */
function fromEuler(out: quat, x: number, y: number, z: number, order?: string): quat;

Utility Functions

/**
 * Generates a random unit quaternion
 * @param out - Receiving quaternion
 * @returns out parameter
 */
function random(out: quat): quat;

/**
 * Sets a quaternion to represent the shortest rotation from one vector to another
 * @param out - Receiving quaternion
 * @param a - Origin vector
 * @param b - Destination vector
 * @returns out parameter
 */
function rotationTo(out: quat, a: ReadonlyVec3, b: ReadonlyVec3): quat;

/**
 * Sets a quaternion from the given direction vectors
 * @param out - Receiving quaternion
 * @param view - Forward direction vector
 * @param right - Right direction vector
 * @param up - Up direction vector
 * @returns out parameter
 */
function setAxes(out: quat, view: ReadonlyVec3, right: ReadonlyVec3, up: ReadonlyVec3): quat;

/**
 * Returns a string representation of a quaternion
 * @param a - Quaternion to represent in string form
 * @returns String representation of the quaternion
 */
function str(a: ReadonlyQuat): string;

/**
 * Returns whether or not the quaternions have exactly the same elements
 * @param a - First quaternion
 * @param b - Second quaternion
 * @returns True if the quaternions are equal, false otherwise
 */
function exactEquals(a: ReadonlyQuat, b: ReadonlyQuat): boolean;

/**
 * Returns whether or not the quaternions have approximately the same elements
 * @param a - First quaternion
 * @param b - Second quaternion
 * @returns True if the quaternions are equal, false otherwise
 */
function equals(a: ReadonlyQuat, b: ReadonlyQuat): boolean;

Inherited Vector Operations

Quaternions inherit several operations from vec4:

/**
 * Adds two quaternions
 * @param out - Receiving quaternion
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function add(out: quat, a: ReadonlyQuat, b: ReadonlyQuat): quat;

/**
 * Scales a quaternion by a scalar number
 * @param out - Receiving quaternion
 * @param a - Quaternion to scale
 * @param b - Amount to scale by
 * @returns out parameter
 */
function scale(out: quat, a: ReadonlyQuat, b: number): quat;

/**
 * Calculates the dot product of two quaternions
 * @param a - First operand
 * @param b - Second operand
 * @returns Dot product of a and b
 */
function dot(a: ReadonlyQuat, b: ReadonlyQuat): number;

/**
 * Calculates the length of a quaternion
 * @param a - Quaternion to calculate length of
 * @returns Length of the quaternion
 */
function length(a: ReadonlyQuat): number;

/**
 * Calculates the squared length of a quaternion
 * @param a - Quaternion to calculate length of
 * @returns Squared length of the quaternion
 */
function squaredLength(a: ReadonlyQuat): number;

/**
 * Normalize a quaternion
 * @param out - Receiving quaternion
 * @param a - Quaternion to normalize
 * @returns out parameter
 */
function normalize(out: quat, a: ReadonlyQuat): quat;

Dual Quaternion Operations (quat2)

Operations for dual quaternions which represent both rotation and translation in a single 8-component structure. Dual quaternions are represented as [real_x, real_y, real_z, real_w, dual_x, dual_y, dual_z, dual_w].

Core Functions

/**
 * Creates a new dual quaternion
 * @returns New dual quaternion initialized to identity
 */
function create(): quat2;

/**
 * Creates a new dual quaternion from an existing dual quaternion
 * @param a - Dual quaternion to clone
 * @returns New dual quaternion with copied values
 */
function clone(a: ReadonlyQuat2): quat2;

/**
 * Creates a new dual quaternion initialized with the given values
 * @param x1-w2 - Eight dual quaternion components
 * @returns New dual quaternion with specified values
 */
function fromValues(x1: number, y1: number, z1: number, w1: number, x2: number, y2: number, z2: number, w2: number): quat2;

/**
 * Creates a dual quaternion from rotation and translation values
 * @param x1-z2 - Rotation and translation components
 * @returns New dual quaternion
 */
function fromRotationTranslationValues(x1: number, y1: number, z1: number, w1: number, x2: number, y2: number, z2: number): quat2;

/**
 * Creates a dual quaternion from a quaternion and a translation vector
 * @param out - Receiving dual quaternion
 * @param q - Rotation quaternion
 * @param t - Translation vector
 * @returns out parameter
 */
function fromRotationTranslation(out: quat2, q: ReadonlyQuat, t: ReadonlyVec3): quat2;

/**
 * Creates a dual quaternion from a translation vector
 * @param out - Receiving dual quaternion
 * @param t - Translation vector
 * @returns out parameter
 */
function fromTranslation(out: quat2, t: ReadonlyVec3): quat2;

/**
 * Creates a dual quaternion from a quaternion
 * @param out - Receiving dual quaternion
 * @param q - Quaternion
 * @returns out parameter
 */
function fromRotation(out: quat2, q: ReadonlyQuat): quat2;

/**
 * Creates a dual quaternion from a 4x4 matrix
 * @param out - Receiving dual quaternion
 * @param a - Transformation matrix
 * @returns out parameter
 */
function fromMat4(out: quat2, a: ReadonlyMat4): quat2;

/**
 * Copy values from one dual quaternion to another
 * @param out - Receiving dual quaternion
 * @param a - Source dual quaternion
 * @returns out parameter
 */
function copy(out: quat2, a: ReadonlyQuat2): quat2;

/**
 * Set a dual quaternion to the identity dual quaternion
 * @param out - Receiving dual quaternion
 * @returns out parameter
 */
function identity(out: quat2): quat2;

/**
 * Set the components of a dual quaternion to the given values
 * @param out - Receiving dual quaternion
 * @param x1-w2 - Eight dual quaternion components
 * @returns out parameter
 */
function set(out: quat2, x1: number, y1: number, z1: number, w1: number, x2: number, y2: number, z2: number, w2: number): quat2;

Component Access

/**
 * Gets the real part of a dual quaternion
 * @param out - Receiving quaternion
 * @param a - Dual quaternion
 * @returns out parameter
 */
function getReal(out: quat, a: ReadonlyQuat2): quat;

/**
 * Gets the dual part of a dual quaternion
 * @param out - Receiving quaternion
 * @param a - Dual quaternion
 * @returns out parameter
 */
function getDual(out: quat, a: ReadonlyQuat2): quat;

/**
 * Sets the real part of a dual quaternion
 * @param out - Receiving dual quaternion
 * @param q - Quaternion to set as real part
 * @returns out parameter
 */
function setReal(out: quat2, q: ReadonlyQuat): quat2;

/**
 * Sets the dual part of a dual quaternion
 * @param out - Receiving dual quaternion
 * @param q - Quaternion to set as dual part
 * @returns out parameter
 */
function setDual(out: quat2, q: ReadonlyQuat): quat2;

/**
 * Gets the translation of a normalized dual quaternion
 * @param out - Receiving translation vector
 * @param a - Dual quaternion to be decomposed
 * @returns out parameter
 */
function getTranslation(out: vec3, a: ReadonlyQuat2): vec3;

Dual Quaternion Operations

/**
 * Translates a dual quaternion by the given vector
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to translate
 * @param v - Vector to translate by
 * @returns out parameter
 */
function translate(out: quat2, a: ReadonlyQuat2, v: ReadonlyVec3): quat2;

/**
 * Rotates a dual quaternion around the X axis
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateX(out: quat2, a: ReadonlyQuat2, rad: number): quat2;

/**
 * Rotates a dual quaternion around the Y axis
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateY(out: quat2, a: ReadonlyQuat2, rad: number): quat2;

/**
 * Rotates a dual quaternion around the Z axis
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to rotate
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateZ(out: quat2, a: ReadonlyQuat2, rad: number): quat2;

/**
 * Rotates a dual quaternion by a given quaternion (multiplication order: q * a)
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to rotate
 * @param q - Quaternion to rotate by
 * @returns out parameter
 */
function rotateByQuatAppend(out: quat2, a: ReadonlyQuat2, q: ReadonlyQuat): quat2;

/**
 * Rotates a dual quaternion by a given quaternion (multiplication order: a * q)
 * @param out - Receiving dual quaternion
 * @param q - Quaternion to rotate by
 * @param a - Dual quaternion to rotate
 * @returns out parameter
 */
function rotateByQuatPrepend(out: quat2, q: ReadonlyQuat, a: ReadonlyQuat2): quat2;

/**
 * Rotates a dual quaternion around a given axis
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to rotate
 * @param axis - Axis to rotate around
 * @param rad - Angle in radians
 * @returns out parameter
 */
function rotateAroundAxis(out: quat2, a: ReadonlyQuat2, axis: ReadonlyVec3, rad: number): quat2;

Dual Quaternion Math

/**
 * Adds two dual quaternions
 * @param out - Receiving dual quaternion
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function add(out: quat2, a: ReadonlyQuat2, b: ReadonlyQuat2): quat2;

/**
 * Multiplies two dual quaternions
 * @param out - Receiving dual quaternion
 * @param a - First operand
 * @param b - Second operand
 * @returns out parameter
 */
function multiply(out: quat2, a: ReadonlyQuat2, b: ReadonlyQuat2): quat2;

/**
 * Scales a dual quaternion by a scalar number
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to scale
 * @param b - Amount to scale by
 * @returns out parameter
 */
function scale(out: quat2, a: ReadonlyQuat2, b: number): quat2;

/**
 * Performs a linear interpolation between two dual quaternions
 * @param out - Receiving dual quaternion
 * @param a - First operand
 * @param b - Second operand
 * @param t - Interpolation amount (0.0 - 1.0)
 * @returns out parameter
 */
function lerp(out: quat2, a: ReadonlyQuat2, b: ReadonlyQuat2, t: number): quat2;

/**
 * Calculates the inverse of a dual quaternion
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to calculate inverse of
 * @returns out parameter
 */
function invert(out: quat2, a: ReadonlyQuat2): quat2;

/**
 * Calculates the conjugate of a dual quaternion
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to calculate conjugate of
 * @returns out parameter
 */
function conjugate(out: quat2, a: ReadonlyQuat2): quat2;

/**
 * Normalize a dual quaternion
 * @param out - Receiving dual quaternion
 * @param a - Dual quaternion to normalize
 * @returns out parameter
 */
function normalize(out: quat2, a: ReadonlyQuat2): quat2;

Utility Functions

/**
 * Returns a string representation of a dual quaternion
 * @param a - Dual quaternion to represent in string form
 * @returns String representation of the dual quaternion
 */
function str(a: ReadonlyQuat2): string;

/**
 * Returns whether or not the dual quaternions have exactly the same elements
 * @param a - First dual quaternion
 * @param b - Second dual quaternion
 * @returns True if the dual quaternions are equal, false otherwise
 */
function exactEquals(a: ReadonlyQuat2, b: ReadonlyQuat2): boolean;

/**
 * Returns whether or not the dual quaternions have approximately the same elements
 * @param a - First dual quaternion
 * @param b - Second dual quaternion
 * @returns True if the dual quaternions are equal, false otherwise
 */
function equals(a: ReadonlyQuat2, b: ReadonlyQuat2): boolean;

Inherited Quaternion Operations

Dual quaternions inherit several operations from regular quaternions:

/**
 * Calculates the dot product of two dual quaternions
 * @param a - First operand
 * @param b - Second operand
 * @returns Dot product of a and b
 */
function dot(a: ReadonlyQuat2, b: ReadonlyQuat2): number;

/**
 * Calculates the length of a dual quaternion
 * @param a - Dual quaternion to calculate length of
 * @returns Length of the dual quaternion
 */
function length(a: ReadonlyQuat2): number;

/**
 * Calculates the squared length of a dual quaternion
 * @param a - Dual quaternion to calculate length of
 * @returns Squared length of the dual quaternion
 */
function squaredLength(a: ReadonlyQuat2): number;

Usage Examples

import { quat, quat2, vec3, mat3 } from "gl-matrix";

// Basic quaternion operations
const rotation = quat.create();
quat.setAxisAngle(rotation, [0, 1, 0], Math.PI / 4); // 45 degrees around Y-axis

// Convert from Euler angles
const eulerRotation = quat.create();
quat.fromEuler(eulerRotation, 0, 45, 0); // 45 degrees Y rotation

// Quaternion multiplication (composition)
const combined = quat.create();
quat.multiply(combined, rotation, eulerRotation);

// Spherical interpolation
const start = quat.create();
const end = quat.create();
quat.setAxisAngle(start, [1, 0, 0], 0);
quat.setAxisAngle(end, [1, 0, 0], Math.PI / 2);

const interpolated = quat.create();
quat.slerp(interpolated, start, end, 0.5); // 50% interpolation

// Convert to matrix
const rotationMatrix = mat3.create();
mat3.fromQuat(rotationMatrix, rotation);

// Dual quaternions for combined rotation and translation
const dq = quat2.create();
const translation = vec3.fromValues(1, 2, 3);
quat2.fromRotationTranslation(dq, rotation, translation);

// Transform with dual quaternion
const newTranslation = vec3.create();
quat2.getTranslation(newTranslation, dq);

// Dual quaternion interpolation
const dq1 = quat2.create();
const dq2 = quat2.create();
quat2.fromTranslation(dq1, [0, 0, 0]);
quat2.fromTranslation(dq2, [10, 0, 0]);

const interpolatedDQ = quat2.create();
quat2.lerp(interpolatedDQ, dq1, dq2, 0.5);

Aliases

Quaternion modules provide convenient aliases:

quat aliases:

mul - alias for multiply
len - alias for length
sqrLen - alias for squaredLength

quat2 aliases:

mul - alias for multiply
len - alias for length
sqrLen - alias for squaredLength

Version

Tile

Files

quaternions.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Quaternion Operations

Capabilities

Quaternion Operations (quat)

Core Functions

Axis-Angle Operations

Quaternion Math Operations

Interpolation

Conversion Functions

Utility Functions

Inherited Vector Operations

Dual Quaternion Operations (quat2)

Core Functions

Component Access

Dual Quaternion Operations

Dual Quaternion Math

Utility Functions

Inherited Quaternion Operations

Usage Examples

Aliases

quaternions.mddocs/