@woosh/meep-engine 2.134.5 → 2.135.0

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

@@ -0,0 +1,339 @@
+import { polynomial_real_roots_in_interval } from "../linalg/polynomial_real_roots_in_interval.js";
+import { solve_linear_system_GEPP_2x2 } from "../linalg/solve_linear_system_GEPP_2x2.js";
+import { spline3_hermite_to_monomial } from "./spline3_hermite_to_monomial.js";
+
+/*
+ ND specialization (dim ≥ 3). Closest approach is the global minimum of
+
+   Φ(s, t) = Σ_d (A_d(s) − B_d(t))²
+
+ over the closed unit square [0, 1]². It can occur at:
+   1. an interior critical point where ∇Φ = 0
+   2. a boundary edge minimum (one parameter pinned at 0 or 1)
+   3. a corner
+
+ Interior critical points are roots of the bivariate gradient system
+
+   F(s, t) = ½ ∂Φ/∂s = Σ_d (A_d(s) − B_d(t)) A_d′(s)         (bidegree (5, 3))
+   G(s, t) = ½ ∂Φ/∂t = −Σ_d (A_d(s) − B_d(t)) B_d′(t)       (bidegree (3, 5))
+
+ The fully analytical route eliminates t through the 8×8 Sylvester resultant
+ of F and G, yielding a univariate of degree ≤ 34 in s. Implementing that
+ with exact polynomial-coefficient arithmetic is genuinely large code, well
+ beyond the scope of this change. As a first cut, this implementation finds
+ interior critical points by 2D Newton from a starting grid — quadratically
+ convergent once close, but reliant on the grid being fine enough to cover
+ the basins of attraction of all real critical points. It is enough for the
+ routine geometric configurations the rest of this proposal targets and
+ leaves a clear seam for the resultant route to land later without changing
+ the public API.
+
+ Boundary edges and corners are handled exactly: each edge reduces to a
+ quintic-derivative root-finding (degree 5) of the kind already used in the
+ 2D path, and corners are direct evaluations.
+*/
+
+const MAX_DIM = 16;
+
+// Per-dim monomial coefficient buffers, one each for A and B. Length 4*MAX_DIM.
+const _a_mono = new Float64Array(4 * MAX_DIM);
+const _b_mono = new Float64Array(4 * MAX_DIM);
+
+const _newton_FG = new Float64Array(2);
+const _newton_J = new Float64Array(4);
+const _newton_J_scratch = new Float64Array(4);
+const _newton_RHS = new Float64Array(2);
+
+const _candidate_st = new Float64Array(2);
+const _edge_fixed_point = new Float64Array(MAX_DIM);
+
+const NEWTON_MAX_ITER = 32;
+const NEWTON_GRADIENT_TOLERANCE = 1e-13;
+const NEWTON_STEP_TOLERANCE = 1e-15;
+
+const GRID_SIDE = 9; // 9x9 = 81 starting points
+
+const EDGE_QUINTIC_LEN = 6;
+const _edge_quintic = new Float64Array(EDGE_QUINTIC_LEN);
+const _edge_roots = new Float64Array(5);
+
+const CRITICAL_POINT_DEDUPE_TOLERANCE = 1e-7;
+const _seen_s = new Float64Array(GRID_SIDE * GRID_SIDE + 8);
+const _seen_t = new Float64Array(GRID_SIDE * GRID_SIDE + 8);
+
+// ── monomial helpers (per-dim cubic) ───────────────────────────────────────
+
+function poly3_eval(coeffs4, base, x) {
+    return coeffs4[base] + x * (coeffs4[base + 1] + x * (coeffs4[base + 2] + x * coeffs4[base + 3]));
+}
+
+function poly3_deriv(coeffs4, base, x) {
+    return coeffs4[base + 1] + x * (2 * coeffs4[base + 2] + x * 3 * coeffs4[base + 3]);
+}
+
+function poly3_second_deriv(coeffs4, base, x) {
+    return 2 * coeffs4[base + 2] + 6 * coeffs4[base + 3] * x;
+}
+
+// ── core: F, G, and Jacobian at (s, t) ─────────────────────────────────────
+
+function eval_FG(dim, s, t, out) {
+    let F = 0, G = 0;
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        const A = poly3_eval(_a_mono, base, s);
+        const Ap = poly3_deriv(_a_mono, base, s);
+        const B = poly3_eval(_b_mono, base, t);
+        const Bp = poly3_deriv(_b_mono, base, t);
+        const diff = A - B;
+        F += diff * Ap;
+        G -= diff * Bp;
+    }
+    out[0] = F;
+    out[1] = G;
+}
+
+function eval_jacobian(dim, s, t, out_J) {
+    let Jss = 0, Jst = 0, Jts = 0, Jtt = 0;
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        const A = poly3_eval(_a_mono, base, s);
+        const Ap = poly3_deriv(_a_mono, base, s);
+        const App = poly3_second_deriv(_a_mono, base, s);
+        const B = poly3_eval(_b_mono, base, t);
+        const Bp = poly3_deriv(_b_mono, base, t);
+        const Bpp = poly3_second_deriv(_b_mono, base, t);
+        const diff = A - B;
+
+        Jss += Ap * Ap + diff * App;
+        Jst += -Bp * Ap;
+        Jts += -Ap * Bp;
+        Jtt += Bp * Bp - diff * Bpp;
+    }
+    // Row-major 2x2: [Jss, Jst; Jts, Jtt]
+    out_J[0] = Jss;
+    out_J[1] = Jst;
+    out_J[2] = Jts;
+    out_J[3] = Jtt;
+}
+
+function eval_phi(dim, s, t) {
+    let acc = 0;
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        const A = poly3_eval(_a_mono, base, s);
+        const B = poly3_eval(_b_mono, base, t);
+        const diff = A - B;
+        acc += diff * diff;
+    }
+    return acc;
+}
+
+/**
+ * 2D Newton on (F, G) from a starting (s, t). Writes the converged (s, t) into
+ * `out` and returns true iff it converged inside [0, 1]² with small gradient.
+ */
+function newton_2d(dim, s_init, t_init, out) {
+    let s = s_init;
+    let t = t_init;
+
+    for (let iter = 0; iter < NEWTON_MAX_ITER; iter++) {
+        eval_FG(dim, s, t, _newton_FG);
+        const F = _newton_FG[0];
+        const G = _newton_FG[1];
+
+        if (Math.abs(F) < NEWTON_GRADIENT_TOLERANCE && Math.abs(G) < NEWTON_GRADIENT_TOLERANCE) {
+            break;
+        }
+
+        eval_jacobian(dim, s, t, _newton_J);
+
+        _newton_RHS[0] = F;
+        _newton_RHS[1] = G;
+
+        // solve_linear_system_GEPP_2x2 mutates the input matrix; use a scratch copy.
+        for (let k = 0; k < 4; k++) _newton_J_scratch[k] = _newton_J[k];
+        if (!solve_linear_system_GEPP_2x2(_newton_J_scratch, _newton_RHS, _newton_RHS)) {
+            return false;
+        }
+
+        const ds = _newton_RHS[0];
+        const dt = _newton_RHS[1];
+
+        s -= ds;
+        t -= dt;
+
+        if (Math.abs(ds) < NEWTON_STEP_TOLERANCE && Math.abs(dt) < NEWTON_STEP_TOLERANCE) {
+            break;
+        }
+    }
+
+    if (s < -1e-9 || s > 1 + 1e-9) return false;
+    if (t < -1e-9 || t > 1 + 1e-9) return false;
+
+    eval_FG(dim, s, t, _newton_FG);
+    if (Math.abs(_newton_FG[0]) > 1e-6 || Math.abs(_newton_FG[1]) > 1e-6) return false;
+
+    out[0] = s < 0 ? 0 : (s > 1 ? 1 : s);
+    out[1] = t < 0 ? 0 : (t > 1 ? 1 : t);
+    return true;
+}
+
+// ── boundary edge: nearest point on (varying-axis) curve to a fixed N-D point ──
+
+/**
+ * Minimise ‖(curve_mono...)(t) − point[]‖² over t ∈ [0, 1], where the curve
+ * is `dim`-dimensional with monomial coefficients packed as
+ * `[α0_0, α1_0, α2_0, α3_0, α0_1, α1_1, ..., α3_{dim-1}]`.
+ *
+ * The squared distance is a degree-6 polynomial in t; its derivative is a
+ * quintic. We hand the quintic to the polynomial root finder, then test the
+ * roots plus the endpoints t = 0 and t = 1.
+ *
+ * Writes `[t_min, dist²]` into `out` (length ≥ 2).
+ */
+function nearest_t_to_fixed_point(curve_mono, dim, point, point_offset, out) {
+    for (let i = 0; i < EDGE_QUINTIC_LEN; i++) _edge_quintic[i] = 0;
+
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        const dx0 = curve_mono[base] - point[point_offset + d];
+        const dx1 = curve_mono[base + 1];
+        const dx2 = curve_mono[base + 2];
+        const dx3 = curve_mono[base + 3];
+        // derivative coefficients
+        const e0 = dx1, e1 = 2 * dx2, e2 = 3 * dx3;
+
+        // (dx0 + dx1 t + dx2 t² + dx3 t³) · (e0 + e1 t + e2 t²) accumulated
+        _edge_quintic[0] += dx0 * e0;
+        _edge_quintic[1] += dx0 * e1 + dx1 * e0;
+        _edge_quintic[2] += dx0 * e2 + dx1 * e1 + dx2 * e0;
+        _edge_quintic[3] += dx1 * e2 + dx2 * e1 + dx3 * e0;
+        _edge_quintic[4] += dx2 * e2 + dx3 * e1;
+        _edge_quintic[5] += dx3 * e2;
+    }
+
+    const root_count = polynomial_real_roots_in_interval(
+        _edge_quintic, 5, 0, 1, _edge_roots, 0
+    );
+
+    let best_t = 0;
+    let best_d2 = Number.POSITIVE_INFINITY;
+
+    for (let i = -2; i < root_count; i++) {
+        const t = i === -2 ? 0 : (i === -1 ? 1 : _edge_roots[i]);
+        let d2 = 0;
+        for (let d = 0; d < dim; d++) {
+            const base = 4 * d;
+            const v = curve_mono[base] + t * (curve_mono[base + 1] + t * (curve_mono[base + 2] + t * curve_mono[base + 3]));
+            const dv = v - point[point_offset + d];
+            d2 += dv * dv;
+        }
+        if (d2 < best_d2) {
+            best_d2 = d2;
+            best_t = t;
+        }
+    }
+
+    out[0] = best_t;
+    out[1] = best_d2;
+}
+
+// ── public ────────────────────────────────────────────────────────────────
+
+/**
+ * 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, b, dim,
+    result, result_offset
+) {
+    if (dim > MAX_DIM) {
+        throw new Error(`dim=${dim} exceeds MAX_DIM=${MAX_DIM}`);
+    }
+
+    // Pack monomial coefficients per-axis into the module buffers.
+    for (let d = 0; d < dim; d++) {
+        const off = 4 * d;
+        spline3_hermite_to_monomial(_a_mono, off, 1, a[off], a[off + 1], a[off + 2], a[off + 3]);
+        spline3_hermite_to_monomial(_b_mono, off, 1, b[off], b[off + 1], b[off + 2], b[off + 3]);
+    }
+
+    let best_s = 0;
+    let best_t = 0;
+    let best_d2 = Number.POSITIVE_INFINITY;
+    let seen_count = 0;
+
+    const try_candidate = (s, t) => {
+        // Dedupe near-identical critical points discovered from different grid starts.
+        for (let i = 0; i < seen_count; i++) {
+            if (Math.abs(_seen_s[i] - s) < CRITICAL_POINT_DEDUPE_TOLERANCE
+                && Math.abs(_seen_t[i] - t) < CRITICAL_POINT_DEDUPE_TOLERANCE) {
+                return;
+            }
+        }
+        _seen_s[seen_count] = s;
+        _seen_t[seen_count] = t;
+        seen_count++;
+
+        const d2 = eval_phi(dim, s, t);
+        if (d2 < best_d2) {
+            best_d2 = d2;
+            best_s = s;
+            best_t = t;
+        }
+    };
+
+    // Interior critical points via Newton from a grid.
+    const step = 1 / (GRID_SIDE - 1);
+    for (let i = 0; i < GRID_SIDE; i++) {
+        const s_init = i * step;
+        for (let j = 0; j < GRID_SIDE; j++) {
+            const t_init = j * step;
+            if (newton_2d(dim, s_init, t_init, _candidate_st)) {
+                try_candidate(_candidate_st[0], _candidate_st[1]);
+            }
+        }
+    }
+
+    // Boundary edges. Each edge problem reduces to "nearest point on the
+    // *other* curve to a fixed point on the boundary curve".
+    const tmp_pt = _edge_fixed_point;
+
+    // Edge s = 0: fixed point is A(0); minimise over t on B.
+    for (let d = 0; d < dim; d++) tmp_pt[d] = _a_mono[4 * d]; // α0
+    nearest_t_to_fixed_point(_b_mono, dim, tmp_pt, 0, _candidate_st);
+    try_candidate(0, _candidate_st[0]);
+
+    // Edge s = 1: A(1) = α0 + α1 + α2 + α3.
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        tmp_pt[d] = _a_mono[base] + _a_mono[base + 1] + _a_mono[base + 2] + _a_mono[base + 3];
+    }
+    nearest_t_to_fixed_point(_b_mono, dim, tmp_pt, 0, _candidate_st);
+    try_candidate(1, _candidate_st[0]);
+
+    // Edge t = 0: fixed point is B(0); minimise over s on A.
+    for (let d = 0; d < dim; d++) tmp_pt[d] = _b_mono[4 * d];
+    nearest_t_to_fixed_point(_a_mono, dim, tmp_pt, 0, _candidate_st);
+    try_candidate(_candidate_st[0], 0);
+
+    // Edge t = 1.
+    for (let d = 0; d < dim; d++) {
+        const base = 4 * d;
+        tmp_pt[d] = _b_mono[base] + _b_mono[base + 1] + _b_mono[base + 2] + _b_mono[base + 3];
+    }
+    nearest_t_to_fixed_point(_a_mono, dim, tmp_pt, 0, _candidate_st);
+    try_candidate(_candidate_st[0], 1);
+
+    result[result_offset] = best_s;
+    result[result_offset + 1] = best_t;
+    return best_d2;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Boolean intersection test for two cubic Hermite curves.
+ *
+ * Returns `true` if a true intersection exists OR if the closest approach is
+ * within `tolerance` (Euclidean distance). Tolerance = 0 reduces to exact
+ * intersection.
+ *
+ * @param {Float64Array|number[]} a length 4*dim, layout described in {@link spline3_hermite_intersection_spline3_hermite}
+ * @param {Float64Array|number[]} b same layout
+ * @param {number} dim ≥ 1
+ * @param {number} tolerance ≥ 0
+ * @returns {boolean}
+ */
+export function spline3_hermite_intersects_spline3_hermite(a: Float64Array | number[], b: Float64Array | number[], dim: number, tolerance: number): boolean;
+//# sourceMappingURL=spline3_hermite_intersects_spline3_hermite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_intersects_spline3_hermite.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_intersects_spline3_hermite.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,8DANW,YAAY,GAAC,MAAM,EAAE,KACrB,YAAY,GAAC,MAAM,EAAE,OACrB,MAAM,aACN,MAAM,GACJ,OAAO,CAKnB"}

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

@@ -0,0 +1,21 @@
+import { spline3_hermite_intersection_spline3_hermite } from "./spline3_hermite_intersection_spline3_hermite.js";
+
+const _scratch_st = new Float64Array(2);
+
+/**
+ * Boolean intersection test for two cubic Hermite curves.
+ *
+ * Returns `true` if a true intersection exists OR if the closest approach is
+ * within `tolerance` (Euclidean distance). Tolerance = 0 reduces to exact
+ * intersection.
+ *
+ * @param {Float64Array|number[]} a length 4*dim, layout described in {@link spline3_hermite_intersection_spline3_hermite}
+ * @param {Float64Array|number[]} b same layout
+ * @param {number} dim ≥ 1
+ * @param {number} tolerance ≥ 0
+ * @returns {boolean}
+ */
+export function spline3_hermite_intersects_spline3_hermite(a, b, dim, tolerance) {
+    const d2 = spline3_hermite_intersection_spline3_hermite(a, b, dim, _scratch_st, 0);
+    return d2 <= tolerance * tolerance;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * One-dimensional cubic Hermite to monomial-basis conversion.
+ *
+ * Given a Hermite segment defined by `(p0, p1, m0, m1)` whose value at parameter
+ * `t ∈ [0, 1]` is computed by {@link spline3_hermite}, this writes the monomial
+ * coefficients `α₀, α₁, α₂, α₃` into the result array such that
+ *
+ *   spline3_hermite(t, p0, p1, m0, m1) === α₀ + α₁·t + α₂·t² + α₃·t³
+ *
+ * for all t.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} result_stride step between successive coefficient slots; useful when interleaving multiple dimensions in one array
+ * @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_to_monomial(result: number[] | Float32Array | Float64Array, result_offset: number, result_stride: number, p0: number, p1: number, m0: number, m1: number): void;
+//# sourceMappingURL=spline3_hermite_to_monomial.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spline3_hermite_to_monomial.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_to_monomial.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,oDAXW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAiBhB"}

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

@@ -0,0 +1,37 @@
+import { assert } from "../../assert.js";
+
+/**
+ * One-dimensional cubic Hermite to monomial-basis conversion.
+ *
+ * Given a Hermite segment defined by `(p0, p1, m0, m1)` whose value at parameter
+ * `t ∈ [0, 1]` is computed by {@link spline3_hermite}, this writes the monomial
+ * coefficients `α₀, α₁, α₂, α₃` into the result array such that
+ *
+ *   spline3_hermite(t, p0, p1, m0, m1) === α₀ + α₁·t + α₂·t² + α₃·t³
+ *
+ * for all t.
+ *
+ * @param {number[]|Float32Array|Float64Array} result
+ * @param {number} result_offset
+ * @param {number} result_stride step between successive coefficient slots; useful when interleaving multiple dimensions in one array
+ * @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_to_monomial(
+    result,
+    result_offset,
+    result_stride,
+    p0, p1, m0, m1
+) {
+    assert.greaterThan(result_stride, 0, 'result_stride must be greater than 0');
+
+    result[result_offset]                    = p0;
+    result[result_offset + result_stride]    = m0;
+    result[result_offset + 2 * result_stride] = -3 * p0 + 3 * p1 - 2 * m0 - m1;
+    result[result_offset + 3 * result_stride] = 2 * p0 - 2 * p1 + m0 + m1;
+}

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

@@ -19,7 +19,7 @@ export function v3_computeCatmullRomSplineUniformDistance(
     for (let i = 0; i < input_count; i++) {
         const v3 = inputs[i];
 
-        v3.writeToArray(inputs_array, i * 3);
+        v3.toArray(inputs_array, i * 3);
     }
 
     computeCatmullRomSplineUniformDistance(

package/src/core/model/node-graph/visual/NodeGraphVisualData.js

@@ -165,7 +165,7 @@ export class NodeGraphVisualData {
             const node = nodes[i];
 
             node.dimensions.position.set(bounds.x0 + PADDING, bounds.y0 + PADDING);
-            node.dimensions.size.set(bounds.getWidth() - PADDING * 2, bounds.getHeight() - PADDING * 2);
+            node.dimensions.size.set(bounds.width - PADDING * 2, bounds.height - PADDING * 2);
         });
     }