Quaternion Operations

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

/**
 * 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;

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);