math 0.0.3 → 0.1.0

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

@@ -0,0 +1,336 @@
+import type { MutableArrayLike } from './arrays.js';
+import type { Mat4 } from './mat4.js';
+import type { Quat } from './quat.js';
+/** A 4D vector */
+export type Vec4 = [x: number, y: number, z: number, w: number];
+/**
+ * Creates a new, empty vec4
+ *
+ * @returns a new 4D vector
+ */
+export declare function create(): Vec4;
+/**
+ * Creates a new vec4 initialized with values from an existing vector
+ *
+ * @param a vector to clone
+ * @returns a new 4D vector
+ */
+export declare function clone(a: Vec4): Vec4;
+/**
+ * Creates a new vec4 initialized with the given values
+ *
+ * @param x X component
+ * @param y Y component
+ * @param z Z component
+ * @param w W component
+ * @returns a new 4D vector
+ */
+export declare function fromValues(x: number, y: number, z: number, w: number): Vec4;
+/**
+ * Copy the values from one vec4 to another
+ *
+ * @param out the receiving vector
+ * @param a the source vector
+ * @returns out
+ */
+export declare function copy(out: Vec4, a: Vec4): Vec4;
+/**
+ * Set the components of a vec4 to the given values
+ *
+ * @param out the receiving vector
+ * @param x X component
+ * @param y Y component
+ * @param z Z component
+ * @param w W component
+ * @returns out
+ */
+export declare function set(out: Vec4, x: number, y: number, z: number, w: number): Vec4;
+/**
+ * Sets the components of a vec4 from a buffer
+ * @param out the receiving vector
+ * @param buffer the source buffer
+ * @param startIndex the starting index in the buffer
+ * @returns out
+ */
+export declare function fromBuffer(out: Vec4, buffer: ArrayLike<number>, startIndex: number): Vec4;
+/**
+ * Writes the components of a vec4 to a buffer
+ * @param outBuffer The output buffer
+ * @param vec The source vector
+ * @param startIndex The starting index in the buffer
+ * @returns The output buffer
+ */
+export declare function toBuffer(outBuffer: MutableArrayLike<number>, vec: Vec4, startIndex: number): MutableArrayLike<number>;
+/**
+ * Adds two vec4's
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function add(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * Subtracts vector b from vector a
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function subtract(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * Multiplies two vec4's
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function multiply(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * Divides two vec4's
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function divide(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * Math.ceil the components of a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to ceil
+ * @returns out
+ */
+export declare function ceil(out: Vec4, a: Vec4): Vec4;
+/**
+ * Math.floor the components of a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to floor
+ * @returns out
+ */
+export declare function floor(out: Vec4, a: Vec4): Vec4;
+/**
+ * Returns the minimum of two vec4's
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function min(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * Returns the maximum of two vec4's
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @returns out
+ */
+export declare function max(out: Vec4, a: Vec4, b: Vec4): Vec4;
+/**
+ * symmetric round the components of a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to round
+ * @returns out
+ */
+export declare function round(out: Vec4, a: Vec4): Vec4;
+/**
+ * Scales a vec4 by a scalar number
+ *
+ * @param out the receiving vector
+ * @param a the vector to scale
+ * @param b amount to scale the vector by
+ * @returns out
+ */
+export declare function scale(out: Vec4, a: Vec4, b: number): Vec4;
+/**
+ * Adds two vec4's after scaling the second operand by a scalar value
+ *
+ * @param out the receiving vector
+ * @param a the first operand
+ * @param b the second operand
+ * @param scale the amount to scale b by before adding
+ * @returns out
+ */
+export declare function scaleAndAdd(out: Vec4, a: Vec4, b: Vec4, scale: number): Vec4;
+/**
+ * Calculates the euclidian distance between two vec4's
+ *
+ * @param a the first operand
+ * @param b the second operand
+ * @returns distance between a and b
+ */
+export declare function distance(a: Vec4, b: Vec4): number;
+/**
+ * Calculates the squared euclidian distance between two vec4's
+ *
+ * @param a the first operand
+ * @param b the second operand
+ * @returns squared distance between a and b
+ */
+export declare function squaredDistance(a: Vec4, b: Vec4): number;
+/**
+ * Calculates the length of a vec4
+ *
+ * @param a vector to calculate length of
+ * @returns length of a
+ */
+export declare function length(a: Vec4): number;
+/**
+ * Calculates the squared length of a vec4
+ *
+ * @param a vector to calculate squared length of
+ * @returns squared length of a
+ */
+export declare function squaredLength(a: Vec4): number;
+/**
+ * Negates the components of a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to negate
+ * @returns out
+ */
+export declare function negate(out: Vec4, a: Vec4): Vec4;
+/**
+ * Returns the inverse of the components of a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to invert
+ * @returns out
+ */
+export declare function inverse(out: Vec4, a: Vec4): Vec4;
+/**
+ * Normalize a vec4
+ *
+ * @param out the receiving vector
+ * @param a vector to normalize
+ * @returns out
+ */
+export declare function normalize(out: Vec4, a: Vec4): Vec4;
+/**
+ * Calculates the dot product of two vec4's
+ *
+ * @param a the first operand
+ * @param b the second operand
+ * @returns dot product of a and b
+ */
+export declare function dot(a: Vec4, b: Vec4): number;
+/**
+ * Returns the cross-product of three vectors in a 4-dimensional space
+ *
+ * @param out the receiving vector
+ * @param u the first vector
+ * @param v the second vector
+ * @param w the third vector
+ * @returns result
+ */
+export declare function cross(out: Vec4, u: Vec4, v: Vec4, w: Vec4): Vec4;
+/**
+ * Performs a linear interpolation between two vec4's
+ *
+ * @param out the receiving vector
+ * @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: Vec4, a: Vec4, b: Vec4, t: number): Vec4;
+/**
+ * Quadratic interpolation through three vectors using Lagrange interpolation.
+ * Passes through a at t=0, b at t=0.5, and c at t=1.
+ *
+ * @param out the receiving vector
+ * @param a vector at t=0
+ * @param b vector at t=0.5
+ * @param c vector at t=1
+ * @param t interpolation amount
+ * @returns out
+ */
+export declare function lagrange(out: Vec4, a: Vec4, b: Vec4, c: Vec4, t: number): Vec4;
+/**
+ * Transforms the vec4 with a mat4.
+ *
+ * @param out the receiving vector
+ * @param a the vector to transform
+ * @param m matrix to transform with
+ * @returns out
+ */
+export declare function transformMat4(out: Vec4, a: Vec4, m: Mat4): Vec4;
+/**
+ * Transforms the vec4 with a quat
+ *
+ * @param out the receiving vector
+ * @param a the vector to transform
+ * @param q quaternion to transform with
+ * @returns out
+ */
+export declare function transformQuat(out: Vec4, a: Vec4, q: Quat): Vec4;
+/**
+ * Set the components of a vec4 to zero
+ *
+ * @param out the receiving vector
+ * @returns out
+ */
+export declare function zero(out: Vec4): Vec4;
+/**
+ * Returns a string representation of a vector
+ *
+ * @param a vector to represent as a string
+ * @returns string representation of the vector
+ */
+export declare function str(a: Vec4): string;
+/**
+ * Returns whether or not the vectors have exactly the same elements in the same position (when compared with ===)
+ *
+ * @param a The first vector.
+ * @param b The second vector.
+ * @returns True if the vectors are equal, false otherwise.
+ */
+export declare function exactEquals(a: Vec4, b: Vec4): boolean;
+/**
+ * Returns whether or not the vectors have approximately the same elements in the same position.
+ *
+ * @param a The first vector.
+ * @param b The second vector.
+ * @returns True if the vectors are equal, false otherwise.
+ */
+export declare function equals(a: Vec4, b: Vec4): boolean;
+/**
+ * Returns whether or not the vector is finite
+ * @param a vector to test
+ * @returns whether or not the vector is finite
+ */
+export declare function finite(a: Vec4): boolean;
+/**
+ * Alias for {@link subtract}
+ */
+export declare const sub: typeof subtract;
+/**
+ * Alias for {@link multiply}
+ */
+export declare const mul: typeof multiply;
+/**
+ * Alias for {@link divide}
+ */
+export declare const div: typeof divide;
+/**
+ * Alias for {@link distance}
+ */
+export declare const dist: typeof distance;
+/**
+ * Alias for {@link squaredDistance}
+ */
+export declare const sqrDist: typeof squaredDistance;
+/**
+ * Alias for {@link length}
+ */
+export declare const len: typeof length;
+/**
+ * Alias for {@link squaredLength}
+ */
+export declare const sqrLen: typeof squaredLength;

package/dist/src/geometry/circumcircle.d.ts

@@ -0,0 +1,9 @@
+import type { Vec2 } from '../core/vec2.js';
+import type { Circle } from '../shapes/circle.js';
+/**
+ * Calculates the circumcircle of three points and stores the center in the output parameter.
+ * @param out The circle to store the result in
+ * @param triangle The triangle defined by three points
+ * @returns
+ */
+export declare function circumcircle(out: Circle, a: Vec2, b: Vec2, c: Vec2): Circle;

package/dist/src/geometry/index.d.ts

@@ -0,0 +1,5 @@
+export * from './circumcircle.js';
+export * from './polygon2-decompose.js';
+export * from './polygon2-triangulate.js';
+export * from './quickhull2.js';
+export * from './quickhull3.js';

package/dist/src/geometry/polygon2-decompose.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Decomposes a simple polygon into convex sub-polygons using Bayazit's fast
+ * approximate algorithm. Fast (~O(n²)) but may use more pieces than the
+ * minimum; may introduce new (Steiner) vertices. Input winding is normalised
+ * internally, so either winding is accepted.
+ *
+ * Implemented iteratively with an explicit worklist of sub-polygons rather than
+ * recursion.
+ *
+ * @param vertices polygon vertices as a flat array `[x0, y0, x1, y1, ...]`
+ * @param n number of vertices to read from `vertices`
+ * @returns an array of convex sub-polygons, each a flat `[x0, y0, ...]` array (CCW)
+ */
+export declare function decomposePolygon2Quick(vertices: number[], n: number): number[][];
+/**
+ * Decomposes a simple polygon into the (near-)minimum number of convex
+ * sub-polygons. Produces fewer pieces than {@link decomposePolygon2Quick} but
+ * is much slower (~O(n⁴)) — use only for small polygons. Input winding is
+ * normalised internally, so either winding is accepted.
+ *
+ * @param vertices polygon vertices as a flat array `[x0, y0, x1, y1, ...]`
+ * @param n number of vertices to read from `vertices`
+ * @returns an array of convex sub-polygons, each a flat `[x0, y0, ...]` array (CCW)
+ */
+export declare function decomposePolygon2Quality(vertices: number[], n: number): number[][];

package/dist/src/geometry/polygon2-triangulate.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Triangulates a simple polygon by ear clipping, writing triangle indices into
+ * `out` as `[i0, i1, i2, i3, i4, i5, ...]`, where each index refers to a vertex
+ * of the input polygon. Either winding is accepted (normalised internally).
+ *
+ * `out` must have room for at least `3 * (n - 2)` indices. A complete
+ * triangulation returns exactly `n - 2` triangles; a smaller count indicates
+ * the polygon could not be fully triangulated (e.g. degenerate input).
+ *
+ * @param out output array of triangle indices
+ * @param vertices polygon vertices as a flat array `[x0, y0, x1, y1, ...]`
+ * @param n number of vertices to read from `vertices`
+ * @returns the number of triangles written
+ */
+export declare function triangulatePolygon2(out: number[], vertices: number[], n: number): number;

package/dist/src/geometry/quickhull2.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Computes the convex hull of a set of 2D points using the QuickHull algorithm.
+ * The hull is returned as an array of indices in counter-clockwise order.
+ *
+ * Implementation of pseudocode from: https://en.wikipedia.org/wiki/Quickhull
+ *
+ * @param points flat array of 2D points: [x0, y0, x1, y1, ...]
+ * @returns indices of hull vertices in ccw order
+ */
+export declare function quickhull2(points: number[]): number[];

package/dist/src/geometry/quickhull3.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Incremental Convex Hull 3D implementation based on Three.js ConvexHull.
+ *
+ * This implements the QuickHull algorithm with an incremental approach that maintains
+ * a valid hull at each step using a half-edge data structure (DCEL - Doubly Connected
+ * Edge List) for O(1) face adjacency queries.
+ *
+ * The algorithm is based on John Lloyd's Java implementation and was ported to
+ * JavaScript by Mauricio Poppe (quickhull3d), then incorporated into Three.js.
+ *
+ * References:
+ * - Three.js ConvexHull: https://github.com/mrdoob/three.js/blob/dev/examples/jsm/math/ConvexHull.js
+ * - quickhull3d by Mauricio Poppe: https://github.com/maurizzzio/quickhull3d/
+ * - Original Java by John Lloyd: http://www.cs.ubc.ca/~lloyd/java/quickhull3d.html
+ * - Dirk Gregorius presentation: https://archive.org/details/GDC2014Gregorius
+ *
+ * Algorithm: QuickHull (incremental variant)
+ * Time complexity: O(n log n) average, O(n²) worst case
+ * Space complexity: O(n + f + e) where f=faces, e=edges (~3x more than basic)
+ */
+/**
+ * Computes the convex hull of a set of 3D points using an incremental QuickHull algorithm.
+ *
+ * @param points An array of numbers representing the 3D points (x1, y1, z1, x2, y2, z2, ...)
+ * @returns An array of indices representing the triangles of the convex hull (i1, j1, k1, i2, j2, k2, ...).
+ */
+export declare function quickhull3(points: number[]): number[];