@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -0,0 +1,181 @@
+import { uf_find, uf_init, uf_union } from "../../../../core/collection/union-find/union_find.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { sphere_fibonacci_point } from "../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
+
+// Connectivity refinement may place probes finer than the spacing hint, down to minSpacing / this factor.
+const DEFAULT_MAX_REFINE_FACTOR = 4;
+// Two components are candidates to thread only if probes come within this multiple of minSpacing — beyond it
+// we assume they're genuinely sealed (a closed wall, not a bend). Also the SDF / waypoint search radius.
+const DEFAULT_CORRIDOR_REACH_FACTOR = 4;
+// Per-step waypoint search: directions on a Fibonacci sphere × these fractions of the segment length.
+const SAMPLE_DIRECTIONS = 24;
+const SAMPLE_RADII = [0.5, 0.25, 0.125];
+// Bound the greedy walk so a hopeless gap can't recurse forever.
+const MAX_THREAD_DEPTH = 12;
+
+// module-static scratch
+const RAY = new Ray3();
+const DIR = [0, 0, 0];
+
+/**
+ * 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, field, minSpacing, options = {}) {
+    const maxRefineFactor = options.maxRefineFactor ?? DEFAULT_MAX_REFINE_FACTOR;
+    const reach = (options.corridorReachFactor ?? DEFAULT_CORRIDOR_REACH_FACTOR) * minSpacing;
+    const floor = minSpacing / maxRefineFactor;
+
+    const n = field.size;
+    const graph = field.visibilityGraph;
+
+    // connected components of the provisional visibility graph
+    const parent = new Uint32Array(n);
+    uf_init(parent, n);
+    for (let v = 0; v < n; v++) {
+        for (let k = graph.edge_addresses[v]; k < graph.edge_addresses[v + 1]; k++) {
+            uf_union(parent, v, graph.adjacency[k]);
+        }
+    }
+
+    const waypoints = [];
+    const hits = [];
+
+    for (let i = 0; i < n; i++) {
+        const ix = field.probeX(i), iy = field.probeY(i), iz = field.probeZ(i);
+
+        const count = field.probesWithinRadius(hits, 0, ix, iy, iz, reach);
+
+        for (let h = 0; h < count; h++) {
+            const j = hits[h];
+            if (j <= i) {
+                continue;
+            }
+            // re-read roots each time — an earlier successful thread may have merged these components, directly
+            // or transitively (so we don't thread a redundant chain across 3+ mutually-near components)
+            if (uf_find(parent, i) === uf_find(parent, j)) {
+                continue;
+            }
+
+            const chain = thread(index, ix, iy, iz, field.probeX(j), field.probeY(j), field.probeZ(j), floor, reach, 0);
+            if (chain !== null) {
+                uf_union(parent, i, j); // merge → later pairs across these now-connected components are skipped
+                for (let w = 0; w < chain.length; w++) {
+                    waypoints.push(chain[w]);
+                }
+            }
+        }
+    }
+
+    return waypoints;
+}
+
+/**
+ * Greedily walk from (ax,ay,az) toward (bx,by,bz) through open air, inserting waypoints, until a waypoint
+ * sees the target. Returns the flat waypoint list `[x,y,z, …]`, or `null` if no open chain was found.
+ */
+function thread(index, ax, ay, az, bx, by, bz, floor, reach, depth) {
+    if (segment_clear(index, ax, ay, az, bx, by, bz)) {
+        return []; // already mutually visible
+    }
+    if (depth >= MAX_THREAD_DEPTH) {
+        return null;
+    }
+
+    const w = open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach);
+    if (w === null) {
+        return null; // no visible open point makes progress → sealed
+    }
+
+    const dx = w[0] - ax, dy = w[1] - ay, dz = w[2] - az;
+    if (Math.sqrt(dx * dx + dy * dy + dz * dz) < floor) {
+        return null; // would need probes finer than the refine floor
+    }
+
+    const rest = thread(index, w[0], w[1], w[2], bx, by, bz, floor, reach, depth + 1);
+    if (rest === null) {
+        return null;
+    }
+
+    return [w[0], w[1], w[2], ...rest];
+}
+
+/**
+ * Among open-air points sampled around the (a→b) segment that are VISIBLE from `a`, return the one nearest
+ * `b` that makes progress (closer to `b` than `a` is), or `null`. Sampled on a Fibonacci sphere around the
+ * segment midpoint at a few fractions of the segment length, so both perpendicular detours (over a baffle)
+ * and along-segment steps are covered.
+ * @returns {number[]|null} `[x,y,z]` or null
+ */
+function open_waypoint_toward_target(index, ax, ay, az, bx, by, bz, reach) {
+    const mx = (ax + bx) * 0.5, my = (ay + by) * 0.5, mz = (az + bz) * 0.5;
+    const segLen = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
+
+    let best = null;
+    // must improve on a's own distance to b (strict progress → the walk terminates)
+    let bestDistB = Math.sqrt((bx - ax) * (bx - ax) + (by - ay) * (by - ay) + (bz - az) * (bz - az));
+
+    for (let d = 0; d < SAMPLE_DIRECTIONS; d++) {
+        sphere_fibonacci_point(DIR, 0, d, SAMPLE_DIRECTIONS);
+
+        for (let r = 0; r < SAMPLE_RADII.length; r++) {
+            const radius = segLen * SAMPLE_RADII[r];
+            const sx = mx + DIR[0] * radius;
+            const sy = my + DIR[1] * radius;
+            const sz = mz + DIR[2] * radius;
+
+            // must be in open air (clearance > a small margin so the reverb bake + visibility are valid)
+            if (index.signedDistanceAt(sx, sy, sz, reach) <= 1e-3) {
+                continue;
+            }
+
+            const distB = Math.sqrt((bx - sx) * (bx - sx) + (by - sy) * (by - sy) + (bz - sz) * (bz - sz));
+            if (distB >= bestDistB) {
+                continue; // no progress toward b
+            }
+
+            if (!segment_clear(index, ax, ay, az, sx, sy, sz)) {
+                continue; // a can't see this waypoint
+            }
+
+            bestDistB = distB;
+            best = best === null ? [sx, sy, sz] : best;
+            best[0] = sx; best[1] = sy; best[2] = sz;
+        }
+    }
+
+    return best;
+}
+
+/** Whether the open segment a→b is clear of occluders (one shadow ray; mirrors probe_edge_visible). */
+function segment_clear(index, ax, ay, az, bx, by, bz) {
+    const dx = bx - ax, dy = by - ay, dz = bz - az;
+    const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (d === 0) {
+        return true;
+    }
+
+    const inv = 1 / d;
+    RAY.setOrigin(ax, ay, az);
+    RAY.setDirection(dx * inv, dy * inv, dz * inv);
+    RAY.tMax = d;
+
+    return !index.anyHit(RAY);
+}

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

@@ -0,0 +1,100 @@
+/**
+ * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
+ * ({@link probe_place_sdf_cover}) and portal detection ({@link probe_detect_portals}) so the expensive
+ * {@link AcousticOccluderIndex#signedDistanceAt} sweep (up to 256³ queries) is paid once.
+ *
+ * @typedef {Object} SdfGrid
+ * @property {Float32Array} sdf per-voxel signed distance (world units), capped at `maxSpacing`
+ * @property {number} rx @property {number} ry @property {number} rz per-axis voxel resolution
+ * @property {number} strideZ `rx·ry` @property {number} total `strideZ·rz`
+ * @property {number} x0 @property {number} y0 @property {number} z0 region min corner
+ * @property {number} x1 @property {number} y1 @property {number} z1 region max corner
+ * @property {number} vsX @property {number} vsY @property {number} vsZ per-axis voxel size (0 if degenerate)
+ * @property {number} minSpacing @property {number} maxSpacing the spacing hint + sparseness ceiling
+ * @property {number} clearanceFloor a voxel above this SDF is "open air" (off any surface)
+ */
+/**
+ * Build a signed distance field on a voxel grid over `bounds` by sampling
+ * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
+ * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
+ * @param {number} minSpacing the probe spacing hint
+ * @param {number} [sparsenessRatio]
+ * @returns {SdfGrid}
+ */
+export function build_sdf_grid(index: AcousticOccluderIndex, bounds: number[], minSpacing: number, sparsenessRatio?: number): SdfGrid;
+/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
+export function grid_voxel_to_world(grid: any, out: any, fx: any, fy: any, fz: any): void;
+/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
+export function grid_sample_world(grid: any, x: any, y: any, z: any): any;
+/** Trilinear sample of the SDF grid at fractional voxel coordinates (edge-clamped). */
+export function grid_sample_trilinear(grid: any, x: any, y: any, z: any): any;
+/**
+ * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
+ * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
+ * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
+ */
+export function grid_local_maximum(out: any, grid: any, vx: any, vy: any, vz: any): void;
+/**
+ * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
+ * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
+ */
+export function grid_claim_sphere(claimed: any, grid: any, px: any, py: any, pz: any, radius: any): void;
+export const OVERSAMPLE: 2;
+export const RESOLUTION_LIMIT: 256;
+export const DEFAULT_SPARSENESS_RATIO: 4;
+/**
+ * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
+ * ({@link probe_place_sdf_cover }) and portal detection ({@link probe_detect_portals }) so the expensive
+ * {@link AcousticOccluderIndexsignedDistanceAt } sweep (up to 256³ queries) is paid once.
+ */
+export type SdfGrid = {
+    /**
+     * per-voxel signed distance (world units), capped at `maxSpacing`
+     */
+    sdf: Float32Array;
+    rx: number;
+    ry: number;
+    /**
+     * per-axis voxel resolution
+     */
+    rz: number;
+    /**
+     * `rx·ry`
+     */
+    strideZ: number;
+    /**
+     * `strideZ·rz`
+     */
+    total: number;
+    x0: number;
+    y0: number;
+    /**
+     * region min corner
+     */
+    z0: number;
+    x1: number;
+    y1: number;
+    /**
+     * region max corner
+     */
+    z1: number;
+    vsX: number;
+    vsY: number;
+    /**
+     * per-axis voxel size (0 if degenerate)
+     */
+    vsZ: number;
+    minSpacing: number;
+    /**
+     * the spacing hint + sparseness ceiling
+     */
+    maxSpacing: number;
+    /**
+     * a voxel above this SDF is "open air" (off any surface)
+     */
+    clearanceFloor: number;
+};
+//# sourceMappingURL=probe_sdf_grid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_sdf_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_sdf_grid.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AACH,qEALW,MAAM,EAAE,cACR,MAAM,oBACN,MAAM,GACJ,OAAO,CA8CnB;AAED,4FAA4F;AAC5F,0FAIC;AAED,sFAAsF;AACtF,0EAKC;AAED,uFAAuF;AACvF,8EAkBC;AAED;;;;GAIG;AACH,yFAqBC;AAED;;;GAGG;AACH,yGAuBC;AA9KD,2BAA4B;AAE5B,mCAAoC;AAGpC,yCAA0C;;;;;;;;;;SAW5B,YAAY;QACZ,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;;;;aAClD,MAAM;;;;WAA6B,MAAM;QACzC,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;QAClD,MAAM;QAAgB,MAAM;;;;QAAgB,MAAM;SAClD,MAAM;SAAiB,MAAM;;;;SAAiB,MAAM;gBACpD,MAAM;;;;gBAAwB,MAAM;;;;oBACpC,MAAM"}

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

@@ -0,0 +1,183 @@
+import { clamp } from "../../../../core/math/clamp.js";
+import { lerp } from "../../../../core/math/lerp.js";
+
+// Voxel grid is finer than the spacing hint so it resolves sub-`minSpacing` features (thin corridors).
+export const OVERSAMPLE = 2;
+// Per-axis voxel resolution is capped so the SDF grid stays bounded (256³ f32 ≈ 64 MB).
+export const RESOLUTION_LIMIT = 256;
+// Open halls get probes at most this multiple of `minSpacing` apart (the sparseness ceiling + the SDF query
+// cutoff — beyond it "very open" is good enough).
+export const DEFAULT_SPARSENESS_RATIO = 4;
+
+const ASCENT_ITERATIONS = 5;
+const ASCENT_RATE = 0.2;
+
+/**
+ * A signed distance field sampled on a regular voxel grid over a bake region. Shared by the placement cover
+ * ({@link probe_place_sdf_cover}) and portal detection ({@link probe_detect_portals}) so the expensive
+ * {@link AcousticOccluderIndex#signedDistanceAt} sweep (up to 256³ queries) is paid once.
+ *
+ * @typedef {Object} SdfGrid
+ * @property {Float32Array} sdf per-voxel signed distance (world units), capped at `maxSpacing`
+ * @property {number} rx @property {number} ry @property {number} rz per-axis voxel resolution
+ * @property {number} strideZ `rx·ry` @property {number} total `strideZ·rz`
+ * @property {number} x0 @property {number} y0 @property {number} z0 region min corner
+ * @property {number} x1 @property {number} y1 @property {number} z1 region max corner
+ * @property {number} vsX @property {number} vsY @property {number} vsZ per-axis voxel size (0 if degenerate)
+ * @property {number} minSpacing @property {number} maxSpacing the spacing hint + sparseness ceiling
+ * @property {number} clearanceFloor a voxel above this SDF is "open air" (off any surface)
+ */
+
+/**
+ * Build a signed distance field on a voxel grid over `bounds` by sampling
+ * {@link AcousticOccluderIndex#signedDistanceAt}. The grid is finer than `minSpacing` (by {@link OVERSAMPLE})
+ * so it resolves sub-spacing features, and capped at {@link RESOLUTION_LIMIT}³.
+ *
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {number[]} bounds `[x0,y0,z0,x1,y1,z1]`
+ * @param {number} minSpacing the probe spacing hint
+ * @param {number} [sparsenessRatio]
+ * @returns {SdfGrid}
+ */
+export function build_sdf_grid(index, bounds, minSpacing, sparsenessRatio = DEFAULT_SPARSENESS_RATIO) {
+    const maxSpacing = minSpacing * sparsenessRatio;
+
+    const x0 = bounds[0], y0 = bounds[1], z0 = bounds[2];
+    const x1 = bounds[3], y1 = bounds[4], z1 = bounds[5];
+
+    const extX = x1 - x0, extY = y1 - y0, extZ = z1 - z0;
+
+    const voxel = minSpacing / OVERSAMPLE;
+    const rx = clamp(Math.ceil(extX / voxel) + 1, 2, RESOLUTION_LIMIT);
+    const ry = clamp(Math.ceil(extY / voxel) + 1, 2, RESOLUTION_LIMIT);
+    const rz = clamp(Math.ceil(extZ / voxel) + 1, 2, RESOLUTION_LIMIT);
+
+    // actual per-axis voxel size (probe positions lerp over [0, res-1])
+    const vsX = extX / (rx - 1);
+    const vsY = extY / (ry - 1);
+    const vsZ = extZ / (rz - 1);
+
+    const strideZ = rx * ry;
+    const total = strideZ * rz;
+
+    const sdf = new Float32Array(total);
+    for (let zi = 0; zi < rz; zi++) {
+        const z = lerp(z0, z1, zi / (rz - 1));
+        for (let yi = 0; yi < ry; yi++) {
+            const y = lerp(y0, y1, yi / (ry - 1));
+            for (let xi = 0; xi < rx; xi++) {
+                const x = lerp(x0, x1, xi / (rx - 1));
+                sdf[zi * strideZ + yi * rx + xi] = index.signedDistanceAt(x, y, z, maxSpacing);
+            }
+        }
+    }
+
+    // "open air" = off any surface by ~½ a NOMINAL voxel. Based on the spacing hint, NOT the actual per-axis
+    // voxel size: a degenerate (zero-extent) axis can't zero it, and the resolution cap can't inflate it past
+    // maxSpacing (which would reject every voxel).
+    const clearanceFloor = (minSpacing / OVERSAMPLE) * 0.5;
+
+    return {
+        sdf, rx, ry, rz, strideZ, total,
+        x0, y0, z0, x1, y1, z1,
+        vsX, vsY, vsZ,
+        minSpacing, maxSpacing, clearanceFloor,
+    };
+}
+
+/** World position of the (fractional) voxel coordinate `(fx,fy,fz)`, written into `out`. */
+export function grid_voxel_to_world(grid, out, fx, fy, fz) {
+    out[0] = grid.x0 + fx * grid.vsX;
+    out[1] = grid.y0 + fy * grid.vsY;
+    out[2] = grid.z0 + fz * grid.vsZ;
+}
+
+/** SDF at a WORLD position via trilinear interpolation of the grid (edge-clamped). */
+export function grid_sample_world(grid, x, y, z) {
+    const fx = grid.vsX > 0 ? (x - grid.x0) / grid.vsX : 0;
+    const fy = grid.vsY > 0 ? (y - grid.y0) / grid.vsY : 0;
+    const fz = grid.vsZ > 0 ? (z - grid.z0) / grid.vsZ : 0;
+    return grid_sample_trilinear(grid, fx, fy, fz);
+}
+
+/** Trilinear sample of the SDF grid at fractional voxel coordinates (edge-clamped). */
+export function grid_sample_trilinear(grid, x, y, z) {
+    const { sdf, rx, ry, rz, strideZ } = grid;
+
+    const x0 = Math.floor(x), y0 = Math.floor(y), z0 = Math.floor(z);
+    const u = x - x0, v = y - y0, w = z - z0;
+
+    const sx0 = clampInt(x0, rx), sy0 = clampInt(y0, ry), sz0 = clampInt(z0, rz);
+    const sx1 = clampInt(x0 + 1, rx), sy1 = clampInt(y0 + 1, ry), sz1 = clampInt(z0 + 1, rz);
+
+    const c000 = sdf[sz0 * strideZ + sy0 * rx + sx0], c100 = sdf[sz0 * strideZ + sy0 * rx + sx1];
+    const c010 = sdf[sz0 * strideZ + sy1 * rx + sx0], c110 = sdf[sz0 * strideZ + sy1 * rx + sx1];
+    const c001 = sdf[sz1 * strideZ + sy0 * rx + sx0], c101 = sdf[sz1 * strideZ + sy0 * rx + sx1];
+    const c011 = sdf[sz1 * strideZ + sy1 * rx + sx0], c111 = sdf[sz1 * strideZ + sy1 * rx + sx1];
+
+    const c00 = c000 + (c100 - c000) * u, c01 = c001 + (c101 - c001) * u;
+    const c10 = c010 + (c110 - c010) * u, c11 = c011 + (c111 - c011) * u;
+    const c0 = c00 + (c10 - c00) * v, c1 = c01 + (c11 - c01) * v;
+    return c0 + (c1 - c0) * w;
+}
+
+/**
+ * Gradient-ascend a voxel to the local SDF maximum (the most-open sub-voxel point), written into `out` as a
+ * fractional voxel coordinate clamped to within ½ voxel of the start. Central-difference gradient on the
+ * trilinearly-sampled SDF; the gradient is not normalised, so steps shrink near the maximum.
+ */
+export function grid_local_maximum(out, grid, vx, vy, vz) {
+    const minX = vx - 0.4999, maxX = vx + 0.4999;
+    const minY = vy - 0.4999, maxY = vy + 0.4999;
+    const minZ = vz - 0.4999, maxZ = vz + 0.4999;
+
+    let cx = vx, cy = vy, cz = vz;
+    const e = 0.001;
+
+    for (let i = 0; i < ASCENT_ITERATIONS; i++) {
+        const gx = grid_sample_trilinear(grid, cx + e, cy, cz) - grid_sample_trilinear(grid, cx - e, cy, cz);
+        const gy = grid_sample_trilinear(grid, cx, cy + e, cz) - grid_sample_trilinear(grid, cx, cy - e, cz);
+        const gz = grid_sample_trilinear(grid, cx, cy, cz + e) - grid_sample_trilinear(grid, cx, cy, cz - e);
+
+        cx = clamp(cx + gx * ASCENT_RATE, minX, maxX);
+        cy = clamp(cy + gy * ASCENT_RATE, minY, maxY);
+        cz = clamp(cz + gz * ASCENT_RATE, minZ, maxZ);
+    }
+
+    out[0] = cx;
+    out[1] = cy;
+    out[2] = cz;
+}
+
+/**
+ * Mark every voxel whose centre is within `radius` of the world point `(px,py,pz)` as claimed. O((radius/voxel)³)
+ * per call. A degenerate axis (`vs===0`, a zero-extent bake region) claims all its coincident layers.
+ */
+export function grid_claim_sphere(claimed, grid, px, py, pz, radius) {
+    const { rx, ry, rz, strideZ, x0, y0, z0, vsX, vsY, vsZ } = grid;
+    const r2 = radius * radius;
+
+    const xlo = vsX > 0 ? Math.max(0, Math.floor((px - x0 - radius) / vsX)) : 0;
+    const xhi = vsX > 0 ? Math.min(rx - 1, Math.ceil((px - x0 + radius) / vsX)) : rx - 1;
+    const ylo = vsY > 0 ? Math.max(0, Math.floor((py - y0 - radius) / vsY)) : 0;
+    const yhi = vsY > 0 ? Math.min(ry - 1, Math.ceil((py - y0 + radius) / vsY)) : ry - 1;
+    const zlo = vsZ > 0 ? Math.max(0, Math.floor((pz - z0 - radius) / vsZ)) : 0;
+    const zhi = vsZ > 0 ? Math.min(rz - 1, Math.ceil((pz - z0 + radius) / vsZ)) : rz - 1;
+
+    for (let zi = zlo; zi <= zhi; zi++) {
+        const dz = (vsZ > 0 ? z0 + zi * vsZ : z0) - pz;
+        for (let yi = ylo; yi <= yhi; yi++) {
+            const dy = (vsY > 0 ? y0 + yi * vsY : y0) - py;
+            for (let xi = xlo; xi <= xhi; xi++) {
+                const dx = (vsX > 0 ? x0 + xi * vsX : x0) - px;
+                if (dx * dx + dy * dy + dz * dz <= r2) {
+                    claimed[zi * strideZ + yi * rx + xi] = 1;
+                }
+            }
+        }
+    }
+}
+
+function clampInt(i, res) {
+    return i < 0 ? 0 : (i > res - 1 ? res - 1 : i);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Augment a probe-visibility graph with a budgeted handful of shortcut edges that improve path quality.
+ * The Delaunay base routes only through local hops, so a graph path can detour or kink where a clear
+ * straight line exists. For each 2-ring chord `(u,v)` (sharing a base neighbour `w`, not already adjacent)
+ * that is unoccluded, add it when EITHER:
+ *  - **length** (greedy spanner): the straight `‖uv‖` beats the 2-hop `‖uw‖+‖wv‖` by ≥ `stretchFactor`, or
+ *  - **directionality** (diffraction-angle gate): the corner at `w` is acute — `dot(̂(u−w), −̂(v−w)) < kink`.
+ *
+ * For a 2-ring chord the two criteria largely coincide (an acute corner is also a big detour), but the
+ * explicit angle gate catches sharp corners the length threshold alone would miss. The length test is local
+ * (vs the 2-hop, not a global Dijkstra) — cheap and O(n·degree²); acoustically the bends that matter are
+ * local corners. Candidates are added highest-detour-first up to `budgetFraction` of the base edge count.
+ * Pure geometry; offline (no WebAudio).
+ *
+ * @param {AcousticProbeField} field
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the current edges (base + bridges)
+ * @param {number} [stretchFactor] add a chord when the straight ‖uv‖ beats the 2-hop ‖uw‖+‖wv‖ by ≥ this
+ * @param {number} [kinkThreshold] add a chord when the corner at w is acute: dot(̂(u−w), −̂(v−w)) < this
+ * @param {number} [budgetFraction] cap added edges at this fraction of the base edge count
+ * @returns {{a: number[], b: number[]}} the shortcut edges to add (possibly empty)
+ */
+export function probe_visibility_augment(field: AcousticProbeField, index: AcousticOccluderIndex, edges: {
+    a: ArrayLike<number>;
+    b: ArrayLike<number>;
+}, stretchFactor?: number, kinkThreshold?: number, budgetFraction?: number): {
+    a: number[];
+    b: number[];
+};
+//# sourceMappingURL=probe_visibility_augment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_visibility_augment.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_visibility_augment.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yGANW;IAAC,CAAC,EAAE,UAAU,MAAM,CAAC,CAAC;IAAC,CAAC,EAAE,UAAU,MAAM,CAAC,CAAA;CAAC,kBAC5C,MAAM,kBACN,MAAM,mBACN,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAC,CA4HtC"}