@woosh/meep-engine 2.131.3 → 2.131.5

package/src/core/math/physics/mie/lorenz_mie_coefs.js

@@ -0,0 +1,233 @@
+import { assert } from "../../../assert.js";
+import { v2_length } from "../../../geom/vec2/v2_length.js";
+import { complex_add } from "../../complex/complex_add.js";
+import { complex_div } from "../../complex/complex_div.js";
+import { complex_mul } from "../../complex/complex_mul.js";
+import { complex_sub } from "../../complex/complex_sub.js";
+
+export function vec2(x, y) {
+    return new Float64Array([x, y]);
+}
+
+function vec4(x, y, z, w) {
+    return new Float64Array([x, y, z, w]);
+}
+
+export function cadd(a, b) {
+    const r = vec2(0, 0);
+
+    complex_add(r, a, b);
+
+    return r;
+}
+
+function csub(a, b) {
+    const r = vec2(0, 0);
+
+
+    complex_sub(r, a, b);
+
+    return r;
+}
+
+export function cmult(a, b) {
+    const r = vec2(0, 0);
+
+
+    complex_mul(r, a, b);
+
+    return r;
+}
+
+export function cdiv(a, b) {
+    const r = vec2(0, 0);
+
+
+    complex_div(r, a, b);
+
+    return r;
+}
+
+// Number of terms to include in infinite sums (truncation)
+function terms_to_sum(z) {
+    const size = v2_length(z[0], z[1]);
+    return Math.ceil(size + 4.3 * Math.cbrt(size) + 1.0);
+}
+
+// Downward recurrence for A
+function A_all_n(z, M) {
+    const A = new Array(M + 2);
+    A[M + 1] = vec2(0.0, 0.0);
+    for (let n = M; n >= 0; --n) {
+        const tmp = cdiv(vec2(n + 1.0, 0.0), z);
+        A[n] = csub(tmp, cdiv(vec2(1.0, 0.0), cadd(tmp, A[n + 1])));
+    }
+    return A;
+}
+
+// Upward recurrences for B, psi_zeta, and R
+function psi_zeta(n, z, A, old_B, old_psi_zeta) {
+    if (n > 0) {
+        const n_z = cdiv(vec2(n, 0.0), z);
+        const tmp = cmult(csub(n_z, A[n - 1]), csub(n_z, old_B));
+        old_psi_zeta = cmult(old_psi_zeta, tmp);
+    }
+    return old_psi_zeta;
+}
+
+/**
+ * Calculates the B_n(z) coefficient for term 'n' via upward recurrence.
+ * This is a helper function for LorenzMie_ab.
+ *
+ * @param {number} n - The current recurrence term index (n >= 0).
+ * @param {vec2} z - The complex size parameter (x or y).
+ * @param {Array<vec2>} A - Pre-computed log-derivatives A_n(z).
+ * @param {vec2} old_B - The previous B coefficient (B_{n-1}).
+ * @param {vec2} old_psi_zeta - The previous psi_zeta product term.
+ * @returns {vec2} The new B_n coefficient (complex number).
+ */
+function B(n, z, A, old_B, old_psi_zeta) {
+
+    if (n > 0) {
+        old_B.psi_zeta = psi_zeta(n, z, A, old_B, old_psi_zeta);
+        old_B = cadd(A[n], cdiv(vec2(0.0, 1.0), old_B.psi_zeta));
+    }
+
+    return old_B;
+}
+
+/**
+ * Calculates the R_n(z) coefficient (ratio psi_n / zeta_n) for term 'n'.
+ * This is a helper function for LorenzMie_ab.
+ *
+ * @param {number} n - The current recurrence term index (n >= 0).
+ * @param {vec2} z - The complex size parameter (x).
+ * @param {Array<vec2>} A - Pre-computed log-derivatives A_n(z).
+ * @param {vec2} B_n - The current B_n(z) coefficient.
+ * @param {vec2} old_R - The previous R coefficient (R_{n-1}).
+ * @returns {vec2} The new R_n coefficient (complex number).
+ */
+function R(n, z, A, B_n, old_R) {
+    if (n > 0) {
+        const n_z = cdiv(vec2(n, 0.0), z);
+        const tmp = cdiv(cadd(B_n, n_z), cadd(A[n], n_z));
+        old_R = cmult(old_R, tmp);
+    }
+    return old_R;
+}
+
+/**
+ * Calculates the Lorenz-Mie scattering coefficients a_n and b_n for a single term 'n'.
+ * This implements the formulas from Figure 3 of Frisvad et al. 2007.
+ *
+ * @param {number} n - The current recurrence term index (n >= 0).
+ * @param {number} size - Unitless size parameter x_vac = 2*pi*r / lambda_vac.
+ * @param {vec2} n_p - Complex refractive index of the particle.
+ * @param {vec2} n_med - Complex refractive index of the medium.
+ * @param {Array<vec2>} A_p - Pre-computed log-derivatives A_n(y) for the particle.
+ * @param {Array<vec2>} A_med - Pre-computed log-derivatives A_n(x) for the medium.
+ * @param {vec2} old_B - The previous B_{n-1}(x) coefficient.
+ * @param {vec2} old_R - The previous R_{n-1}(x) coefficient.
+ * @param {vec2} old_psi_zeta - The previous psi_zeta product.
+ * @returns {vec4} A vec4 [Re(a_n), Im(a_n), Re(b_n), Im(b_n)] with state properties
+ * (.old_B, .old_R, .old_psi_zeta) attached for the next iteration.
+ */
+function LorenzMie_ab(n, size, n_p, n_med, A_p, A_med, old_B, old_R, old_psi_zeta) {
+
+    const x = vec2(size * n_med[0], size * n_med[1]);
+    const B_n = B(n, x, A_med, old_B, old_psi_zeta);
+    const R_n = R(n, x, A_med, B_n, old_R);
+    const n_med_A_p = cmult(n_med, A_p[n]);
+    const n_p_A_med = cmult(n_p, A_med[n]);
+    const n_p_A_p = cmult(n_p, A_p[n]);
+    const n_med_A_med = cmult(n_med, A_med[n]);
+    const n_p_B_n = cmult(n_p, B_n);
+    const n_med_B_n = cmult(n_med, B_n);
+    const a = cmult(R_n, cdiv(csub(n_med_A_p, n_p_A_med), csub(n_med_A_p, n_p_B_n)));
+    const b = cmult(R_n, cdiv(csub(n_p_A_p, n_med_A_med), csub(n_p_A_p, n_med_B_n)));
+
+
+    const ab = vec4(a[0], a[1], b[0], b[1]);
+
+    ab.old_psi_zeta = n > 0 ? old_B.psi_zeta : old_psi_zeta;
+    ab.old_B = B_n;
+    ab.old_R = R_n;
+
+    return ab;
+}
+
+/**
+ * The following source code implements Lorenz-Mie theory using the formulas presented in the SIGGRAPH 2007 paper
+ *
+ * Computing the Scattering Properties of Participating
+ * Media Using Lorenz-Mie Theory
+ *
+ * By authors: Jeppe Revall Frisvad
+ *             Niels Joergen Christensen
+ *             Henrik Wann Jensen
+ *
+ * Code written by Jeppe Revall Frisvad, 2017.
+ * Copyright (c) Jeppe Revall Frisvad 2017
+ *
+ * Permission is granted to anyone to use this code as
+ * software for any purpose, including commercial applications.
+ * However, the software is provided 'as-is' without any warranty.
+ *
+ * @param {number} radius_m - Particle radius (in meters).
+ * @param {number} wavelength_m - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_p - Complex refractive index of the particle
+ * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
+ * @returns {Float64Array} Mie coefficients a_n and b_n in form [a_n0.r, a_n0.i, b_n0.r, b_n0.i, ... a_nN.r, a_nN.i, b_nN.r, b_nN.i]
+ */
+export function lorenz_mie_coefs(
+    wavelength_m,
+    radius_m,
+    n_p,
+    n_med
+) {
+
+    assert.isNumber(wavelength_m, 'wavelength_m');
+    assert.isFinite(wavelength_m, 'wavelength_m');
+    assert.greaterThan(wavelength_m, 0, 'wavelength_m');
+
+    assert.isNumber(radius_m, 'radius_m');
+    assert.isFinite(radius_m, 'radius_m');
+    assert.greaterThan(radius_m, 0, 'radius_m');
+
+    const psize = 2.0 * Math.PI * radius_m / wavelength_m;
+
+    const x = vec2(psize * n_med[0], psize * n_med[1]);
+    const y = vec2(psize * n_p[0], psize * n_p[1]);
+    const M = terms_to_sum(x);
+    const A_med = A_all_n(x, M);
+    const A_p = A_all_n(y, M);
+
+    const e_term = Math.exp(2.0 * x[1]);
+
+    let prev_psi_zeta = vec2(0.5 * (1.0 - Math.cos(2.0 * x[0]) / e_term), -0.5 * Math.sin(2.0 * x[0]) / e_term);
+    let prev_B = vec2(0.0, 1.0);
+    let prev_R = vec2(0.5 * (1.0 - Math.cos(2.0 * x[0]) * e_term), 0.5 * Math.sin(2.0 * x[0]) * e_term);
+
+    const ab = new Float64Array(M * 4);
+
+    for (let n = 0; n < M; ++n) {
+
+        const ab_n = LorenzMie_ab(
+            n, psize, n_p, n_med, A_p, A_med,
+            prev_B, prev_R, prev_psi_zeta
+        );
+
+        prev_psi_zeta = ab_n.old_psi_zeta;
+        prev_B = ab_n.old_B;
+        prev_R = ab_n.old_R;
+
+        // plug the data in
+        ab[4 * n] = ab_n[0];
+        ab[4 * n + 1] = ab_n[1];
+        ab[4 * n + 2] = ab_n[2];
+        ab[4 * n + 3] = ab_n[3];
+
+    }
+
+    return ab;
+}

package/src/core/math/physics/mie/mie_ab_to_optical_properties.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Calculates the final optical properties by summing the Mie coefficients.
+ * This function implements Equations (2) and (3) from the 2007 paper
+ * "Computing the Scattering Properties of Participating Media..."
+ *
+ * @param {Float32Array} ab - The flat array of a_n, b_n coefficients from LorenzMie_coefs.
+ * @param {number} radius - Particle radius (in meters).
+ * @param {number} wavelength - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
+ * @returns {object} An object with Q_e, Q_s, albedo, C_ext, and C_sca.
+ */
+export function mie_ab_to_optical_properties(ab: Float32Array, wavelength: number, radius: number, n_med: typeof vec2): object;
+import { vec2 } from "./lorenz_mie_coefs.js";
+//# sourceMappingURL=mie_ab_to_optical_properties.d.ts.map

package/src/core/math/physics/mie/mie_ab_to_optical_properties.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mie_ab_to_optical_properties.d.ts","sourceRoot":"","sources":["../../../../../../src/core/math/physics/mie/mie_ab_to_optical_properties.js"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,iDANW,YAAY,cAEZ,MAAM,UADN,MAAM,uBAGJ,MAAM,CAgGlB;qBA3GuC,uBAAuB"}

package/src/core/math/physics/mie/mie_ab_to_optical_properties.js

@@ -0,0 +1,109 @@
+import { v2_dot } from "../../../geom/vec2/v2_dot.js";
+import { cadd, cdiv, cmult, vec2 } from "./lorenz_mie_coefs.js";
+
+/**
+ * Calculates the final optical properties by summing the Mie coefficients.
+ * This function implements Equations (2) and (3) from the 2007 paper
+ * "Computing the Scattering Properties of Participating Media..."
+ *
+ * @param {Float32Array} ab - The flat array of a_n, b_n coefficients from LorenzMie_coefs.
+ * @param {number} radius - Particle radius (in meters).
+ * @param {number} wavelength - Wavelength of light in vacuum (in meters).
+ * @param {vec2} n_med - Complex refractive index of the medium (e.g., [1.0, 0.0] for air).
+ * @returns {object} An object with Q_e, Q_s, albedo, C_ext, and C_sca.
+ */
+export function mie_ab_to_optical_properties(
+    ab,
+    wavelength,
+    radius,
+    n_med
+) {
+    const M = ab.length / 4;
+
+    let sum_t = vec2(0, 0); // Complex sum for Ct
+    let sum_s = 0; // Real sum for Cs
+    let sum_g = 0;          // Real sum for Asymmetry (g)
+
+    for (let n = 1; n < M; ++n) {
+        // The 'n' in the paper's formulas
+        const multiplier = 2 * n + 1;
+
+        // Get an and bn from your flat array
+        const an = vec2(ab[4 * n], ab[4 * n + 1]);
+        const bn = vec2(ab[4 * n + 2], ab[4 * n + 3]);
+
+        // 1. For Extinction (Ct)
+        const an_plus_bn = cadd(an, bn);
+        // You need complex math functions cadd, cdiv
+        const n_med_sq = cmult(n_med, n_med);
+        const term_t = cdiv(an_plus_bn, n_med_sq);
+        sum_t = cadd(sum_t, cmult(vec2(multiplier, 0), term_t));
+
+        // 2. For Scattering (Cs)
+        const an_mag_sq = an[0] * an[0] + an[1] * an[1];
+        const bn_mag_sq = bn[0] * bn[0] + bn[1] * bn[1];
+        sum_s += multiplier * (an_mag_sq + bn_mag_sq);
+
+        // 3. Asymmetry Accumulation (New)
+        // Term A: Interference of an and bn
+        // Formula: (2n+1) / (n(n+1)) * Re(an * bn*)
+        const factor_A = (2 * n + 1) / (n * (n + 1));
+        sum_g += factor_A * v2_dot(an[0], an[1], bn[0], bn[1]);
+
+        // Term B: Interference of n and n+1
+        // Formula: (n(n+2)) / (n+1) * Re(an * an+1* + bn * bn+1*)
+        if (n < M - 1) {
+            const n_next = n + 1;
+            const an1_r = ab[4 * n_next];
+            const an1_i = ab[4 * n_next + 1];
+            const bn1_r = ab[4 * n_next + 2];
+            const bn1_i = ab[4 * n_next + 3];
+
+            const factor_B = (n * (n + 2)) / (n + 1);
+
+            const term_an_an1 = v2_dot(an[0], an[1], an1_r, an1_i);
+            const term_bn_bn1 = v2_dot(bn[0], bn[1], bn1_r, bn1_i);
+
+            sum_g += factor_B * (term_an_an1 + term_bn_bn1);
+        }
+    }
+
+    // --- Final Calculations ---
+
+    // Asymmetry Parameter (g)
+    // g = (4/x^2 * sum_g) / (2/x^2 * sum_s) => 2 * sum_g / sum_s
+    let g = 0;
+    if (sum_s > 1e-12) {
+        g = (2 * sum_g) / sum_s;
+    }
+
+    // Extinction (Ct from Eq. 22)
+    const C_t = (Math.pow(wavelength, 2) / (2 * Math.PI)) * sum_t[0]; //
+
+    // Scattering (Cs from Eq. 23)
+    const alpha = (4 * Math.PI * radius * n_med[1]) / wavelength;
+    let gamma;
+    if (Math.abs(alpha) < 1e-10) {
+        // avoid division by 0
+        gamma = 1;
+    } else {
+        gamma = (2 * (1 + (alpha - 1) * Math.exp(alpha))) / Math.pow(alpha, 2);
+    }
+    const n_med_mag_sq = n_med[0] * n_med[0] + n_med[1] * n_med[1];
+    const C_s_factor = (Math.pow(wavelength, 2) * Math.exp(-alpha)) / (2 * Math.PI * gamma * n_med_mag_sq);
+    const C_s = C_s_factor * sum_s;
+
+    // Bulk Coefficients (assuming number density N)
+    const sigma_a_med = (4 * Math.PI * n_med[1]) / wavelength;
+
+    // To get bulk coefficients sigma_t and sigma_s, use the following formulae, where N is numeric density (particles per cubic meter):
+    // sigma_t = sigma_a_med + C_t * N;
+    // sigma_s = C_s * N;
+
+    return {
+        sigma_a_med,
+        C_ext: C_t,
+        C_sca: C_s,
+        g, // Anisotropy parameter
+    }
+}

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

@@ -12,10 +12,17 @@
  *
  *  jump_curve.evaluate(0.1); // what is the height at time 0.1?
  *
+ * @example
+ *  const curve = AnimationCurve.easeInOut();
+ *
+ *  sprite.transparency = curve.evaluate(time); // smoothly animate transparency of the sprite
+ *
+ * @implements Iterable<Keyframe>
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
  */
-export class AnimationCurve {
+export class AnimationCurve implements Iterable<Keyframe> {
     /**
      * Utility constructor
      * @param {Keyframe[]} keys
@@ -25,6 +32,7 @@ export class AnimationCurve {
     /**
      * S-shaped curve that starts slowly, ramps up and flattens out again.
      * Useful for pleasing transitions where exit and entry should not be abrupt.
+     *
      * @param {number} [timeStart]
      * @param {number} [valueStart]
      * @param {number} [timeEnd]
@@ -71,7 +79,7 @@ export class AnimationCurve {
     /**
      *
      * @param {Keyframe} key
-     * @returns {boolean}
+     * @returns {boolean} true if the key was removed, false if the key was not found
      */
     remove(key: Keyframe): boolean;
     /**
@@ -108,10 +116,12 @@ export class AnimationCurve {
     get duration(): number;
     /**
      * Returns index of a key that is just before or at the time specified.
+     * Useful for insertion and evaluation logic.
+     * Note: if time is past the end of last key - index of the last key will be returned instead
      * @param {number} time
      * @returns {number} index of the key
      */
-    getKeyIndexByTime(time: number): number;
+    getKeyIndexLow(time: number): number;
     /**
      * Evaluate interpolated value across the curve at a given time.
      * @param {number} time time in seconds
@@ -164,6 +174,11 @@ export class AnimationCurve {
      * @type {boolean}
      */
     readonly isAnimationCurve: boolean;
+    /**
+     * @deprecated use `getKeyIndexLow` instead
+     */
+    getKeyIndexByTime: (time: number) => number;
+    [Symbol.iterator](): Generator<Keyframe, void, unknown>;
 }
 import { Keyframe } from "./Keyframe.js";
 //# sourceMappingURL=AnimationCurve.d.ts.map

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":"AAqBA;;;;;;;;;;;;;;;;GAgBG;AACH;IAkXI;;;;OAIG;IACH,kBAHW,QAAQ,EAAE,GACR,cAAc,CAQ1B;IAED;;;;;;;;OAQG;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;IApbD;;;;;OAKG;IACH,eAFU,QAAQ,EAAE,CAEV;IAEV;;;;;OAKG;IACH,SAHW,QAAQ,GACN,MAAM,CAiClB;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;;;;OAIG;IACH,wBAHW,MAAM,GACJ,MAAM,CA0ClB;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;;aAeC;IAyEL;;;;OAIG;IACH,2BAFU,OAAO,CAEwB;CARxC;yBAndwB,eAAe"}
+{"version":3,"file":"AnimationCurve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/curve/AnimationCurve.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,gDALwB,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;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;yBA/ewB,eAAe"}

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

@@ -1,5 +1,4 @@
 import { assert } from "../../../core/assert.js";
-import { binarySearchHighIndex } from "../../../core/collection/array/binarySearchHighIndex.js";
 import { computeHashArray } from "../../../core/collection/array/computeHashArray.js";
 import { isArrayEqual } from "../../../core/collection/array/isArrayEqual.js";
 import { lerp } from "../../../core/math/lerp.js";
@@ -9,16 +8,6 @@ import { invokeObjectToJSON } from "../../../core/model/object/invokeObjectToJSO
 import { evaluate_two_key_curve } from "./evaluate_two_key_curve.js";
 import { Keyframe } from "./Keyframe.js";
 
-/**
- *
- * @param {number} time
- * @param {Keyframe} keyframe
- * @return {number}
- */
-function compareKeyframeToTime(time, keyframe) {
-    return time - keyframe.time;
-}
-
 /**
  * Describes change of a numeric value over time.
  * Values are stored in {@link Keyframe}s, interpolation is defined by tangents on {@link Keyframe}s.
@@ -33,6 +22,13 @@ function compareKeyframeToTime(time, keyframe) {
  *
  *  jump_curve.evaluate(0.1); // what is the height at time 0.1?
  *
+ * @example
+ *  const curve = AnimationCurve.easeInOut();
+ *
+ *  sprite.transparency = curve.evaluate(time); // smoothly animate transparency of the sprite
+ *
+ * @implements Iterable<Keyframe>
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2025
  */
@@ -61,6 +57,8 @@ export class AnimationCurve {
         const key_count = keys.length;
         const last_key_index = key_count - 1;
 
+        // Optimization: if the curve is empty or the new key is chronologically
+        // after the last key, we can simply push it to the end.
         if (
             last_key_index < 0
             || keys[last_key_index].time <= key.time
@@ -71,17 +69,21 @@ export class AnimationCurve {
 
             return key_count;
 
-        } else {
+        } else if (key_count > 0 && keys[0].time > key.time) {
 
-            // figure out the right place to insert the key
-            // TODO make use of this.getKeyIndexByTime instead
-            const i = binarySearchHighIndex(keys, key.time, compareKeyframeToTime, 0, last_key_index);
+            keys.unshift(key);
 
-            // insert key at the right place
-            keys.splice(i, 0, key);
-
-            return i;
+            return 0;
         }
+
+        // figure out the right place to insert the key
+        const i = this.getKeyIndexLow(key.time) + 1;
+
+        // insert key at the right place
+        keys.splice(i, 0, key);
+
+        return i;
+
     }
 
     /**
@@ -101,7 +103,7 @@ export class AnimationCurve {
     /**
      *
      * @param {Keyframe} key
-     * @returns {boolean}
+     * @returns {boolean} true if the key was removed, false if the key was not found
      */
     remove(key) {
         const i = this.keys.indexOf(key);
@@ -196,21 +198,37 @@ export class AnimationCurve {
 
     /**
      * Returns index of a key that is just before or at the time specified.
+     * Useful for insertion and evaluation logic.
+     * Note: if time is past the end of last key - index of the last key will be returned instead
      * @param {number} time
      * @returns {number} index of the key
      */
-    getKeyIndexByTime(time) {
+    getKeyIndexLow(time) {
+        assert.isNumber(time, 'time');
+        assert.notNaN(time, 'time');
+
         const keys = this.keys;
         const key_count = keys.length;
 
-        let i0 = 0;
-        let i1 = key_count - 1;
+        if (key_count === 0) {
+            // no keys
+            return 0;
+        }
 
         if (time <= keys[0].time) {
             // before start
             return 0;
         }
 
+        if (time >= keys[key_count - 1].time) {
+            // after the end
+            return key_count - 1;
+        }
+
+        let found_index = 0;
+        let i0 = 0;
+        let i1 = key_count - 1;
+
         // binary search
         while (i0 <= i1) {
             const pivot = (i0 + i1) >>> 1;
@@ -218,27 +236,22 @@ export class AnimationCurve {
             const key = keys[pivot];
             const key_time = key.time;
 
-            if (key_time < time) {
+            if (key_time <= time) {
+                found_index = pivot;
                 i0 = pivot + 1;
             } else if (key_time > time) {
                 i1 = pivot - 1;
-            } else {
-                i0 = pivot;
-                break;
             }
         }
 
-        if (i0 > i1) {
-            // swap
-            i0 = i1;
-        }
+        assert.lessThanOrEqual(keys[found_index].time, time, 'keys[found_index].time >= time');
 
         // fast-forward to last matching frame if there are multiple matches
-        while (i0 + 1 < key_count - 1 && keys[i0 + 1].time === time) {
-            i0++;
+        while (found_index + 2 < key_count && keys[found_index + 1].time === time) {
+            found_index++;
         }
 
-        return i0;
+        return found_index;
     }
 
     /**
@@ -262,7 +275,7 @@ export class AnimationCurve {
             return keys[0].value;
         }
 
-        const i = this.getKeyIndexByTime(time);
+        const i = this.getKeyIndexLow(time);
 
         if (i >= key_count - 1) {
             // past last keyframe
@@ -400,12 +413,25 @@ export class AnimationCurve {
 
             keyframe.fromJSON(keys[i]);
 
+            // The 'add' sorts the keys incrementally, we can do this faster if we assume the input is already sorted.
+            // But to be safe we don't make that assumption
+
             this.add(keyframe);
 
         }
 
     }
 
+    * [Symbol.iterator]() {
+
+        for (const key of this.keys) {
+
+            yield key;
+
+        }
+
+    }
+
     /**
      * Utility constructor
      * @param {Keyframe[]} keys
@@ -422,6 +448,7 @@ export class AnimationCurve {
     /**
      * S-shaped curve that starts slowly, ramps up and flattens out again.
      * Useful for pleasing transitions where exit and entry should not be abrupt.
+     *
      * @param {number} [timeStart]
      * @param {number} [valueStart]
      * @param {number} [timeEnd]
@@ -482,4 +509,10 @@ export class AnimationCurve {
  * @readonly
  * @type {boolean}
  */
-AnimationCurve.prototype.isAnimationCurve = true;
+AnimationCurve.prototype.isAnimationCurve = true;
+
+
+/**
+ * @deprecated use `getKeyIndexLow` instead
+ */
+AnimationCurve.prototype.getKeyIndexByTime = AnimationCurve.prototype.getKeyIndexLow;