math 0.0.0 → 0.1.0

package/dist/src/core/quat2.d.ts

@@ -0,0 +1,344 @@
+import type { Mat4 } from './mat4.js';
+import type { Quat } from './quat.js';
+import type { Vec3 } from './vec3.js';
+/** A dual quaternion that represents both rotation and translation */
+export type Quat2 = [x: number, y: number, z: number, w: number, x2: number, y2: number, z2: number, w2: number];
+/**
+ * Creates a new identity dual quat
+ *
+ * @returns a new dual quaternion [real -> rotation, dual -> translation]
+ */
+export declare function create(): Quat2;
+/**
+ * Creates a new quat initialized with values from an existing quaternion
+ *
+ * @param a dual quaternion to clone
+ * @returns new dual quaternion
+ * @function
+ */
+export declare function clone(a: Quat2): Quat2;
+/**
+ * Creates a new dual quat initialized with the given values
+ *
+ * @param x1 X component
+ * @param y1 Y component
+ * @param z1 Z component
+ * @param w1 W component
+ * @param x2 X component
+ * @param y2 Y component
+ * @param z2 Z component
+ * @param w2 W component
+ * @returns new dual quaternion
+ * @function
+ */
+export declare function fromValues(x1: number, y1: number, z1: number, w1: number, x2: number, y2: number, z2: number, w2: number): Quat2;
+/**
+ * Creates a new dual quat from the given values (quat and translation)
+ *
+ * @param x1 X component
+ * @param y1 Y component
+ * @param z1 Z component
+ * @param w1 W component
+ * @param x2 X component (translation)
+ * @param y2 Y component (translation)
+ * @param z2 Z component (translation)
+ * @returns new dual quaternion
+ * @function
+ */
+export declare function fromRotationTranslationValues(x1: number, y1: number, z1: number, w1: number, x2: number, y2: number, z2: number): Quat2;
+/**
+ * Creates a dual quat from a quaternion and a translation
+ *
+ * @param out dual quaternion receiving operation result
+ * @param q a normalized quaternion
+ * @param t translation vector
+ * @returns dual quaternion receiving operation result
+ * @function
+ */
+export declare function fromRotationTranslation(out: Quat2, q: Quat, t: Vec3): Quat2;
+/**
+ * Creates a dual quat from a translation
+ *
+ * @param out dual quaternion receiving operation result
+ * @param t translation vector
+ * @returns dual quaternion receiving operation result
+ * @function
+ */
+export declare function fromTranslation(out: Quat2, t: Vec3): Quat2;
+/**
+ * Creates a dual quat from a quaternion
+ *
+ * @param out dual quaternion receiving operation result
+ * @param q the quaternion
+ * @returns dual quaternion receiving operation result
+ * @function
+ */
+export declare function fromRotation(out: Quat2, q: Quat): Quat2;
+/**
+ * Creates a new dual quat from a matrix (4x4)
+ *
+ * @param out the dual quaternion
+ * @param a the matrix
+ * @returns dual quat receiving operation result
+ */
+export declare function fromMat4(out: Quat2, a: Mat4): Quat2;
+/**
+ * Copy the values from one dual quat to another
+ *
+ * @param out the receiving dual quaternion
+ * @param a the source dual quaternion
+ * @returns out
+ * @function
+ */
+export declare function copy(out: Quat2, a: Quat2): Quat2;
+/**
+ * Set a dual quat to the identity dual quaternion
+ *
+ * @param out the receiving quaternion
+ * @returns out
+ */
+export declare function identity(out: Quat2): Quat2;
+/**
+ * Set the components of a dual quat to the given values
+ *
+ * @param out the receiving quaternion
+ * @param x1 X component
+ * @param y1 Y component
+ * @param z1 Z component
+ * @param w1 W component
+ * @param x2 X component
+ * @param y2 Y component
+ * @param z2 Z component
+ * @param w2 W component
+ * @returns out
+ * @function
+ */
+export declare 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 quat
+ * @param  out real part
+ * @param  a Dual Quaternion
+ * @return real part
+ */
+export declare function getReal(out: Quat, a: Quat2): Quat;
+/**
+ * Gets the dual part of a dual quat
+ * @param  out dual part
+ * @param  a Dual Quaternion
+ * @return dual part
+ */
+export declare function getDual(out: Quat, a: Quat2): Quat;
+/**
+ * Set the real component of a dual quat to the given quaternion
+ *
+ * @param out the receiving dual quaternion
+ * @param q a quaternion representing the real part
+ * @returns out
+ */
+export declare function setReal(out: Quat2, q: Quat): Quat2;
+/**
+ * Set the dual component of a dual quat to the given quaternion
+ *
+ * @param out the receiving quaternion
+ * @param q a quaternion representing the dual part
+ * @returns out
+ * @function
+ */
+export declare function setDual(out: Quat2, q: Quat): Quat2;
+/**
+ * Gets the translation of a normalized dual quat
+ * @param  out translation
+ * @param  a Dual Quaternion to be decomposed
+ * @return translation
+ */
+export declare function getTranslation(out: Vec3, a: Quat2): Vec3;
+/**
+ * Translates a dual quat by the given vector
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to translate
+ * @param v vector to translate by
+ * @returns out
+ */
+export declare function translate(out: Quat2, a: Quat2, v: Vec3): Quat2;
+/**
+ * Rotates a dual quat around the X axis
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to rotate
+ * @param rad how far should the rotation be
+ * @returns out
+ */
+export declare function rotateX(out: Quat2, a: Quat2, rad: number): Quat2;
+/**
+ * Rotates a dual quat around the Y axis
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to rotate
+ * @param rad how far should the rotation be
+ * @returns out
+ */
+export declare function rotateY(out: Quat2, a: Quat2, rad: number): Quat2;
+/**
+ * Rotates a dual quat around the Z axis
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to rotate
+ * @param rad how far should the rotation be
+ * @returns out
+ */
+export declare function rotateZ(out: Quat2, a: Quat2, rad: number): Quat2;
+/**
+ * Rotates a dual quat by a given quaternion (a * q)
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to rotate
+ * @param q quaternion to rotate by
+ * @returns out
+ */
+export declare function rotateByQuatAppend(out: Quat2, a: Quat2, q: Quat): Quat2;
+/**
+ * Rotates a dual quat by a given quaternion (q * a)
+ *
+ * @param out the receiving dual quaternion
+ * @param q quaternion to rotate by
+ * @param a the dual quaternion to rotate
+ * @returns out
+ */
+export declare function rotateByQuatPrepend(out: Quat2, q: Quat, a: Quat2): Quat2;
+/**
+ * Rotates a dual quat around a given axis. Does the normalisation automatically
+ *
+ * @param out the receiving dual quaternion
+ * @param a the dual quaternion to rotate
+ * @param axis the axis to rotate around
+ * @param rad how far the rotation should be
+ * @returns out
+ */
+export declare function rotateAroundAxis(out: Quat2, a: Quat2, axis: Vec3, rad: number): Quat2;
+/**
+ * Adds two dual quat's
+ *
+ * @param out the receiving dual quaternion
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ * @function
+ */
+export declare function add(out: Quat2, a: Quat2, b: Quat2): Quat2;
+/**
+ * Multiplies two dual quat's
+ *
+ * @param out the receiving dual quaternion
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function multiply(out: Quat2, a: Quat2, b: Quat2): Quat2;
+/**
+ * Alias for {@link quat2.multiply}
+ * @function
+ */
+export declare const mul: typeof multiply;
+/**
+ * Scales a dual quat by a scalar number
+ *
+ * @param out the receiving dual quat
+ * @param a the dual quat to scale
+ * @param b amount to scale the dual quat by
+ * @returns out
+ * @function
+ */
+export declare function scale(out: Quat2, a: Quat2, b: number): Quat2;
+/**
+ * Calculates the dot product of two dual quat's (The dot product of the real parts)
+ *
+ * @param a the first operand
+ * @param b the second operand
+ * @returns dot product of a and b
+ */
+export declare function dot(a: Quat2, b: Quat2): number;
+/**
+ * Performs a linear interpolation between two dual quats's
+ * NOTE: The resulting dual quaternions won't always be normalized (The error is most noticeable when t = 0.5)
+ *
+ * @param out the receiving dual quat
+ * @param a the first operand
+ * @param b the second operand
+ * @param t interpolation amount, in the range [0-1], between the two inputs
+ * @returns out
+ */
+export declare function lerp(out: Quat2, a: Quat2, b: Quat2, t: number): Quat2;
+/**
+ * Calculates the inverse of a dual quat. If they are normalized, conjugate is cheaper
+ *
+ * @param out the receiving dual quaternion
+ * @param a dual quat to calculate inverse of
+ * @returns out
+ */
+export declare function invert(out: Quat2, a: Quat2): Quat2;
+/**
+ * Calculates the conjugate of a dual quat
+ * If the dual quaternion is normalized, this function is faster than quat2.inverse and produces the same result.
+ *
+ * @param out the receiving quaternion
+ * @param a quat to calculate conjugate of
+ * @returns out
+ */
+export declare function conjugate(out: Quat2, a: Quat2): Quat2;
+/**
+ * Calculates the length of a dual quat (the length of its real/rotation part)
+ *
+ * @param a dual quat to calculate length of
+ * @returns length of a
+ */
+export declare function length(a: Quat2): number;
+/**
+ * Alias for {@link quat2.length}
+ * @function
+ */
+export declare const len: typeof length;
+/**
+ * Calculates the squared length of a dual quat (the squared length of its real/rotation part)
+ *
+ * @param a dual quat to calculate squared length of
+ * @returns squared length of a
+ */
+export declare function squaredLength(a: Quat2): number;
+/**
+ * Alias for {@link quat2.squaredLength}
+ * @function
+ */
+export declare const sqrLen: typeof squaredLength;
+/**
+ * Normalize a dual quat
+ *
+ * @param out the receiving dual quaternion
+ * @param a dual quaternion to normalize
+ * @returns out
+ * @function
+ */
+export declare function normalize(out: Quat2, a: Quat2): Quat2;
+/**
+ * Returns a string representation of a dual quaternion
+ *
+ * @param a dual quaternion to represent as a string
+ * @returns string representation of the dual quat
+ */
+export declare function str(a: Quat2): string;
+/**
+ * Returns whether or not the dual quaternions have exactly the same elements in the same position (when compared with ===)
+ *
+ * @param a the first dual quaternion.
+ * @param b the second dual quaternion.
+ * @returns true if the dual quaternions are equal, false otherwise.
+ */
+export declare function exactEquals(a: Quat2, b: Quat2): boolean;
+/**
+ * Returns whether or not the dual quaternions have approximately the same elements in the same position.
+ *
+ * @param a the first dual quat.
+ * @param b the second dual quat.
+ * @returns true if the dual quats are equal, false otherwise.
+ */
+export declare function equals(a: Quat2, b: Quat2): boolean;

package/dist/src/core/scalar.d.ts

@@ -0,0 +1,75 @@
+export declare const EPSILON = 0.000001;
+/**
+ * Symmetric round
+ * see https://www.npmjs.com/package/round-half-up-symmetric#user-content-detailed-background
+ *
+ * @param a value to round
+ */
+export declare function round(a: number): number;
+/**
+ * Tests whether or not the arguments have approximately the same value, within an absolute
+ * or relative tolerance of glMatrix.EPSILON (an absolute tolerance is used for values less
+ * than or equal to 1.0, and a relative tolerance is used for larger values)
+ *
+ * @param a The first number to test.
+ * @param b The second number to test.
+ * @returns True if the numbers are approximately equal, false otherwise.
+ */
+export declare function equals(a: number, b: number, epsilon?: number): boolean;
+/**
+ * Ease-in-out, goes to -Infinite before 0 and Infinite after 1
+ *
+ * https://www.desmos.com/calculator/vsnmlaljdu
+ *
+ * @param t
+ * @returns
+ */
+export declare function fade(t: number): number;
+/**
+ *
+ * Returns the result of linearly interpolating between input A and input B by input T.
+ *
+ * @param v0
+ * @param v1
+ * @param t
+ * @returns
+ */
+export declare function lerp(v0: number, v1: number, t: number): number;
+/**
+ *
+ * Quadratic interpolation through three values using Lagrange interpolation.
+ * Passes through v0 at t=0, v1 at t=0.5, and v2 at t=1.
+ *
+ * @param v0 value at t=0
+ * @param v1 value at t=0.5
+ * @param v2 value at t=1
+ * @param t
+ * @returns
+ */
+export declare function lagrange(v0: number, v1: number, v2: number, t: number): number;
+/**
+ *
+ * Binomial coefficient, "n choose k": the number of ways to choose k items
+ * from a set of n without order or repetition.
+ *
+ * @param n total number of items
+ * @param k number of items to choose
+ * @returns the binomial coefficient, or 0 when k is out of range
+ */
+export declare function binomial(n: number, k: number): number;
+/**
+ * Clamp a value between min and max
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Loops `t` so that it is never larger than `length` and never smaller than 0.
+ */
+export declare function repeat(t: number, length: number): number;
+/**
+ * Remaps a number from one range to another.
+ */
+export declare function remap(number: number, inLow: number, inHigh: number, outLow: number, outHigh: number): number;
+/**
+ * Remaps a number from one range to another, clamping the result to the output range.
+ */
+export declare function remapClamp(value: number, inLow: number, inHigh: number, outLow: number, outHigh: number): number;

package/dist/src/core/spherical.d.ts

@@ -0,0 +1,165 @@
+import type { Vec2 } from './vec2.js';
+import type { Vec3 } from './vec3.js';
+/**
+ * A point in spherical coordinates [r, theta, phi] (Three.js / OpenGL convention)
+ *  r     - radial distance from the origin
+ *  theta - azimuthal angle in the XZ plane from the +Z axis (radians, range [-π, π])
+ *  phi   - polar angle from the +Y axis (radians, range [0, π])
+ */
+export type Spherical = [r: number, theta: number, phi: number];
+/**
+ * Creates a new spherical coordinate at r=1, theta=0, phi=0
+ *
+ * @returns a new Spherical
+ */
+export declare function create(): Spherical;
+/**
+ * Creates a new Spherical initialized with the given values
+ *
+ * @param r radial distance
+ * @param theta azimuthal angle in the XZ plane from +Z (radians)
+ * @param phi polar angle from +Y axis (radians)
+ * @returns a new Spherical
+ */
+export declare function fromValues(r: number, theta: number, phi: number): Spherical;
+/**
+ * Creates a new Spherical initialized with values from an existing one
+ *
+ * @param a the source Spherical
+ * @returns a new Spherical
+ */
+export declare function clone(a: Spherical): Spherical;
+/**
+ * Copies values from one Spherical to another
+ *
+ * @param out the receiving Spherical
+ * @param a the source Spherical
+ * @returns out
+ */
+export declare function copy(out: Spherical, a: Spherical): Spherical;
+/**
+ * Sets the components of a Spherical
+ *
+ * @param out the receiving Spherical
+ * @param r radial distance
+ * @param theta azimuthal angle in the XZ plane from +Z (radians)
+ * @param phi polar angle from +Y axis (radians)
+ * @returns out
+ */
+export declare function set(out: Spherical, r: number, theta: number, phi: number): Spherical;
+/**
+ * Sets r=1, preserving the angles. No-op if r is already zero.
+ *
+ * @param out the receiving Spherical
+ * @param a the source Spherical
+ * @returns out
+ */
+export declare function normalize(out: Spherical, a: Spherical): Spherical;
+/**
+ * Scales the radial distance r by a scalar
+ *
+ * @param out the receiving Spherical
+ * @param a the source Spherical
+ * @param s scalar to multiply r by
+ * @returns out
+ */
+export declare function scale(out: Spherical, a: Spherical, s: number): Spherical;
+/**
+ * Linearly interpolates between two Spherical coordinates taking the shortest
+ * angular path for theta and phi.
+ *
+ * @param out the receiving Spherical
+ * @param a the first operand
+ * @param b the second operand
+ * @param t interpolation factor in [0, 1]
+ * @returns out
+ */
+export declare function lerp(out: Spherical, a: Spherical, b: Spherical, t: number): Spherical;
+/**
+ * Sets a Spherical from Cartesian Vec3 coordinates (Three.js / OpenGL convention):
+ *   r     = sqrt(x² + y² + z²)
+ *   theta = atan2(x, z)   (azimuthal angle in XZ plane from +Z)
+ *   phi   = acos(y / r)   (polar angle from +Y)
+ *
+ * @param out the receiving Spherical
+ * @param v the source Vec3
+ * @returns out
+ */
+export declare function setFromVec3(out: Spherical, v: Vec3): Spherical;
+/** @alias setFromVec3 */
+export declare const fromVec3: typeof setFromVec3;
+/**
+ * Clamps phi to the range [EPSILON, π - EPSILON] to avoid coordinate
+ * singularities at the poles (gimbal lock / division by zero).
+ * r and theta are left unchanged.
+ *
+ * @param out the receiving Spherical
+ * @param a the source Spherical
+ * @returns out
+ */
+export declare function makeSafe(out: Spherical, a: Spherical): Spherical;
+/**
+ * Converts spherical coordinates to a Cartesian Vec3 (Three.js / OpenGL convention):
+ *   x = r * sin(phi) * sin(theta)
+ *   y = r * cos(phi)
+ *   z = r * sin(phi) * cos(theta)
+ *
+ * @param out the receiving Vec3
+ * @param a the source Spherical
+ * @returns out
+ */
+export declare function toVec3(out: Vec3, a: Spherical): Vec3;
+/**
+ * Converts a Vec2 (x, z) in the horizontal XZ plane to spherical coordinates.
+ * The point is treated as lying on the equator (phi = π/2, y = 0).
+ *
+ * @param out the receiving Spherical
+ * @param v the source Vec2 interpreted as (x, z)
+ * @returns out
+ */
+export declare function fromVec2(out: Spherical, v: Vec2): Spherical;
+/**
+ * Projects spherical coordinates onto the XZ plane, returning a Vec2 (x, z).
+ * Equivalent to taking the horizontal footprint of the 3D point.
+ *
+ * @param out the receiving Vec2
+ * @param a the source Spherical
+ * @returns out
+ */
+export declare function toVec2(out: Vec2, a: Spherical): Vec2;
+/**
+ * Returns true if two Spherical coordinates are approximately equal,
+ * within an absolute/relative tolerance of EPSILON.
+ *
+ * @param a the first Spherical
+ * @param b the second Spherical
+ * @returns true if approximately equal
+ */
+export declare function equals(a: Spherical, b: Spherical): boolean;
+/**
+ * Returns true if two Spherical coordinates are exactly equal (===).
+ *
+ * @param a the first Spherical
+ * @param b the second Spherical
+ * @returns true if exactly equal
+ */
+export declare function exactEquals(a: Spherical, b: Spherical): boolean;
+/**
+ * Returns a string representation of a Spherical
+ *
+ * @param a the source Spherical
+ * @returns string representation
+ */
+export declare function str(a: Spherical): string;
+/**
+ * Returns the great-circle angle (in radians) between two spherical coordinates,
+ * ignoring r. Equivalent to the central angle between the two directions on a
+ * unit sphere.
+ *
+ * Uses the numerically stable haversine formula.
+ *
+ * @param a the first Spherical
+ * @param b the second Spherical
+ * @returns angle in radians in [0, π]
+ */
+export declare function angleTo(a: Spherical, b: Spherical): number;