@woosh/meep-engine 2.134.5 → 2.135.0

package/src/core/math/solveCubic.js

@@ -0,0 +1,82 @@
+import { assert } from "../assert.js";
+import { EPSILON } from "./EPSILON.js";
+import { solveQuadratic } from "./solveQuadratic.js";
+
+const ONE_THIRD = 1.0 / 3.0;
+const TWO_THIRDS_PI = 2.0 * Math.PI / 3.0;
+
+/**
+ * Return real solutions for a cubic polynomial: ax³ + bx² + cx + d
+ * Repeated roots are written once each — multiplicity is not duplicated in the output.
+ * Imaginary roots are not provided.
+ *
+ * @param {number[]|Float32Array|Float64Array} result solutions are written here
+ * @param {number} result_offset offset into result array where solutions are written to
+ * @param {number} a
+ * @param {number} b
+ * @param {number} c
+ * @param {number} d
+ * @returns {number} number of real roots found (0, 1, 2, or 3)
+ */
+export function solveCubic(result, result_offset, a, b, c, d) {
+    assert.isNumber(a, 'a');
+    assert.isNumber(b, 'b');
+    assert.isNumber(c, 'c');
+    assert.isNumber(d, 'd');
+
+    if (Math.abs(a) < EPSILON) {
+        // degrade to quadratic
+        return solveQuadratic(result, result_offset, b, c, d);
+    }
+
+    // normalize: x³ + B·x² + C·x + D = 0
+    const inv_a = 1 / a;
+    const B = b * inv_a;
+    const C = c * inv_a;
+    const D = d * inv_a;
+
+    // depress via x = y - B/3 → y³ + p·y + q = 0
+    const B_third = B * ONE_THIRD;
+    const p = C - B * B_third;
+    const q = 2 * B_third * B_third * B_third - C * B_third + D;
+
+    if (Math.abs(p) < EPSILON && Math.abs(q) < EPSILON) {
+        // triple root at y = 0
+        result[result_offset] = -B_third;
+        return 1;
+    }
+
+    // Cardano's discriminant criterion. ratio = (q/2)² + (p/3)³.
+    //   ratio > 0  → one real root, two complex
+    //   ratio = 0  → repeated real roots (single + double, or triple covered above)
+    //   ratio < 0  → three distinct real roots
+    const half_q = q * 0.5;
+    const third_p = p * ONE_THIRD;
+    const ratio = half_q * half_q + third_p * third_p * third_p;
+
+    if (ratio > EPSILON) {
+        const sqrt_ratio = Math.sqrt(ratio);
+        const u = Math.cbrt(-half_q + sqrt_ratio);
+        const v = Math.cbrt(-half_q - sqrt_ratio);
+
+        result[result_offset] = u + v - B_third;
+        return 1;
+    }
+
+    if (ratio < -EPSILON) {
+        // p must be negative for ratio < 0; sqrt(-p/3) is real
+        const m = 2 * Math.sqrt(-third_p);
+        const theta_third = ONE_THIRD * Math.acos(3 * q / (p * m));
+
+        result[result_offset]     = m * Math.cos(theta_third) - B_third;
+        result[result_offset + 1] = m * Math.cos(theta_third - TWO_THIRDS_PI) - B_third;
+        result[result_offset + 2] = m * Math.cos(theta_third - 2 * TWO_THIRDS_PI) - B_third;
+        return 3;
+    }
+
+    // ratio ≈ 0: simple + double root
+    const u = Math.cbrt(-half_q);
+    result[result_offset]     = 2 * u - B_third;
+    result[result_offset + 1] = -u - B_third;
+    return 2;
+}

package/src/core/math/spline/spline3_hermite_bounds_t.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Compute the parameter values `t` at which a cubic Hermite spline reaches its
+ * minimum and maximum on `[0, 1]`. `t_at_min` is written to
+ * `result[result_offset]`, `t_at_max` to `result[result_offset + result_stride]`.
+ * Both values lie in `[0, 1]`.
+ *
+ * Companion to {@link spline3_hermite_bounds}, which writes the values; this
+ * one writes the parameters at which those values are reached. Either function
+ * does its own critical-point search — call whichever you actually need.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} result_stride
+ * @param {number} p0
+ * @param {number} p1
+ * @param {number} m0
+ * @param {number} m1
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export function spline3_hermite_bounds_t(result: number[] | Float32Array | Float64Array, result_offset: number, result_stride: number, p0: number, p1: number, m0: number, m1: number): void;
+//# sourceMappingURL=spline3_hermite_bounds_t.d.ts.map

package/src/core/math/spline/spline3_hermite_bounds_t.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_bounds_t.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_bounds_t.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iDAXW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAyFhB"}

package/src/core/math/spline/spline3_hermite_bounds_t.js

@@ -0,0 +1,109 @@
+import { assert } from "../../assert.js";
+import { spline3_hermite } from "./spline3_hermite.js";
+
+/**
+ * Compute the parameter values `t` at which a cubic Hermite spline reaches its
+ * minimum and maximum on `[0, 1]`. `t_at_min` is written to
+ * `result[result_offset]`, `t_at_max` to `result[result_offset + result_stride]`.
+ * Both values lie in `[0, 1]`.
+ *
+ * Companion to {@link spline3_hermite_bounds}, which writes the values; this
+ * one writes the parameters at which those values are reached. Either function
+ * does its own critical-point search — call whichever you actually need.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} result_stride
+ * @param {number} p0
+ * @param {number} p1
+ * @param {number} m0
+ * @param {number} m1
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2025
+ */
+export function spline3_hermite_bounds_t(
+    result,
+    result_offset,
+    result_stride,
+    p0, p1, m0, m1
+) {
+    assert.greaterThan(result_stride, 0, 'result_stride must be greater than 0');
+    assert.isInteger(result_stride, 'result_stride');
+
+    // Derivative of the Hermite polynomial:
+    //   3 t² (m0 + m1 + 2 p0 - 2 p1) - 2 t (2 m0 + m1 + 3 p0 - 3 p1) + m0
+    const a = 3 * (m0 + m1 + 2 * p0 - 2 * p1);
+    const b = -2 * (2 * m0 + m1 + 3 * p0 - 3 * p1);
+    const c = m0;
+
+    let min, max, t_at_min, t_at_max;
+    if (p0 <= p1) {
+        min = p0; t_at_min = 0;
+        max = p1; t_at_max = 1;
+    } else {
+        min = p1; t_at_min = 1;
+        max = p0; t_at_max = 0;
+    }
+
+    if (Math.abs(a) < 1e-12) {
+
+        if (Math.abs(b) >= 1e-12) {
+            const t = -c / b;
+
+            if (0 < t && t < 1) {
+                const value = spline3_hermite(t, p0, p1, m0, m1);
+
+                if (value < min) {
+                    min = value;
+                    t_at_min = t;
+                }
+                if (value > max) {
+                    max = value;
+                    t_at_max = t;
+                }
+            }
+        }
+
+    } else {
+
+        const b2ac = b * b - 4 * c * a;
+
+        if (b2ac >= 0) {
+            const sqrtb2ac = Math.sqrt(b2ac);
+
+            const t1 = (-b + sqrtb2ac) / (2 * a);
+
+            if (0 < t1 && t1 < 1) {
+                const value = spline3_hermite(t1, p0, p1, m0, m1);
+
+                if (value < min) {
+                    min = value;
+                    t_at_min = t1;
+                }
+                if (value > max) {
+                    max = value;
+                    t_at_max = t1;
+                }
+            }
+
+            const t2 = (-b - sqrtb2ac) / (2 * a);
+
+            if (0 < t2 && t2 < 1) {
+                const value = spline3_hermite(t2, p0, p1, m0, m1);
+
+                if (value < min) {
+                    min = value;
+                    t_at_min = t2;
+                }
+                if (value > max) {
+                    max = value;
+                    t_at_max = t2;
+                }
+            }
+        }
+    }
+
+    result[result_offset] = t_at_min;
+    result[result_offset + result_stride] = t_at_max;
+}

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Closest approach between two cubic Hermite curves over the full [0,1]²
+ * parameter square. Writes `[s, t]` of the closest pair to
+ * `result[result_offset], result[result_offset + 1]` and returns the squared
+ * distance at that pair.
+ *
+ * Coefficient layout for `a` and `b`: per-dimension grouped quads,
+ *   `[p0_0, p1_0, m0_0, m1_0, p0_1, p1_1, m0_1, m1_1, ..., m1_{dim-1}]`,
+ * length `4 * dim`. dim ≥ 1.
+ *
+ * Internally dispatched by dimension because the algebra of the closest-
+ * approach problem is genuinely different per dim:
+ *   - 1D: range overlap (a single equation in two unknowns).
+ *   - 2D: direct (3,3)/(3,3) Bezout resultant of degree ≤ 9.
+ *   - ND (≥ 3): gradient resultant of distance², degree ≤ 34.
+ *
+ * @param {Float64Array|number[]} a length 4*dim
+ * @param {Float64Array|number[]} b length 4*dim
+ * @param {number} dim
+ * @param {Float64Array|number[]} result
+ * @param {number} result_offset
+ * @returns {number} squared distance at closest approach
+ */
+export function spline3_hermite_intersection_spline3_hermite(a: Float64Array | number[], b: Float64Array | number[], dim: number, result: Float64Array | number[], result_offset: number): number;
+//# sourceMappingURL=spline3_hermite_intersection_spline3_hermite.d.ts.map

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_intersection_spline3_hermite.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_intersection_spline3_hermite.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gEAPW,YAAY,GAAC,MAAM,EAAE,KACrB,YAAY,GAAC,MAAM,EAAE,OACrB,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,GACJ,MAAM,CAiBlB"}

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite.js

@@ -0,0 +1,44 @@
+import { assert } from "../../assert.js";
+import { spline3_hermite_intersection_spline3_hermite_1d } from "./spline3_hermite_intersection_spline3_hermite_1d.js";
+import { spline3_hermite_intersection_spline3_hermite_2d } from "./spline3_hermite_intersection_spline3_hermite_2d.js";
+import { spline3_hermite_intersection_spline3_hermite_nd } from "./spline3_hermite_intersection_spline3_hermite_nd.js";
+
+/**
+ * Closest approach between two cubic Hermite curves over the full [0,1]²
+ * parameter square. Writes `[s, t]` of the closest pair to
+ * `result[result_offset], result[result_offset + 1]` and returns the squared
+ * distance at that pair.
+ *
+ * Coefficient layout for `a` and `b`: per-dimension grouped quads,
+ *   `[p0_0, p1_0, m0_0, m1_0, p0_1, p1_1, m0_1, m1_1, ..., m1_{dim-1}]`,
+ * length `4 * dim`. dim ≥ 1.
+ *
+ * Internally dispatched by dimension because the algebra of the closest-
+ * approach problem is genuinely different per dim:
+ *   - 1D: range overlap (a single equation in two unknowns).
+ *   - 2D: direct (3,3)/(3,3) Bezout resultant of degree ≤ 9.
+ *   - ND (≥ 3): gradient resultant of distance², degree ≤ 34.
+ *
+ * @param {Float64Array|number[]} a length 4*dim
+ * @param {Float64Array|number[]} b length 4*dim
+ * @param {number} dim
+ * @param {Float64Array|number[]} result
+ * @param {number} result_offset
+ * @returns {number} squared distance at closest approach
+ */
+export function spline3_hermite_intersection_spline3_hermite(
+    a, b, dim,
+    result, result_offset
+) {
+    assert.greaterThanOrEqual(dim, 1, 'dim');
+
+    if (dim === 1) {
+        return spline3_hermite_intersection_spline3_hermite_1d(a, b, result, result_offset);
+    }
+
+    if (dim === 2) {
+        return spline3_hermite_intersection_spline3_hermite_2d(a, b, result, result_offset);
+    }
+
+    return spline3_hermite_intersection_spline3_hermite_nd(a, b, dim, result, result_offset);
+}

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite_1d.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Closest approach of two 1D cubic Hermite curves. Inputs are flat 4-element
+ * arrays `[p0, p1, m0, m1]` for each curve (the dim=1 slice of the full
+ * intersection API).
+ *
+ * Writes `[s, t]` to `result[result_offset], result[result_offset + 1]` and
+ * returns the squared distance at the closest approach.
+ *
+ * @param {Float64Array|number[]} a length 4
+ * @param {Float64Array|number[]} b length 4
+ * @param {Float64Array|number[]} result length >= result_offset + 2
+ * @param {number} result_offset
+ * @returns {number}
+ */
+export function spline3_hermite_intersection_spline3_hermite_1d(a: Float64Array | number[], b: Float64Array | number[], result: Float64Array | number[], result_offset: number): number;
+//# sourceMappingURL=spline3_hermite_intersection_spline3_hermite_1d.d.ts.map

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite_1d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_intersection_spline3_hermite_1d.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_intersection_spline3_hermite_1d.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;GAaG;AACH,mEANW,YAAY,GAAC,MAAM,EAAE,KACrB,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,GACJ,MAAM,CAgElB"}

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite_1d.js

@@ -0,0 +1,120 @@
+import { solveCubic } from "../solveCubic.js";
+import { spline3_hermite_bounds } from "./spline3_hermite_bounds.js";
+import { spline3_hermite_bounds_t } from "./spline3_hermite_bounds_t.js";
+
+/*
+ 1D specialization: A and B are scalar functions on [0, 1]. The "intersection"
+ is anywhere their value ranges coincide.
+
+ Two regimes:
+   - Ranges overlap: any (s, t) with A(s) = v = B(t) for some v in the overlap
+     is a true intersection. We pick v = midpoint of the overlap, then solve
+     each cubic A(s) = v and B(t) = v for the first root in [0, 1].
+   - Ranges disjoint: the closest pair sits at the inner extrema — A's max if A
+     is below B (or A's min if A is above B), paired with the corresponding
+     extremum of B. The parameter at each extremum comes from
+     `spline3_hermite_bounds_t`.
+*/
+
+const _bounds_value = new Float64Array(4); // [a_lo, a_hi, b_lo, b_hi]
+const _bounds_t = new Float64Array(4);     // [a_t_min, a_t_max, b_t_min, b_t_max]
+const _cubic_roots = new Float64Array(3);
+
+function first_cubic_root_in_unit(p0, p1, m0, m1, target) {
+    // A(s) - target = (2 p0 - 2 p1 + m0 + m1) s³
+    //               + (-3 p0 + 3 p1 - 2 m0 - m1) s²
+    //               +  m0 s
+    //               + (p0 - target)
+    const a3 = 2 * p0 - 2 * p1 + m0 + m1;
+    const a2 = -3 * p0 + 3 * p1 - 2 * m0 - m1;
+    const a1 = m0;
+    const a0 = p0 - target;
+
+    const count = solveCubic(_cubic_roots, 0, a3, a2, a1, a0);
+    let best_s = -1;
+    for (let i = 0; i < count; i++) {
+        const r = _cubic_roots[i];
+        if (r >= 0 && r <= 1) {
+            if (best_s < 0 || r < best_s) best_s = r;
+        }
+    }
+    return best_s;
+}
+
+/**
+ * Closest approach of two 1D cubic Hermite curves. Inputs are flat 4-element
+ * arrays `[p0, p1, m0, m1]` for each curve (the dim=1 slice of the full
+ * intersection API).
+ *
+ * Writes `[s, t]` to `result[result_offset], result[result_offset + 1]` and
+ * returns the squared distance at the closest approach.
+ *
+ * @param {Float64Array|number[]} a length 4
+ * @param {Float64Array|number[]} b length 4
+ * @param {Float64Array|number[]} result length >= result_offset + 2
+ * @param {number} result_offset
+ * @returns {number}
+ */
+export function spline3_hermite_intersection_spline3_hermite_1d(
+    a, b,
+    result, result_offset
+) {
+    const a_p0 = a[0], a_p1 = a[1], a_m0 = a[2], a_m1 = a[3];
+    const b_p0 = b[0], b_p1 = b[1], b_m0 = b[2], b_m1 = b[3];
+
+    spline3_hermite_bounds(_bounds_value, 0, 1, a_p0, a_p1, a_m0, a_m1);
+    const a_lo = _bounds_value[0];
+    const a_hi = _bounds_value[1];
+
+    spline3_hermite_bounds(_bounds_value, 2, 1, b_p0, b_p1, b_m0, b_m1);
+    const b_lo = _bounds_value[2];
+    const b_hi = _bounds_value[3];
+
+    const overlap_lo = a_lo > b_lo ? a_lo : b_lo;
+    const overlap_hi = a_hi < b_hi ? a_hi : b_hi;
+
+    if (overlap_lo <= overlap_hi) {
+        // Ranges overlap → exact intersection at distance 0.
+        const target = 0.5 * (overlap_lo + overlap_hi);
+
+        let s = first_cubic_root_in_unit(a_p0, a_p1, a_m0, a_m1, target);
+        let t = first_cubic_root_in_unit(b_p0, b_p1, b_m0, b_m1, target);
+
+        // The cubic root finder shouldn't miss given that target lies inside
+        // both ranges, but guard against pathological numerics by falling back
+        // to the relevant extremum parameter.
+        if (s < 0 || t < 0) {
+            spline3_hermite_bounds_t(_bounds_t, 0, 1, a_p0, a_p1, a_m0, a_m1);
+            spline3_hermite_bounds_t(_bounds_t, 2, 1, b_p0, b_p1, b_m0, b_m1);
+            if (s < 0) s = (target === a_lo) ? _bounds_t[0] : _bounds_t[1];
+            if (t < 0) t = (target === b_lo) ? _bounds_t[2] : _bounds_t[3];
+        }
+
+        result[result_offset] = s;
+        result[result_offset + 1] = t;
+        return 0;
+    }
+
+    // Ranges disjoint. Recover the t parameters at the inner extrema.
+    spline3_hermite_bounds_t(_bounds_t, 0, 1, a_p0, a_p1, a_m0, a_m1);
+    spline3_hermite_bounds_t(_bounds_t, 2, 1, b_p0, b_p1, b_m0, b_m1);
+    const a_t_min = _bounds_t[0];
+    const a_t_max = _bounds_t[1];
+    const b_t_min = _bounds_t[2];
+    const b_t_max = _bounds_t[3];
+
+    let s, t, gap;
+    if (a_hi < b_lo) {
+        s = a_t_max;
+        t = b_t_min;
+        gap = b_lo - a_hi;
+    } else {
+        s = a_t_min;
+        t = b_t_max;
+        gap = a_lo - b_hi;
+    }
+
+    result[result_offset] = s;
+    result[result_offset + 1] = t;
+    return gap * gap;
+}

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite_2d.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 2D specialization of the closest-approach intersection finder.
+ *
+ * @param {Float64Array|number[]} a length 8: [a_p0_x, a_p1_x, a_m0_x, a_m1_x, a_p0_y, a_p1_y, a_m0_y, a_m1_y]
+ * @param {Float64Array|number[]} b length 8 (same layout)
+ * @param {Float64Array|number[]} result writes [s, t]
+ * @param {number} result_offset
+ * @returns {number} squared distance at the closest approach
+ */
+export function spline3_hermite_intersection_spline3_hermite_2d(a: Float64Array | number[], b: Float64Array | number[], result: Float64Array | number[], result_offset: number): number;
+//# sourceMappingURL=spline3_hermite_intersection_spline3_hermite_2d.d.ts.map

package/src/core/math/spline/spline3_hermite_intersection_spline3_hermite_2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_intersection_spline3_hermite_2d.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_intersection_spline3_hermite_2d.js"],"names":[],"mappings":"AA4VA;;;;;;;;GAQG;AACH,mEANW,YAAY,GAAC,MAAM,EAAE,KACrB,YAAY,GAAC,MAAM,EAAE,UACrB,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,GACJ,MAAM,CA+FlB"}