@woosh/meep-engine 2.134.3 → 2.134.5

package/package.json

@@ -5,7 +5,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.134.3",
+  "version": "2.134.5",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

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

@@ -0,0 +1,23 @@
+/**
+ * Closed-form solution for the rotation that best aligns two sets of unit
+ * vectors, via Horn (1987) "Closed-form solution of absolute orientation using
+ * unit quaternions".
+ *
+ * Given paired unit vectors {a_i} and {b_i}, finds the unit quaternion q such
+ * that rotating each b_i by q minimizes Σ |a_i − R(q)·b_i|².
+ *
+ * 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`).
+ *
+ * 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 {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`.
+ */
+export function v3_rigid_align_paired_unit_vectors(a_xyz: Float32Array | number[], b_xyz: Float32Array | number[], count: number, out_quaternion: Float32Array | 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

@@ -0,0 +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"}

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

@@ -0,0 +1,96 @@
+import { BinaryDataType } from "../../binary/type/BinaryDataType.js";
+import { matrix_top_eigenvector_power_iteration } from "../../graph/eigen/matrix_top_eigenvector_power_iteration.js";
+import { SquareMatrix } from "../../math/matrix/SquareMatrix.js"
+
+const scratch_horn_n = new SquareMatrix(4, BinaryDataType.Float64);
+
+/**
+ * Closed-form solution for the rotation that best aligns two sets of unit
+ * vectors, via Horn (1987) "Closed-form solution of absolute orientation using
+ * unit quaternions".
+ *
+ * Given paired unit vectors {a_i} and {b_i}, finds the unit quaternion q such
+ * that rotating each b_i by q minimizes Σ |a_i − R(q)·b_i|².
+ *
+ * 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`).
+ *
+ * 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 {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`.
+ */
+export function v3_rigid_align_paired_unit_vectors(a_xyz, b_xyz, count, out_quaternion) {
+
+    // Cross-correlation matrix S_ij = Σ b_i_component * a_j_component
+    // Note: S is built as Σ b ⊗ aᵀ (Horn 1987 convention) — the rotation
+    // recovered will take b onto a.
+    let Sxx = 0, Sxy = 0, Sxz = 0;
+    let Syx = 0, Syy = 0, Syz = 0;
+    let Szx = 0, Szy = 0, Szz = 0;
+
+    for (let i = 0; i < count; i++) {
+        const i3 = i * 3;
+        const ax = a_xyz[i3], ay = a_xyz[i3 + 1], az = a_xyz[i3 + 2];
+        const bx = b_xyz[i3], by = b_xyz[i3 + 1], bz = b_xyz[i3 + 2];
+
+        Sxx += bx * ax;
+        Sxy += bx * ay;
+        Sxz += bx * az;
+        Syx += by * ax;
+        Syy += by * ay;
+        Syz += by * az;
+        Szx += bz * ax;
+        Szy += bz * ay;
+        Szz += bz * az;
+    }
+
+    // Horn's 4x4 symmetric matrix N (scalar-last quaternion ordering: x, y, z, w).
+    //
+    // From the paper, ordered for scalar-FIRST quaternion (w, x, y, z):
+    //   N00 = Sxx + Syy + Szz       N01 = Syz - Szy            N02 = Szx - Sxz            N03 = Sxy - Syx
+    //   N11 = Sxx - Syy - Szz       N12 = Sxy + Syx            N13 = Szx + Sxz
+    //   N22 = -Sxx + Syy - Szz      N23 = Syz + Szy
+    //   N33 = -Sxx - Syy + Szz
+    //
+    // We rebind to (x, y, z, w):
+    //   row/col 0 = x, 1 = y, 2 = z, 3 = w
+    // i.e. swap original index 0 with 3 and shift others down.
+    const Nxx = Sxx - Syy - Szz;
+    const Nyy = -Sxx + Syy - Szz;
+    const Nzz = -Sxx - Syy + Szz;
+    const Nww = Sxx + Syy + Szz;
+    const Nxy = Sxy + Syx;
+    const Nxz = Szx + Sxz;
+    const Nxw = Syz - Szy;
+    const Nyz = Syz + Szy;
+    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]
+    d[0] = Nxx;
+    d[5] = Nyy;
+    d[10] = Nzz;
+    d[15] = Nww;
+    d[1] = Nxy;
+    d[4] = Nxy;
+    d[2] = Nxz;
+    d[8] = Nxz;
+    d[3] = Nxw;
+    d[12] = Nxw;
+    d[6] = Nyz;
+    d[9] = Nyz;
+    d[7] = Nyw;
+    d[13] = Nyw;
+    d[11] = Nzw;
+    d[14] = Nzw;
+
+    return matrix_top_eigenvector_power_iteration(N, out_quaternion);
+}

package/src/core/graph/eigen/matrix_top_eigenvector_power_iteration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Find the eigenvector corresponding to the largest-magnitude eigenvalue of a
+ * 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.
+ *
+ * NOTE: intended to live in @woosh/meep-engine under core/graph/eigen/. Kept
+ * local for now.
+ *
+ * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
+ * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size
+ * @param {number} [max_iterations=64]
+ * @param {number} [tolerance=1e-8] Convergence stops when ||v_next - v|| < tolerance
+ * @returns {number} The Rayleigh quotient (estimated eigenvalue)
+ */
+export function matrix_top_eigenvector_power_iteration(matrix: SquareMatrix, out: number[] | Float32Array | Float64Array, max_iterations?: number, tolerance?: number): number;
+//# sourceMappingURL=matrix_top_eigenvector_power_iteration.d.ts.map

package/src/core/graph/eigen/matrix_top_eigenvector_power_iteration.d.ts.map

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

package/src/core/graph/eigen/matrix_top_eigenvector_power_iteration.js

@@ -0,0 +1,110 @@
+import { assert } from "@woosh/meep-engine/src/core/assert.js";
+
+let scratch_next = new Float64Array(16);
+
+function ensure_scratch(n) {
+    if (scratch_next.length < n) scratch_next = new Float64Array(n);
+    return scratch_next;
+}
+
+/**
+ * Find the eigenvector corresponding to the largest-magnitude eigenvalue of a
+ * 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.
+ *
+ * NOTE: intended to live in @woosh/meep-engine under core/graph/eigen/. Kept
+ * local for now.
+ *
+ * @param {SquareMatrix} matrix Symmetric, column-major as per SquareMatrix
+ * @param {number[]|Float32Array|Float64Array} out Eigenvector is written here, length >= matrix.size
+ * @param {number} [max_iterations=64]
+ * @param {number} [tolerance=1e-8] Convergence stops when ||v_next - v|| < tolerance
+ * @returns {number} The Rayleigh quotient (estimated eigenvalue)
+ */
+export function matrix_top_eigenvector_power_iteration(
+    matrix,
+    out,
+    max_iterations = 64,
+    tolerance = 1e-8
+) {
+    assert.defined(matrix, "matrix");
+    assert.defined(out, "out");
+
+    const n = matrix.size;
+    const data = matrix.data;
+
+    // Deterministic asymmetric initial vector. A uniform init (e.g. 1/√n in
+    // every slot) can be orthogonal to the dominant eigenvector when the matrix
+    // has block structure, stalling iteration on a sub-dominant eigenvalue.
+    // Irrational-component cosines avoid this for any reasonable n.
+    let init_norm_sq = 0;
+    for (let i = 0; i < n; i++) {
+        const v = Math.cos(i * 1.7 + 0.3);
+        out[i] = v;
+        init_norm_sq += v * v;
+    }
+    const init_inv = 1 / Math.sqrt(init_norm_sq);
+    for (let i = 0; i < n; i++) out[i] *= init_inv;
+
+    const next = ensure_scratch(n);
+    let eigenvalue = 0;
+
+    for (let iter = 0; iter < max_iterations; iter++) {
+        // next = matrix * out
+        // Column-major: data[col * n + row] is element at (row, col)
+        for (let row = 0; row < n; row++) {
+            let sum = 0;
+            for (let col = 0; col < n; col++) {
+                sum += data[col * n + row] * out[col];
+            }
+            next[row] = sum;
+        }
+
+        // Rayleigh quotient = out . next  (since out is unit length and matrix is symmetric)
+        let rayleigh = 0;
+        for (let i = 0; i < n; i++) {
+            rayleigh += out[i] * next[i];
+        }
+
+        // Normalize next
+        let length_sqr = 0;
+        for (let i = 0; i < n; i++) {
+            length_sqr += next[i] * next[i];
+        }
+
+        if (length_sqr === 0) {
+            // Degenerate input — bail out, leave `out` as-is
+            return 0;
+        }
+
+        const inv_length = 1 / Math.sqrt(length_sqr);
+
+        // Sign-align next with out so we can measure convergence by raw difference.
+        // (Power iteration has a sign ambiguity per step when eigenvalue is negative.)
+        let dot = 0;
+        for (let i = 0; i < n; i++) {
+            dot += next[i] * out[i];
+        }
+        const sign = dot < 0 ? -inv_length : inv_length;
+
+        let delta_sqr = 0;
+        for (let i = 0; i < n; i++) {
+            const v = next[i] * sign;
+            const d = v - out[i];
+            delta_sqr += d * d;
+            out[i] = v;
+        }
+
+        eigenvalue = rayleigh;
+
+        if (delta_sqr < tolerance * tolerance) {
+            break;
+        }
+    }
+
+    return eigenvalue;
+}

package/src/engine/animation/curve/AnimationCurve.d.ts

@@ -136,12 +136,15 @@ export class AnimationCurve implements Iterable<Keyframe> {
      */
     alignTangents(index: number): void;
     /**
-     *
+     * @deprecated
      * @param {number} index Index of keyframe to be affected
      * @param {number} weight How much smoothing to apply, 1 will be fully smoothed out and 0 will have no effect at all. Value between 0 and 1
      */
     smoothTangents(index: number, weight: number): void;
-    smoothAllTangents(): void;
+    /**
+     * Smooth out the curve
+     */
+    alignAllTangents(): void;
     /**
      * The copy is deep
      * @param {AnimationCurve} other
@@ -175,6 +178,11 @@ export class AnimationCurve implements Iterable<Keyframe> {
      * @type {boolean}
      */
     readonly isAnimationCurve: boolean;
+    /**
+     * Smooths out the curve.
+     * Alias to {@link alignAllTangents}.
+     */
+    smooth: () => void;
     /**
      * @deprecated use `getKeyIndexLow` instead
      */

package/src/engine/animation/curve/AnimationCurve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gDANwB,QAAQ;IAsZ5B;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;;OASG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAezB;IAndD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAuClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAmDlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAmChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAWhB;IAED,0BAKC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAkBC;IAoFL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;IAGzC;;OAEG;IACH,0BA3Te,MAAM,KACJ,MAAM,CA0TmB;IA7FtC,wDAQC;CAuEJ;yBAhfwB,eAAe"}
+{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,gDANwB,QAAQ;IAqZ5B;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;;OASG;IACH,6BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAUzB;IAED;;;;;;OAMG;IACH,4BALW,MAAM,YACN,MAAM,UACN,MAAM,GACL,cAAc,CAOzB;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,eACN,MAAM,YACN,MAAM,aACN,MAAM,GACL,cAAc,CAezB;IAldD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAuClB;IAED;;;OAGG;IACH,cAFW,QAAQ,EAAE,QAUpB;IAED;;;;OAIG;IACH,YAHW,QAAQ,GACN,OAAO,CAYnB;IAED;;OAEG;IACH,cAEC;IAGD;;;OAGG;IACH,WAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,qBAEC;IAED;;;;OAIG;IACH,yBAUC;IAED;;;;OAIG;IACH,uBAUC;IAED;;;;OAIG;IACH,uBAcC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAmDlB;IAED;;;;OAIG;IACH,eAHW,MAAM,GACL,MAAM,CAoCjB;IAED;;;;OAIG;IACH,qBAFW,MAAM,QAmChB;IAED;;;;OAIG;IACH,sBAHW,MAAM,UACN,MAAM,QAIhB;IAED;;OAEG;IACH,yBAQC;IAGD;;;OAGG;IACH,YAFW,cAAc,QAIxB;IAED;;;OAGG;IACH,SAFY,cAAc,CAQzB;IAED;;;;OAIG;IACH,cAHW,cAAc,GACb,OAAO,CAIlB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;MAIC;IAED;;aAkBC;IAoFL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;IAGzC;;;OAGG;IACH,mBAA+B;IAE/B;;OAEG;IACH,0BAhUe,MAAM,KACJ,MAAM,CA+TmB;IAnGtC,wDAQC;CAuEJ;yBA/ewB,eAAe"}

package/src/engine/animation/curve/AnimationCurve.js

@@ -1,7 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { computeHashArray } from "../../../core/collection/array/computeHashArray.js";
 import { isArrayEqual } from "../../../core/collection/array/isArrayEqual.js";
-import { lerp } from "../../../core/math/lerp.js";
 import { invokeObjectClone } from "../../../core/model/object/invokeObjectClone.js";
 import { invokeObjectHash } from "../../../core/model/object/invokeObjectHash.js";
 import { invokeObjectToJSON } from "../../../core/model/object/invokeObjectToJSON.js";
@@ -337,25 +336,24 @@ export class AnimationCurve {
     }
 
     /**
-     *
+     * @deprecated
      * @param {number} index Index of keyframe to be affected
      * @param {number} weight How much smoothing to apply, 1 will be fully smoothed out and 0 will have no effect at all. Value between 0 and 1
      */
     smoothTangents(index, weight) {
-        const keys = this.keys;
-
-        const key = keys[index];
-
-        const average = lerp(key.inTangent, key.outTangent, 0.5);
-
-        key.inTangent = lerp(key.inTangent, average, weight);
-        key.outTangent = lerp(key.outTangent, average, weight);
+        throw new Error('Deprecated, use alignTagents() instead');
     }
 
-    smoothAllTangents() {
+    /**
+     * Smooth out the curve
+     */
+    alignAllTangents() {
         const n = this.length;
+
+        // TODO add support for looping curves
+
         for (let i = 0; i < n; i++) {
-            this.smoothTangents(i, 1);
+            this.alignTangents(i);
         }
     }
 
@@ -513,6 +511,12 @@ export class AnimationCurve {
 AnimationCurve.prototype.isAnimationCurve = true;
 
 
+/**
+ * Smooths out the curve.
+ * Alias to {@link alignAllTangents}.
+ */
+AnimationCurve.prototype.smooth = AnimationCurve.prototype.alignAllTangents;
+
 /**
  * @deprecated use `getKeyIndexLow` instead
  */

package/src/engine/animation/curve/view/prototype.js

@@ -81,6 +81,6 @@ for (let i = 0; i < keys.length; i++) {
 
     curve.alignTangents(i);
 }
-curve.smoothAllTangents();
+curve.alignAllTangents();
 
 addCurve(curve)