@woosh/meep-engine 2.163.10 → 2.164.0

package/src/engine/sound/simulation/probe/bakeProbeField.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Automatically bake a {@link AcousticProbeField} over the scene: place probes adaptively (sparse in open
+ * halls, dense along detail / corridors, never inside solids), guarantee they connect through every real
+ * acoustic path, then bake each probe's per-band reverb (RT60) from the scene geometry. Offline (no
+ * WebAudio); deterministic for given geometry + `random`. The result is serializable — bake once, ship,
+ * load at runtime.
+ *
+ * The bake REGION is derived from the scene, not configured: the combined occluder hull
+ * ({@link AcousticOccluderIndex#computeWorldBounds}) inflated by {@link BOUNDS_MARGIN_SCALE} × `minSpacing`
+ * on every side. An empty index (no occluders) yields an empty field. A caller wanting a hand-picked region
+ * drops to the lower-level {@link probe_place_sdf_cover} + {@link bakeVisibility} + {@link bakeReverbBands}.
+ *
+ * Pipeline (see PROBE_PLACEMENT.md):
+ *  1. **SDF grid + portal discovery** — build the shared SDF grid ({@link build_sdf_grid}) once; a provisional
+ *     {@link probe_place_sdf_cover} + {@link bakeVisibility} resolve the openings (a doorway is sub-voxel, so
+ *     it is found from the visibility graph's BVH rays, not the grid), and {@link probe_detect_portals} returns
+ *     each opening's throat.
+ *  2. **SDF cover (portals pre-seeded)** — re-cover with the portal throats {@link probe_place_sdf_cover}
+ *     `predefined`, so they carve the SDF (no redundant probe lands on them) and lead the probe list. A
+ *     maximal-empty-sphere cover keyed on `minSpacing`: probes no closer than the hint, sparser in open
+ *     volume, all in air.
+ *  3. **Connectivity refinement** — {@link bakeVisibility} (densified around portals so cross-opening routing
+ *     is symmetric — {@link probe_densify_portals}), then {@link probe_refine_connectivity} inserts extra
+ *     probes (down to `minSpacing / maxRefineFactor`) to thread bends/throats; re-bake and repeat until the
+ *     graph stops gaining components.
+ *  4. **Reverb** — bake per-band RT60 + arrival direction at every final probe.
+ *  5. **Reflector lobes** — harvest each probe's local reflectors ({@link bakeProbeReflectors}) into the
+ *     directional-transfer lobes the corner-leak pathing gates bends with (see {@link acoustic_probe_transfer}).
+ *
+ * The `minSpacing` hint drives the initial cover/fit; only connectivity refinement may go finer.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene (its occluder hull defines the bake region)
+ * @param {number} minSpacing target/min probe spacing — the density hint (smaller = denser)
+ * @param {number} rayCount rays per probe (reverb estimate quality)
+ * @param {function():number} random seeded RNG (reverb bake)
+ * @param {{sparsenessRatio?: number, maxRefineFactor?: number, corridorReachFactor?: number, maxRefineRounds?: number, detectPortals?: boolean, constrictionFactor?: number, portalFloorRatio?: number}} [options]
+ *        `detectPortals` (default true) toggles the portal discovery + densification stages.
+ * @returns {AcousticProbeField}
+ */
+export function bakeProbeField(index: AcousticOccluderIndex, minSpacing: number, rayCount: number, random: () => number, options?: {
+    sparsenessRatio?: number;
+    maxRefineFactor?: number;
+    corridorReachFactor?: number;
+    maxRefineRounds?: number;
+    detectPortals?: boolean;
+    constrictionFactor?: number;
+    portalFloorRatio?: number;
+}): AcousticProbeField;
+import { AcousticProbeField } from "./AcousticProbeField.js";
+//# sourceMappingURL=bakeProbeField.d.ts.map

package/src/engine/sound/simulation/probe/bakeProbeField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bakeProbeField.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeField.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,yEAPW,MAAM,YACN,MAAM,gBACK,MAAM,YACjB;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAC,GAE3L,kBAAkB,CA+E9B;mCAtJkC,yBAAyB"}

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

@@ -0,0 +1,169 @@
+import { bakeReverbBands } from "./bakeReverbBands.js";
+import { bakeVisibility } from "./bakeVisibility.js";
+import { AcousticProbeField } from "./AcousticProbeField.js";
+import { build_sdf_grid } from "./probe_sdf_grid.js";
+import { probe_detect_portals } from "./probe_detect_portals.js";
+import { probe_place_sdf_cover } from "./probe_place_sdf_cover.js";
+import { probe_refine_connectivity } from "./probe_refine_connectivity.js";
+import { bakeProbeReflectors, MAX_LOBES } from "./bakeProbeReflectors.js";
+import { LOBE_STRIDE } from "./acoustic_probe_transfer.js";
+
+const NO_PORTALS = [];
+
+// module scratch — the per-band RT60 + arrival direction bakeReverbBands writes for the current probe
+const BANDS = new Float32Array(3);
+const DIRECTIONS = new Float32Array(9);
+
+// module scratch — the occluder hull, inflated into the bake bounds
+const HULL = new Float32Array(6);
+
+// Bake region = the occluder hull inflated by this × minSpacing on every side: an air ring around the
+// geometry so a listener/source just outside still gets coverage and the cover doesn't end flush on the
+// outermost surfaces. (Open exterior air gets only sparse, max-spacing probes, so this margin is cheap.)
+const BOUNDS_MARGIN_SCALE = 2;
+
+// Connectivity refinement re-bakes between rounds (each round may insert probes that unlock the next); a
+// handful converges. Bounded so a pathological scene can't loop.
+const DEFAULT_MAX_REFINE_ROUNDS = 3;
+
+// Reflector harvest (directional transfer, Phase 0): a reflector within this × minSpacing of a probe is
+// "local" enough to bend a route through it; REFLECTOR_RAYS = rays/probe for reflector coverage.
+const REFLECTOR_RADIUS_SCALE = 2;
+const REFLECTOR_RAYS = 128;
+
+// scratch — one probe's harvested lobes
+const LOBE_SCRATCH = new Float32Array(MAX_LOBES * LOBE_STRIDE);
+
+/**
+ * Automatically bake a {@link AcousticProbeField} over the scene: place probes adaptively (sparse in open
+ * halls, dense along detail / corridors, never inside solids), guarantee they connect through every real
+ * acoustic path, then bake each probe's per-band reverb (RT60) from the scene geometry. Offline (no
+ * WebAudio); deterministic for given geometry + `random`. The result is serializable — bake once, ship,
+ * load at runtime.
+ *
+ * The bake REGION is derived from the scene, not configured: the combined occluder hull
+ * ({@link AcousticOccluderIndex#computeWorldBounds}) inflated by {@link BOUNDS_MARGIN_SCALE} × `minSpacing`
+ * on every side. An empty index (no occluders) yields an empty field. A caller wanting a hand-picked region
+ * drops to the lower-level {@link probe_place_sdf_cover} + {@link bakeVisibility} + {@link bakeReverbBands}.
+ *
+ * Pipeline (see PROBE_PLACEMENT.md):
+ *  1. **SDF grid + portal discovery** — build the shared SDF grid ({@link build_sdf_grid}) once; a provisional
+ *     {@link probe_place_sdf_cover} + {@link bakeVisibility} resolve the openings (a doorway is sub-voxel, so
+ *     it is found from the visibility graph's BVH rays, not the grid), and {@link probe_detect_portals} returns
+ *     each opening's throat.
+ *  2. **SDF cover (portals pre-seeded)** — re-cover with the portal throats {@link probe_place_sdf_cover}
+ *     `predefined`, so they carve the SDF (no redundant probe lands on them) and lead the probe list. A
+ *     maximal-empty-sphere cover keyed on `minSpacing`: probes no closer than the hint, sparser in open
+ *     volume, all in air.
+ *  3. **Connectivity refinement** — {@link bakeVisibility} (densified around portals so cross-opening routing
+ *     is symmetric — {@link probe_densify_portals}), then {@link probe_refine_connectivity} inserts extra
+ *     probes (down to `minSpacing / maxRefineFactor`) to thread bends/throats; re-bake and repeat until the
+ *     graph stops gaining components.
+ *  4. **Reverb** — bake per-band RT60 + arrival direction at every final probe.
+ *  5. **Reflector lobes** — harvest each probe's local reflectors ({@link bakeProbeReflectors}) into the
+ *     directional-transfer lobes the corner-leak pathing gates bends with (see {@link acoustic_probe_transfer}).
+ *
+ * The `minSpacing` hint drives the initial cover/fit; only connectivity refinement may go finer.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene (its occluder hull defines the bake region)
+ * @param {number} minSpacing target/min probe spacing — the density hint (smaller = denser)
+ * @param {number} rayCount rays per probe (reverb estimate quality)
+ * @param {function():number} random seeded RNG (reverb bake)
+ * @param {{sparsenessRatio?: number, maxRefineFactor?: number, corridorReachFactor?: number, maxRefineRounds?: number, detectPortals?: boolean, constrictionFactor?: number, portalFloorRatio?: number}} [options]
+ *        `detectPortals` (default true) toggles the portal discovery + densification stages.
+ * @returns {AcousticProbeField}
+ */
+export function bakeProbeField(index, minSpacing, rayCount, random, options = {}) {
+    // Derive the bake region from the scene: the occluder hull + a spacing-scaled margin. No occluders →
+    // nothing to cover → an empty field.
+    if (index.computeWorldBounds(HULL) === 0) {
+        return new AcousticProbeField();
+    }
+    const margin = BOUNDS_MARGIN_SCALE * minSpacing;
+    const bounds = [
+        HULL[0] - margin, HULL[1] - margin, HULL[2] - margin,
+        HULL[3] + margin, HULL[4] + margin, HULL[5] + margin,
+    ];
+
+    // The SDF grid is the expensive part (up to 256³ signedDistanceAt queries); build it once and reuse it for
+    // both the provisional and the final cover.
+    const grid = build_sdf_grid(index, bounds, minSpacing, options.sparsenessRatio);
+
+    // 1. Portal discovery — a provisional cover + visibility resolves the openings (a doorway is sub-voxel, so
+    //    it is found from the graph's BVH visibility rays, not the grid), then detect each opening's throat.
+    const provisional = new AcousticProbeField();
+    placeProbes(provisional, probe_place_sdf_cover(grid));
+    bakeVisibility(provisional, index);
+    const portals = options.detectPortals === false
+        ? NO_PORTALS
+        : probe_detect_portals(provisional, index, minSpacing, options);
+
+    // 2. Final cover — re-place with the portal throats PRE-SEEDED so they carve the SDF (no redundant cover
+    //    probe lands on them) and lead the probe list (indices [0, portalCount)). Densify the visibility around
+    //    them so routing through an opening is symmetric. No opening found → reuse the provisional field.
+    let field;
+    let portalIndices;
+    if (portals.length === 0) {
+        field = provisional;
+        portalIndices = NO_PORTALS;
+    } else {
+        field = new AcousticProbeField();
+        placeProbes(field, probe_place_sdf_cover(grid, { predefined: portals }));
+        portalIndices = indexRange(portals.length / 3);
+        bakeVisibility(field, index, portalIndices, minSpacing);
+    }
+
+    // 3. Connectivity refinement — thread bends/throats so a visible probe chain spans every acoustic path.
+    //    Inserted waypoints append AFTER the cover, so the portals stay at [0, portalCount).
+    const maxRounds = options.maxRefineRounds ?? DEFAULT_MAX_REFINE_ROUNDS;
+    for (let round = 0; round < maxRounds; round++) {
+        const waypoints = probe_refine_connectivity(index, field, minSpacing, options);
+        if (waypoints.length === 0) {
+            break;
+        }
+        placeProbes(field, waypoints);
+        bakeVisibility(field, index, portalIndices, minSpacing); // re-bake (densified) with the inserted probes
+    }
+
+    // 4. Per-probe reverb at the final positions (the visibility graph is already baked above)
+    for (let i = 0; i < field.size; i++) {
+        bakeReverbBands(index, field.probeX(i), field.probeY(i), field.probeZ(i), rayCount, random, BANDS, DIRECTIONS);
+        field.setProbeReverbDecay(i, BANDS[0], BANDS[1], BANDS[2]);
+        field.setProbeReverbDirections(i, DIRECTIONS);
+    }
+
+    // 5. Reflector lobes — the directional TRANSFER each probe imposes on a routed bend (corner-leak gating):
+    //    probe-local reflectors → SG lobes (see acoustic_probe_transfer). Stored CSR-style on the field.
+    const reflectorRadius = REFLECTOR_RADIUS_SCALE * minSpacing;
+    const lobeOffsets = new Uint32Array(field.size + 1);
+    const lobeData = [];
+    let lobesSoFar = 0;
+    for (let i = 0; i < field.size; i++) {
+        lobeOffsets[i] = lobesSoFar;
+        const count = bakeProbeReflectors(index, field.probeX(i), field.probeY(i), field.probeZ(i), reflectorRadius, REFLECTOR_RAYS, LOBE_SCRATCH);
+        for (let f = 0; f < count * LOBE_STRIDE; f++) {
+            lobeData.push(LOBE_SCRATCH[f]);
+        }
+        lobesSoFar += count;
+    }
+    lobeOffsets[field.size] = lobesSoFar;
+    field.setLobes(lobeOffsets, Float32Array.from(lobeData));
+
+    return field;
+}
+
+/** Append a flat `[x,y,z, …]` list of positions to the field as probes. */
+function placeProbes(field, positions) {
+    for (let i = 0; i < positions.length; i += 3) {
+        field.setProbePosition(field.size, positions[i], positions[i + 1], positions[i + 2]);
+    }
+}
+
+/** The index range `[0, count)` — the indices of the pre-seeded portal probes (placed first). */
+function indexRange(count) {
+    const out = new Uint32Array(count);
+    for (let i = 0; i < count; i++) {
+        out[i] = i;
+    }
+    return out;
+}

package/src/engine/sound/simulation/probe/bakeProbeReflectors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bake the reflector lobes for a probe at (x, y, z), writing them into `outLobes` (a flat Float32Array of at
+ * least `MAX_LOBES · LOBE_STRIDE`) and returning the lobe count (0…MAX_LOBES). A probe in the open (no
+ * occluder within `radius`) yields 0 lobes — pure forward transfer.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number} x @param {number} y @param {number} z probe position
+ * @param {number} radius probe-local reflector radius (a reflector beyond this can't bend a local probe)
+ * @param {number} rayCount rays to shoot (more = finer reflector coverage)
+ * @param {Float32Array} outLobes destination, ≥ MAX_LOBES·LOBE_STRIDE floats
+ * @returns {number} number of lobes written
+ */
+export function bakeProbeReflectors(index: AcousticOccluderIndex, x: number, y: number, z: number, radius: number, rayCount: number, outLobes: Float32Array): number;
+export const MAX_LOBES: 8;
+//# sourceMappingURL=bakeProbeReflectors.d.ts.map

package/src/engine/sound/simulation/probe/bakeProbeReflectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bakeProbeReflectors.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeProbeReflectors.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;GAWG;AACH,qEANW,MAAM,KAAY,MAAM,KAAY,MAAM,UAC1C,MAAM,YACN,MAAM,YACN,YAAY,GACV,MAAM,CA+DlB;AA5FD,0BAAoB"}

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

@@ -0,0 +1,108 @@
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { RayHit } from "../core/RayHit.js";
+import { LOBE_STRIDE } from "./acoustic_probe_transfer.js";
+
+// Harvest the PROBE-LOCAL reflectors that give a probe its directional transfer (the lobes consumed by
+// acoustic_probe_transfer). Shoots a Fibonacci sphere of short rays from the probe; every ray that hits an
+// occluder within `radius` is a local reflector sample (the radius is the "near the probe" gate that makes a
+// bend physical only locally). Samples are greedily CLUSTERED by surface normal into reflector lobes — one
+// SG per cluster: axis = the (air-side, ray-facing) normal, per-band reflectivity ρ = mean(1 − absorption).
+//
+// Offline, deterministic (fixed Fibonacci set), allocation-free. See PROBE_TRANSFER_RESEARCH.md §3–4.
+
+const MAX_LOBES = 8;                              // cap on reflector clusters per probe
+const CLUSTER_COS = Math.cos(25 * Math.PI / 180); // merge hit-normals agreeing within 25°
+
+// Phase-0 reflector sharpness: a fixed, moderate specular width. (Curvature-derived λ — broad for a sphere,
+// sharp for a flat mirror — is the Phase-1 refinement; the refuse/admit gate is λ-insensitive, so a constant
+// is fine here. See PROBE_TRANSFER_RESEARCH.md §9.)
+const LOBE_LAMBDA = 16;
+
+// module scratch — bake is offline but stays allocation-free across probes
+const RAY = new Ray3();
+const HIT = new RayHit();
+const FIB = [0, 0, 0];
+// per-cluster accumulators (summed normal, summed per-band ρ, sample count)
+const C_NX = new Float32Array(MAX_LOBES);
+const C_NY = new Float32Array(MAX_LOBES);
+const C_NZ = new Float32Array(MAX_LOBES);
+const C_RHO = new Float32Array(MAX_LOBES * 3);
+const C_COUNT = new Float32Array(MAX_LOBES);
+
+/**
+ * Bake the reflector lobes for a probe at (x, y, z), writing them into `outLobes` (a flat Float32Array of at
+ * least `MAX_LOBES · LOBE_STRIDE`) and returning the lobe count (0…MAX_LOBES). A probe in the open (no
+ * occluder within `radius`) yields 0 lobes — pure forward transfer.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number} x @param {number} y @param {number} z probe position
+ * @param {number} radius probe-local reflector radius (a reflector beyond this can't bend a local probe)
+ * @param {number} rayCount rays to shoot (more = finer reflector coverage)
+ * @param {Float32Array} outLobes destination, ≥ MAX_LOBES·LOBE_STRIDE floats
+ * @returns {number} number of lobes written
+ */
+export function bakeProbeReflectors(index, x, y, z, radius, rayCount, outLobes) {
+    let nClusters = 0;
+
+    for (let i = 0; i < rayCount; i++) {
+        sphere_fibonacci_point(FIB, 0, i, rayCount);
+
+        RAY.setOrigin(x, y, z);
+        RAY.setDirection(FIB[0], FIB[1], FIB[2]);
+        RAY.tMax = radius;
+
+        if (!index.closestHit(RAY, HIT)) {
+            continue; // open in this direction within the local radius
+        }
+
+        const nx = HIT.normal[0], ny = HIT.normal[1], nz = HIT.normal[2];
+        const a = HIT.material.absorption;
+        const r0 = 1 - a[0], r1 = 1 - a[1], r2 = 1 - a[2]; // per-band reflectivity
+
+        // assign to the first cluster whose mean normal agrees within CLUSTER_COS, else open a new one
+        let c = -1;
+        for (let k = 0; k < nClusters; k++) {
+            const sx = C_NX[k], sy = C_NY[k], sz = C_NZ[k];
+            const slen = Math.sqrt(sx * sx + sy * sy + sz * sz);
+            if (slen > 0 && (nx * sx + ny * sy + nz * sz) / slen > CLUSTER_COS) {
+                c = k;
+                break;
+            }
+        }
+        if (c === -1) {
+            if (nClusters >= MAX_LOBES) {
+                continue; // cluster budget exhausted — drop the extra reflector
+            }
+            c = nClusters++;
+            C_NX[c] = 0; C_NY[c] = 0; C_NZ[c] = 0;
+            C_RHO[c * 3] = 0; C_RHO[c * 3 + 1] = 0; C_RHO[c * 3 + 2] = 0;
+            C_COUNT[c] = 0;
+        }
+
+        C_NX[c] += nx; C_NY[c] += ny; C_NZ[c] += nz;
+        C_RHO[c * 3] += r0; C_RHO[c * 3 + 1] += r1; C_RHO[c * 3 + 2] += r2;
+        C_COUNT[c]++;
+    }
+
+    // finalize each cluster into a lobe: unit mean normal + mean reflectivity
+    for (let k = 0; k < nClusters; k++) {
+        const cnt = C_COUNT[k];
+        const sx = C_NX[k], sy = C_NY[k], sz = C_NZ[k];
+        const slen = Math.sqrt(sx * sx + sy * sy + sz * sz);
+        const inv = slen > 0 ? 1 / slen : 0;
+
+        const b = k * LOBE_STRIDE;
+        outLobes[b] = sx * inv;
+        outLobes[b + 1] = sy * inv;
+        outLobes[b + 2] = sz * inv;
+        outLobes[b + 3] = LOBE_LAMBDA;
+        outLobes[b + 4] = C_RHO[k * 3] / cnt;
+        outLobes[b + 5] = C_RHO[k * 3 + 1] / cnt;
+        outLobes[b + 6] = C_RHO[k * 3 + 2] / cnt;
+    }
+
+    return nClusters;
+}
+
+export { MAX_LOBES };

package/src/engine/sound/simulation/probe/bakeReverbBands.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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: AcousticOccluderIndex, x: number, y: number, z: number, rayCount: number, random: () => number, outBands: Float32Array, outDirections: Float32Array): void;
+//# sourceMappingURL=bakeReverbBands.d.ts.map

package/src/engine/sound/simulation/probe/bakeReverbBands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bakeReverbBands.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeReverbBands.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,iEARW,MAAM,KACN,MAAM,KACN,MAAM,YACN,MAAM,gBACK,MAAM,YACjB,YAAY,iBACZ,YAAY,QA2DtB"}

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

@@ -0,0 +1,114 @@
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+import { v3_matrix3_rotate } from "../../../../core/geom/vec3/v3_matrix3_rotate.js";
+import { v3_orthonormal_matrix_from_normal } from "../../../../core/geom/vec3/v3_orthonormal_matrix_from_normal.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
+    const rz = 2 * random() - 1;
+    const ra = 2 * Math.PI * random();
+    const rr = Math.sqrt(Math.max(0, 1 - rz * rz));
+
+    v3_orthonormal_matrix_from_normal(ROTATION, 0, rr * Math.cos(ra), rr * Math.sin(ra), rz);
+
+    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.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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: AcousticProbeField, index: AcousticOccluderIndex, portals?: ArrayLike<number>, minSpacing?: number): AcousticProbeField;
+/**
+ * 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: AcousticProbeField, sourceX: number, sourceY: number, sourceZ: number, listenerX: number, listenerY: number, listenerZ: number): {
+    x: number;
+    y: number;
+    z: number;
+}[] | null;
+//# sourceMappingURL=bakeVisibility.d.ts.map

package/src/engine/sound/simulation/probe/bakeVisibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bakeVisibility.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/bakeVisibility.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uGAJW,UAAU,MAAM,CAAC,eACjB,MAAM,sBAiHhB;AAED;;;;;;;;;;;;;;GAcG;AACH,qEARW,MAAM,WACN,MAAM,WACN,MAAM,aACN,MAAM,aACN,MAAM,aACN,MAAM,GACJ;IAAC,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAC;IAAA,CAAC,EAAC,MAAM,CAAA;CAAC,EAAE,GAAC,IAAI,CAiB/C"}