@woosh/meep-engine 2.165.7 → 2.167.0

package/src/core/math/build_gaussian_kernel_1d.js

@@ -1,12 +1,14 @@
+import { assert } from "../assert.js";
 import { gaussian } from "./gaussian.js";
 
 /**
- *
+ * Build a normalized 1-dimensional gaussian kernel, taps sum to 1.
  * @param {Float32Array} kernel
  * @param {number} sample_count
- * @param {number} sigma
+ * @param {number} sigma standard deviation, must be greater than 0. A sigma of 0 makes every tap `NaN`, as the centre tap evaluates `exp(-0/0)`
  */
 export function build_gaussian_kernel_1d(kernel, sample_count, sigma) {
+    assert.greaterThan(sigma, 0, 'sigma');
 
     const half_width = (sample_count - 1) * 0.5;
 

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

@@ -3,8 +3,8 @@
  * @param {number[]|Float32Array} result
  * @param {number} samplesX
  * @param {number} samplesY
- * @param {number} sigma_x
- * @param {number} sigma_y
+ * @param {number} sigma_x standard deviation along X, must be greater than 0. A sigma of 0 makes every tap `NaN`, as the centre tap evaluates `exp(-0/0)`
+ * @param {number} sigma_y standard deviation along Y, must be greater than 0
  */
 export function build_gaussian_kernel_2d(result: number[] | Float32Array, samplesX: number, samplesY: number, sigma_x: number, sigma_y: number): void;
 //# sourceMappingURL=build_gaussian_kernel_2d.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"build_gaussian_kernel_2d.d.ts","sourceRoot":"","sources":["../../../../src/core/math/build_gaussian_kernel_2d.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iDANW,MAAM,EAAE,GAAC,YAAY,YACrB,MAAM,YACN,MAAM,WACN,MAAM,WACN,MAAM,QA6ChB"}
+{"version":3,"file":"build_gaussian_kernel_2d.d.ts","sourceRoot":"","sources":["../../../../src/core/math/build_gaussian_kernel_2d.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iDANW,MAAM,EAAE,GAAC,YAAY,YACrB,MAAM,YACN,MAAM,WACN,MAAM,WACN,MAAM,QA+ChB"}

package/src/core/math/build_gaussian_kernel_2d.js

@@ -6,8 +6,8 @@ import { gaussian } from "./gaussian.js";
  * @param {number[]|Float32Array} result
  * @param {number} samplesX
  * @param {number} samplesY
- * @param {number} sigma_x
- * @param {number} sigma_y
+ * @param {number} sigma_x standard deviation along X, must be greater than 0. A sigma of 0 makes every tap `NaN`, as the centre tap evaluates `exp(-0/0)`
+ * @param {number} sigma_y standard deviation along Y, must be greater than 0
  */
 export function build_gaussian_kernel_2d(
     result,
@@ -16,6 +16,8 @@ export function build_gaussian_kernel_2d(
 ) {
     assert.isNonNegativeInteger(samplesX, 'samplesX');
     assert.isNonNegativeInteger(samplesY, 'samplesY');
+    assert.greaterThan(sigma_x, 0, 'sigma_x');
+    assert.greaterThan(sigma_y, 0, 'sigma_y');
 
     const half_samples_x = (samplesX - 1) * 0.5;
     const half_samples_y = (samplesY - 1) * 0.5;

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

@@ -2,9 +2,9 @@
  * Un-normalized gaussian: `exp(−distance² / (2·sigma²))`.
  * This is not the standard gaussian — it lacks the normalization factor;
  * the standard gaussian would be weighted by `1 / √(2π·sigma²)`.
- * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance.
+ * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance. Must be greater than 0; at 0 the exponent is a division by zero and the result is `NaN` for `distance === 0`.
  * @param {number} distance Distance from the mean (the point at which to evaluate the curve). At 0 the result is 1; it decays toward 0 as |distance| grows.
- * @returns {number} Ranges from 0 to 1 (exclusive of 0, inclusive of 1 at distance 0)
+ * @returns {number} Ranges from 0 to 1, inclusive of 1 at distance 0. Non-zero in exact arithmetic, but `Math.exp` underflows to exactly 0 once `distance/sigma` is large enough (around 27 standard deviations), so callers must not assume a non-zero result.
  */
 export function gaussian(sigma: number, distance: number): number;
 //# sourceMappingURL=gaussian.d.ts.map

package/src/core/math/gaussian.js

@@ -2,9 +2,9 @@
  * Un-normalized gaussian: `exp(−distance² / (2·sigma²))`.
  * This is not the standard gaussian — it lacks the normalization factor;
  * the standard gaussian would be weighted by `1 / √(2π·sigma²)`.
- * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance.
+ * @param {number} sigma Standard deviation. Controls the "width" of the bell curve: larger sigma → wider curve, slower falloff with distance. Must be greater than 0; at 0 the exponent is a division by zero and the result is `NaN` for `distance === 0`.
  * @param {number} distance Distance from the mean (the point at which to evaluate the curve). At 0 the result is 1; it decays toward 0 as |distance| grows.
- * @returns {number} Ranges from 0 to 1 (exclusive of 0, inclusive of 1 at distance 0)
+ * @returns {number} Ranges from 0 to 1, inclusive of 1 at distance 0. Non-zero in exact arithmetic, but `Math.exp` underflows to exactly 0 once `distance/sigma` is large enough (around 27 standard deviations), so callers must not assume a non-zero result.
  */
 export function gaussian(sigma, distance) {
     const d2 = distance * distance;

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

@@ -1 +1 @@
-{"version":3,"file":"spline3_bezier_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_bezier_bounds.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,8CARW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAuEhB"}
+{"version":3,"file":"spline3_bezier_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_bezier_bounds.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,8CARW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA6EhB"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../assert.js";
 import { max2 } from "../max2.js";
+import { max3 } from "../max3.js";
 import { min2 } from "../min2.js";
 import { spline3_bezier } from "./spline3_bezier.js";
 
@@ -27,9 +28,14 @@ export function spline3_bezier_bounds(result, result_offset, result_stride, p0,
     let min = min2(p0, p3);
     let max = max2(p0, p3);
 
-    if (Math.abs(a) < 1e-12) {
+    // `a`, `b` and `c` all scale linearly with the curve's coordinates, so the degeneracy test has to
+    // be relative to them. An absolute threshold silently treats an entire small-coordinate curve as
+    // degenerate and reports the endpoints as the bounds, missing interior extrema.
+    const epsilon = max3(Math.abs(a), Math.abs(b), Math.abs(c)) * 1e-12;
 
-        if (Math.abs(b) >= 1e-12) {
+    if (Math.abs(a) <= epsilon) {
+
+        if (Math.abs(b) > epsilon) {
             const t = -c / b;
 
             if (0 < t && t < 1) {
@@ -49,10 +55,11 @@ export function spline3_bezier_bounds(result, result_offset, result_stride, p0,
     } else {
 
         const b2ac = b * b - 4 * c * a;
-        const sqrtb2ac = Math.sqrt(b2ac);
 
         if (b2ac >= 0) {
 
+            const sqrtb2ac = Math.sqrt(b2ac);
+
             const t1 = (-b + sqrtb2ac) / (2 * a);
 
             if (0 < t1 && t1 < 1) {

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

@@ -1,14 +1,15 @@
 /**
- * 1D
- * Cubic spline.
- * The result is [v0, m0, v1, m1] where X are values are M are tangents.
+ * One-dimensional cubic curve conversion from bezier to Hermite
+ * The result is `[p0, p1, m0, m1]` where P are positions and M are tangents, matching the argument
+ * order taken by {@link spline3_hermite} and the layout written by {@link spline3_hermite_subdivide}.
+ * The result can therefore be fed straight back into {@link spline3_hermite_to_bezier}.
  * @param {Float32Array|number[]} result where to put results
  * @param {number} result_offset offset to start writing at in result array
  * @param {number} result_stride how far to step between each written value. Necessary for N-dimensional curves where we want to interleave multiple curves together, such as for color or quaternions
- * @param {number} p0
- * @param {number} p1
- * @param {number} p2
- * @param {number} p3
+ * @param {number} p0 first bezier control point
+ * @param {number} p1 second bezier control point
+ * @param {number} p2 third bezier control point
+ * @param {number} p3 fourth bezier control point
  * @see spline3_hermite_to_bezier
  */
 export function spline3_bezier_to_hermite(result: Float32Array | number[], result_offset: number, result_stride: number, p0: number, p1: number, p2: number, p3: number): void;

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

@@ -1 +1 @@
-{"version":3,"file":"spline3_bezier_to_hermite.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_bezier_to_hermite.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,kDATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB"}
+{"version":3,"file":"spline3_bezier_to_hermite.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_bezier_to_hermite.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,kDATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB"}

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

@@ -1,14 +1,15 @@
 /**
- * 1D
- * Cubic spline.
- * The result is [v0, m0, v1, m1] where X are values are M are tangents.
+ * One-dimensional cubic curve conversion from bezier to Hermite
+ * The result is `[p0, p1, m0, m1]` where P are positions and M are tangents, matching the argument
+ * order taken by {@link spline3_hermite} and the layout written by {@link spline3_hermite_subdivide}.
+ * The result can therefore be fed straight back into {@link spline3_hermite_to_bezier}.
  * @param {Float32Array|number[]} result where to put results
  * @param {number} result_offset offset to start writing at in result array
  * @param {number} result_stride how far to step between each written value. Necessary for N-dimensional curves where we want to interleave multiple curves together, such as for color or quaternions
- * @param {number} p0
- * @param {number} p1
- * @param {number} p2
- * @param {number} p3
+ * @param {number} p0 first bezier control point
+ * @param {number} p1 second bezier control point
+ * @param {number} p2 third bezier control point
+ * @param {number} p3 fourth bezier control point
  * @see spline3_hermite_to_bezier
  */
 export function spline3_bezier_to_hermite(
@@ -22,12 +23,12 @@ export function spline3_bezier_to_hermite(
 
     const TENSION_FACTOR = 3;
 
-    const v0 = (p1 - p0) * TENSION_FACTOR;
-    const v1 = (p3 - p2) * TENSION_FACTOR;
+    const m0 = (p1 - p0) * TENSION_FACTOR;
+    const m1 = (p3 - p2) * TENSION_FACTOR;
 
     result[result_offset + 0 * result_stride] = p0;
-    result[result_offset + 1 * result_stride] = v0;
-    result[result_offset + 2 * result_stride] = p3;
-    result[result_offset + 3 * result_stride] = v1;
+    result[result_offset + 1 * result_stride] = p3;
+    result[result_offset + 2 * result_stride] = m0;
+    result[result_offset + 3 * result_stride] = m1;
 
 }

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

@@ -1 +1 @@
-{"version":3,"file":"spline3_hermite_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_bounds.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,+CAXW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAqFhB"}
+{"version":3,"file":"spline3_hermite_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_bounds.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,+CAXW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA2FhB"}

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

@@ -1,5 +1,6 @@
 import { assert } from "../../assert.js";
 import { max2 } from "../max2.js";
+import { max3 } from "../max3.js";
 import { min2 } from "../min2.js";
 import { spline3_hermite } from "./spline3_hermite.js";
 
@@ -40,9 +41,14 @@ export function spline3_hermite_bounds(
     let min = min2(p0, p1);
     let max = max2(p0, p1);
 
-    if (Math.abs(a) < 1e-12) {
+    // `a`, `b` and `c` all scale linearly with the curve's coordinates, so the degeneracy test has to
+    // be relative to them. An absolute threshold silently treats an entire small-coordinate curve as
+    // degenerate and reports the endpoints as the bounds, missing interior extrema.
+    const epsilon = max3(Math.abs(a), Math.abs(b), Math.abs(c)) * 1e-12;
 
-        if (Math.abs(b) >= 1e-12) {
+    if (Math.abs(a) <= epsilon) {
+
+        if (Math.abs(b) > epsilon) {
             const t = -c / b;
 
             if (0 < t && t < 1) {
@@ -62,10 +68,11 @@ export function spline3_hermite_bounds(
     } else {
 
         const b2ac = b * b - 4 * c * a;
-        const sqrtb2ac = Math.sqrt(b2ac);
 
         if (b2ac >= 0) {
 
+            const sqrtb2ac = Math.sqrt(b2ac);
+
             const t1 = (-b + sqrtb2ac) / (2 * a);
 
             if (0 < t1 && t1 < 1) {

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

@@ -1 +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"}
+{"version":3,"file":"spline3_hermite_bounds_t.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_bounds_t.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,iDAXW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA8FhB"}

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

@@ -1,109 +1,115 @@
-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) 2026
- */
-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;
-}
+import { assert } from "../../assert.js";
+import { max3 } from "../max3.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) 2026
+ */
+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;
+    }
+
+    // `a`, `b` and `c` all scale linearly with the curve's coordinates, so the degeneracy test has to
+    // be relative to them. An absolute threshold silently treats an entire small-coordinate curve as
+    // degenerate and reports the endpoints as the extrema, missing interior ones.
+    const epsilon = max3(Math.abs(a), Math.abs(b), Math.abs(c)) * 1e-12;
+
+    if (Math.abs(a) <= epsilon) {
+
+        if (Math.abs(b) > epsilon) {
+            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_to_bezier.d.ts

@@ -1,5 +1,7 @@
 /**
  * One-dimensional cubic curve conversion from Hermite to bezier
+ * The result is the 4 bezier control points in order. {@link spline3_bezier_to_hermite} inverts this,
+ * and writes its Hermite as `[p0, p1, m0, m1]`, so its output can be fed straight back in here.
  * @param {Float32Array|number[]} result where to put results
  * @param {number} result_offset offset to start writing at in result array
  * @param {number} result_stride how far to step between each written value. Necessary for N-dimensional curves where we want to interleave multiple curves together, such as for color or quaternions

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

@@ -1 +1 @@
-{"version":3,"file":"spline3_hermite_to_bezier.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_to_bezier.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,kDATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB"}
+{"version":3,"file":"spline3_hermite_to_bezier.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/spline/spline3_hermite_to_bezier.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,kDATW,YAAY,GAAC,MAAM,EAAE,iBACrB,MAAM,iBACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QAsBhB"}

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

@@ -1,5 +1,7 @@
 /**
  * One-dimensional cubic curve conversion from Hermite to bezier
+ * The result is the 4 bezier control points in order. {@link spline3_bezier_to_hermite} inverts this,
+ * and writes its Hermite as `[p0, p1, m0, m1]`, so its output can be fed straight back in here.
  * @param {Float32Array|number[]} result where to put results
  * @param {number} result_offset offset to start writing at in result array
  * @param {number} result_stride how far to step between each written value. Necessary for N-dimensional curves where we want to interleave multiple curves together, such as for color or quaternions

package/src/core/math/statistics/computeStatisticalMean.js

@@ -14,7 +14,7 @@ export function computeStatisticalMean(values, start = 0, end = values.length) {
 
     const sample_count = end - start;
 
-    for (let i = 0; i < end; i++) {
+    for (let i = start; i < end; i++) {
         const value = values[i];
 
         total += value;

package/src/core/math/statistics/gaussian_amplitude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gaussian_amplitude.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/statistics/gaussian_amplitude.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,6CAJW,MAAM,sBACN,MAAM,GACJ,MAAM,CAMlB"}
+{"version":3,"file":"gaussian_amplitude.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/statistics/gaussian_amplitude.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,6CAJW,MAAM,sBACN,MAAM,GACJ,MAAM,CAQlB"}

package/src/core/math/statistics/gaussian_amplitude.js

@@ -9,5 +9,7 @@ import { gaussian } from "../gaussian.js";
 export function gaussian_amplitude(variance, distance_from_mean) {
     // Adapted from https://github.com/Kitware/VTK/blob/af928016f4041ad8a6a193d032355b909721fc95/Common/Core/vtkMath.cxx#L339
 
-    return 1.0 / Math.sqrt(2.0 * Math.PI * variance) * gaussian(variance, distance_from_mean);
+    // gaussian() takes a standard deviation and squares it internally, so pass sqrt(variance) to get
+    // the exponent -distance^2 / (2 * variance) that the 1/sqrt(2*PI*variance) normalization expects.
+    return 1.0 / Math.sqrt(2.0 * Math.PI * variance) * gaussian(Math.sqrt(variance), distance_from_mean);
 }

package/src/engine/animation/clip/ecd_bind_animation_curve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ecd_bind_animation_curve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/ecd_bind_animation_curve.js"],"names":[],"mappings":"AAoGA;;;;GAIG;AACH,2DAFW,mBAAmB,wBAgC7B;8BArI6B,oBAAoB;qCACb,2BAA2B"}
+{"version":3,"file":"ecd_bind_animation_curve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/ecd_bind_animation_curve.js"],"names":[],"mappings":"AA6GA;;;;GAIG;AACH,2DAFW,mBAAmB,wBAgC7B;8BA9I6B,oBAAoB;qCACb,2BAA2B"}

package/src/engine/animation/clip/ecd_bind_animation_curve.js

@@ -7,6 +7,7 @@ import { AnimationTrack } from "./AnimationTrack.js";
 import { AnimationTrackBinding } from "./AnimationTrackBinding.js";
 import { bind_property_writer } from "./bind_property_writer.js";
 import { curve_from_track_data } from "./curve_from_track_data.js";
+import { hemisphere_align_quaternion_values } from "./hemisphere_align_quaternion_values.js";
 
 
 /**
@@ -44,7 +45,7 @@ function track_to_interpolation(track) {
  */
 function convert_three_track_to_curves(track) {
 
-    const values = track.values;
+    let values = track.values;
     const times = track.times;
 
     const key_count = times.length;
@@ -58,6 +59,14 @@ function convert_three_track_to_curves(track) {
     // figure out interpolation type
     const interpolation = track_to_interpolation(track);
 
+    // A quaternion track is interpolated below as four independent per-component curves; without hemisphere
+    // alignment a pair of adjacent keys with a negative dot product interpolates the long way around. Negate
+    // keys into a common hemisphere first so the component nlerp takes the short arc. (Discrete needs no
+    // interpolation; CubicTangents packs tangents per key and is handled separately / not yet aligned.)
+    if (interpolation === AnimationInterpolationKind.Linear && track.ValueTypeName === 'quaternion') {
+        values = hemisphere_align_quaternion_values(values, key_count);
+    }
+
     const values_per_key = values.length / key_count;
 
     const component_count = interpolation === AnimationInterpolationKind.CubicTangents ? values_per_key / 3 : values_per_key;

package/src/engine/animation/clip/hemisphere_align_quaternion_values.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Return a copy of a flat quaternion keyframe-value array (`[x0,y0,z0,w0, x1,y1,z1,w1, ...]`) in which every
+ * key has been negated as needed so that consecutive keys lie in the same hemisphere (their dot product is
+ * non-negative).
+ *
+ * A quaternion and its negation represent the same rotation, so this does not change the pose at any key. It
+ * does change what happens BETWEEN keys: the animation clip pipeline interpolates a quaternion track as four
+ * independent per-component curves (component-wise normalized-lerp), and without hemisphere alignment a pair of
+ * adjacent keys whose dot product is negative interpolates the long way around — spinning nearly 360 degrees and
+ * dipping through a near-degenerate quaternion at the midpoint. Aligning the keys first makes the component nlerp
+ * take the short arc, matching what three.js does at interpolation time via Quaternion.slerpFlat's sign flip.
+ *
+ * The input array is not mutated.
+ *
+ * @param {number[]|Float32Array|Float64Array} values flat quaternion components, 4 per key
+ * @param {number} key_count number of keyframes
+ * @returns {number[]|Float32Array|Float64Array} a copy with hemisphere-aligned keys
+ */
+export function hemisphere_align_quaternion_values(values: number[] | Float32Array | Float64Array, key_count: number): number[] | Float32Array | Float64Array;
+//# sourceMappingURL=hemisphere_align_quaternion_values.d.ts.map

package/src/engine/animation/clip/hemisphere_align_quaternion_values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hemisphere_align_quaternion_values.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/hemisphere_align_quaternion_values.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,2DAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,aAClC,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAoB9C"}

package/src/engine/animation/clip/hemisphere_align_quaternion_values.js

@@ -0,0 +1,37 @@
+/**
+ * Return a copy of a flat quaternion keyframe-value array (`[x0,y0,z0,w0, x1,y1,z1,w1, ...]`) in which every
+ * key has been negated as needed so that consecutive keys lie in the same hemisphere (their dot product is
+ * non-negative).
+ *
+ * A quaternion and its negation represent the same rotation, so this does not change the pose at any key. It
+ * does change what happens BETWEEN keys: the animation clip pipeline interpolates a quaternion track as four
+ * independent per-component curves (component-wise normalized-lerp), and without hemisphere alignment a pair of
+ * adjacent keys whose dot product is negative interpolates the long way around — spinning nearly 360 degrees and
+ * dipping through a near-degenerate quaternion at the midpoint. Aligning the keys first makes the component nlerp
+ * take the short arc, matching what three.js does at interpolation time via Quaternion.slerpFlat's sign flip.
+ *
+ * The input array is not mutated.
+ *
+ * @param {number[]|Float32Array|Float64Array} values flat quaternion components, 4 per key
+ * @param {number} key_count number of keyframes
+ * @returns {number[]|Float32Array|Float64Array} a copy with hemisphere-aligned keys
+ */
+export function hemisphere_align_quaternion_values(values, key_count) {
+    const out = values.slice();
+
+    for (let i = 1; i < key_count; i++) {
+        const p = (i - 1) * 4;
+        const c = i * 4;
+
+        const dot = out[p] * out[c] + out[p + 1] * out[c + 1] + out[p + 2] * out[c + 2] + out[p + 3] * out[c + 3];
+
+        if (dot < 0) {
+            out[c] = -out[c];
+            out[c + 1] = -out[c + 1];
+            out[c + 2] = -out[c + 2];
+            out[c + 3] = -out[c + 3];
+        }
+    }
+
+    return out;
+}