@woosh/meep-engine 2.134.4 → 2.135.0

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"}

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

@@ -0,0 +1,451 @@
+import { polynomial_real_roots_in_interval } from "../linalg/polynomial_real_roots_in_interval.js";
+import { solveCubic } from "../solveCubic.js";
+import { spline3_hermite } from "./spline3_hermite.js";
+import { spline3_hermite_intersection_spline3_hermite_nd } from "./spline3_hermite_intersection_spline3_hermite_nd.js";
+import { spline3_hermite_to_monomial } from "./spline3_hermite_to_monomial.js";
+
+/*
+ 2D specialization. Two equations (one per axis), each bidegree (3,3) in (s,t):
+
+   P(s, t) = A_x(s) − B_x(t) = 0
+   Q(s, t) = A_y(s) − B_y(t) = 0
+
+ Eliminate t through the Bezout 3×3 resultant matrix (smaller and easier than
+ the 6×6 Sylvester form). The resultant det(Bezout) is a univariate polynomial
+ in s of degree ≤ 9. Its real roots in [0, 1] give the s-coordinates of all
+ true intersections; for each, the corresponding t is recovered by solving the
+ cubic A_x(s_i) − B_x(t) = 0 and verifying agreement on the y component.
+
+ Closest-approach handling:
+   - Any true interior intersection ⇒ distance² = 0; report it.
+   - Otherwise, the global minimum of squared distance over [0,1]² lies on the
+     boundary: an edge minimum (one parameter pinned at 0 or 1, the other a
+     quintic minimisation reduced to a quartic root-finding) or a corner.
+
+ Polynomial-coefficient buffers and the small ad-hoc polynomial arithmetic
+ used to assemble det(Bezout) are kept private to this module — they are
+ implementation glue, not a general "polynomial library".
+*/
+
+// Per-curve monomial buffers (4 coeffs per axis).
+const _A_x_mono = new Float64Array(4);
+const _A_y_mono = new Float64Array(4);
+const _B_x_mono = new Float64Array(4);
+const _B_y_mono = new Float64Array(4);
+
+// Bezout entries. The four polynomial-valued ones are degree ≤ 3 in s; the two
+// scalar-valued ones are stored as plain numbers in `_bz_const`.
+//   _bz_poly[0] = B[0,0]   (degree 3 in s)
+//   _bz_poly[1] = B[0,1]
+//   _bz_poly[2] = B[0,2]
+//   _bz_poly[3] = B[1,1]
+const _bz_poly = [
+    new Float64Array(4),
+    new Float64Array(4),
+    new Float64Array(4),
+    new Float64Array(4),
+];
+// _bz_const[0] = B[1,2], _bz_const[1] = B[2,2]
+const _bz_const = new Float64Array(2);
+
+// Resultant coefficients (degree ≤ 9 → 10 slots).
+const _resultant = new Float64Array(10);
+
+// Scratch polynomials used while computing det(Bezout).
+const _tmp_poly_a = new Float64Array(10);
+const _tmp_poly_b = new Float64Array(10);
+const _tmp_poly_c = new Float64Array(10);
+const _tmp_poly_d = new Float64Array(10);
+
+const _root_buffer_s = new Float64Array(9);
+const _root_buffer_t = new Float64Array(3);
+
+const Y_MATCH_TOLERANCE = 1e-7;
+
+// ── private polynomial helpers (coefficient-array form) ────────────────────
+
+function poly_mul(out, a, a_len, b, b_len) {
+    const out_len = a_len + b_len - 1;
+    for (let i = 0; i < out_len; i++) out[i] = 0;
+    for (let i = 0; i < a_len; i++) {
+        const ai = a[i];
+        if (ai === 0) continue;
+        for (let j = 0; j < b_len; j++) {
+            out[i + j] += ai * b[j];
+        }
+    }
+    return out_len;
+}
+
+function poly_add_into(target, target_len, a, a_len) {
+    const n = a_len > target_len ? a_len : target_len;
+    for (let i = target_len; i < n; i++) target[i] = 0;
+    for (let i = 0; i < a_len; i++) target[i] += a[i];
+    return n;
+}
+
+function poly_sub_into(target, target_len, a, a_len) {
+    const n = a_len > target_len ? a_len : target_len;
+    for (let i = target_len; i < n; i++) target[i] = 0;
+    for (let i = 0; i < a_len; i++) target[i] -= a[i];
+    return n;
+}
+
+function poly_scale_into(target, target_len, scalar) {
+    for (let i = 0; i < target_len; i++) target[i] *= scalar;
+}
+
+// ── core algorithm helpers ────────────────────────────────────────────────
+
+/**
+ * Build the 6 Bezout entries (4 polynomial, 2 constant) from the monomial
+ * coefficients of A and B. See module preamble for the algebraic derivation.
+ *
+ * Layout:
+ *   a-side polys are A_*(s) in monomial basis (cubic in s). Their coefficient
+ *   arrays here are length 4 (constant ... s³).
+ *   b-side polys are B_*(t) — we only need the *coefficients* (constants
+ *   wrt s) in the bivariate form P(s,t) = A_x(s) − B_x(t). So β_kx = the k-th
+ *   monomial coefficient of B_x.
+ */
+function build_bezout_entries(a_x, a_y, b_x, b_y) {
+    // Coefficients of P(s, t) viewed as polynomial in t with s-poly coeffs:
+    //   p_0(s) = A_x(s) − β0_x   (cubic in s)
+    //   p_1   = -β1_x  (constant)
+    //   p_2   = -β2_x
+    //   p_3   = -β3_x
+    // and similarly q_k for Q.
+
+    const beta_1x = -b_x[1];
+    const beta_2x = -b_x[2];
+    const beta_3x = -b_x[3];
+    const beta_1y = -b_y[1];
+    const beta_2y = -b_y[2];
+    const beta_3y = -b_y[3];
+
+    // p_0(s) = A_x(s) - β0_x
+    const p0 = _tmp_poly_a;
+    p0[0] = a_x[0] - b_x[0];
+    p0[1] = a_x[1];
+    p0[2] = a_x[2];
+    p0[3] = a_x[3];
+
+    // q_0(s) = A_y(s) - β0_y
+    const q0 = _tmp_poly_b;
+    q0[0] = a_y[0] - b_y[0];
+    q0[1] = a_y[1];
+    q0[2] = a_y[2];
+    q0[3] = a_y[3];
+
+    // B[0,0] = a_1 b_0 - a_0 b_1 = beta_1x * q_0(s) - p_0(s) * beta_1y
+    const b00 = _bz_poly[0];
+    for (let i = 0; i < 4; i++) b00[i] = beta_1x * q0[i] - p0[i] * beta_1y;
+
+    // B[0,1] = a_2 b_0 - a_0 b_2 = beta_2x * q_0(s) - p_0(s) * beta_2y
+    const b01 = _bz_poly[1];
+    for (let i = 0; i < 4; i++) b01[i] = beta_2x * q0[i] - p0[i] * beta_2y;
+
+    // B[0,2] = a_3 b_0 - a_0 b_3 = beta_3x * q_0(s) - p_0(s) * beta_3y
+    const b02 = _bz_poly[2];
+    for (let i = 0; i < 4; i++) b02[i] = beta_3x * q0[i] - p0[i] * beta_3y;
+
+    // B[1,1] = (a_3 b_0 - a_0 b_3) + (a_2 b_1 - a_1 b_2)
+    //        = B[0,2] + (beta_2x * beta_1y - beta_1x * beta_2y)
+    const b11 = _bz_poly[3];
+    const inner = beta_2x * beta_1y - beta_1x * beta_2y;
+    for (let i = 0; i < 4; i++) b11[i] = b02[i];
+    b11[0] += inner;
+
+    // B[1,2] = a_3 b_1 - a_1 b_3 = beta_3x * beta_1y - beta_1x * beta_3y (constant)
+    _bz_const[0] = beta_3x * beta_1y - beta_1x * beta_3y;
+
+    // B[2,2] = a_3 b_2 - a_2 b_3 = beta_3x * beta_2y - beta_2x * beta_3y (constant)
+    _bz_const[1] = beta_3x * beta_2y - beta_2x * beta_3y;
+}
+
+/**
+ * Compute det(Bezout) as a polynomial in s and write its coefficients into
+ * `_resultant`. Returns the (effective) degree + 1 — i.e. the number of
+ * coefficients that are meaningful.
+ *
+ * Closed form: det(B) = B[0,2]·(B[0,1]·B[1,2] − B[0,2]·B[1,1])
+ *                     − B[1,2]·(B[0,0]·B[1,2] − B[0,2]·B[0,1])
+ *                     + B[2,2]·(B[0,0]·B[1,1] − B[0,1]²)
+ *
+ *   B[0,0], B[0,1], B[0,2], B[1,1] are cubic polynomials in s (length 4).
+ *   B[1,2], B[2,2] are constants (length 1).
+ */
+function compute_resultant() {
+    const b00 = _bz_poly[0]; // length 4
+    const b01 = _bz_poly[1]; // length 4
+    const b02 = _bz_poly[2]; // length 4
+    const b11 = _bz_poly[3]; // length 4
+    const b12 = _bz_const[0];
+    const b22 = _bz_const[1];
+
+    for (let i = 0; i < 10; i++) _resultant[i] = 0;
+
+    // ── Term A: B[0,2] · (B[0,1] · B[1,2] − B[0,2] · B[1,1]) ──
+    // tmp_c = B[0,1] · B[1,2]   (cubic × constant → cubic, length 4)
+    const tmp_c = _tmp_poly_c;
+    let tmp_c_len = 4;
+    for (let i = 0; i < 4; i++) tmp_c[i] = b01[i] * b12;
+
+    // tmp_d = B[0,2] · B[1,1]   (cubic × cubic → degree 6, length 7)
+    const tmp_d = _tmp_poly_d;
+    const tmp_d_len = poly_mul(tmp_d, b02, 4, b11, 4);
+
+    // tmp_c -= tmp_d  (length 7)
+    tmp_c_len = poly_sub_into(tmp_c, tmp_c_len, tmp_d, tmp_d_len);
+
+    // term_a = B[0,2] · tmp_c  (length 4 + 7 − 1 = 10)
+    const tmp_a = _tmp_poly_a;
+    const tmp_a_len = poly_mul(tmp_a, b02, 4, tmp_c, tmp_c_len);
+
+    // resultant += term_a
+    poly_add_into(_resultant, 0, tmp_a, tmp_a_len);
+
+    // ── Term B: −B[1,2] · (B[0,0] · B[1,2] − B[0,2] · B[0,1]) ──
+    // tmp_c = B[0,0] · B[1,2]   (cubic × constant)
+    tmp_c_len = 4;
+    for (let i = 0; i < 4; i++) tmp_c[i] = b00[i] * b12;
+
+    // tmp_d = B[0,2] · B[0,1]   (cubic × cubic → length 7)
+    const tmp_d_len_2 = poly_mul(tmp_d, b02, 4, b01, 4);
+
+    tmp_c_len = poly_sub_into(tmp_c, tmp_c_len, tmp_d, tmp_d_len_2);
+
+    poly_scale_into(tmp_c, tmp_c_len, -b12);
+    poly_add_into(_resultant, _resultant.length, tmp_c, tmp_c_len);
+
+    // ── Term C: B[2,2] · (B[0,0] · B[1,1] − B[0,1]²) ──
+    const tmp_d_len_3 = poly_mul(tmp_d, b00, 4, b11, 4); // length 7
+    tmp_c_len = poly_mul(tmp_c, b01, 4, b01, 4);          // length 7
+
+    poly_sub_into(tmp_d, tmp_d_len_3, tmp_c, tmp_c_len);
+
+    poly_scale_into(tmp_d, tmp_d_len_3, b22);
+    poly_add_into(_resultant, _resultant.length, tmp_d, tmp_d_len_3);
+}
+
+/**
+ * For a given s, find a t in [0,1] such that A_x(s) − B_x(t) = 0 AND
+ * A_y(s) ≈ B_y(t) (the latter within Y_MATCH_TOLERANCE). Returns the matched
+ * t, or -1 if none.
+ */
+function recover_t(a, b, s) {
+    // A_x(s) value:
+    const a_x_at_s = spline3_hermite(s, a[0], a[1], a[2], a[3]);
+    const a_y_at_s = spline3_hermite(s, a[4], a[5], a[6], a[7]);
+
+    // Solve B_x(t) = a_x_at_s for t:
+    // B_x in monomial: β0_x + β1_x t + β2_x t² + β3_x t³ - a_x_at_s = 0
+    const t_count = solveCubic(
+        _root_buffer_t, 0,
+        _B_x_mono[3], _B_x_mono[2], _B_x_mono[1], _B_x_mono[0] - a_x_at_s
+    );
+
+    let best_t = -1;
+    let best_dy = Number.POSITIVE_INFINITY;
+
+    for (let i = 0; i < t_count; i++) {
+        const t = _root_buffer_t[i];
+        if (t < 0 || t > 1) continue;
+        const b_y_at_t = spline3_hermite(t, b[4], b[5], b[6], b[7]);
+        const dy = Math.abs(a_y_at_s - b_y_at_t);
+        if (dy < best_dy) {
+            best_dy = dy;
+            best_t = t;
+        }
+    }
+
+    if (best_dy > Y_MATCH_TOLERANCE) return -1;
+    return best_t;
+}
+
+/**
+ * Find the minimum of ||point − B(t)||² over t in [0,1], where `point` is a 2D
+ * point (px, py). Solves the quintic ∂/∂t = 0 by feeding it to
+ * polynomial_real_roots_in_interval and tests each root + the two endpoints.
+ *
+ * Writes `[t, dist²]` into the returned 2-element module scratch.
+ */
+const _edge_tmp_eval = new Float64Array(6);
+const _edge_tmp_quintic = new Float64Array(6);
+const _edge_tmp_roots = new Float64Array(5);
+const _edge_result = new Float64Array(2);
+
+function nearest_t_on_curve(b_mono_x, b_mono_y, point_x, point_y) {
+    // B(t) − point is a cubic in t per axis. ‖B(t) − point‖² is degree 6.
+    // Its derivative wrt t is degree 5.
+
+    // Δ_x(t) = (β0_x − px) + β1_x t + β2_x t² + β3_x t³
+    const dx0 = b_mono_x[0] - point_x;
+    const dx1 = b_mono_x[1];
+    const dx2 = b_mono_x[2];
+    const dx3 = b_mono_x[3];
+
+    const dy0 = b_mono_y[0] - point_y;
+    const dy1 = b_mono_y[1];
+    const dy2 = b_mono_y[2];
+    const dy3 = b_mono_y[3];
+
+    // d/dt ‖Δ‖² = 2 (Δ_x · dΔ_x/dt + Δ_y · dΔ_y/dt) → drop the factor of 2.
+    // dΔ_x/dt = β1_x + 2 β2_x t + 3 β3_x t² (degree 2)
+
+    // Compute each pair-product as a quintic, then sum.
+    // (a0 + a1 t + a2 t² + a3 t³) · (b0 + b1 t + b2 t²) = up to degree 5.
+
+    const quintic = _edge_tmp_quintic;
+    for (let i = 0; i < 6; i++) quintic[i] = 0;
+
+    // x-axis contribution
+    {
+        const a0 = dx0, a1 = dx1, a2 = dx2, a3 = dx3;
+        const b0 = dx1, b1 = 2 * dx2, b2 = 3 * dx3;
+        quintic[0] += a0 * b0;
+        quintic[1] += a0 * b1 + a1 * b0;
+        quintic[2] += a0 * b2 + a1 * b1 + a2 * b0;
+        quintic[3] += a1 * b2 + a2 * b1 + a3 * b0;
+        quintic[4] += a2 * b2 + a3 * b1;
+        quintic[5] += a3 * b2;
+    }
+    // y-axis contribution
+    {
+        const a0 = dy0, a1 = dy1, a2 = dy2, a3 = dy3;
+        const b0 = dy1, b1 = 2 * dy2, b2 = 3 * dy3;
+        quintic[0] += a0 * b0;
+        quintic[1] += a0 * b1 + a1 * b0;
+        quintic[2] += a0 * b2 + a1 * b1 + a2 * b0;
+        quintic[3] += a1 * b2 + a2 * b1 + a3 * b0;
+        quintic[4] += a2 * b2 + a3 * b1;
+        quintic[5] += a3 * b2;
+    }
+
+    const root_count = polynomial_real_roots_in_interval(
+        quintic, 5, 0, 1, _edge_tmp_roots, 0
+    );
+
+    let best_t = 0;
+    let best_d2 = Number.POSITIVE_INFINITY;
+
+    for (let i = -2; i < root_count; i++) {
+        // i = -2 → t = 0; i = -1 → t = 1; otherwise interior roots
+        const t = i === -2 ? 0 : (i === -1 ? 1 : _edge_tmp_roots[i]);
+        const ex = dx0 + t * (dx1 + t * (dx2 + t * dx3));
+        const ey = dy0 + t * (dy1 + t * (dy2 + t * dy3));
+        const d2 = ex * ex + ey * ey;
+        if (d2 < best_d2) {
+            best_d2 = d2;
+            best_t = t;
+        }
+    }
+
+    _edge_result[0] = best_t;
+    _edge_result[1] = best_d2;
+    return _edge_result;
+}
+
+/**
+ * 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, b,
+    result, result_offset
+) {
+    spline3_hermite_to_monomial(_A_x_mono, 0, 1, a[0], a[1], a[2], a[3]);
+    spline3_hermite_to_monomial(_A_y_mono, 0, 1, a[4], a[5], a[6], a[7]);
+    spline3_hermite_to_monomial(_B_x_mono, 0, 1, b[0], b[1], b[2], b[3]);
+    spline3_hermite_to_monomial(_B_y_mono, 0, 1, b[4], b[5], b[6], b[7]);
+
+    build_bezout_entries(_A_x_mono, _A_y_mono, _B_x_mono, _B_y_mono);
+    compute_resultant();
+
+    // Detect a degenerate resultant. This happens when one (or both) input
+    // curves is degree < 3 in its parameter — straight axis-aligned lines are
+    // the canonical example. The (3,3)/(3,3) Bezout construction collapses
+    // because the relevant leading coefficients are zero. In that case, fall
+    // back to the dimension-agnostic Newton-from-grid path.
+    let max_resultant_mag = 0;
+    for (let i = 0; i < _resultant.length; i++) {
+        const v = Math.abs(_resultant[i]);
+        if (v > max_resultant_mag) max_resultant_mag = v;
+    }
+    if (max_resultant_mag < 1e-12) {
+        return spline3_hermite_intersection_spline3_hermite_nd(a, b, 2, result, result_offset);
+    }
+
+    const s_root_count = polynomial_real_roots_in_interval(
+        _resultant, 9, 0, 1, _root_buffer_s, 0
+    );
+
+    // Look for a true intersection (distance² = 0).
+    for (let i = 0; i < s_root_count; i++) {
+        const s = _root_buffer_s[i];
+        const t = recover_t(a, b, s);
+        if (t >= 0) {
+            result[result_offset] = s;
+            result[result_offset + 1] = t;
+            return 0;
+        }
+    }
+
+    // Otherwise the global min is on the boundary. Test all four edges + four
+    // corners. The corners are picked up automatically by `nearest_t_on_curve`
+    // since it tests t = 0 and t = 1 for the free parameter.
+
+    let best_s = 0;
+    let best_t = 0;
+    let best_d2 = Number.POSITIVE_INFINITY;
+
+    // Edge s = 0: minimise ‖A(0) − B(t)‖² over t.
+    {
+        const px = a[0], py = a[4];
+        const r = nearest_t_on_curve(_B_x_mono, _B_y_mono, px, py);
+        if (r[1] < best_d2) {
+            best_d2 = r[1];
+            best_s = 0;
+            best_t = r[0];
+        }
+    }
+    // Edge s = 1.
+    {
+        const px = a[1], py = a[5];
+        const r = nearest_t_on_curve(_B_x_mono, _B_y_mono, px, py);
+        if (r[1] < best_d2) {
+            best_d2 = r[1];
+            best_s = 1;
+            best_t = r[0];
+        }
+    }
+    // Edge t = 0: minimise ‖A(s) − B(0)‖² over s.
+    {
+        const px = b[0], py = b[4];
+        const r = nearest_t_on_curve(_A_x_mono, _A_y_mono, px, py);
+        if (r[1] < best_d2) {
+            best_d2 = r[1];
+            best_s = r[0];
+            best_t = 0;
+        }
+    }
+    // Edge t = 1.
+    {
+        const px = b[1], py = b[5];
+        const r = nearest_t_on_curve(_A_x_mono, _A_y_mono, px, py);
+        if (r[1] < best_d2) {
+            best_d2 = r[1];
+            best_s = r[0];
+            best_t = 1;
+        }
+    }
+
+    result[result_offset] = best_s;
+    result[result_offset + 1] = best_t;
+    return best_d2;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * ND specialization (dim ≥ 3). See module preamble for algorithmic notes.
+ *
+ * @param {Float64Array|number[]} a length 4*dim
+ * @param {Float64Array|number[]} b length 4*dim
+ * @param {number} dim ≥ 3 (also correct for dim ≥ 2 but slower than the 2D path)
+ * @param {Float64Array|number[]} result writes [s, t]
+ * @param {number} result_offset
+ * @returns {number} squared distance at closest approach
+ */
+export function spline3_hermite_intersection_spline3_hermite_nd(a: Float64Array | number[], b: Float64Array | number[], dim: number, result: Float64Array | number[], result_offset: number): number;
+//# sourceMappingURL=spline3_hermite_intersection_spline3_hermite_nd.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_intersection_spline3_hermite_nd.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_intersection_spline3_hermite_nd.js"],"names":[],"mappings":"AAmPA;;;;;;;;;GASG;AACH,mEAPW,YAAY,GAAC,MAAM,EAAE,KACrB,YAAY,GAAC,MAAM,EAAE,OACrB,MAAM,UACN,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,GACJ,MAAM,CAuFlB"}