@woosh/meep-engine 2.134.4 → 2.135.0

package/src/core/math/linalg/polynomial_real_roots_in_interval.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Find all real roots of a univariate polynomial that lie inside the closed
+ * interval [lo, hi]. Roots are written to `out[out_offset ..]` in ascending
+ * order; the count of roots written is returned.
+ *
+ * @param {Float64Array|number[]} coeffs ascending power order: coeffs[i] is the coefficient of x^i
+ * @param {number} degree polynomial degree (coeffs must have at least `degree + 1` entries)
+ * @param {number} lo
+ * @param {number} hi
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @returns {number} number of roots written
+ */
+export function polynomial_real_roots_in_interval(coeffs: Float64Array | number[], degree: number, lo: number, hi: number, out: Float64Array | number[], out_offset: number): number;
+//# sourceMappingURL=polynomial_real_roots_in_interval.d.ts.map

package/src/core/math/linalg/polynomial_real_roots_in_interval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polynomial_real_roots_in_interval.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/linalg/polynomial_real_roots_in_interval.js"],"names":[],"mappings":"AAsGA;;;;;;;;;;;;GAYG;AACH,0DARW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,YAAY,GAAC,MAAM,EAAE,cACrB,MAAM,GACJ,MAAM,CAsFlB"}

package/src/core/math/linalg/polynomial_real_roots_in_interval.js

@@ -0,0 +1,200 @@
+import { assert } from "../../assert.js";
+import { solveQuadratic } from "../solveQuadratic.js";
+import { polynomial_complex_roots_aberth_ehrlich } from "./polynomial_complex_roots_aberth_ehrlich.js";
+
+/*
+ Find all real roots of a univariate polynomial that lie inside a closed interval [lo, hi].
+ Coefficient layout: coeffs[i] is the coefficient of x^i, so
+
+   p(x) = coeffs[0] + coeffs[1]*x + coeffs[2]*x^2 + ... + coeffs[degree]*x^degree
+
+ Approach:
+   1. Trim leading zeros (treat the polynomial at its effective degree).
+   2. Closed-form for degrees 1 and 2.
+   3. For degree ≥ 3, isolate all complex roots via
+      polynomial_complex_roots_aberth_ehrlich, then keep the ones whose
+      imaginary part is below a scale-relative threshold and whose real part
+      lies in [lo, hi]. Each survivor is Newton-polished against the real
+      polynomial as a sanity / precision pass.
+*/
+
+const MAX_SUPPORTED_DEGREE = 64;
+
+const SCRATCH_COEFF = new Float64Array(MAX_SUPPORTED_DEGREE + 1);
+const SCRATCH_ROOTS_RE = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_ROOTS_IM = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_OUT_REAL = new Float64Array(MAX_SUPPORTED_DEGREE);
+const SCRATCH_QUADRATIC = new Float64Array(2);
+const SCRATCH_EVAL = new Float64Array(2);
+
+const NEWTON_MAX_ITERATIONS = 32;
+
+// Imaginary part below this fraction of root scale is treated as real.
+const IMAG_PART_REAL_THRESHOLD = 1e-8;
+
+const NEWTON_RELATIVE_RESIDUAL_TOLERANCE = 1e-10;
+
+const DEDUPE_RELATIVE_TOLERANCE = 1e-7;
+
+function poly_eval_with_derivative(coeffs, degree, x, out) {
+    let p = coeffs[degree];
+    let dp = 0;
+
+    for (let i = degree - 1; i >= 0; i--) {
+        dp = dp * x + p;
+        p = p * x + coeffs[i];
+    }
+
+    out[0] = p;
+    out[1] = dp;
+}
+
+function max_abs_coefficient(coeffs, degree) {
+    let m = 0;
+    for (let i = 0; i <= degree; i++) {
+        const a = Math.abs(coeffs[i]);
+        if (a > m) m = a;
+    }
+    return m;
+}
+
+function root_scale_estimate(coeffs, degree) {
+    const lead = Math.abs(coeffs[degree]);
+    let m = 0;
+    for (let i = 0; i < degree; i++) {
+        const a = Math.abs(coeffs[i]);
+        if (a > m) m = a;
+    }
+    return 1 + m / lead;
+}
+
+function newton_polish_real(coeffs, degree, x_init) {
+    let x = x_init;
+
+    for (let i = 0; i < NEWTON_MAX_ITERATIONS; i++) {
+        poly_eval_with_derivative(coeffs, degree, x, SCRATCH_EVAL);
+
+        const p = SCRATCH_EVAL[0];
+        const dp = SCRATCH_EVAL[1];
+
+        if (dp === 0) break;
+
+        const step = p / dp;
+        x -= step;
+
+        if (Math.abs(step) <= Math.abs(x) * 1e-15) break;
+    }
+
+    return x;
+}
+
+function insert_sorted_unique(roots, count, value, dedupe_tolerance) {
+    let i = 0;
+    while (i < count && roots[i] < value) i++;
+
+    if (i > 0 && Math.abs(roots[i - 1] - value) <= dedupe_tolerance) return count;
+    if (i < count && Math.abs(roots[i] - value) <= dedupe_tolerance) return count;
+
+    for (let j = count; j > i; j--) roots[j] = roots[j - 1];
+    roots[i] = value;
+    return count + 1;
+}
+
+/**
+ * Find all real roots of a univariate polynomial that lie inside the closed
+ * interval [lo, hi]. Roots are written to `out[out_offset ..]` in ascending
+ * order; the count of roots written is returned.
+ *
+ * @param {Float64Array|number[]} coeffs ascending power order: coeffs[i] is the coefficient of x^i
+ * @param {number} degree polynomial degree (coeffs must have at least `degree + 1` entries)
+ * @param {number} lo
+ * @param {number} hi
+ * @param {Float64Array|number[]} out
+ * @param {number} out_offset
+ * @returns {number} number of roots written
+ */
+export function polynomial_real_roots_in_interval(
+    coeffs,
+    degree,
+    lo, hi,
+    out, out_offset
+) {
+    assert.isNonNegativeInteger(degree, 'degree');
+    assert.isNonNegativeInteger(out_offset, 'out_offset');
+    assert.greaterThanOrEqual(MAX_SUPPORTED_DEGREE, degree, 'degree exceeds MAX_SUPPORTED_DEGREE');
+
+    if (degree === 0) return 0;
+
+    const coeff_norm = max_abs_coefficient(coeffs, degree);
+    if (coeff_norm === 0) return 0;
+
+    let effective_degree = degree;
+    const leading_zero_threshold = coeff_norm * 1e-14;
+    while (effective_degree > 0 && Math.abs(coeffs[effective_degree]) <= leading_zero_threshold) {
+        effective_degree--;
+    }
+    if (effective_degree === 0) return 0;
+
+    if (effective_degree === 1) {
+        const root = -coeffs[0] / coeffs[1];
+        if (root >= lo && root <= hi) {
+            out[out_offset] = root;
+            return 1;
+        }
+        return 0;
+    }
+
+    if (effective_degree === 2) {
+        const root_count = solveQuadratic(SCRATCH_QUADRATIC, 0, coeffs[2], coeffs[1], coeffs[0]);
+        let written = 0;
+        for (let i = 0; i < root_count; i++) {
+            const r = SCRATCH_QUADRATIC[i];
+            if (r >= lo && r <= hi) {
+                if (written === 0 || Math.abs(out[out_offset + written - 1] - r) > 0) {
+                    out[out_offset + written] = r;
+                    written++;
+                }
+            }
+        }
+        return written;
+    }
+
+    for (let i = 0; i <= effective_degree; i++) SCRATCH_COEFF[i] = coeffs[i];
+
+    polynomial_complex_roots_aberth_ehrlich(
+        SCRATCH_COEFF, effective_degree,
+        SCRATCH_ROOTS_RE, SCRATCH_ROOTS_IM, 0
+    );
+
+    const root_scale = root_scale_estimate(SCRATCH_COEFF, effective_degree);
+    const imag_threshold = IMAG_PART_REAL_THRESHOLD * Math.max(1, root_scale);
+    const residual_tolerance = NEWTON_RELATIVE_RESIDUAL_TOLERANCE * coeff_norm;
+    const dedupe_tolerance = DEDUPE_RELATIVE_TOLERANCE * Math.max(1, Math.max(Math.abs(lo), Math.abs(hi)));
+
+    let unique_count = 0;
+
+    for (let i = 0; i < effective_degree; i++) {
+        const re = SCRATCH_ROOTS_RE[i];
+        const im = SCRATCH_ROOTS_IM[i];
+
+        if (!Number.isFinite(re) || !Number.isFinite(im)) continue;
+
+        if (Math.abs(im) > imag_threshold) continue;
+
+        const polished = newton_polish_real(SCRATCH_COEFF, effective_degree, re);
+        if (!Number.isFinite(polished)) continue;
+
+        poly_eval_with_derivative(SCRATCH_COEFF, effective_degree, polished, SCRATCH_EVAL);
+        if (Math.abs(SCRATCH_EVAL[0]) > residual_tolerance) continue;
+
+        if (polished < lo || polished > hi) continue;
+
+        unique_count = insert_sorted_unique(SCRATCH_OUT_REAL, unique_count, polished, dedupe_tolerance);
+    }
+
+    for (let i = 0; i < unique_count; i++) {
+        out[out_offset + i] = SCRATCH_OUT_REAL[i];
+    }
+
+    return unique_count;
+}

package/src/core/math/solveCubic.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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: number[] | Float32Array | Float64Array, result_offset: number, a: number, b: number, c: number, d: number): number;
+//# sourceMappingURL=solveCubic.d.ts.map

package/src/core/math/solveCubic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solveCubic.d.ts","sourceRoot":"","sources":["../../../../src/core/math/solveCubic.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,mCARW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA+DlB"}

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;
+}