@woosh/meep-engine 2.163.11 → 2.164.0

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

@@ -0,0 +1,143 @@
+import { line3_compute_segment_point_distance_sqr } from "../../../../core/geom/3d/line/line3_compute_segment_point_distance_sqr.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// Gather neighbours of a portal within this × minSpacing — far enough to reach probes on BOTH sides of a wall
+// opening (matches the bridge search radius).
+const DEFAULT_NEIGHBOR_RADIUS_FACTOR = 2.5;
+// Cap the per-portal neighbour set so the pairwise visibility test stays O(N²) with small N.
+const DEFAULT_MAX_NEIGHBORS = 12;
+// A chord "threads the opening" if it passes within this × the throat clearance of the portal — so a wide arch
+// admits a wide fan of chords and a tight door a narrow one (the directionality the symmetry needs).
+const DEFAULT_BIAS_FACTOR = 2.0;
+// …but never tighter than this × minSpacing, so even a probe that landed slightly off the true throat still
+// fans enough chords to break the single-funnel asymmetry.
+const BIAS_FLOOR_FACTOR = 0.5;
+
+/**
+ * Densify the visibility graph AROUND portal probes so routing through an opening is symmetric instead of
+ * funnelled through one off-centre probe. The cover places probes by clearance, with no notion of openings, so
+ * the single Delaunay/bridge edge that survives across a narrow doorway lands on whichever probe happened to
+ * be nearest — and every cross-opening path detours through it, giving a listener on the left and one on the
+ * right very different routed lengths. This adds the missing cross-opening CHORDS: for each portal, the
+ * mutually-visible pairs among its nearest neighbours whose connecting line threads PAST the portal throat
+ * (small point-to-segment distance — the user's bias). A fan of such chords gives Dijkstra direct, mirror-
+ * symmetric routes through the opening; the residual asymmetry drops to the probe spacing.
+ *
+ * Adds only edges to the existing edge set (deduped) — no new runtime object, nothing to serialize; the portal
+ * concept lives only during the bake. Run as a stage of {@link bakeVisibility}, before the CSR is assembled.
+ *
+ * Pure geometry; offline (no WebAudio).
+ *
+ * @param {import("./AcousticProbeField.js").AcousticProbeField} field
+ * @param {import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex} index the acoustic scene
+ * @param {ArrayLike<number>} portals probe indices of the portal throats (the pre-seeded probes)
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the edges already in the graph (for dedup)
+ * @param {number} minSpacing the probe spacing hint
+ * @param {{neighborRadiusFactor?: number, maxNeighbors?: number, biasFactor?: number}} [options]
+ * @returns {{a: number[], b: number[]}} the cross-opening chord edges to add (possibly empty)
+ */
+export function probe_densify_portals(field, index, portals, edges, minSpacing, options = {}) {
+    const newA = [];
+    const newB = [];
+
+    if (portals.length === 0) {
+        return { a: newA, b: newB };
+    }
+
+    const radius = (options.neighborRadiusFactor ?? DEFAULT_NEIGHBOR_RADIUS_FACTOR) * minSpacing;
+    const maxNeighbors = options.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
+    const biasFactor = options.biasFactor ?? DEFAULT_BIAS_FACTOR;
+    const biasFloor = BIAS_FLOOR_FACTOR * minSpacing;
+    const maxDistance = minSpacing * 4;
+
+    const n = field.size;
+
+    // existing + newly-added edges, keyed undirected, so a chord the base graph already has is not duplicated
+    const seen = new Set();
+    for (let i = 0; i < edges.a.length; i++) {
+        seen.add(edgeKey(edges.a[i], edges.b[i], n));
+    }
+
+    const hits = []; // probesWithinRadius scratch (auto-grows; valid length is the returned count)
+
+    for (let pi = 0; pi < portals.length; pi++) {
+        const p = portals[pi];
+        const px = field.probeX(p), py = field.probeY(p), pz = field.probeZ(p);
+
+        // how far a chord may pass from the throat and still count as threading this opening
+        const throat = index.signedDistanceAt(px, py, pz, maxDistance);
+        let bias = biasFactor * throat;
+        if (bias < biasFloor) {
+            bias = biasFloor;
+        }
+        const bias2 = bias * bias;
+
+        const count = field.probesWithinRadius(hits, 0, px, py, pz, radius);
+        const neighbours = nearestVisible(field, index, p, px, py, pz, hits, count, maxNeighbors);
+
+        for (let a = 0; a < neighbours.length; a++) {
+            const i = neighbours[a];
+            const ix = field.probeX(i), iy = field.probeY(i), iz = field.probeZ(i);
+
+            for (let b = a + 1; b < neighbours.length; b++) {
+                const j = neighbours[b];
+
+                const key = edgeKey(i, j, n);
+                if (seen.has(key)) {
+                    continue;
+                }
+
+                const jx = field.probeX(j), jy = field.probeY(j), jz = field.probeZ(j);
+
+                // bias: only chords that thread PAST the portal throat (the cross-opening ones); two probes on
+                // the same side that happen to see each other in open air pass far from the throat and are skipped
+                if (line3_compute_segment_point_distance_sqr(ix, iy, iz, jx, jy, jz, px, py, pz) > bias2) {
+                    continue;
+                }
+
+                if (!probe_edge_visible(field, index, i, j)) {
+                    continue; // a wall blocks it
+                }
+
+                seen.add(key);
+                newA.push(i);
+                newB.push(j);
+            }
+        }
+    }
+
+    return { a: newA, b: newB };
+}
+
+/**
+ * The up-to-`max` nearest probes to portal `p` that are VISIBLE from it. The bias gate alone could admit a
+ * chord between two same-side probes that straddle the throat line; requiring each endpoint to see the portal
+ * keeps the fan to probes that genuinely flank the opening.
+ * @returns {number[]} probe indices, nearest first
+ */
+function nearestVisible(field, index, p, px, py, pz, hits, count, max) {
+    const found = [];
+    for (let h = 0; h < count; h++) {
+        const j = hits[h];
+        if (j === p) {
+            continue;
+        }
+        if (!probe_edge_visible(field, index, p, j)) {
+            continue;
+        }
+        const dx = field.probeX(j) - px, dy = field.probeY(j) - py, dz = field.probeZ(j) - pz;
+        found.push({ j, d: dx * dx + dy * dy + dz * dz });
+    }
+
+    found.sort((a, b) => a.d - b.d);
+    if (found.length > max) {
+        found.length = max;
+    }
+
+    return found.map((o) => o.j);
+}
+
+/** Undirected edge key (order-independent). */
+function edgeKey(a, b, n) {
+    return a < b ? a * n + b : b * n + a;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Detect acoustic PORTALS — the throats of openings (door frames, windows, arches) — over a probe field's
+ * positions. A portal is where a clear line of sight between two probes threads a CONSTRICTION: the two probes
+ * sit in open rooms (high clearance) but the line between them squeezes through a narrow gap that is bounded by
+ * solid on opposing sides (a doorway's jambs, a window's frame).
+ *
+ * Candidates are every nearby MUTUALLY-VISIBLE probe pair (a BVH radius gather), NOT just the baked visibility
+ * edges — so an opening is found whether or not the sparse cover happened to drop an edge across it. Each
+ * candidate is screened three ways:
+ *  - **constriction** — the throat (narrowest point, by the exact union SDF — the cover grid is far too coarse
+ *    to resolve a doorway) is markedly narrower than the more-open room;
+ *  - **aperture** — the throat is bounded by solid on BOTH sides of some axis perpendicular to the passage
+ *    ({@link throatIsAperture}); this rejects a one-sided graze past a pillar and an open region boundary,
+ *    which dip the SDF without being a coupling between two volumes;
+ *  - **dedup** — collapse the many crossings of one opening to its single widest (most central) throat.
+ *
+ * The throats are fed back as PRE-SEEDED probes to a re-cover ({@link probe_place_sdf_cover} `predefined`) so
+ * they carve the SDF and become first-class probes, and seed {@link probe_densify_portals}. Pure geometry;
+ * offline (no WebAudio). Deterministic for a given field + scene.
+ *
+ * @param {import("./AcousticProbeField.js").AcousticProbeField} field the probe positions to detect over
+ * @param {import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex} index the acoustic scene
+ * @param {number} minSpacing the probe spacing hint (scales the gather radius, opening-width floor, dedup)
+ * @param {{constrictionFactor?: number, portalFloorRatio?: number, neighborRadiusFactor?: number}} [options]
+ * @returns {number[]} flat throat positions `[x,y,z, …]`, one per detected opening (possibly empty)
+ */
+export function probe_detect_portals(field: import("./AcousticProbeField.js").AcousticProbeField, index: import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex, minSpacing: number, options?: {
+    constrictionFactor?: number;
+    portalFloorRatio?: number;
+    neighborRadiusFactor?: number;
+}): number[];
+//# sourceMappingURL=probe_detect_portals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_detect_portals.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_detect_portals.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,4CANW,OAAO,yBAAyB,EAAE,kBAAkB,SACpD,OAAO,kCAAkC,EAAE,qBAAqB,cAChE,MAAM;yBACgB,MAAM;uBAAqB,MAAM;2BAAyB,MAAM;IACpF,MAAM,EAAE,CAyEpB"}

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

@@ -0,0 +1,196 @@
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// Interior sample points along each candidate pair (the throat is the narrowest of these).
+const EDGE_SAMPLES = 6;
+// Gather candidate partners within this × minSpacing. The cover places probes at the SPARSEST up to
+// `maxSpacing` (= sparsenessRatio·minSpacing, default 4) apart, so the two probes flanking an opening — placed
+// at their room interiors, away from the low-clearance throat — can be a full maxSpacing apart. The gather
+// must span that, or a wide room's doorway is never tested. (The constriction + aperture screens reject the
+// extra far/in-room pairs this admits.)
+const DEFAULT_NEIGHBOR_RADIUS_FACTOR = 4;
+// A throat counts as a portal only if it is at least this much narrower than the MORE-open of its two rooms —
+// a real dip, not a flat open line. Loose on purpose: the genuine selectivity is the APERTURE gate (bounded on
+// opposing sides), so this only has to reject lines that never squeeze. (A doorway in a low room barely dips —
+// e.g. a 0.7 m jamb throat vs a 1.1 m floor-limited room is ratio 0.64 — so the bar must sit above that.)
+const DEFAULT_CONSTRICTION_FACTOR = 0.8;
+// …and only if the throat is at least this fraction of `minSpacing` wide (an SDF/half-width floor) — a
+// passable opening, not a polygon crack the visibility ray happened to thread.
+const DEFAULT_PORTAL_FLOOR_RATIO = 0.1;
+// Two throats within this × minSpacing are the same opening — keep the widest (most central) crossing.
+const DEDUP_RADIUS_FACTOR = 1.0;
+// An opening up to this × minSpacing wide is bounded within reach — how far an aperture ray looks for the far
+// jamb / opposing wall.
+const APERTURE_REACH_FACTOR = 2;
+// module-static scratch for the aperture rays
+const APERTURE_RAY = new Ray3();
+
+/**
+ * Detect acoustic PORTALS — the throats of openings (door frames, windows, arches) — over a probe field's
+ * positions. A portal is where a clear line of sight between two probes threads a CONSTRICTION: the two probes
+ * sit in open rooms (high clearance) but the line between them squeezes through a narrow gap that is bounded by
+ * solid on opposing sides (a doorway's jambs, a window's frame).
+ *
+ * Candidates are every nearby MUTUALLY-VISIBLE probe pair (a BVH radius gather), NOT just the baked visibility
+ * edges — so an opening is found whether or not the sparse cover happened to drop an edge across it. Each
+ * candidate is screened three ways:
+ *  - **constriction** — the throat (narrowest point, by the exact union SDF — the cover grid is far too coarse
+ *    to resolve a doorway) is markedly narrower than the more-open room;
+ *  - **aperture** — the throat is bounded by solid on BOTH sides of some axis perpendicular to the passage
+ *    ({@link throatIsAperture}); this rejects a one-sided graze past a pillar and an open region boundary,
+ *    which dip the SDF without being a coupling between two volumes;
+ *  - **dedup** — collapse the many crossings of one opening to its single widest (most central) throat.
+ *
+ * The throats are fed back as PRE-SEEDED probes to a re-cover ({@link probe_place_sdf_cover} `predefined`) so
+ * they carve the SDF and become first-class probes, and seed {@link probe_densify_portals}. Pure geometry;
+ * offline (no WebAudio). Deterministic for a given field + scene.
+ *
+ * @param {import("./AcousticProbeField.js").AcousticProbeField} field the probe positions to detect over
+ * @param {import("../core/AcousticOccluderIndex.js").AcousticOccluderIndex} index the acoustic scene
+ * @param {number} minSpacing the probe spacing hint (scales the gather radius, opening-width floor, dedup)
+ * @param {{constrictionFactor?: number, portalFloorRatio?: number, neighborRadiusFactor?: number}} [options]
+ * @returns {number[]} flat throat positions `[x,y,z, …]`, one per detected opening (possibly empty)
+ */
+export function probe_detect_portals(field, index, minSpacing, options = {}) {
+    const constrictionFactor = options.constrictionFactor ?? DEFAULT_CONSTRICTION_FACTOR;
+    const portalFloor = (options.portalFloorRatio ?? DEFAULT_PORTAL_FLOOR_RATIO) * minSpacing;
+    const radius = (options.neighborRadiusFactor ?? DEFAULT_NEIGHBOR_RADIUS_FACTOR) * minSpacing;
+    const maxDistance = minSpacing * 4; // SDF query cutoff (matches the cover's sparseness ceiling)
+
+    const n = field.size;
+
+    // candidate throats, then greedily deduped widest-first into one portal per opening
+    const candX = [];
+    const candY = [];
+    const candZ = [];
+    const candWidth = []; // the throat clearance (SDF) — wider = more central crossing
+
+    const hits = []; // probesWithinRadius scratch (auto-grows; valid length is the returned count)
+
+    for (let a = 0; a < n; a++) {
+        const ax = field.probeX(a), ay = field.probeY(a), az = field.probeZ(a);
+        const sdfA = index.signedDistanceAt(ax, ay, az, maxDistance);
+
+        const count = field.probesWithinRadius(hits, 0, ax, ay, az, radius);
+
+        for (let h = 0; h < count; h++) {
+            const b = hits[h];
+            if (b <= a) {
+                continue; // each unordered pair once
+            }
+
+            if (!probe_edge_visible(field, index, a, b)) {
+                continue; // a wall blocks it — the pair does not couple through an opening
+            }
+
+            const bx = field.probeX(b), by = field.probeY(b), bz = field.probeZ(b);
+            const sdfB = index.signedDistanceAt(bx, by, bz, maxDistance);
+
+            // the narrowest INTERIOR point of the segment = the throat
+            let minS = Infinity, mt = 0;
+            for (let s = 1; s <= EDGE_SAMPLES; s++) {
+                const t = s / (EDGE_SAMPLES + 1);
+                const sdfP = index.signedDistanceAt(
+                    ax + (bx - ax) * t, ay + (by - ay) * t, az + (bz - az) * t, maxDistance);
+                if (sdfP < minS) {
+                    minS = sdfP;
+                    mt = t;
+                }
+            }
+
+            // …narrower than the MORE-open of the two rooms. A doorway onto a low/tight room barely dips
+            // against THAT room's (often unrelated, e.g. floor-limited) clearance, so comparing against the
+            // less-open side would reject it; the aperture gate below is what rejects genuine non-openings.
+            const roomClearance = sdfA > sdfB ? sdfA : sdfB;
+            if (minS <= portalFloor || minS >= constrictionFactor * roomClearance) {
+                continue;
+            }
+
+            const tx = ax + (bx - ax) * mt, ty = ay + (by - ay) * mt, tz = az + (bz - az) * mt;
+
+            const ex = bx - ax, ey = by - ay, ez = bz - az;
+            const elen = Math.sqrt(ex * ex + ey * ey + ez * ez);
+            if (elen === 0 || !throatIsAperture(index, tx, ty, tz, ex / elen, ey / elen, ez / elen, minSpacing)) {
+                continue;
+            }
+
+            candX.push(tx);
+            candY.push(ty);
+            candZ.push(tz);
+            candWidth.push(minS);
+        }
+    }
+
+    return dedupeWidestFirst(candX, candY, candZ, candWidth, DEDUP_RADIUS_FACTOR * minSpacing);
+}
+
+/**
+ * Collapse candidate throats that belong to the same opening (within `radius`) to one portal each, keeping the
+ * WIDEST (most central) crossing of each cluster. Greedy: sort by width descending, accept a candidate only if
+ * no already-accepted portal is within `radius`.
+ * @returns {number[]} flat accepted positions `[x,y,z, …]`
+ */
+function dedupeWidestFirst(candX, candY, candZ, candWidth, radius) {
+    const order = candWidth.map((_, i) => i).sort((a, b) => candWidth[b] - candWidth[a]);
+    const r2 = radius * radius;
+
+    const out = [];
+    for (let o = 0; o < order.length; o++) {
+        const i = order[o];
+        const x = candX[i], y = candY[i], z = candZ[i];
+
+        let merged = false;
+        for (let k = 0; k < out.length; k += 3) {
+            const dx = out[k] - x, dy = out[k + 1] - y, dz = out[k + 2] - z;
+            if (dx * dx + dy * dy + dz * dz <= r2) {
+                merged = true;
+                break;
+            }
+        }
+
+        if (!merged) {
+            out.push(x, y, z);
+        }
+    }
+
+    return out;
+}
+
+/**
+ * Whether the throat `(tx,ty,tz)` is a genuine APERTURE: bounded by solid on BOTH sides of the HORIZONTAL axis
+ * perpendicular to the passage `(ex,ey,ez)` — the doorway's jambs / the window's frame sides. A one-sided graze
+ * past a pillar or wall stub is bounded on only ONE side of that axis; an open region boundary on neither —
+ * both dip the SDF but are not couplings between two volumes, so they are rejected.
+ *
+ * Only the horizontal cross-axis discriminates: the vertical axis is trivially bounded by the floor and ceiling
+ * in any enclosed room shorter than 2·reach, so testing it would rescue every indoor candidate (a graze past a
+ * pillar would pass on the floor/ceiling alone). Sound sources and listeners are at comparable heights, so the
+ * passage is near-horizontal and its jambs are the horizontal cross-axis.
+ */
+function throatIsAperture(index, tx, ty, tz, ex, ey, ez, minSpacing) {
+    const reach = APERTURE_REACH_FACTOR * minSpacing;
+
+    // the horizontal axis perpendicular to the passage = ê × world-up (the jamb axis). For a near-vertical
+    // passage ê ∥ up, so swap the reference to keep the cross product well-conditioned (it stays horizontal).
+    let rx = 0, ry = 1, rz = 0;
+    if (Math.abs(ey) > 0.9) {
+        rx = 1; ry = 0; rz = 0;
+    }
+    let ux = ey * rz - ez * ry, uy = ez * rx - ex * rz, uz = ex * ry - ey * rx;
+    const ul = Math.sqrt(ux * ux + uy * uy + uz * uz);
+    ux /= ul; uy /= ul; uz /= ul;
+
+    return boundedBothSides(index, tx, ty, tz, ux, uy, uz, reach);
+}
+
+function boundedBothSides(index, ox, oy, oz, dx, dy, dz, reach) {
+    return solidWithin(index, ox, oy, oz, dx, dy, dz, reach)
+        && solidWithin(index, ox, oy, oz, -dx, -dy, -dz, reach);
+}
+
+function solidWithin(index, ox, oy, oz, dx, dy, dz, reach) {
+    APERTURE_RAY.setOrigin(ox, oy, oz);
+    APERTURE_RAY.setDirection(dx, dy, dz);
+    APERTURE_RAY.tMax = reach;
+    return index.anyHit(APERTURE_RAY);
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Whether probes `a` and `b` have clear line of sight in the current `index` — a single shadow ray along the
+ * segment between them, true if no occluder blocks it. This is the one visibility test shared by the offline
+ * bake ({@link bakeVisibility}) and the runtime {@link ProbeVisibilityRecheck}, so they agree exactly.
+ * Coincident probes are trivially "visible" (a zero-length segment blocks nothing). Allocation-free; no
+ * WebAudio.
+ *
+ * @param {AcousticProbeField} probeField
+ * @param {AcousticOccluderIndex} index the acoustic scene (live geometry — a door that has since closed will
+ *        block the ray even though the baked graph still has the edge)
+ * @param {number} a probe index
+ * @param {number} b probe index
+ * @returns {boolean}
+ */
+export function probe_edge_visible(probeField: AcousticProbeField, index: AcousticOccluderIndex, a: number, b: number): boolean;
+//# sourceMappingURL=probe_edge_visible.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_edge_visible.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_edge_visible.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,oGAJW,MAAM,KACN,MAAM,GACJ,OAAO,CAuBnB"}

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

@@ -0,0 +1,41 @@
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+
+// module-static scratch — the shadow ray between two probes (allocation-free)
+const RAY = new Ray3();
+
+/**
+ * Whether probes `a` and `b` have clear line of sight in the current `index` — a single shadow ray along the
+ * segment between them, true if no occluder blocks it. This is the one visibility test shared by the offline
+ * bake ({@link bakeVisibility}) and the runtime {@link ProbeVisibilityRecheck}, so they agree exactly.
+ * Coincident probes are trivially "visible" (a zero-length segment blocks nothing). Allocation-free; no
+ * WebAudio.
+ *
+ * @param {AcousticProbeField} probeField
+ * @param {AcousticOccluderIndex} index the acoustic scene (live geometry — a door that has since closed will
+ *        block the ray even though the baked graph still has the edge)
+ * @param {number} a probe index
+ * @param {number} b probe index
+ * @returns {boolean}
+ */
+export function probe_edge_visible(probeField, index, a, b) {
+    const ax = probeField.probeX(a);
+    const ay = probeField.probeY(a);
+    const az = probeField.probeZ(a);
+
+    const dx = probeField.probeX(b) - ax;
+    const dy = probeField.probeY(b) - ay;
+    const dz = probeField.probeZ(b) - az;
+
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (distance === 0) {
+        return true;
+    }
+
+    const inv = 1 / distance;
+    RAY.setOrigin(ax, ay, az);
+    RAY.setDirection(dx * inv, dy * inv, dz * inv);
+    RAY.tMax = distance;
+
+    return !index.anyHit(RAY);
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Place acoustic probes over a prebuilt SDF grid ({@link build_sdf_grid}) with a maximal-empty-sphere greedy
+ * cover — adaptive density: one big-radius probe fills an open hall, a chain of small-radius probes lines a
+ * corridor, and nothing is placed inside solid. Ported from the reference GI placer
+ * (`lpv_generate_probe_locations2`) with the acoustic spacing model.
+ *
+ * Take the voxels in open air (`SDF > clearanceFloor`), sort by openness descending; greedily take the
+ * most-open voxel, nudge it to the local SDF maximum (most-open sub-voxel point), emit a probe there, and
+ * claim every voxel within its empty-sphere radius so no second probe lands in the same open region. The
+ * radius is floored at `minSpacing` and capped at `maxSpacing` — so the INITIAL cover never packs probes
+ * closer than the hint (connectivity refinement does that later) and never sparser than the ceiling.
+ *
+ * PRE-SEEDED PROBES: `options.predefined` (a flat `[x,y,z, …]` placed by an earlier stage — e.g. the portal
+ * throats from {@link probe_detect_portals}, which sit in narrow openings the cover would otherwise skip as
+ * sub-clearance) are emitted FIRST and carve their empty spheres into the grid, so the greedy cover never
+ * packs a redundant probe on top of one. They lead the returned list (indices `[0, K)`), so a caller can
+ * recover them by count.
+ *
+ * Pure geometry; offline (no WebAudio); deterministic for a given grid.
+ *
+ * @param {import("./probe_sdf_grid.js").SdfGrid} grid prebuilt SDF grid
+ * @param {{predefined?: ArrayLike<number>}} [options]
+ * @returns {number[]} flat probe positions `[x,y,z, …]`, all in open air; predefined first
+ */
+export function probe_place_sdf_cover(grid: import("./probe_sdf_grid.js").SdfGrid, options?: {
+    predefined?: ArrayLike<number>;
+}): number[];
+//# sourceMappingURL=probe_place_sdf_cover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_place_sdf_cover.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_place_sdf_cover.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,4CAJW,OAAO,qBAAqB,EAAE,OAAO;iBACvB,UAAU,MAAM,CAAC;IAC7B,MAAM,EAAE,CAwDpB"}

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

@@ -0,0 +1,82 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import { grid_claim_sphere, grid_local_maximum, grid_sample_world, grid_voxel_to_world } from "./probe_sdf_grid.js";
+
+/**
+ * Place acoustic probes over a prebuilt SDF grid ({@link build_sdf_grid}) with a maximal-empty-sphere greedy
+ * cover — adaptive density: one big-radius probe fills an open hall, a chain of small-radius probes lines a
+ * corridor, and nothing is placed inside solid. Ported from the reference GI placer
+ * (`lpv_generate_probe_locations2`) with the acoustic spacing model.
+ *
+ * Take the voxels in open air (`SDF > clearanceFloor`), sort by openness descending; greedily take the
+ * most-open voxel, nudge it to the local SDF maximum (most-open sub-voxel point), emit a probe there, and
+ * claim every voxel within its empty-sphere radius so no second probe lands in the same open region. The
+ * radius is floored at `minSpacing` and capped at `maxSpacing` — so the INITIAL cover never packs probes
+ * closer than the hint (connectivity refinement does that later) and never sparser than the ceiling.
+ *
+ * PRE-SEEDED PROBES: `options.predefined` (a flat `[x,y,z, …]` placed by an earlier stage — e.g. the portal
+ * throats from {@link probe_detect_portals}, which sit in narrow openings the cover would otherwise skip as
+ * sub-clearance) are emitted FIRST and carve their empty spheres into the grid, so the greedy cover never
+ * packs a redundant probe on top of one. They lead the returned list (indices `[0, K)`), so a caller can
+ * recover them by count.
+ *
+ * Pure geometry; offline (no WebAudio); deterministic for a given grid.
+ *
+ * @param {import("./probe_sdf_grid.js").SdfGrid} grid prebuilt SDF grid
+ * @param {{predefined?: ArrayLike<number>}} [options]
+ * @returns {number[]} flat probe positions `[x,y,z, …]`, all in open air; predefined first
+ */
+export function probe_place_sdf_cover(grid, options = {}) {
+    const { rx, ry, strideZ, total, minSpacing, maxSpacing, clearanceFloor } = grid;
+    const sdf = grid.sdf;
+
+    const claimed = new Uint8Array(total); // voxels already inside a placed probe's empty sphere
+    const positions = [];
+    const ascended = [0, 0, 0];
+    const world = [0, 0, 0];
+
+    // Pre-seeded probes lead, and carve their empty spheres so the greedy cover fills only what they leave.
+    // Their throat clearance clamps to `minSpacing` (a doorway is narrower than the hint), so a portal claims
+    // a modest sphere — enough that the cover won't drop a duplicate on it, not so much it leaves a gap.
+    const predefined = options.predefined;
+    if (predefined !== undefined) {
+        for (let i = 0; i + 2 < predefined.length; i += 3) {
+            const px = predefined[i], py = predefined[i + 1], pz = predefined[i + 2];
+            positions.push(px, py, pz);
+            const radius = clamp(grid_sample_world(grid, px, py, pz), minSpacing, maxSpacing);
+            grid_claim_sphere(claimed, grid, px, py, pz, radius);
+        }
+    }
+
+    // candidate voxels = in open air, off any surface; most-open first
+    const candidates = [];
+    for (let i = 0; i < total; i++) {
+        if (sdf[i] > clearanceFloor) {
+            candidates.push(i);
+        }
+    }
+    candidates.sort((a, b) => sdf[b] - sdf[a]);
+
+    for (let c = 0; c < candidates.length; c++) {
+        const voxelIndex = candidates[c];
+        if (claimed[voxelIndex] === 1) {
+            continue; // swept up by an earlier, more-open probe (or a pre-seeded portal)
+        }
+
+        const vx = voxelIndex % rx;
+        const vy = Math.floor(voxelIndex / rx) % ry;
+        const vz = Math.floor(voxelIndex / strideZ);
+
+        // nudge to the local SDF maximum (most-open sub-voxel point)
+        grid_local_maximum(ascended, grid, vx, vy, vz);
+        grid_voxel_to_world(grid, world, ascended[0], ascended[1], ascended[2]);
+
+        // empty-sphere radius: the clearance, floored at the hint and capped at the ceiling
+        const radius = clamp(sdf[voxelIndex], minSpacing, maxSpacing);
+
+        grid_claim_sphere(claimed, grid, world[0], world[1], world[2], radius);
+
+        positions.push(world[0], world[1], world[2]);
+    }
+
+    return positions;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Connectivity refinement — the acoustic stage the reference GI placer lacks. After the SDF cover + a
+ * provisional {@link bakeVisibility}, the graph may have islands a bend/throat separates even though sound
+ * routes between them: `bakeVisibility` only links probes with STRAIGHT line of sight, so a corridor that
+ * bends sharper than the cover's spacing leaves its two ends in different components. This inserts the
+ * minimum extra probes so a chain of mutually-visible probes spans every such path — "ray bounces between
+ * probes", as a bounded greedy walk through open air.
+ *
+ * For each pair of nearby components (within `corridorReachFactor · minSpacing`), it walks from one side
+ * toward the other: at each step it samples open-air waypoints around the segment (a Fibonacci sphere × a
+ * few radii), keeps those visible from the current point, and steps to the one nearest the target — until a
+ * waypoint sees the target (chain complete) or no progress is possible (give up — a genuinely sealed wall
+ * stays disconnected, correctly). It never subdivides below `minSpacing / maxRefineFactor`. The waypoints
+ * are returned for the caller to append; the FINAL `bakeVisibility` then links them.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {AcousticProbeField} field cover probes WITH a baked visibility graph (defines the components)
+ * @param {number} minSpacing the placement spacing hint
+ * @param {{maxRefineFactor?: number, corridorReachFactor?: number}} [options]
+ * @returns {number[]} flat extra probe positions `[x,y,z, …]` (possibly empty)
+ */
+export function probe_refine_connectivity(index: AcousticOccluderIndex, field: AcousticProbeField, minSpacing: number, options?: {
+    maxRefineFactor?: number;
+    corridorReachFactor?: number;
+}): number[];
+//# sourceMappingURL=probe_refine_connectivity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_refine_connectivity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_refine_connectivity.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+GAJW,MAAM;sBACa,MAAM;0BAAwB,MAAM;IACrD,MAAM,EAAE,CAiDpB"}