@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/sound/simulation/probe/acoustic_probe_transfer.js

@@ -1,103 +1,103 @@
-// Per-probe directional transfer T(ω_in, ω_out): the fraction of energy, per band, that — arriving at a
-// probe's neighbourhood travelling propagation direction ω_in — leaves travelling ω_out. It is a property
-// of the MEDIUM around the probe (source/listener-agnostic), composed of:
-//   • a FORWARD / passthrough term — straight-through energy (ω_out ≈ ω_in), always present (free air);
-//   • zero or more REFLECTOR LOBES — each a spherical Gaussian on the HALF-VECTOR ĥ = normalize(ω_out − ω_in)
-//     about a reflector's air-side normal n (peaks when the pair is specular about n), scaled by per-band
-//     reflectivity ρ.
-//
-// The half-vector is the reciprocal variable: ĥ(−ω_out, −ω_in) = ĥ(ω_in, ω_out), and ω_in·ω_out is likewise
-// swap-invariant, so T(ω_in,ω_out) = T(−ω_out,−ω_in) BY CONSTRUCTION (acoustic reciprocity, medium at rest).
-// And ĥ·n only reaches +1 when ω_in·n < 0 (the in-ray enters the surface's FRONT face), so a lobe cannot
-// fire for a ray hitting the back — the front-face/reachability gate is intrinsic, no separate test needed.
-//
-// See PROBE_TRANSFER_RESEARCH.md §3. Pure math; no allocation; no WebAudio.
-
-// Lobe layout in a flat Float32Array: STRIDE floats per lobe.
-export const LOBE_STRIDE = 7;
-const LOBE_NX = 0, LOBE_NY = 1, LOBE_NZ = 2; // air-side normal (the SG axis, unit)
-const LOBE_LAMBDA = 3;                        // SG sharpness (large = flat mirror; small = rough/curved)
-const LOBE_RHO = 4;                           // per-band reflectivity ρ[low,mid,high] at LOBE_RHO + band
-
-// FORWARD / passthrough plateau. Φ(c), c = ω_in·ω_out (1 = straight). It is a PLATEAU (≡1 up to the graph's
-// typical edge-to-edge angle, then falls off) — NOT a sharp Gaussian — so a straight corridor sampled by a
-// jittered probe graph accrues NO per-hop loss (a sharp term would bleed loss at every probe and a long
-// straight run would spuriously attenuate). These are DISCRETIZATION knobs (probe spacing/jitter), not
-// physics: PLATEAU_COS = cos(angle below which a bend is "straight enough"), FALLOFF = decay steepness past it.
-export const FORWARD_PLATEAU_COS = 0.766; // cos 40° — bends ≤ 40° pass free
-export const FORWARD_FALLOFF = 4;         // e.g. a 90° open-air bend → Φ ≈ 0.05 (−13 dB), 135° → ≈ −25 dB
-
-// Below this half-vector length the pair is ~straight (ĥ ill-defined): reflections vanish, forward owns it.
-const STRAIGHT_EPSILON = 1e-9;
-
-/**
- * Forward / passthrough transfer for a bend whose in·out cosine is `c` (1 = perfectly straight). 1 on the
- * plateau, exponential decay past it. Band-independent (geometry, not material).
- * @param {number} c ω_in·ω_out
- * @returns {number} forward transfer in [0, 1]
- */
-export function forward_plateau(c) {
-    if (c >= FORWARD_PLATEAU_COS) {
-        return 1;
-    }
-    return Math.exp(FORWARD_FALLOFF * (c - FORWARD_PLATEAU_COS));
-}
-
-/**
- * Per-band transfer T(ω_in, ω_out) at a probe, written into `out[0..2]` (low/mid/high) — clamped to [0, 1].
- * `out_b = min(1, max(forward, max over lobes of ρ_b · SG(ĥ·n; λ)))`, the dominant of the forward
- * passthrough and the best reflection lobe (the leak picks the best mechanism; `max` keeps it ≤ 1, i.e. a
- * probe never amplifies, and makes straight-through full regardless of nearby reflectors). Reflection lobes
- * are weighted by the bend `(1−ω_in·ω_out)/2` so the ĥ-undefined straight region is the forward term's alone.
- *
- * Directions are unit PROPAGATION directions (the way the wave travels). Reciprocal:
- * `T(ω_in,ω_out) = T(−ω_out,−ω_in)`.
- *
- * @param {Float32Array|number[]} out length ≥ 3 — per-band result
- * @param {Float32Array} lobes flat lobe array (LOBE_STRIDE floats each)
- * @param {number} lobeOffset start index of this probe's lobes in `lobes`
- * @param {number} lobeCount number of lobes for this probe
- * @param {number} inx ω_in x (unit)
- * @param {number} iny ω_in y (unit)
- * @param {number} inz ω_in z (unit)
- * @param {number} outx ω_out x (unit)
- * @param {number} outy ω_out y (unit)
- * @param {number} outz ω_out z (unit)
- */
-export function acoustic_probe_transfer(out, lobes, lobeOffset, lobeCount, inx, iny, inz, outx, outy, outz) {
-    const c = inx * outx + iny * outy + inz * outz; // ω_in·ω_out
-
-    // forward seeds every band (the floor every reflection competes with)
-    const fwd = forward_plateau(c);
-    let b0 = fwd, b1 = fwd, b2 = fwd;
-
-    // half-vector ĥ = normalize(ω_out − ω_in); the reciprocal reflection variable
-    let hx = outx - inx, hy = outy - iny, hz = outz - inz;
-    const hlen2 = hx * hx + hy * hy + hz * hz;
-
-    if (hlen2 > STRAIGHT_EPSILON && lobeCount > 0) {
-        const hinv = 1 / Math.sqrt(hlen2);
-        hx *= hinv; hy *= hinv; hz *= hinv;
-
-        // a "reflection" with no direction change is not one — fade lobes in with the bend
-        const bend = (1 - c) * 0.5; // 0 at straight, → 1 at reversal
-
-        for (let k = 0; k < lobeCount; k++) {
-            const base = lobeOffset + k * LOBE_STRIDE;
-            const hdotn = hx * lobes[base + LOBE_NX] + hy * lobes[base + LOBE_NY] + hz * lobes[base + LOBE_NZ];
-            const g = bend * Math.exp(lobes[base + LOBE_LAMBDA] * (hdotn - 1)); // SG at the half-vector
-
-            const r0 = lobes[base + LOBE_RHO] * g;
-            const r1 = lobes[base + LOBE_RHO + 1] * g;
-            const r2 = lobes[base + LOBE_RHO + 2] * g;
-
-            if (r0 > b0) b0 = r0;
-            if (r1 > b1) b1 = r1;
-            if (r2 > b2) b2 = r2;
-        }
-    }
-
-    out[0] = b0 > 1 ? 1 : b0;
-    out[1] = b1 > 1 ? 1 : b1;
-    out[2] = b2 > 1 ? 1 : b2;
-}
+// Per-probe directional transfer T(ω_in, ω_out): the fraction of energy, per band, that — arriving at a
+// probe's neighbourhood travelling propagation direction ω_in — leaves travelling ω_out. It is a property
+// of the MEDIUM around the probe (source/listener-agnostic), composed of:
+//   • a FORWARD / passthrough term — straight-through energy (ω_out ≈ ω_in), always present (free air);
+//   • zero or more REFLECTOR LOBES — each a spherical Gaussian on the HALF-VECTOR ĥ = normalize(ω_out − ω_in)
+//     about a reflector's air-side normal n (peaks when the pair is specular about n), scaled by per-band
+//     reflectivity ρ.
+//
+// The half-vector is the reciprocal variable: ĥ(−ω_out, −ω_in) = ĥ(ω_in, ω_out), and ω_in·ω_out is likewise
+// swap-invariant, so T(ω_in,ω_out) = T(−ω_out,−ω_in) BY CONSTRUCTION (acoustic reciprocity, medium at rest).
+// And ĥ·n only reaches +1 when ω_in·n < 0 (the in-ray enters the surface's FRONT face), so a lobe cannot
+// fire for a ray hitting the back — the front-face/reachability gate is intrinsic, no separate test needed.
+//
+// See PROBE_TRANSFER_RESEARCH.md §3. Pure math; no allocation; no WebAudio.
+
+// Lobe layout in a flat Float32Array: STRIDE floats per lobe.
+export const LOBE_STRIDE = 7;
+const LOBE_NX = 0, LOBE_NY = 1, LOBE_NZ = 2; // air-side normal (the SG axis, unit)
+const LOBE_LAMBDA = 3;                        // SG sharpness (large = flat mirror; small = rough/curved)
+const LOBE_RHO = 4;                           // per-band reflectivity ρ[low,mid,high] at LOBE_RHO + band
+
+// FORWARD / passthrough plateau. Φ(c), c = ω_in·ω_out (1 = straight). It is a PLATEAU (≡1 up to the graph's
+// typical edge-to-edge angle, then falls off) — NOT a sharp Gaussian — so a straight corridor sampled by a
+// jittered probe graph accrues NO per-hop loss (a sharp term would bleed loss at every probe and a long
+// straight run would spuriously attenuate). These are DISCRETIZATION knobs (probe spacing/jitter), not
+// physics: PLATEAU_COS = cos(angle below which a bend is "straight enough"), FALLOFF = decay steepness past it.
+export const FORWARD_PLATEAU_COS = 0.766; // cos 40° — bends ≤ 40° pass free
+export const FORWARD_FALLOFF = 4;         // e.g. a 90° open-air bend → Φ ≈ 0.05 (−13 dB), 135° → ≈ −25 dB
+
+// Below this half-vector length the pair is ~straight (ĥ ill-defined): reflections vanish, forward owns it.
+const STRAIGHT_EPSILON = 1e-9;
+
+/**
+ * Forward / passthrough transfer for a bend whose in·out cosine is `c` (1 = perfectly straight). 1 on the
+ * plateau, exponential decay past it. Band-independent (geometry, not material).
+ * @param {number} c ω_in·ω_out
+ * @returns {number} forward transfer in [0, 1]
+ */
+export function forward_plateau(c) {
+    if (c >= FORWARD_PLATEAU_COS) {
+        return 1;
+    }
+    return Math.exp(FORWARD_FALLOFF * (c - FORWARD_PLATEAU_COS));
+}
+
+/**
+ * Per-band transfer T(ω_in, ω_out) at a probe, written into `out[0..2]` (low/mid/high) — clamped to [0, 1].
+ * `out_b = min(1, max(forward, max over lobes of ρ_b · SG(ĥ·n; λ)))`, the dominant of the forward
+ * passthrough and the best reflection lobe (the leak picks the best mechanism; `max` keeps it ≤ 1, i.e. a
+ * probe never amplifies, and makes straight-through full regardless of nearby reflectors). Reflection lobes
+ * are weighted by the bend `(1−ω_in·ω_out)/2` so the ĥ-undefined straight region is the forward term's alone.
+ *
+ * Directions are unit PROPAGATION directions (the way the wave travels). Reciprocal:
+ * `T(ω_in,ω_out) = T(−ω_out,−ω_in)`.
+ *
+ * @param {Float32Array|number[]} out length ≥ 3 — per-band result
+ * @param {Float32Array} lobes flat lobe array (LOBE_STRIDE floats each)
+ * @param {number} lobeOffset start index of this probe's lobes in `lobes`
+ * @param {number} lobeCount number of lobes for this probe
+ * @param {number} inx ω_in x (unit)
+ * @param {number} iny ω_in y (unit)
+ * @param {number} inz ω_in z (unit)
+ * @param {number} outx ω_out x (unit)
+ * @param {number} outy ω_out y (unit)
+ * @param {number} outz ω_out z (unit)
+ */
+export function acoustic_probe_transfer(out, lobes, lobeOffset, lobeCount, inx, iny, inz, outx, outy, outz) {
+    const c = inx * outx + iny * outy + inz * outz; // ω_in·ω_out
+
+    // forward seeds every band (the floor every reflection competes with)
+    const fwd = forward_plateau(c);
+    let b0 = fwd, b1 = fwd, b2 = fwd;
+
+    // half-vector ĥ = normalize(ω_out − ω_in); the reciprocal reflection variable
+    let hx = outx - inx, hy = outy - iny, hz = outz - inz;
+    const hlen2 = hx * hx + hy * hy + hz * hz;
+
+    if (hlen2 > STRAIGHT_EPSILON && lobeCount > 0) {
+        const hinv = 1 / Math.sqrt(hlen2);
+        hx *= hinv; hy *= hinv; hz *= hinv;
+
+        // a "reflection" with no direction change is not one — fade lobes in with the bend
+        const bend = (1 - c) * 0.5; // 0 at straight, → 1 at reversal
+
+        for (let k = 0; k < lobeCount; k++) {
+            const base = lobeOffset + k * LOBE_STRIDE;
+            const hdotn = hx * lobes[base + LOBE_NX] + hy * lobes[base + LOBE_NY] + hz * lobes[base + LOBE_NZ];
+            const g = bend * Math.exp(lobes[base + LOBE_LAMBDA] * (hdotn - 1)); // SG at the half-vector
+
+            const r0 = lobes[base + LOBE_RHO] * g;
+            const r1 = lobes[base + LOBE_RHO + 1] * g;
+            const r2 = lobes[base + LOBE_RHO + 2] * g;
+
+            if (r0 > b0) b0 = r0;
+            if (r1 > b1) b1 = r1;
+            if (r2 > b2) b2 = r2;
+        }
+    }
+
+    out[0] = b0 > 1 ? 1 : b0;
+    out[1] = b1 > 1 ? 1 : b1;
+    out[2] = b2 > 1 ? 1 : b2;
+}

package/src/engine/sound/simulation/probe/acoustic_trace_energy.js

@@ -1,136 +1,136 @@
-import { getBiasedNormalSample } from "../../../graphics/sh3/path_tracer/sampling/getBiasedNormalSample.js";
-import { v3_reflect } from "../../../../core/geom/vec3/v3_reflect.js";
-import { RayHit } from "../core/RayHit.js";
-
-/**
- * Speed of sound in air (m/s, ~20 °C). Converts a ray's path length to arrival time.
- * @type {number}
- */
-export const SPEED_OF_SOUND_MPS = 343;
-
-// module-static scratch — the bake is offline but stays allocation-free across rays/probes.
-const HIT = new RayHit();
-const SCATTER_DIR = [0, 0, 0];
-
-/**
- * Base self-occlusion offset; scaled by coordinate magnitude so it stays above the Float32 ULP at large
- * world scales (a fixed epsilon silently leaks energy through walls far from the origin).
- * @type {number}
- */
-const SELF_OCCLUSION_OFFSET = 0.00001;
-
-/**
- * Trace ONE ray's multi-bounce energy through the scene, depositing per-band energy into a time-binned
- * echogram. "Reverb = reflections with the source at the listener": the ray starts at the probe carrying
- * unit per-band energy `[low, mid, high]`; at each surface hit it deposits its surviving energy into the
- * bin for the cumulative arrival time (`pathLength / speedOfSound`), then loses `material.absorption[band]`
- * and scatters — diffuse (cosine lobe about the normal) with probability `material.scattering`, else
- * specular (reflect about the normal). A ray stops when it escapes, reaches the echogram window, decays
- * below `energyThreshold`, or hits `maxBounce`.
- *
- * Termination is by ENERGY THRESHOLD, not Russian roulette. RR with a fixed survival probability is the
- * wrong estimator for acoustic reflectance: a survivor at bounce `n` carries energy `(1−α)^n` yet is
- * scaled by `2^n`, so for a live room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and the rare
- * deep survivors dominate the late bins with enormous weights — exactly the part of the curve the RT60
- * slope is fitted to. Decaying each ray deterministically until it falls below the fit floor (then
- * dropping it, no survivor scaling) is unbiased for the fit window and far lower variance.
- *
- * DIRECTIONAL (FOA) encode: by acoustic reciprocity the reverberant energy this "source-at-the-listener"
- * ray represents ARRIVES at the listener from the ray's initial LAUNCH direction (reverse the path — its
- * last segment toward the listener is the launch segment reversed). So every deposit this ray makes is
- * attributed to that one launch direction: `directionAccum` accumulates, per band, the energy-weighted
- * launch direction (the first-order / B-format `XYZ` arrival vector; the echogram is the `W` omni term).
- * Summed over a sphere of rays and normalised by total energy, it gives the room's per-band arrival
- * anisotropy at the probe (≈0 = diffuse, →1 = one strong direction).
- *
- * Leak-free (the scale-aware self-occlusion offset). Allocation-free (module scratch); deterministic for a
- * given `random`. No WebAudio.
- *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {Ray3} ray origin (= probe) + initial UNIT direction; CONSUMED (mutated as it bounces)
- * @param {Float32Array} echogram per-band time bins, band-major `[band * binCount + bin]`, ACCUMULATED into
- * @param {Float32Array} directionAccum per-band energy-weighted launch direction, band-major `[band*3 + xyz]`
- *        (length 9), ACCUMULATED into
- * @param {number} binCount number of time bins per band
- * @param {number} binSeconds seconds per bin
- * @param {number} speedOfSound metres/second (e.g. {@link SPEED_OF_SOUND_MPS})
- * @param {number} maxBounce hard bounce cap (safety net for a near-lossless scene)
- * @param {number} energyThreshold stop once every band's energy is below this (set below the RT60 fit floor)
- * @param {function():number} random seeded RNG
- */
-export function acoustic_trace_energy(
-    index, ray, echogram, directionAccum, binCount, binSeconds, speedOfSound, maxBounce, energyThreshold, random
-) {
-    let energyLow = 1;
-    let energyMid = 1;
-    let energyHigh = 1;
-
-    // the launch direction (read before the bounce loop mutates ray[3..5]) — every deposit this ray makes
-    // is attributed to it as the arrival direction (reciprocity, see above)
-    const launchX = ray[3];
-    const launchY = ray[4];
-    const launchZ = ray[5];
-
-    let pathLength = 0;
-
-    const irMetres = binCount * binSeconds * speedOfSound; // path length at which the echogram window ends
-
-    for (let bounce = 0; bounce < maxBounce; bounce++) {
-        // never trace past the echogram window — a hit beyond it could not be deposited anyway
-        ray.tMax = irMetres - pathLength;
-
-        if (ray.tMax <= 0 || !index.closestHit(ray, HIT)) {
-            return; // escaped, or no more geometry within the remaining window
-        }
-
-        pathLength += HIT.t;
-
-        const bin = Math.floor((pathLength / speedOfSound) / binSeconds);
-
-        if (bin >= binCount) {
-            return; // arrived past the last bin
-        }
-
-        echogram[bin] += energyLow;
-        echogram[binCount + bin] += energyMid;
-        echogram[2 * binCount + bin] += energyHigh;
-
-        // FOA arrival vector: this deposit's energy arrives from the launch direction (reciprocity)
-        directionAccum[0] += energyLow * launchX;
-        directionAccum[1] += energyLow * launchY;
-        directionAccum[2] += energyLow * launchZ;
-        directionAccum[3] += energyMid * launchX;
-        directionAccum[4] += energyMid * launchY;
-        directionAccum[5] += energyMid * launchZ;
-        directionAccum[6] += energyHigh * launchX;
-        directionAccum[7] += energyHigh * launchY;
-        directionAccum[8] += energyHigh * launchZ;
-
-        // fold in this surface's absorption (the energy that continues past the reflection)
-        const absorption = HIT.material.absorption;
-        energyLow *= 1 - absorption[0];
-        energyMid *= 1 - absorption[1];
-        energyHigh *= 1 - absorption[2];
-
-        // drop the ray once even its loudest band has decayed below the fit floor
-        if (energyLow < energyThreshold && energyMid < energyThreshold && energyHigh < energyThreshold) {
-            return;
-        }
-
-        // bounce from the hit point: diffuse (cosine lobe) with prob `scattering`, else specular.
-        // v3_reflect must read the INCOMING direction (ray[3..5]) before we overwrite it.
-        if (random() < HIT.material.scattering) {
-            getBiasedNormalSample(SCATTER_DIR, 0, HIT.normal, 0, 1, random);
-        } else {
-            v3_reflect(SCATTER_DIR, 0, ray[3], ray[4], ray[5], HIT.normal[0], HIT.normal[1], HIT.normal[2]);
-        }
-
-        ray.setOrigin(HIT.position[0], HIT.position[1], HIT.position[2]);
-        ray.setDirection(SCATTER_DIR[0], SCATTER_DIR[1], SCATTER_DIR[2]);
-
-        // step off the surface so the next query doesn't immediately re-hit it; scale with coordinate
-        // magnitude so the nudge stays above the Float32 ULP far from the origin.
-        const magnitude = Math.max(Math.abs(ray[0]), Math.abs(ray[1]), Math.abs(ray[2]));
-        ray.shiftForward(SELF_OCCLUSION_OFFSET * Math.max(1, magnitude));
-    }
-}
+import { getBiasedNormalSample } from "../../../graphics/sh3/path_tracer/sampling/getBiasedNormalSample.js";
+import { v3_reflect } from "../../../../core/geom/vec3/v3_reflect.js";
+import { RayHit } from "../core/RayHit.js";
+
+/**
+ * Speed of sound in air (m/s, ~20 °C). Converts a ray's path length to arrival time.
+ * @type {number}
+ */
+export const SPEED_OF_SOUND_MPS = 343;
+
+// module-static scratch — the bake is offline but stays allocation-free across rays/probes.
+const HIT = new RayHit();
+const SCATTER_DIR = [0, 0, 0];
+
+/**
+ * Base self-occlusion offset; scaled by coordinate magnitude so it stays above the Float32 ULP at large
+ * world scales (a fixed epsilon silently leaks energy through walls far from the origin).
+ * @type {number}
+ */
+const SELF_OCCLUSION_OFFSET = 0.00001;
+
+/**
+ * Trace ONE ray's multi-bounce energy through the scene, depositing per-band energy into a time-binned
+ * echogram. "Reverb = reflections with the source at the listener": the ray starts at the probe carrying
+ * unit per-band energy `[low, mid, high]`; at each surface hit it deposits its surviving energy into the
+ * bin for the cumulative arrival time (`pathLength / speedOfSound`), then loses `material.absorption[band]`
+ * and scatters — diffuse (cosine lobe about the normal) with probability `material.scattering`, else
+ * specular (reflect about the normal). A ray stops when it escapes, reaches the echogram window, decays
+ * below `energyThreshold`, or hits `maxBounce`.
+ *
+ * Termination is by ENERGY THRESHOLD, not Russian roulette. RR with a fixed survival probability is the
+ * wrong estimator for acoustic reflectance: a survivor at bounce `n` carries energy `(1−α)^n` yet is
+ * scaled by `2^n`, so for a live room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and the rare
+ * deep survivors dominate the late bins with enormous weights — exactly the part of the curve the RT60
+ * slope is fitted to. Decaying each ray deterministically until it falls below the fit floor (then
+ * dropping it, no survivor scaling) is unbiased for the fit window and far lower variance.
+ *
+ * DIRECTIONAL (FOA) encode: by acoustic reciprocity the reverberant energy this "source-at-the-listener"
+ * ray represents ARRIVES at the listener from the ray's initial LAUNCH direction (reverse the path — its
+ * last segment toward the listener is the launch segment reversed). So every deposit this ray makes is
+ * attributed to that one launch direction: `directionAccum` accumulates, per band, the energy-weighted
+ * launch direction (the first-order / B-format `XYZ` arrival vector; the echogram is the `W` omni term).
+ * Summed over a sphere of rays and normalised by total energy, it gives the room's per-band arrival
+ * anisotropy at the probe (≈0 = diffuse, →1 = one strong direction).
+ *
+ * Leak-free (the scale-aware self-occlusion offset). Allocation-free (module scratch); deterministic for a
+ * given `random`. No WebAudio.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {Ray3} ray origin (= probe) + initial UNIT direction; CONSUMED (mutated as it bounces)
+ * @param {Float32Array} echogram per-band time bins, band-major `[band * binCount + bin]`, ACCUMULATED into
+ * @param {Float32Array} directionAccum per-band energy-weighted launch direction, band-major `[band*3 + xyz]`
+ *        (length 9), ACCUMULATED into
+ * @param {number} binCount number of time bins per band
+ * @param {number} binSeconds seconds per bin
+ * @param {number} speedOfSound metres/second (e.g. {@link SPEED_OF_SOUND_MPS})
+ * @param {number} maxBounce hard bounce cap (safety net for a near-lossless scene)
+ * @param {number} energyThreshold stop once every band's energy is below this (set below the RT60 fit floor)
+ * @param {function():number} random seeded RNG
+ */
+export function acoustic_trace_energy(
+    index, ray, echogram, directionAccum, binCount, binSeconds, speedOfSound, maxBounce, energyThreshold, random
+) {
+    let energyLow = 1;
+    let energyMid = 1;
+    let energyHigh = 1;
+
+    // the launch direction (read before the bounce loop mutates ray[3..5]) — every deposit this ray makes
+    // is attributed to it as the arrival direction (reciprocity, see above)
+    const launchX = ray[3];
+    const launchY = ray[4];
+    const launchZ = ray[5];
+
+    let pathLength = 0;
+
+    const irMetres = binCount * binSeconds * speedOfSound; // path length at which the echogram window ends
+
+    for (let bounce = 0; bounce < maxBounce; bounce++) {
+        // never trace past the echogram window — a hit beyond it could not be deposited anyway
+        ray.tMax = irMetres - pathLength;
+
+        if (ray.tMax <= 0 || !index.closestHit(ray, HIT)) {
+            return; // escaped, or no more geometry within the remaining window
+        }
+
+        pathLength += HIT.t;
+
+        const bin = Math.floor((pathLength / speedOfSound) / binSeconds);
+
+        if (bin >= binCount) {
+            return; // arrived past the last bin
+        }
+
+        echogram[bin] += energyLow;
+        echogram[binCount + bin] += energyMid;
+        echogram[2 * binCount + bin] += energyHigh;
+
+        // FOA arrival vector: this deposit's energy arrives from the launch direction (reciprocity)
+        directionAccum[0] += energyLow * launchX;
+        directionAccum[1] += energyLow * launchY;
+        directionAccum[2] += energyLow * launchZ;
+        directionAccum[3] += energyMid * launchX;
+        directionAccum[4] += energyMid * launchY;
+        directionAccum[5] += energyMid * launchZ;
+        directionAccum[6] += energyHigh * launchX;
+        directionAccum[7] += energyHigh * launchY;
+        directionAccum[8] += energyHigh * launchZ;
+
+        // fold in this surface's absorption (the energy that continues past the reflection)
+        const absorption = HIT.material.absorption;
+        energyLow *= 1 - absorption[0];
+        energyMid *= 1 - absorption[1];
+        energyHigh *= 1 - absorption[2];
+
+        // drop the ray once even its loudest band has decayed below the fit floor
+        if (energyLow < energyThreshold && energyMid < energyThreshold && energyHigh < energyThreshold) {
+            return;
+        }
+
+        // bounce from the hit point: diffuse (cosine lobe) with prob `scattering`, else specular.
+        // v3_reflect must read the INCOMING direction (ray[3..5]) before we overwrite it.
+        if (random() < HIT.material.scattering) {
+            getBiasedNormalSample(SCATTER_DIR, 0, HIT.normal, 0, 1, random);
+        } else {
+            v3_reflect(SCATTER_DIR, 0, ray[3], ray[4], ray[5], HIT.normal[0], HIT.normal[1], HIT.normal[2]);
+        }
+
+        ray.setOrigin(HIT.position[0], HIT.position[1], HIT.position[2]);
+        ray.setDirection(SCATTER_DIR[0], SCATTER_DIR[1], SCATTER_DIR[2]);
+
+        // step off the surface so the next query doesn't immediately re-hit it; scale with coordinate
+        // magnitude so the nudge stays above the Float32 ULP far from the origin.
+        const magnitude = Math.max(Math.abs(ray[0]), Math.abs(ray[1]), Math.abs(ray[2]));
+        ray.shiftForward(SELF_OCCLUSION_OFFSET * Math.max(1, magnitude));
+    }
+}