@woosh/meep-engine 2.163.10 → 2.164.0

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

@@ -0,0 +1,182 @@
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// A chord is worth adding when the straight line beats the existing 2-hop route through their shared
+// neighbour by at least this factor (a local greedy-spanner stretch test).
+const DEFAULT_STRETCH = 1.06;
+// ...or when the corner at the shared neighbour is sharp: dot(̂(u−w), −̂(v−w)) < this — i.e. the angle u-w-v
+// is acute (a diffraction corner the sound must wrap around). -0.5 ≈ corners sharper than 60°.
+const DEFAULT_KINK = -0.866;
+// Cap added edges at this fraction of the base edge count — a handful of the highest-benefit shortcuts, so
+// the augmentation composes with the base graph rather than densifying it.
+const DEFAULT_BUDGET = 3;
+
+/**
+ * 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,
+    index,
+    edges,
+    stretchFactor = DEFAULT_STRETCH,
+    kinkThreshold = DEFAULT_KINK,
+    budgetFraction = DEFAULT_BUDGET
+) {
+    const n = field.size;
+
+    const m = edges.a.length;
+    if (m === 0) {
+        return { a: [], b: [] };
+    }
+
+    // sorted CSR adjacency over the current edges (for 2-ring walks + O(log d) "already adjacent?" tests)
+    const degree = new Uint32Array(n);
+    for (let i = 0; i < m; i++) {
+        degree[edges.a[i]]++;
+        degree[edges.b[i]]++;
+    }
+    const addr = new Uint32Array(n + 1);
+    for (let v = 0; v < n; v++) {
+        addr[v + 1] = addr[v] + degree[v];
+    }
+    const adj = new Uint32Array(2 * m);
+    const cursor = addr.slice(0, n);
+    for (let i = 0; i < m; i++) {
+        const a = edges.a[i];
+        const b = edges.b[i];
+        adj[cursor[a]++] = b;
+        adj[cursor[b]++] = a;
+    }
+    for (let v = 0; v < n; v++) {
+        adj.subarray(addr[v], addr[v + 1]).sort();
+    }
+
+    // eligible chords (allowing duplicates from multiple shared neighbours; deduped at add-time)
+    const candU = [];
+    const candV = [];
+    const candBenefit = [];
+
+    for (let u = 0; u < n; u++) {
+        const ux = field.probeX(u);
+        const uy = field.probeY(u);
+        const uz = field.probeZ(u);
+
+        const edge_count = addr[u + 1];
+
+        for (let ki = addr[u]; ki < edge_count; ki++) {
+            const w = adj[ki];
+
+            const wx = field.probeX(w);
+            const wy = field.probeY(w);
+            const wz = field.probeZ(w);
+
+            const uwx = ux - wx, uwy = uy - wy, uwz = uz - wz;
+            const uw = Math.sqrt(uwx * uwx + uwy * uwy + uwz * uwz);
+
+            for (let kj = addr[w]; kj < addr[w + 1]; kj++) {
+                const v = adj[kj];
+                if (v <= u) {
+                    continue; // canonical u<v (and skips v===u: u is a neighbour of w)
+                }
+                if (isNeighbour(adj, addr, u, v)) {
+                    continue; // already connected — a triangle, no shortcut needed
+                }
+
+                const vx = field.probeX(v);
+                const vy = field.probeY(v);
+                const vz = field.probeZ(v);
+
+                const wvx = vx - wx, wvy = vy - wy, wvz = vz - wz;
+                const wv = Math.sqrt(wvx * wvx + wvy * wvy + wvz * wvz);
+
+                const uvx = vx - ux, uvy = vy - uy, uvz = vz - uz;
+                const uv = Math.sqrt(uvx * uvx + uvy * uvy + uvz * uvz);
+
+                const stretchOK = uv * stretchFactor < uw + wv;
+
+                // dot(̂(u−w), −̂(v−w)) = −(uw·wv)/(‖uw‖‖wv‖); acute corner → near −1
+                const kinkVal = -(uwx * wvx + uwy * wvy + uwz * wvz) / (uw * wv);
+                const kinkOK = kinkVal < kinkThreshold;
+
+                if (!stretchOK && !kinkOK) {
+                    continue;
+                }
+
+                if (!probe_edge_visible(field, index, u, v)) {
+                    continue; // a wall blocks the shortcut
+                }
+
+                candU.push(u);
+                candV.push(v);
+                candBenefit.push((uw + wv) / uv); // detour ratio — higher means a better shortcut
+            }
+        }
+    }
+
+    // add highest-detour chords first, up to the budget, deduping repeats
+    const order = candU.map((_, i) => i);
+    order.sort((i, j) => candBenefit[j] - candBenefit[i]);
+
+    const budget = Math.floor(budgetFraction * m);
+    const added = new Set();
+    const outA = [];
+    const outB = [];
+
+    for (let i = 0; i < order.length && outA.length < budget; i++) {
+        const idx = order[i];
+        const u = candU[idx];
+        const v = candV[idx];
+        const key = u * n + v;
+        if (added.has(key)) {
+            continue;
+        }
+        added.add(key);
+        outA.push(u);
+        outB.push(v);
+    }
+
+    return { a: outA, b: outB };
+}
+
+/**
+ * Whether `v` is in `u`'s (sorted) adjacency slice — binary search.
+ * @param {Uint32Array} adj
+ * @param {Uint32Array} addr
+ * @param {number} u
+ * @param {number} v
+ * @returns {boolean}
+ */
+function isNeighbour(adj, addr, u, v) {
+    let lo = addr[u];
+    let hi = addr[u + 1] - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const x = adj[mid];
+        if (x === v) {
+            return true;
+        } else if (x < v) {
+            lo = mid + 1;
+        } else {
+            hi = mid - 1;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Bridge the connected components ("islands") of a probe-visibility base graph. Dropping occluded Delaunay
+ * edges (stage A) fragments the graph along walls; two rooms joined by a doorway the Delaunay edge happened
+ * to miss become separate components even though sound passes between them. This re-connects them with the
+ * shortest VISIBLE cross-component edges — the PRM/SPARS component-connection ("bridge") heuristic.
+ *
+ * Borůvka-style: build the components, then in each round connect every component to its nearest visible
+ * probe in a different component (the shortest candidate per component-pair, found by a BVH radius query),
+ * union, and repeat until no component can reach another. Genuinely sealed regions stay separate — correct;
+ * a closed vault must not leak. Pure geometry; offline (no WebAudio).
+ *
+ * Only the probes in `sources` are searched from — pass the probes that border a wall (the endpoints of the
+ * occluded edges that fragmented the graph); an interior probe whose every Delaunay neighbour is visible can
+ * never be the near side of a missed doorway. An empty scene drops no edges, so `sources` is empty and this
+ * does nothing.
+ *
+ * @param {AcousticProbeField} field
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the visible base edges (define the components)
+ * @param {ArrayLike<number>} sources probe indices to search bridges from (the wall-adjacent probes)
+ * @param {number} [radiusFactor] search radius as a multiple of the median base-edge length
+ * @returns {{a: number[], b: number[]}} the bridge edges to add (possibly empty)
+ */
+export function probe_visibility_bridge_components(field: AcousticProbeField, index: AcousticOccluderIndex, edges: {
+    a: ArrayLike<number>;
+    b: ArrayLike<number>;
+}, sources: ArrayLike<number>, radiusFactor?: number): {
+    a: number[];
+    b: number[];
+};
+//# sourceMappingURL=probe_visibility_bridge_components.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"probe_visibility_bridge_components.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/simulation/probe/probe_visibility_bridge_components.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,mHALW;IAAC,CAAC,EAAE,UAAU,MAAM,CAAC,CAAC;IAAC,CAAC,EAAE,UAAU,MAAM,CAAC,CAAA;CAAC,WAC5C,UAAU,MAAM,CAAC,iBACjB,MAAM,GACJ;IAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,CAAC,EAAE,MAAM,EAAE,CAAA;CAAC,CA8EtC"}

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

@@ -0,0 +1,166 @@
+import { uf_find, uf_init, uf_union } from "../../../../core/collection/union-find/union_find.js";
+import { probe_edge_visible } from "./probe_edge_visible.js";
+
+// Search radius for a bridge, as a multiple of the median base-edge length (the probe spacing). A door/wall
+// gap is typically 1-2 spacings across, so ~2.5 reaches a visible probe on the far side without ballooning
+// the per-probe neighbour count.
+const DEFAULT_RADIUS_FACTOR = 2.5;
+
+/**
+ * Bridge the connected components ("islands") of a probe-visibility base graph. Dropping occluded Delaunay
+ * edges (stage A) fragments the graph along walls; two rooms joined by a doorway the Delaunay edge happened
+ * to miss become separate components even though sound passes between them. This re-connects them with the
+ * shortest VISIBLE cross-component edges — the PRM/SPARS component-connection ("bridge") heuristic.
+ *
+ * Borůvka-style: build the components, then in each round connect every component to its nearest visible
+ * probe in a different component (the shortest candidate per component-pair, found by a BVH radius query),
+ * union, and repeat until no component can reach another. Genuinely sealed regions stay separate — correct;
+ * a closed vault must not leak. Pure geometry; offline (no WebAudio).
+ *
+ * Only the probes in `sources` are searched from — pass the probes that border a wall (the endpoints of the
+ * occluded edges that fragmented the graph); an interior probe whose every Delaunay neighbour is visible can
+ * never be the near side of a missed doorway. An empty scene drops no edges, so `sources` is empty and this
+ * does nothing.
+ *
+ * @param {AcousticProbeField} field
+ * @param {AcousticOccluderIndex} index the acoustic scene
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges the visible base edges (define the components)
+ * @param {ArrayLike<number>} sources probe indices to search bridges from (the wall-adjacent probes)
+ * @param {number} [radiusFactor] search radius as a multiple of the median base-edge length
+ * @returns {{a: number[], b: number[]}} the bridge edges to add (possibly empty)
+ */
+export function probe_visibility_bridge_components(field, index, edges, sources, radiusFactor = DEFAULT_RADIUS_FACTOR) {
+    const n = field.size;
+
+    const parent = new Uint32Array(n);
+    uf_init(parent, n);
+    for (let i = 0; i < edges.a.length; i++) {
+        uf_union(parent, edges.a[i], edges.b[i]);
+    }
+
+    const radius = radiusFactor * medianEdgeLength(field, edges);
+
+    const bridgeA = [];
+    const bridgeB = [];
+    const hits = []; // reused radius-query result (auto-grows; valid length is the returned count)
+
+    let added;
+    do {
+        added = 0;
+
+        // shortest visible cross-component candidate per unordered component-pair this round
+        const best = new Map(); // key = rootLo*n + rootHi -> {a, b, d}
+
+        for (let s = 0; s < sources.length; s++) {
+            const i = sources[s];
+            const ri = uf_find(parent, i);
+
+            const ix = field.probeX(i);
+            const iy = field.probeY(i);
+            const iz = field.probeZ(i);
+
+            const count = field.probesWithinRadius(hits, 0, ix, iy, iz, radius);
+
+            for (let h = 0; h < count; h++) {
+                const j = hits[h];
+                if (j === i) {
+                    continue;
+                }
+
+                const rj = uf_find(parent, j);
+                if (ri === rj) {
+                    continue; // already in the same component
+                }
+
+                if (!probe_edge_visible(field, index, i, j)) {
+                    continue; // a wall blocks this would-be bridge
+                }
+
+                const dx = field.probeX(j) - ix;
+                const dy = field.probeY(j) - iy;
+                const dz = field.probeZ(j) - iz;
+                const d = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+                const rlo = ri < rj ? ri : rj;
+                const rhi = ri < rj ? rj : ri;
+                const key = rlo * n + rhi;
+
+                const prev = best.get(key);
+                if (prev === undefined || d < prev.d) {
+                    best.set(key, { a: i, b: j, d });
+                }
+            }
+        }
+
+        for (const cand of best.values()) {
+            // a bridge added earlier this round may already have merged these via transitivity
+            if (uf_find(parent, cand.a) === uf_find(parent, cand.b)) {
+                continue;
+            }
+            uf_union(parent, cand.a, cand.b);
+            bridgeA.push(cand.a);
+            bridgeB.push(cand.b);
+            added++;
+        }
+    } while (added > 0);
+
+    return { a: bridgeA, b: bridgeB };
+}
+
+/**
+ * Median length of the base edges — a robust estimate of the local probe spacing (Delaunay slivers near the
+ * hull make the mean skew long). Falls back to a bounding-box density estimate when there are no edges.
+ * @param {AcousticProbeField} field
+ * @param {{a: ArrayLike<number>, b: ArrayLike<number>}} edges
+ * @returns {number}
+ */
+function medianEdgeLength(field, edges) {
+    const m = edges.a.length;
+
+    if (m === 0) {
+        return boundsSpacing(field);
+    }
+
+    const lengths = new Float64Array(m);
+    for (let i = 0; i < m; i++) {
+        const a = edges.a[i];
+        const b = edges.b[i];
+        const dx = field.probeX(b) - field.probeX(a);
+        const dy = field.probeY(b) - field.probeY(a);
+        const dz = field.probeZ(b) - field.probeZ(a);
+        lengths[i] = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+
+    lengths.sort();
+    return lengths[m >>> 1];
+}
+
+/**
+ * Spacing estimate from the probe bounding box: the cube root of the per-probe volume. Only used when the
+ * base graph has no edges (a fully-occluded field).
+ * @param {AcousticProbeField} field
+ * @returns {number}
+ */
+function boundsSpacing(field) {
+    const n = field.size;
+    if (n === 0) {
+        return 1;
+    }
+
+    let minX = Infinity, minY = Infinity, minZ = Infinity;
+    let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+
+    for (let i = 0; i < n; i++) {
+        const x = field.probeX(i);
+        const y = field.probeY(i);
+        const z = field.probeZ(i);
+
+        if (x < minX) minX = x; if (x > maxX) maxX = x;
+        if (y < minY) minY = y; if (y > maxY) maxY = y;
+        if (z < minZ) minZ = z; if (z > maxZ) maxZ = z;
+    }
+
+    const volume = Math.max(1e-9, (maxX - minX) * (maxY - minY) * (maxZ - minZ));
+
+    return Math.cbrt(volume / n);
+}

package/src/engine/sound/simulation/prototypeAcousticSolver.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=prototypeAcousticSolver.d.ts.map

package/src/engine/sound/simulation/prototypeAcousticSolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototypeAcousticSolver.d.ts","sourceRoot":"","sources":["../../../../../src/engine/sound/simulation/prototypeAcousticSolver.js"],"names":[],"mappings":""}