@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,110 +1,110 @@
-import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
-import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
-import { random_orthonormal_basis } from "../../../../core/geom/random/random_orthonormal_basis.js";
-import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.js";
-import { acoustic_trace_energy, SPEED_OF_SOUND_MPS } from "./acoustic_trace_energy.js";
-import { echogram_band_rt60 } from "./echogram_band_rt60.js";
-
-// Echogram resolution + trace budget. Fixed (not per-call tunables): the IR window must exceed the
-// longest RT60 being measured, so 3 s; 5 ms bins resolve the early decay finely enough for the slope fit.
-const IR_BIN_SECONDS = 0.005;
-const IR_BIN_COUNT = 600;
-// Drop a ray once its loudest band falls below −40 dB (10^-4 energy) — comfortably under the −35 dB the
-// RT60 slope is fitted to. MAX_BOUNCE is just a safety net for a near-lossless room (the IR-window bound
-// already stops a ray that fills the echogram).
-const ENERGY_THRESHOLD = 1e-4;
-const MAX_BOUNCE = 256;
-
-// module-static scratch — bake is offline but stays allocation-free across probes.
-const RAY = new Ray3();
-const FIBONACCI = [0, 0, 0];
-const DIRECTION = [0, 0, 0];
-const ROTATION = new Float32Array(9);
-const ECHOGRAM = new Float32Array(3 * IR_BIN_COUNT);
-// per-band energy-weighted arrival direction (band-major xyz) accumulated across this probe's rays
-const DIRECTION_ACCUM = new Float32Array(9);
-
-/**
- * Bake the per-band reverberation RT60 (seconds) for a probe at (x, y, z) by multi-bounce energy ray
- * tracing — "reverb = reflections with the source at the listener". Shoots `rayCount` rays evenly over the
- * sphere (Fibonacci set, randomly oriented per bake), each depositing per-band energy into a shared
- * time-binned echogram ({@link acoustic_trace_energy}); each band's decay is then reduced to an RT60
- * ({@link echogram_band_rt60}). A point in the open (no reflections) bakes to all-zero bands.
- *
- * This replaces the single-hit mean-free-path heuristic of `bakeReverb`: the RT60 is now *measured* from
- * the traced reflectogram (so it carries room timbre and per-band material absorption) rather than scaled
- * by a hand-tuned constant.
- *
- * Also bakes the per-band ARRIVAL DIRECTION (the FOA / first-order anisotropy vector): each ray's
- * reverberant energy is attributed to its launch direction (reciprocity — see {@link acoustic_trace_energy}),
- * and the energy-weighted sum is normalised per band by that band's total energy. The result is a vector of
- * magnitude 0…1 per band — ≈0 in a diffuse/symmetric room (arrivals cancel), →1 when the reverb comes
- * predominantly from one direction (an open side, a single strong reflector). This is what a directional
- * (B-format) reverb renderer steers the wet field by.
- *
- * Pure geometry → three RT60s + three direction vectors; offline (no WebAudio). Deterministic for a given
- * `random`.
- *
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @param {number} rayCount rays to shoot (more = smoother estimate)
- * @param {function():number} random seeded RNG
- * @param {Float32Array} outBands Strcuture [low, mid, high] RT60 seconds written here
- * @param {Float32Array} outDirections per-band arrival direction (band-major xyz, length 9) written here
- */
-export function bakeReverbBands(
-    index,
-    x, y, z,
-    rayCount,
-    random,
-    outBands,
-    outDirections
-) {
-
-    ECHOGRAM.fill(0);
-    DIRECTION_ACCUM.fill(0);
-
-    // randomly orient the Fibonacci set so accumulation isn't biased by the fixed lattice
-    random_orthonormal_basis(ROTATION, 0, random);
-
-    for (let i = 0; i < rayCount; i++) {
-        sphere_fibonacci_point(FIBONACCI, 0, i, rayCount);
-        v3_matrix3_rotate(DIRECTION, 0, FIBONACCI[0], FIBONACCI[1], FIBONACCI[2], ROTATION);
-
-        RAY.setOrigin(x, y, z);
-        RAY.setDirection(DIRECTION[0], DIRECTION[1], DIRECTION[2]);
-
-        acoustic_trace_energy(
-            index, RAY, ECHOGRAM, DIRECTION_ACCUM,
-            IR_BIN_COUNT, IR_BIN_SECONDS, SPEED_OF_SOUND_MPS,
-            MAX_BOUNCE, ENERGY_THRESHOLD, random
-        );
-    }
-
-    outBands[0] = echogram_band_rt60(ECHOGRAM, 0, IR_BIN_COUNT, IR_BIN_SECONDS);
-    outBands[1] = echogram_band_rt60(ECHOGRAM, IR_BIN_COUNT, IR_BIN_COUNT, IR_BIN_SECONDS);
-    outBands[2] = echogram_band_rt60(ECHOGRAM, 2 * IR_BIN_COUNT, IR_BIN_COUNT, IR_BIN_SECONDS);
-
-    // normalise each band's arrival vector by that band's total deposited energy → a 0…1 anisotropy vector
-    for (let band = 0; band < 3; band++) {
-        let bandEnergy = 0;
-        const bandOffset = band * IR_BIN_COUNT;
-        for (let bin = 0; bin < IR_BIN_COUNT; bin++) {
-            bandEnergy += ECHOGRAM[bandOffset + bin];
-        }
-
-        const d = band * 3;
-        if (bandEnergy > 0) {
-            const inv = 1 / bandEnergy;
-            outDirections[d] = DIRECTION_ACCUM[d] * inv;
-            outDirections[d + 1] = DIRECTION_ACCUM[d + 1] * inv;
-            outDirections[d + 2] = DIRECTION_ACCUM[d + 2] * inv;
-        } else {
-            outDirections[d] = 0;
-            outDirections[d + 1] = 0;
-            outDirections[d + 2] = 0;
-        }
-    }
-}
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { random_orthonormal_basis } from "../../../../core/geom/random/random_orthonormal_basis.js";
+import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.js";
+import { acoustic_trace_energy, SPEED_OF_SOUND_MPS } from "./acoustic_trace_energy.js";
+import { echogram_band_rt60 } from "./echogram_band_rt60.js";
+
+// Echogram resolution + trace budget. Fixed (not per-call tunables): the IR window must exceed the
+// longest RT60 being measured, so 3 s; 5 ms bins resolve the early decay finely enough for the slope fit.
+const IR_BIN_SECONDS = 0.005;
+const IR_BIN_COUNT = 600;
+// Drop a ray once its loudest band falls below −40 dB (10^-4 energy) — comfortably under the −35 dB the
+// RT60 slope is fitted to. MAX_BOUNCE is just a safety net for a near-lossless room (the IR-window bound
+// already stops a ray that fills the echogram).
+const ENERGY_THRESHOLD = 1e-4;
+const MAX_BOUNCE = 256;
+
+// module-static scratch — bake is offline but stays allocation-free across probes.
+const RAY = new Ray3();
+const FIBONACCI = [0, 0, 0];
+const DIRECTION = [0, 0, 0];
+const ROTATION = new Float32Array(9);
+const ECHOGRAM = new Float32Array(3 * IR_BIN_COUNT);
+// per-band energy-weighted arrival direction (band-major xyz) accumulated across this probe's rays
+const DIRECTION_ACCUM = new Float32Array(9);
+
+/**
+ * Bake the per-band reverberation RT60 (seconds) for a probe at (x, y, z) by multi-bounce energy ray
+ * tracing — "reverb = reflections with the source at the listener". Shoots `rayCount` rays evenly over the
+ * sphere (Fibonacci set, randomly oriented per bake), each depositing per-band energy into a shared
+ * time-binned echogram ({@link acoustic_trace_energy}); each band's decay is then reduced to an RT60
+ * ({@link echogram_band_rt60}). A point in the open (no reflections) bakes to all-zero bands.
+ *
+ * This replaces the single-hit mean-free-path heuristic of `bakeReverb`: the RT60 is now *measured* from
+ * the traced reflectogram (so it carries room timbre and per-band material absorption) rather than scaled
+ * by a hand-tuned constant.
+ *
+ * Also bakes the per-band ARRIVAL DIRECTION (the FOA / first-order anisotropy vector): each ray's
+ * reverberant energy is attributed to its launch direction (reciprocity — see {@link acoustic_trace_energy}),
+ * and the energy-weighted sum is normalised per band by that band's total energy. The result is a vector of
+ * magnitude 0…1 per band — ≈0 in a diffuse/symmetric room (arrivals cancel), →1 when the reverb comes
+ * predominantly from one direction (an open side, a single strong reflector). This is what a directional
+ * (B-format) reverb renderer steers the wet field by.
+ *
+ * Pure geometry → three RT60s + three direction vectors; offline (no WebAudio). Deterministic for a given
+ * `random`.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number} x
+ * @param {number} y
+ * @param {number} z
+ * @param {number} rayCount rays to shoot (more = smoother estimate)
+ * @param {function():number} random seeded RNG
+ * @param {Float32Array} outBands Strcuture [low, mid, high] RT60 seconds written here
+ * @param {Float32Array} outDirections per-band arrival direction (band-major xyz, length 9) written here
+ */
+export function bakeReverbBands(
+    index,
+    x, y, z,
+    rayCount,
+    random,
+    outBands,
+    outDirections
+) {
+
+    ECHOGRAM.fill(0);
+    DIRECTION_ACCUM.fill(0);
+
+    // randomly orient the Fibonacci set so accumulation isn't biased by the fixed lattice
+    random_orthonormal_basis(ROTATION, 0, random);
+
+    for (let i = 0; i < rayCount; i++) {
+        sphere_fibonacci_point(FIBONACCI, 0, i, rayCount);
+        v3_matrix3_rotate(DIRECTION, 0, FIBONACCI[0], FIBONACCI[1], FIBONACCI[2], ROTATION);
+
+        RAY.setOrigin(x, y, z);
+        RAY.setDirection(DIRECTION[0], DIRECTION[1], DIRECTION[2]);
+
+        acoustic_trace_energy(
+            index, RAY, ECHOGRAM, DIRECTION_ACCUM,
+            IR_BIN_COUNT, IR_BIN_SECONDS, SPEED_OF_SOUND_MPS,
+            MAX_BOUNCE, ENERGY_THRESHOLD, random
+        );
+    }
+
+    outBands[0] = echogram_band_rt60(ECHOGRAM, 0, IR_BIN_COUNT, IR_BIN_SECONDS);
+    outBands[1] = echogram_band_rt60(ECHOGRAM, IR_BIN_COUNT, IR_BIN_COUNT, IR_BIN_SECONDS);
+    outBands[2] = echogram_band_rt60(ECHOGRAM, 2 * IR_BIN_COUNT, IR_BIN_COUNT, IR_BIN_SECONDS);
+
+    // normalise each band's arrival vector by that band's total deposited energy → a 0…1 anisotropy vector
+    for (let band = 0; band < 3; band++) {
+        let bandEnergy = 0;
+        const bandOffset = band * IR_BIN_COUNT;
+        for (let bin = 0; bin < IR_BIN_COUNT; bin++) {
+            bandEnergy += ECHOGRAM[bandOffset + bin];
+        }
+
+        const d = band * 3;
+        if (bandEnergy > 0) {
+            const inv = 1 / bandEnergy;
+            outDirections[d] = DIRECTION_ACCUM[d] * inv;
+            outDirections[d + 1] = DIRECTION_ACCUM[d + 1] * inv;
+            outDirections[d + 2] = DIRECTION_ACCUM[d + 2] * inv;
+        } else {
+            outDirections[d] = 0;
+            outDirections[d + 1] = 0;
+            outDirections[d + 2] = 0;
+        }
+    }
+}

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

@@ -1,148 +1,148 @@
-import {
-    csr_graph_from_undirected_edge_list
-} from "../../../../core/graph/csr/csr_graph_from_undirected_edge_list.js";
-import { probe_delaunay_edges } from "./probe_delaunay_edges.js";
-import { probe_densify_portals } from "./probe_densify_portals.js";
-import { probe_edge_visible } from "./probe_edge_visible.js";
-import { probe_visibility_augment } from "./probe_visibility_augment.js";
-import { probe_visibility_bridge_components } from "./probe_visibility_bridge_components.js";
-
-const NO_PORTALS = [];
-
-/**
- * Bake the probe-visibility graph into a {@link AcousticProbeField}: a sparse, occlusion-respecting connectivity
- * graph over the probes, weighted by distance, that sound routes through ({@link findAcousticPath}). Built
- * topologically in three stages so the complete O(n²) pair graph is never enumerated (see
- * VISIBILITY_GRAPH_PLAN.md):
- *
- *  - **A** — the Delaunay tetrahedralisation of the probe positions gives ≈6-7·n candidate edges
- *    ({@link probe_delaunay_edges}); keep those with clear line of sight. Dropping the occluded ones
- *    fragments the graph into islands (rooms) along walls.
- *  - **B** — bridge islands that a doorway connects but the Delaunay edge missed, with the shortest visible
- *    cross-component edges ({@link probe_visibility_bridge_components}). Sealed regions stay separate.
- *  - **C** — add a budgeted handful of shortcut edges that straighten detours/corners
- *    ({@link probe_visibility_augment}), since the local Delaunay base can route around clear lines.
- *  - **D** — when `portals` are given, fan extra cross-opening CHORDS around each portal throat
- *    ({@link probe_densify_portals}) so routing through an opening is symmetric, not funnelled through one
- *    off-centre probe. No-op for an empty `portals`, so plain callers are unchanged.
- *
- * O(n) edges and O(n) shadow rays, not O(n²). The result is stored as a {@link CSRGraph} on the field
- * (connectivity is an inherent property of the field). Offline (no WebAudio).
- *
- * @param {AcousticProbeField} probeField the field whose probes get connected (mutated: its visibility graph is set)
- * @param {AcousticOccluderIndex} index the acoustic scene
- * @param {ArrayLike<number>} [portals] probe indices of portal throats to densify around (stage D)
- * @param {number} [minSpacing] the probe spacing hint — required (scales the densify radius/bias) iff `portals` given
- * @returns {AcousticProbeField} the same field, now carrying its visibility graph
- */
-export function bakeVisibility(probeField, index, portals = NO_PORTALS, minSpacing = 0) {
-    const n = probeField.size;
-
-    // Stage A: Delaunay candidate edges, kept where the line of sight is clear. The endpoints of the OCCLUDED
-    // (dropped) candidates border a wall — the only probes a missed doorway can be bridged from (stage B).
-    const candidates = probe_delaunay_edges(probeField);
-    /**
-     *
-     * @type {number[]}
-     */
-    const baseA = [];
-    /**
-     *
-     * @type {number[]}
-     */
-    const baseB = [];
-    const onWall = new Uint8Array(n);
-
-    /**
-     *
-     * @type {number[]}
-     */
-    const sources = [];
-    for (let i = 0; i < candidates.a.length; i++) {
-        const a = candidates.a[i];
-        const b = candidates.b[i];
-        if (probe_edge_visible(probeField, index, a, b)) {
-            baseA.push(a);
-            baseB.push(b);
-        } else {
-            if (onWall[a] === 0) {
-                onWall[a] = 1;
-                sources.push(a);
-            }
-            if (onWall[b] === 0) {
-                onWall[b] = 1;
-                sources.push(b);
-            }
-        }
-    }
-
-    // Stage B: bridge the islands that dropping occluded edges created, searching from the wall-adjacent probes
-    const bridges = probe_visibility_bridge_components(probeField, index, { a: baseA, b: baseB }, sources);
-
-    const currentA = baseA.concat(bridges.a);
-    const currentB = baseB.concat(bridges.b);
-
-    // Stage C: shortcut augmentation for path quality
-    const augment = probe_visibility_augment(probeField, index, { a: currentA, b: currentB });
-
-    let edgeA = currentA.concat(augment.a);
-    let edgeB = currentB.concat(augment.b);
-
-    // Stage D: portal densification — cross-opening chords so routing through an opening is symmetric. Runs
-    // after A-C so it dedups against the full base/bridge/augment edge set; no-op without portals.
-    if (portals.length > 0) {
-        const chords = probe_densify_portals(probeField, index, portals, { a: edgeA, b: edgeB }, minSpacing);
-        edgeA = edgeA.concat(chords.a);
-        edgeB = edgeB.concat(chords.b);
-    }
-
-    // assemble the final undirected edge list, weighted by inter-probe distance (the runtime recheck
-    // restores weights the same way)
-    const edgeCount = edgeA.length;
-
-    const edgeW = new Float32Array(edgeCount);
-    for (let e = 0; e < edgeCount; e++) {
-        const dx = probeField.probeX(edgeB[e]) - probeField.probeX(edgeA[e]);
-        const dy = probeField.probeY(edgeB[e]) - probeField.probeY(edgeA[e]);
-        const dz = probeField.probeZ(edgeB[e]) - probeField.probeZ(edgeA[e]);
-        edgeW[e] = Math.sqrt(dx * dx + dy * dy + dz * dz);
-    }
-
-    const graph = csr_graph_from_undirected_edge_list(n, edgeA, edgeB, edgeW);
-
-    probeField.setVisibilityGraph(graph);
-
-    return probeField;
-}
-
-/**
- * Find the acoustic path from a source to the listener through a `field`'s baked visibility graph: snaps
- * each end to its nearest probe and returns the shortest route as a list of probe positions `{x, y, z}`
- * (inclusive), or null if they are in disconnected regions. The probe just before the listener's end is the
- * EXIT POINT — the apparent direction the leaked sound arrives from (spatialize by exit, not by source).
- *
- * @param {AcousticProbeField} field a field with a baked visibility graph ({@link bakeVisibility})
- * @param {number} sourceX
- * @param {number} sourceY
- * @param {number} sourceZ
- * @param {number} listenerX
- * @param {number} listenerY
- * @param {number} listenerZ
- * @returns {{x:number,y:number,z:number}[]|null}
- */
-export function findAcousticPath(field, sourceX, sourceY, sourceZ, listenerX, listenerY, listenerZ) {
-    const from = field.nearestIndex(sourceX, sourceY, sourceZ);
-    const to = field.nearestIndex(listenerX, listenerY, listenerZ);
-
-    if (from === -1 || to === -1) {
-        return null;
-    }
-
-    const indices = field.shortestPath(from, to);
-
-    if (indices === null) {
-        return null;
-    }
-
-    return indices.map((i) => ({ x: field.probeX(i), y: field.probeY(i), z: field.probeZ(i) }));
-}
+import {
+    csr_graph_from_undirected_edge_list
+} from "../../../../core/graph/csr/csr_graph_from_undirected_edge_list.js";
+import { probe_delaunay_edges } from "./probe_delaunay_edges.js";
+import { probe_densify_portals } from "./probe_densify_portals.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+import { probe_visibility_augment } from "./probe_visibility_augment.js";
+import { probe_visibility_bridge_components } from "./probe_visibility_bridge_components.js";
+
+const NO_PORTALS = [];
+
+/**
+ * Bake the probe-visibility graph into a {@link AcousticProbeField}: a sparse, occlusion-respecting connectivity
+ * graph over the probes, weighted by distance, that sound routes through ({@link findAcousticPath}). Built
+ * topologically in three stages so the complete O(n²) pair graph is never enumerated (see
+ * VISIBILITY_GRAPH_PLAN.md):
+ *
+ *  - **A** — the Delaunay tetrahedralisation of the probe positions gives ≈6-7·n candidate edges
+ *    ({@link probe_delaunay_edges}); keep those with clear line of sight. Dropping the occluded ones
+ *    fragments the graph into islands (rooms) along walls.
+ *  - **B** — bridge islands that a doorway connects but the Delaunay edge missed, with the shortest visible
+ *    cross-component edges ({@link probe_visibility_bridge_components}). Sealed regions stay separate.
+ *  - **C** — add a budgeted handful of shortcut edges that straighten detours/corners
+ *    ({@link probe_visibility_augment}), since the local Delaunay base can route around clear lines.
+ *  - **D** — when `portals` are given, fan extra cross-opening CHORDS around each portal throat
+ *    ({@link probe_densify_portals}) so routing through an opening is symmetric, not funnelled through one
+ *    off-centre probe. No-op for an empty `portals`, so plain callers are unchanged.
+ *
+ * O(n) edges and O(n) shadow rays, not O(n²). The result is stored as a {@link CSRGraph} on the field
+ * (connectivity is an inherent property of the field). Offline (no WebAudio).
+ *
+ * @param {AcousticProbeField} probeField the field whose probes get connected (mutated: its visibility graph is set)
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {ArrayLike<number>} [portals] probe indices of portal throats to densify around (stage D)
+ * @param {number} [minSpacing] the probe spacing hint — required (scales the densify radius/bias) iff `portals` given
+ * @returns {AcousticProbeField} the same field, now carrying its visibility graph
+ */
+export function bakeVisibility(probeField, index, portals = NO_PORTALS, minSpacing = 0) {
+    const n = probeField.size;
+
+    // Stage A: Delaunay candidate edges, kept where the line of sight is clear. The endpoints of the OCCLUDED
+    // (dropped) candidates border a wall — the only probes a missed doorway can be bridged from (stage B).
+    const candidates = probe_delaunay_edges(probeField);
+    /**
+     *
+     * @type {number[]}
+     */
+    const baseA = [];
+    /**
+     *
+     * @type {number[]}
+     */
+    const baseB = [];
+    const onWall = new Uint8Array(n);
+
+    /**
+     *
+     * @type {number[]}
+     */
+    const sources = [];
+    for (let i = 0; i < candidates.a.length; i++) {
+        const a = candidates.a[i];
+        const b = candidates.b[i];
+        if (probe_edge_visible(probeField, index, a, b)) {
+            baseA.push(a);
+            baseB.push(b);
+        } else {
+            if (onWall[a] === 0) {
+                onWall[a] = 1;
+                sources.push(a);
+            }
+            if (onWall[b] === 0) {
+                onWall[b] = 1;
+                sources.push(b);
+            }
+        }
+    }
+
+    // Stage B: bridge the islands that dropping occluded edges created, searching from the wall-adjacent probes
+    const bridges = probe_visibility_bridge_components(probeField, index, { a: baseA, b: baseB }, sources);
+
+    const currentA = baseA.concat(bridges.a);
+    const currentB = baseB.concat(bridges.b);
+
+    // Stage C: shortcut augmentation for path quality
+    const augment = probe_visibility_augment(probeField, index, { a: currentA, b: currentB });
+
+    let edgeA = currentA.concat(augment.a);
+    let edgeB = currentB.concat(augment.b);
+
+    // Stage D: portal densification — cross-opening chords so routing through an opening is symmetric. Runs
+    // after A-C so it dedups against the full base/bridge/augment edge set; no-op without portals.
+    if (portals.length > 0) {
+        const chords = probe_densify_portals(probeField, index, portals, { a: edgeA, b: edgeB }, minSpacing);
+        edgeA = edgeA.concat(chords.a);
+        edgeB = edgeB.concat(chords.b);
+    }
+
+    // assemble the final undirected edge list, weighted by inter-probe distance (the runtime recheck
+    // restores weights the same way)
+    const edgeCount = edgeA.length;
+
+    const edgeW = new Float32Array(edgeCount);
+    for (let e = 0; e < edgeCount; e++) {
+        const dx = probeField.probeX(edgeB[e]) - probeField.probeX(edgeA[e]);
+        const dy = probeField.probeY(edgeB[e]) - probeField.probeY(edgeA[e]);
+        const dz = probeField.probeZ(edgeB[e]) - probeField.probeZ(edgeA[e]);
+        edgeW[e] = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+
+    const graph = csr_graph_from_undirected_edge_list(n, edgeA, edgeB, edgeW);
+
+    probeField.setVisibilityGraph(graph);
+
+    return probeField;
+}
+
+/**
+ * Find the acoustic path from a source to the listener through a `field`'s baked visibility graph: snaps
+ * each end to its nearest probe and returns the shortest route as a list of probe positions `{x, y, z}`
+ * (inclusive), or null if they are in disconnected regions. The probe just before the listener's end is the
+ * EXIT POINT — the apparent direction the leaked sound arrives from (spatialize by exit, not by source).
+ *
+ * @param {AcousticProbeField} field a field with a baked visibility graph ({@link bakeVisibility})
+ * @param {number} sourceX
+ * @param {number} sourceY
+ * @param {number} sourceZ
+ * @param {number} listenerX
+ * @param {number} listenerY
+ * @param {number} listenerZ
+ * @returns {{x:number,y:number,z:number}[]|null}
+ */
+export function findAcousticPath(field, sourceX, sourceY, sourceZ, listenerX, listenerY, listenerZ) {
+    const from = field.nearestIndex(sourceX, sourceY, sourceZ);
+    const to = field.nearestIndex(listenerX, listenerY, listenerZ);
+
+    if (from === -1 || to === -1) {
+        return null;
+    }
+
+    const indices = field.shortestPath(from, to);
+
+    if (indices === null) {
+        return null;
+    }
+
+    return indices.map((i) => ({ x: field.probeX(i), y: field.probeY(i), z: field.probeZ(i) }));
+}