@woosh/meep-engine 3.39.0 → 3.41.0

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.39.0",
+  "version": "3.41.0",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/core/geom/3d/quaternion/swing_twist_clamp.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Project a rotation into a box of swing-twist limits: the twist about X and the swing over Y and Z,
+ * as {@link swing_twist_error_array} measures them, each clamped to its own `[lower, upper]`.
+ *
+ * This is the box a physics `Joint` with `swingTwist` on allows: the joint solver limits each of
+ * the three positions separately, so Y and Z swing are a box and not a cone. A rotation already
+ * inside is written back unchanged, bit for bit; one outside is composed again from the clamped
+ * positions ({@link swing_twist_compose_array}).
+ *
+ * An axis that is not limited takes `-Infinity` / `Infinity`; a locked one takes `0` / `0`.
+ *
+ * `out` may be `q`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} q
+ * @param {number} q_offset `[x, y, z, w]`, unit
+ * @param {Float64Array} lower
+ * @param {Float64Array} upper
+ * @param {number} limit_offset `[twist, swing y, swing z]` in `lower` and `upper`, radians
+ * @returns {boolean} whether any position was outside its limits
+ */
+export function swing_twist_clamp_array(out: Float64Array, out_offset: number, q: Float64Array, q_offset: number, lower: Float64Array, upper: Float64Array, limit_offset: number): boolean;
+//# sourceMappingURL=swing_twist_clamp.d.ts.map

package/src/core/geom/3d/quaternion/swing_twist_clamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_clamp.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_clamp.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6CATW,YAAY,cACZ,MAAM,KACN,YAAY,YACZ,MAAM,SACN,YAAY,SACZ,YAAY,gBACZ,MAAM,GACJ,OAAO,CAgCnB"}

package/src/core/geom/3d/quaternion/swing_twist_clamp.js

@@ -0,0 +1,62 @@
+import { swing_twist_compose_array } from "./swing_twist_compose.js";
+import { swing_twist_error_array } from "./swing_twist_error.js";
+
+/**
+ * The three swing-twist positions, measured and then clamped.
+ * @type {Float64Array}
+ */
+const e = new Float64Array(3);
+
+/**
+ * Project a rotation into a box of swing-twist limits: the twist about X and the swing over Y and Z,
+ * as {@link swing_twist_error_array} measures them, each clamped to its own `[lower, upper]`.
+ *
+ * This is the box a physics `Joint` with `swingTwist` on allows: the joint solver limits each of
+ * the three positions separately, so Y and Z swing are a box and not a cone. A rotation already
+ * inside is written back unchanged, bit for bit; one outside is composed again from the clamped
+ * positions ({@link swing_twist_compose_array}).
+ *
+ * An axis that is not limited takes `-Infinity` / `Infinity`; a locked one takes `0` / `0`.
+ *
+ * `out` may be `q`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} q
+ * @param {number} q_offset `[x, y, z, w]`, unit
+ * @param {Float64Array} lower
+ * @param {Float64Array} upper
+ * @param {number} limit_offset `[twist, swing y, swing z]` in `lower` and `upper`, radians
+ * @returns {boolean} whether any position was outside its limits
+ */
+export function swing_twist_clamp_array(out, out_offset, q, q_offset, lower, upper, limit_offset) {
+    swing_twist_error_array(q, q_offset, e);
+
+    let clamped = false;
+
+    for (let k = 0; k < 3; k++) {
+        const lo = lower[limit_offset + k];
+        const hi = upper[limit_offset + k];
+
+        const value = e[k];
+
+        if (value < lo) {
+            e[k] = lo;
+            clamped = true;
+        } else if (value > hi) {
+            e[k] = hi;
+            clamped = true;
+        }
+    }
+
+    if (clamped) {
+        swing_twist_compose_array(out, out_offset, e, 0);
+    } else if (out !== q || out_offset !== q_offset) {
+        out[out_offset] = q[q_offset];
+        out[out_offset + 1] = q[q_offset + 1];
+        out[out_offset + 2] = q[q_offset + 2];
+        out[out_offset + 3] = q[q_offset + 3];
+    }
+
+    return clamped;
+}

package/src/core/geom/3d/quaternion/swing_twist_compose.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The rotation whose swing-twist positions are `e[e_offset ..+2]`: the inverse of
+ * {@link swing_twist_error_array}.
+ *
+ * `e[0]` is the twist about X, `e[1]`, `e[2]` the swing as `φ·axis` over Y and Z, and the rotation is
+ * `swing ⊗ twist`. Composed back from what {@link swing_twist_error_array} measured, it is the
+ * measured rotation, on the hemisphere with `w ≥ 0`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} e
+ * @param {number} e_offset `[twist, swing y, swing z]`, radians
+ */
+export function swing_twist_compose_array(out: Float64Array, out_offset: number, e: Float64Array, e_offset: number): void;
+//# sourceMappingURL=swing_twist_compose.d.ts.map

package/src/core/geom/3d/quaternion/swing_twist_compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_compose.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_compose.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,+CALW,YAAY,cACZ,MAAM,KACN,YAAY,YACZ,MAAM,QAwBhB"}

package/src/core/geom/3d/quaternion/swing_twist_compose.js

@@ -0,0 +1,36 @@
+/**
+ * The rotation whose swing-twist positions are `e[e_offset ..+2]`: the inverse of
+ * {@link swing_twist_error_array}.
+ *
+ * `e[0]` is the twist about X, `e[1]`, `e[2]` the swing as `φ·axis` over Y and Z, and the rotation is
+ * `swing ⊗ twist`. Composed back from what {@link swing_twist_error_array} measured, it is the
+ * measured rotation, on the hemisphere with `w ≥ 0`.
+ *
+ * @param {Float64Array} out
+ * @param {number} out_offset receives `[x, y, z, w]`
+ * @param {Float64Array} e
+ * @param {number} e_offset `[twist, swing y, swing z]`, radians
+ */
+export function swing_twist_compose_array(out, out_offset, e, e_offset) {
+    const twist = e[e_offset];
+    const y = e[e_offset + 1];
+    const z = e[e_offset + 2];
+
+    const tx = Math.sin(twist * 0.5);
+    const tw = Math.cos(twist * 0.5);
+
+    const phi = Math.sqrt(y * y + z * z);
+
+    // sin(φ/2) / φ, which is 1/2 as φ goes to 0, as the measure's small-angle branch is
+    const s = phi < 1e-9 ? 0.5 : Math.sin(phi * 0.5) / phi;
+
+    const sy = y * s;
+    const sz = z * s;
+    const sw = Math.cos(phi * 0.5);
+
+    // (0, sy, sz, sw) ⊗ (tx, 0, 0, tw)
+    out[out_offset] = sw * tx;
+    out[out_offset + 1] = sy * tw + sz * tx;
+    out[out_offset + 2] = sz * tw - sy * tx;
+    out[out_offset + 3] = sw * tw;
+}

package/src/core/geom/3d/quaternion/swing_twist_error.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
+ * the per-frame-axis angular positions used by wide-cone angular DOFs.
+ *
+ * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
+ * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
+ * about an axis in the YZ plane that carries X to its new direction). Writes,
+ * into `out`:
+ *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
+ *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
+ *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
+ *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
+ *     an accurate (box-shaped) cone that holds at large tilt.
+ * Reduces continuously to the small-angle vector near identity. Pure scratch /
+ * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
+ * class has an object-based `computeSwingAndTwist`; this is the inlined,
+ * allocation-free form — see the bench that justifies it.)
+ *
+ * The physics joint solver measures a `Joint`'s angular DOFs with it, and IK clamps to the same
+ * measure ({@link swing_twist_clamp_array}), so the two agree on what a limit allows.
+ *
+ * @param {number} dx  qD x
+ * @param {number} dy  qD y
+ * @param {number} dz  qD z
+ * @param {number} dw  qD w
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error(dx: number, dy: number, dz: number, dw: number, out: Float64Array): void;
+/**
+ * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
+ * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
+ * would box each into a new heap object.
+ *
+ * @param {Float64Array} q
+ * @param {number} q_offset
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error_array(q: Float64Array, q_offset: number, out: Float64Array): void;
+//# sourceMappingURL=swing_twist_error.d.ts.map

package/src/core/geom/3d/quaternion/swing_twist_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swing_twist_error.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/quaternion/swing_twist_error.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,sCANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,YAAY,QAWtB;AAKD;;;;;;;;GAQG;AACH,2CAJW,YAAY,YACZ,MAAM,OACN,YAAY,QAoCtB"}

package/src/core/geom/3d/quaternion/swing_twist_error.js

@@ -0,0 +1,85 @@
+/**
+ * Swing-twist decomposition of the relative rotation `qD = conj(qA)⊗qB`, giving
+ * the per-frame-axis angular positions used by wide-cone angular DOFs.
+ *
+ * Decomposes `qD = swing ⊗ twist`, with **twist** the rotation about frame
+ * axis X (the bone / twist axis) and **swing** the residual tilt (a rotation
+ * about an axis in the YZ plane that carries X to its new direction). Writes,
+ * into `out`:
+ *   - `out[0]` = signed twist angle about X, in `(−π, π]` — *exact*, so a twist
+ *     limit engages at the true angle, not the `2·sin(θ/2)` small-angle proxy;
+ *   - `out[1]`, `out[2]` = the swing angle distributed over Y and Z
+ *     (`φ·axis`, φ the true swing angle), so independent Y/Z swing limits form
+ *     an accurate (box-shaped) cone that holds at large tilt.
+ * Reduces continuously to the small-angle vector near identity. Pure scratch /
+ * locals — no allocation, suitable for the per-substep hot loop. (The Quaternion
+ * class has an object-based `computeSwingAndTwist`; this is the inlined,
+ * allocation-free form — see the bench that justifies it.)
+ *
+ * The physics joint solver measures a `Joint`'s angular DOFs with it, and IK clamps to the same
+ * measure ({@link swing_twist_clamp_array}), so the two agree on what a limit allows.
+ *
+ * @param {number} dx  qD x
+ * @param {number} dy  qD y
+ * @param {number} dz  qD z
+ * @param {number} dw  qD w
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error(dx, dy, dz, dw, out) {
+    const q = swing_twist_inputs;
+
+    q[0] = dx;
+    q[1] = dy;
+    q[2] = dz;
+    q[3] = dw;
+
+    swing_twist_error_array(q, 0, out);
+}
+
+/** Where {@link swing_twist_error} packs its quaternion. */
+const swing_twist_inputs = new Float64Array(4);
+
+/**
+ * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
+ * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
+ * would box each into a new heap object.
+ *
+ * @param {Float64Array} q
+ * @param {number} q_offset
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error_array(q, q_offset, out) {
+    let dx = q[q_offset], dy = q[q_offset + 1], dz = q[q_offset + 2], dw = q[q_offset + 3];
+
+    // Shortest arc: work with the hemisphere where dw ≥ 0.
+    if (dw < 0) { dx = -dx; dy = -dy; dz = -dz; dw = -dw; }
+
+    const nxt = Math.sqrt(dx * dx + dw * dw); // |twist| (before normalising)
+    let sy, sz, sw;
+    if (nxt < 1e-12) {
+        // dw ≈ 0 and dx ≈ 0: a ~180° pure swing — twist is undefined, take 0.
+        out[0] = 0;
+        // Swing is qD itself; distribute its angle over Y/Z below.
+        sy = dy; sz = dz; sw = dw;
+    } else {
+        out[0] = 2 * Math.atan2(dx, dw); // exact signed twist about X
+        const tx = dx / nxt, tw = dw / nxt; // normalised twist (tx,0,0,tw)
+        // swing = qD ⊗ conj(twist); its X component is identically 0.
+        sy = dy * tw - dz * tx;
+        sz = dy * tx + dz * tw;
+        sw = dw * tw + dx * tx;
+    }
+
+    if (sw < 0) { sy = -sy; sz = -sz; sw = -sw; }
+    const syz = Math.sqrt(sy * sy + sz * sz);
+    if (syz < 1e-9) {
+        // Near-zero swing: small-angle vector (continuous with φ·axis as φ→0).
+        out[1] = 2 * sy;
+        out[2] = 2 * sz;
+    } else {
+        const phi = 2 * Math.atan2(syz, sw); // exact swing angle in [0, π]
+        const s = phi / syz;
+        out[1] = sy * s;
+        out[2] = sz * s;
+    }
+}

package/src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.d.ts

@@ -8,16 +8,21 @@
  *
  * The matrix N is built so that the eigenvector of its largest eigenvalue
  * IS the optimal rotation quaternion (in scalar-last form, matching meep's
- * `Quaternion`).
+ * `Quaternion`). Largest means signed, not by magnitude: for a coplanar set
+ * (every set of two) det S = 0, which makes N's spectrum symmetric about zero,
+ * so −λmax is an eigenvalue too (±count for a perfect fit). N is decomposed
+ * directly (Jacobi), which needs no gap between the top two eigenvalues, so a
+ * set whose twist is weakly determined (nearly parallel vectors) is solved as
+ * exactly as a well-spread one.
  *
  * Inputs are unit vectors so no centroid subtraction is needed — the rotation
  * is recovered from the cross-correlations alone.
  *
- * @param {Float32Array|number[]} a_xyz Source vectors — Length: count*3, unit length per triple
- * @param {Float32Array|number[]} b_xyz Target vectors — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} a_xyz Target vectors, which R·b_i is fitted onto — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} b_xyz Source vectors, which R rotates — Length: count*3, unit length per triple
  * @param {number} count
- * @param {Float32Array|number[]} out_quaternion Length 4 (x, y, z, w)
- * @returns {number} The maximum eigenvalue ≈ Σ a_i · R·b_i. For a perfect alignment this equals `count`.
+ * @param {Float32Array|Float64Array|number[]} out_quaternion Length 4 (x, y, z, w)
+ * @returns {number} The maximum eigenvalue = Σ a_i · R·b_i at the optimum. For a perfect alignment this equals `count`.
  */
-export function v3_rigid_align_paired_unit_vectors(a_xyz: Float32Array | number[], b_xyz: Float32Array | number[], count: number, out_quaternion: Float32Array | number[]): number;
+export function v3_rigid_align_paired_unit_vectors(a_xyz: Float32Array | Float64Array | number[], b_xyz: Float32Array | Float64Array | number[], count: number, out_quaternion: Float32Array | Float64Array | number[]): number;
 //# sourceMappingURL=v3_rigid_align_paired_unit_vectors.d.ts.map

package/src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_rigid_align_paired_unit_vectors.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,0DANW,YAAY,GAAC,MAAM,EAAE,SACrB,YAAY,GAAC,MAAM,EAAE,SACrB,MAAM,kBACN,YAAY,GAAC,MAAM,EAAE,GACnB,MAAM,CAsElB"}
+{"version":3,"file":"v3_rigid_align_paired_unit_vectors.d.ts","sourceRoot":"","sources":["../../../../../src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,0DANW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,SAClC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,SAClC,MAAM,kBACN,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,GAChC,MAAM,CA+ElB"}

package/src/core/geom/vec3/v3_rigid_align_paired_unit_vectors.js

@@ -1,8 +1,8 @@
-import { BinaryDataType } from "../../binary/type/BinaryDataType.js";
-import { matrix_top_eigenvector_power_iteration } from "../../math/linalg/eigen/matrix_top_eigenvector_power_iteration.js";
-import { SquareMatrix } from "../../math/matrix/SquareMatrix.js"
+import { matrix_symmetric_4x4_eigen } from "../../math/linalg/eigen/matrix_symmetric_4x4_eigen.js";
 
-const scratch_horn_n = new SquareMatrix(4, BinaryDataType.Float64);
+const scratch_horn_n = new Float64Array(16);
+const scratch_eigen_values = new Float64Array(4);
+const scratch_eigen_vectors = new Float64Array(16);
 
 /**
  * Closed-form solution for the rotation that best aligns two sets of unit
@@ -14,16 +14,21 @@ const scratch_horn_n = new SquareMatrix(4, BinaryDataType.Float64);
  *
  * The matrix N is built so that the eigenvector of its largest eigenvalue
  * IS the optimal rotation quaternion (in scalar-last form, matching meep's
- * `Quaternion`).
+ * `Quaternion`). Largest means signed, not by magnitude: for a coplanar set
+ * (every set of two) det S = 0, which makes N's spectrum symmetric about zero,
+ * so −λmax is an eigenvalue too (±count for a perfect fit). N is decomposed
+ * directly (Jacobi), which needs no gap between the top two eigenvalues, so a
+ * set whose twist is weakly determined (nearly parallel vectors) is solved as
+ * exactly as a well-spread one.
  *
  * Inputs are unit vectors so no centroid subtraction is needed — the rotation
  * is recovered from the cross-correlations alone.
  *
- * @param {Float32Array|number[]} a_xyz Source vectors — Length: count*3, unit length per triple
- * @param {Float32Array|number[]} b_xyz Target vectors — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} a_xyz Target vectors, which R·b_i is fitted onto — Length: count*3, unit length per triple
+ * @param {Float32Array|Float64Array|number[]} b_xyz Source vectors, which R rotates — Length: count*3, unit length per triple
  * @param {number} count
- * @param {Float32Array|number[]} out_quaternion Length 4 (x, y, z, w)
- * @returns {number} The maximum eigenvalue ≈ Σ a_i · R·b_i. For a perfect alignment this equals `count`.
+ * @param {Float32Array|Float64Array|number[]} out_quaternion Length 4 (x, y, z, w)
+ * @returns {number} The maximum eigenvalue = Σ a_i · R·b_i at the optimum. For a perfect alignment this equals `count`.
  */
 export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quaternion) {
 
@@ -72,9 +77,8 @@ export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quat
     const Nyw = Szx - Sxz;
     const Nzw = Sxy - Syx;
 
-    const N = scratch_horn_n;
-    const d = N.data;
-    // SquareMatrix is column-major: d[col * 4 + row]
+    // Symmetric, so the index is row*4 + col and col*4 + row alike.
+    const d = scratch_horn_n;
     d[0] = Nxx;
     d[5] = Nyy;
     d[10] = Nzz;
@@ -92,5 +96,15 @@ export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quat
     d[11] = Nzw;
     d[14] = Nzw;
 
-    return matrix_top_eigenvector_power_iteration(N, out_quaternion);
+    const values = scratch_eigen_values;
+    const vectors = scratch_eigen_vectors;
+    matrix_symmetric_4x4_eigen(values, vectors, d);
+
+    // Eigenpairs come back ascending; the last is the largest.
+    out_quaternion[0] = vectors[12];
+    out_quaternion[1] = vectors[13];
+    out_quaternion[2] = vectors[14];
+    out_quaternion[3] = vectors[15];
+
+    return values[3];
 }

package/src/core/math/linalg/eigen/matrix_symmetric_4x4_eigen.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Eigendecomposition of a symmetric 4x4 matrix via cyclic Jacobi rotations.
+ *
+ * Only the upper triangle of `m` is read (the matrix is assumed symmetric, so
+ * row- and column-major are the same); the input is not modified. Eigenpairs
+ * are emitted sorted by **ascending eigenvalue** (signed, not by magnitude),
+ * so index 3 is the largest. Equal eigenvalues keep their column order, so a
+ * multiple of the identity comes back as the identity basis, in order.
+ *
+ * Unlike power iteration, this converges whatever the gaps between eigenvalues:
+ * a ±λ pair or a near-tie at the top costs nothing extra, and only the
+ * eigenvectors of a genuinely repeated eigenvalue are arbitrary (any orthonormal
+ * basis of that eigenspace is returned).
+ *
+ * Eigenvector sign is arbitrary (an eigenvector and its negation are both
+ * valid); callers that need a consistent orientation must fix the sign
+ * themselves.
+ *
+ * @param {Float64Array|Float32Array|number[]} out_values length >= 4, eigenvalues ascending
+ * @param {Float64Array|Float32Array|number[]} out_vectors length >= 16, eigenvector k
+ *   in out_vectors[k*4 .. k*4 + 3] (contiguous per eigenvector)
+ * @param {Float64Array|Float32Array|number[]} m symmetric 4x4 (index = row*4 + col)
+ */
+export function matrix_symmetric_4x4_eigen(out_values: Float64Array | Float32Array | number[], out_vectors: Float64Array | Float32Array | number[], m: Float64Array | Float32Array | number[]): void;
+//# sourceMappingURL=matrix_symmetric_4x4_eigen.d.ts.map

package/src/core/math/linalg/eigen/matrix_symmetric_4x4_eigen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix_symmetric_4x4_eigen.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_symmetric_4x4_eigen.js"],"names":[],"mappings":"AAsFA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,uDALW,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,eAClC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,KAElC,YAAY,GAAC,YAAY,GAAC,MAAM,EAAE,QA0D5C"}

package/src/core/math/linalg/eigen/matrix_symmetric_4x4_eigen.js

@@ -0,0 +1,166 @@
+/**
+ * Maximum number of cyclic Jacobi sweeps. A symmetric 4x4 reaches full double
+ * precision in 3-6 sweeps (Jacobi converges quadratically, whatever the gaps
+ * between eigenvalues): never more than 6 over 200,000 measured matrices,
+ * among them ±λ pairs, near and exact ties, rank 1, Horn's N, and scales from
+ * 1e-310 to 1e300. 50 only bounds the loop.
+ * @type {number}
+ */
+const MAX_SWEEPS = 50;
+
+/**
+ * Working copy of the input, row-major (index = row*4 + col).
+ * @type {Float64Array}
+ */
+const scratch_a = new Float64Array(16);
+
+/**
+ * Rotation accumulator, row-major; its columns become the eigenvectors.
+ * @type {Float64Array}
+ */
+const scratch_v = new Float64Array(16);
+
+/**
+ * Column index of each eigenpair, sorted by ascending eigenvalue.
+ * @type {Uint8Array}
+ */
+const scratch_order = new Uint8Array(4);
+
+/**
+ * One Jacobi rotation in the (p, q) plane that zeroes the off-diagonal entry
+ * a[p][q]. `a` and `v` are 4x4 matrices stored row-major (index = row*4 + col).
+ * `a` is the symmetric working matrix; `v` accumulates the rotations so its
+ * columns become the eigenvectors.
+ *
+ * @param {Float64Array} a symmetric 4x4, mutated in place
+ * @param {Float64Array} v 4x4 rotation accumulator, mutated in place
+ * @param {number} p
+ * @param {number} q
+ */
+function jacobi_rotate(a, v, p, q) {
+    const apq = a[p * 4 + q];
+
+    if (apq === 0) {
+        return;
+    }
+
+    const app = a[p * 4 + p];
+    const aqq = a[q * 4 + q];
+
+    // tan of the rotation angle (Numerical Recipes form, |angle| <= pi/4).
+    const theta = (aqq - app) / (2 * apq);
+    const t = (theta >= 0)
+        ? 1 / (theta + Math.sqrt(theta * theta + 1))
+        : -1 / (-theta + Math.sqrt(theta * theta + 1));
+    const c = 1 / Math.sqrt(t * t + 1);
+    const s = t * c;
+
+    a[p * 4 + p] = app - t * apq;
+    a[q * 4 + q] = aqq + t * apq;
+    a[p * 4 + q] = 0;
+    a[q * 4 + p] = 0;
+
+    for (let r = 0; r < 4; r++) {
+        if (r === p || r === q) {
+            continue;
+        }
+
+        const arp = a[r * 4 + p];
+        const arq = a[r * 4 + q];
+
+        const new_rp = c * arp - s * arq;
+        const new_rq = s * arp + c * arq;
+        a[r * 4 + p] = new_rp;
+        a[p * 4 + r] = new_rp;
+        a[r * 4 + q] = new_rq;
+        a[q * 4 + r] = new_rq;
+    }
+
+    for (let row = 0; row < 4; row++) {
+        const vrp = v[row * 4 + p];
+        const vrq = v[row * 4 + q];
+        v[row * 4 + p] = c * vrp - s * vrq;
+        v[row * 4 + q] = s * vrp + c * vrq;
+    }
+}
+
+/**
+ * Eigendecomposition of a symmetric 4x4 matrix via cyclic Jacobi rotations.
+ *
+ * Only the upper triangle of `m` is read (the matrix is assumed symmetric, so
+ * row- and column-major are the same); the input is not modified. Eigenpairs
+ * are emitted sorted by **ascending eigenvalue** (signed, not by magnitude),
+ * so index 3 is the largest. Equal eigenvalues keep their column order, so a
+ * multiple of the identity comes back as the identity basis, in order.
+ *
+ * Unlike power iteration, this converges whatever the gaps between eigenvalues:
+ * a ±λ pair or a near-tie at the top costs nothing extra, and only the
+ * eigenvectors of a genuinely repeated eigenvalue are arbitrary (any orthonormal
+ * basis of that eigenspace is returned).
+ *
+ * Eigenvector sign is arbitrary (an eigenvector and its negation are both
+ * valid); callers that need a consistent orientation must fix the sign
+ * themselves.
+ *
+ * @param {Float64Array|Float32Array|number[]} out_values length >= 4, eigenvalues ascending
+ * @param {Float64Array|Float32Array|number[]} out_vectors length >= 16, eigenvector k
+ *   in out_vectors[k*4 .. k*4 + 3] (contiguous per eigenvector)
+ * @param {Float64Array|Float32Array|number[]} m symmetric 4x4 (index = row*4 + col)
+ */
+export function matrix_symmetric_4x4_eigen(out_values, out_vectors, m) {
+    const a = scratch_a;
+    const v = scratch_v;
+
+    for (let row = 0; row < 4; row++) {
+        for (let col = row; col < 4; col++) {
+            const value = m[row * 4 + col];
+            a[row * 4 + col] = value;
+            a[col * 4 + row] = value;
+
+            v[row * 4 + col] = row === col ? 1 : 0;
+            v[col * 4 + row] = row === col ? 1 : 0;
+        }
+    }
+
+    for (let sweep = 0; sweep < MAX_SWEEPS; sweep++) {
+        const scale = Math.abs(a[0]) + Math.abs(a[5]) + Math.abs(a[10]) + Math.abs(a[15]);
+        const off = Math.abs(a[1]) + Math.abs(a[2]) + Math.abs(a[3])
+            + Math.abs(a[6]) + Math.abs(a[7]) + Math.abs(a[11]);
+
+        if (off <= 1e-18 * scale) {
+            break;
+        }
+
+        jacobi_rotate(a, v, 0, 1);
+        jacobi_rotate(a, v, 0, 2);
+        jacobi_rotate(a, v, 0, 3);
+        jacobi_rotate(a, v, 1, 2);
+        jacobi_rotate(a, v, 1, 3);
+        jacobi_rotate(a, v, 2, 3);
+    }
+
+    // Eigenvalues live on the diagonal; eigenvector k is column k of V.
+    // Stable insertion sort of the four column indices by eigenvalue.
+    const order = scratch_order;
+
+    for (let k = 0; k < 4; k++) {
+        const value = a[k * 5];
+        let slot = k;
+
+        while (slot > 0 && a[order[slot - 1] * 5] > value) {
+            order[slot] = order[slot - 1];
+            slot--;
+        }
+
+        order[slot] = k;
+    }
+
+    for (let k = 0; k < 4; k++) {
+        const col = order[k];
+        out_values[k] = a[col * 5];
+        out_vectors[k * 4] = v[col];
+        out_vectors[k * 4 + 1] = v[4 + col];
+        out_vectors[k * 4 + 2] = v[8 + col];
+        out_vectors[k * 4 + 3] = v[12 + col];
+    }
+}

package/src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.d.ts

@@ -3,9 +3,11 @@
  * symmetric square matrix using power iteration.
  *
  * Designed for small symmetric matrices where the dominant eigenvalue is
- * well-separated from the rest (Horn's quaternion method on a 4x4, PCA on a
- * 3x3 covariance, etc.). Unsuitable when the top two eigenvalues have nearly
- * equal magnitude — convergence stalls in that regime.
+ * well-separated from the rest (PCA on a 3x3 covariance, etc.). Unsuitable
+ * when the top two eigenvalues have nearly equal magnitude — convergence
+ * stalls in that regime. That rules out Horn's quaternion matrix: a coplanar
+ * input makes its spectrum symmetric about zero (+λ and −λ); use
+ * `matrix_symmetric_4x4_eigen` there.
  *
  * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
  * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size

package/src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matrix_top_eigenvector_power_iteration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AACH,kFALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,mBAClC,MAAM,cACN,MAAM,GACJ,MAAM,CAoFlB"}
+{"version":3,"file":"matrix_top_eigenvector_power_iteration.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;GAgBG;AACH,kFALW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,mBAClC,MAAM,cACN,MAAM,GACJ,MAAM,CAoFlB"}

package/src/core/math/linalg/eigen/matrix_top_eigenvector_power_iteration.js

@@ -12,9 +12,11 @@ function ensure_scratch(n) {
  * symmetric square matrix using power iteration.
  *
  * Designed for small symmetric matrices where the dominant eigenvalue is
- * well-separated from the rest (Horn's quaternion method on a 4x4, PCA on a
- * 3x3 covariance, etc.). Unsuitable when the top two eigenvalues have nearly
- * equal magnitude — convergence stalls in that regime.
+ * well-separated from the rest (PCA on a 3x3 covariance, etc.). Unsuitable
+ * when the top two eigenvalues have nearly equal magnitude — convergence
+ * stalls in that regime. That rules out Horn's quaternion matrix: a coplanar
+ * input makes its spectrum symmetric about zero (+λ and −λ); use
+ * `matrix_symmetric_4x4_eigen` there.
  *
  * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
  * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size

package/src/engine/EngineHarness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AA+EA;IAmBI;;;;;OAKG;IACH;QAHmE,aAAa,GAArE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5C,QAAQ,MAAM,CAAC,CAM1B;IAED;;;;;;;;;OASG;IACH,0BAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;;;;OASG;IACH,6BAHW,MAAM,GACJ,aAAa,CAQzB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACN,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;;OAYG;IACH;QAXyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACP,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBA2DhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACpB,QAAQ,MAAM,CAAC,CA6C3B;IAGD;;;;;;;;;;OAUG;IACH;QAR2B,MAAM,EAAtB,MAAM;QACY,IAAI,GAAtB,OAAO;QACU,QAAQ;QACR,UAAU,GAA3B,MAAM;QACW,UAAU,GAA3B,MAAM;QACY,WAAW,GAA7B,OAAO;QACL,OAAO,CA0DnB;IArfD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAEb;IAGL;;;OAGG;IACH,QAFU,MAAM,CAEiC;IA2DrD;;;;;OAKG;IACH;QAJkE,aAAa,GAApE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5B,mBAAmB,GAApC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CAkXJ;;IAID;;;OAGG;IACH,uCAMC;;qCA7iBY,OAAO,iCAAiC,EAAE,sBAAsB;mBAxB1D,aAAa;oCACI,0BAA0B;sBAOxC,kCAAkC;8BAjB1B,mCAAmC;oBAD7C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAG1B,yBAAyB;oBAQzB,8BAA8B"}
+{"version":3,"file":"EngineHarness.d.ts","sourceRoot":"","sources":["../../../src/engine/EngineHarness.js"],"names":[],"mappings":"AAmFA;IAmBI;;;;;OAKG;IACH;QAHmE,aAAa,GAArE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5C,QAAQ,MAAM,CAAC,CAM1B;IAED;;;;;;;;;OASG;IACH,0BAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;;;;OASG;IACH,6BAHW,MAAM,GACJ,aAAa,CAQzB;IAkED;;;;;;;;;;;;;OAaG;IACH;QAZyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACN,MAAM,GAAtB,OAAO;QACQ,QAAQ,GAAvB,MAAM;QACS,KAAK,GAApB,MAAM;QACS,GAAG,GAAlB,MAAM;QACU,QAAQ,GAAxB,OAAO;QACQ,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACS,WAAW,GAA1B,MAAM;QACJ,MAAM,CA+DlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QApB0B,MAAM,EAArB,MAAM;QACgC,KAAK,GAA3C;YAAC,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAC;YAAA,CAAC,EAAC,MAAM,CAAA;SAAC;QACrB,SAAS;QACT,WAAW;QACF,KAAK,GAArB,MAAM;QACU,GAAG,GAAnB,MAAM;QACU,QAAQ,GAAxB,MAAM;QACwB,WAAW,GAAzC;YAAC,CAAC,EAAC,MAAM,CAAC;YAAC,CAAC,EAAC,MAAM,CAAA;SAAC;QACJ,iBAAiB,GAAjC,MAAM;QACW,WAAW,GAA5B,OAAO;QACU,aAAa,GAA9B,OAAO;QACU,YAAY,GAA7B,OAAO;QACU,aAAa,GAA9B,OAAO;QACS,iBAAiB,GAAjC,MAAM;QACU,iBAAiB,GAAjC,MAAM;QACW,gBAAgB,GAAjC,OAAO;QACU,cAAc,GAA/B,OAAO;QACS,mBAAmB,GAAnC,MAAM;QACW,OAAO,GAAxB,OAAO;sBA0EjB;IAGD;;;;;;;;;;;;OAYG;IACH;QAXyB,MAAM,EAApB,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACP,mBAAmB,GAAlC,MAAM;QACU,UAAU,GAA1B,OAAO;QACO,GAAG,GAAjB,KAAK;QACU,YAAY,GAA3B,MAAM;QACU,YAAY,GAA5B,OAAO;QACO,OAAO,GAArB,KAAK;QACU,gBAAgB,GAA/B,MAAM;QACS,iBAAiB,GAAhC,MAAM;sBA2DhB;IAED;;;;;;;OAOG;IACH;QAN0B,YAAY,GAA3B,MAAM;QACQ,MAAM,EAApB,MAAM;QACS,WAAW,GAA1B,MAAM;QACyB,GAAG,GAAlC,sBAAsB;QACpB,QAAQ,MAAM,CAAC,CA6C3B;IAGD;;;;;;;;;;OAUG;IACH;QAR2B,MAAM,EAAtB,MAAM;QACY,IAAI,GAAtB,OAAO;QACU,QAAQ;QACR,UAAU,GAA3B,MAAM;QACW,UAAU,GAA3B,MAAM;QACY,WAAW,GAA7B,OAAO;QACL,OAAO,CAmEnB;IA9fD;;;OAGG;IACH,YAFU,eAAQ,IAAI,CAEb;IAGL;;;OAGG;IACH,QAFU,MAAM,CAEiC;IA2DrD;;;;;OAKG;IACH;QAJkE,aAAa,GAApE,CAAC,MAAM,EAAC,mBAAmB,EAAC,MAAM,EAAC,MAAM,QAAI;QAC5B,mBAAmB,GAApC,OAAO;QACL,QAAQ,MAAM,CAAC,CA0D3B;CA2XJ;;IAID;;;OAGG;IACH,uCAMC;;qCAtjBY,OAAO,iCAAiC,EAAE,sBAAsB;mBA5B1D,aAAa;oCACI,0BAA0B;sBAOxC,kCAAkC;8BAjB1B,mCAAmC;oBAD7C,yBAAyB;mBAK1B,iBAAiB;sBATd,wBAAwB;oBAG1B,yBAAyB;oBAQzB,8BAA8B"}