@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,169 +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;
-}
+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.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 { 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 probe position x
- * @param {number} y probe position y
- * @param {number} z probe position z
- * @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 };
+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 probe position x
+ * @param {number} y probe position y
+ * @param {number} z probe position z
+ * @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 };