@woosh/meep-engine 3.37.0 → 3.39.0

package/src/core/geom/3d/shape/util/mesh_compute_triangle_edge_flags.js

@@ -0,0 +1,538 @@
+import { lowbias32 } from "../../../../math/hash/lowbias32.js";
+import { tri3_classify_shared_edge } from "../../triangle/tri3_classify_shared_edge.js";
+import { TriangleEdgeFlags } from "../../triangle/TriangleEdgeFlags.js";
+
+/**
+ * Vertices of a mesh closer than this fraction of its scale — the largest coordinate, in absolute
+ * value, of a vertex some triangle uses — on every axis are one vertex: 2^-20, eight float32 steps at
+ * that magnitude, so positions an exporter wrote apart only by float32 rounding meet, and 7 µm on a
+ * mesh 7 m from its origin. Capped by {@link WELD_TOLERANCE_EDGE_FRACTION}.
+ * @type {number}
+ */
+const WELD_TOLERANCE_RELATIVE = 2 ** -20;
+
+/**
+ * The weld's tolerance is at most this fraction of the shortest edge of any triangle with area, so it
+ * never closes one up: two corners of a triangle meet only by both welding to one vertex within the
+ * tolerance of each on every axis, so at most half that edge's length apart on every axis and at most
+ * √3/2 of it apart in all — less than the edge's own length. Without the cap, 5 cm quads built 100 km
+ * out had their corners welded together (2^-20 of 1e5 is 95 mm) and lost every edge.
+ * @type {number}
+ */
+const WELD_TOLERANCE_EDGE_FRACTION = 1 / 4;
+
+/**
+ * The weld's tolerance for a mesh: {@link WELD_TOLERANCE_RELATIVE} of the largest finite coordinate of
+ * a vertex some triangle uses, capped by {@link WELD_TOLERANCE_EDGE_FRACTION} of the shortest edge of
+ * any triangle with area and finite corners. A vertex no triangle uses is no part of the surface, and
+ * has no say: a stray one at 1e30 or at Infinity made the tolerance as large.
+ *
+ * @param {ArrayLike<number>} positions
+ * @param {ArrayLike<number>} indices
+ * @param {number} tri_count
+ * @returns {number} > 0
+ */
+function weld_tolerance(positions, indices, tri_count) {
+    let scale = 0;
+    let shortest_sqr = Infinity;
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = indices[t * 3] * 3, b = indices[t * 3 + 1] * 3, c = indices[t * 3 + 2] * 3;
+
+        const ax = positions[a], ay = positions[a + 1], az = positions[a + 2];
+        const bx = positions[b], by = positions[b + 1], bz = positions[b + 2];
+        const cx = positions[c], cy = positions[c + 1], cz = positions[c + 2];
+
+        // finite corners only (NaN fails this too)
+        if (!(Math.abs(ax) + Math.abs(ay) + Math.abs(az) + Math.abs(bx) + Math.abs(by) + Math.abs(bz)
+            + Math.abs(cx) + Math.abs(cy) + Math.abs(cz) < Infinity)) {
+            continue;
+        }
+
+        scale = Math.max(scale, Math.abs(ax), Math.abs(ay), Math.abs(az), Math.abs(bx), Math.abs(by), Math.abs(bz),
+            Math.abs(cx), Math.abs(cy), Math.abs(cz));
+
+        const e1x = bx - ax, e1y = by - ay, e1z = bz - az;
+        const e2x = cx - bx, e2y = cy - by, e2z = cz - bz;
+        const e3x = ax - cx, e3y = ay - cy, e3z = az - cz;
+
+        const nx = e1y * e3z - e1z * e3y, ny = e1z * e3x - e1x * e3z, nz = e1x * e3y - e1y * e3x;
+
+        if (!(nx * nx + ny * ny + nz * nz > 0)) {
+            // no area: no edges to keep apart
+            continue;
+        }
+
+        shortest_sqr = Math.min(shortest_sqr,
+            e1x * e1x + e1y * e1y + e1z * e1z,
+            e2x * e2x + e2y * e2y + e2z * e2z,
+            e3x * e3x + e3y * e3y + e3z * e3z
+        );
+    }
+
+    let tolerance = scale * WELD_TOLERANCE_RELATIVE;
+
+    if (shortest_sqr < Infinity) {
+        tolerance = Math.min(tolerance, WELD_TOLERANCE_EDGE_FRACTION * Math.sqrt(shortest_sqr));
+    }
+
+    // a surface all at one point welds to one point; any positive tolerance does that
+    return tolerance > 0 ? tolerance : 1;
+}
+
+/**
+ * @param {number} n
+ * @returns {number} the smallest power of two ≥ 2n (at least 2)
+ */
+function table_size(n) {
+    let size = 2;
+    while (size < 2 * n) size *= 2;
+    return size;
+}
+
+/**
+ * @param {number} cx integer cell coordinates
+ * @param {number} cy
+ * @param {number} cz
+ * @returns {number}
+ */
+function cell_hash(cx, cy, cz) {
+    return lowbias32((cx | 0) ^ Math.imul(cy | 0, 0x9E3779B1) ^ Math.imul(cz | 0, 0x85EBCA77));
+}
+
+/**
+ * For each vertex, the vertex it is welded to: the first one, in buffer order, within `tolerance` of
+ * it on every axis — the vertices as the surface sees them, whatever the buffer split for normals or
+ * UVs, and wherever float rounding left copies of one point apart.
+ *
+ * A grid of cells twice the tolerance wide, as Box3D's `b3WeldVertices` grids its welds: a vertex can
+ * reach only the cells across the nearer face of its own on each axis, so it looks in its own cell
+ * first — a copy at the very same point is there — then in the seven others of that 2 × 2 × 2 block.
+ *
+ * @param {ArrayLike<number>} positions
+ * @param {number} vertex_count
+ * @param {number} tolerance > 0
+ * @returns {Int32Array}
+ */
+function weld_by_position(positions, vertex_count, tolerance) {
+    const welded = new Int32Array(vertex_count);
+    const size = table_size(vertex_count);
+    const mask = size - 1;
+    const slots = new Int32Array(size).fill(-1);
+    const inv = 0.5 / tolerance;
+
+    for (let v = 0; v < vertex_count; v++) {
+        const x = positions[v * 3], y = positions[v * 3 + 1], z = positions[v * 3 + 2];
+
+        const fx = x * inv, fy = y * inv, fz = z * inv;
+        const cx = Math.floor(fx), cy = Math.floor(fy), cz = Math.floor(fz);
+
+        // the neighbour cell on each axis is across the nearer face
+        const sx = fx - cx < 0.5 ? -1 : 1;
+        const sy = fy - cy < 0.5 ? -1 : 1;
+        const sz = fz - cz < 0.5 ? -1 : 1;
+
+        let found = -1;
+
+        for (let n = 0; n < 8 && found === -1; n++) {
+            const h = cell_hash(cx + (n & 1) * sx, cy + ((n >> 1) & 1) * sy, cz + (n >> 2) * sz);
+
+            // every kept vertex in the cell's chain (and any other cell's sharing it) within the tolerance
+            for (let slot = h & mask; ; slot = (slot + 1) & mask) {
+                const other = slots[slot];
+
+                if (other === -1) {
+                    break;
+                }
+
+                if (Math.abs(positions[other * 3] - x) <= tolerance
+                    && Math.abs(positions[other * 3 + 1] - y) <= tolerance
+                    && Math.abs(positions[other * 3 + 2] - z) <= tolerance) {
+                    found = other;
+                    break;
+                }
+            }
+        }
+
+        if (found !== -1) {
+            welded[v] = found;
+            continue;
+        }
+
+        welded[v] = v;
+
+        let slot = cell_hash(cx, cy, cz) & mask;
+        while (slots[slot] !== -1) slot = (slot + 1) & mask;
+        slots[slot] = v;
+    }
+
+    return welded;
+}
+/**
+ * Outward normal of triangle `t`, unnormalised, into `out`.
+ */
+function triangle_normal(out, out_offset, positions, indices, t) {
+    const a = indices[t * 3] * 3, b = indices[t * 3 + 1] * 3, c = indices[t * 3 + 2] * 3;
+
+    const e1x = positions[b] - positions[a], e1y = positions[b + 1] - positions[a + 1], e1z = positions[b + 2] - positions[a + 2];
+    const e2x = positions[c] - positions[a], e2y = positions[c + 1] - positions[a + 1], e2z = positions[c + 2] - positions[a + 2];
+
+    out[out_offset] = e1y * e2z - e1z * e2y;
+    out[out_offset + 1] = e1z * e2x - e1x * e2z;
+    out[out_offset + 2] = e1x * e2y - e1y * e2x;
+}
+
+const scratch_normals = new Float64Array(6);
+
+/**
+ * Classify one side of a shared edge: edge `k1` of triangle `t1`, whose neighbour across it is
+ * triangle `t2`, lying along it with its edge `k2`.
+ *
+ * @returns {number} {@link TriangleEdgeFlags} bits for edge k1
+ */
+function classify_side(positions, indices, t1, k1, t2, k2) {
+    triangle_normal(scratch_normals, 0, positions, indices, t1);
+    triangle_normal(scratch_normals, 3, positions, indices, t2);
+
+    // a point on the edge, and the vertex of t2 off it
+    const p = indices[t1 * 3 + k1] * 3;
+    const o = indices[t2 * 3 + (k2 + 2) % 3] * 3;
+
+    return tri3_classify_shared_edge(
+        scratch_normals[0], scratch_normals[1], scratch_normals[2],
+        scratch_normals[3], scratch_normals[4], scratch_normals[5],
+        positions[o] - positions[p], positions[o + 1] - positions[p + 1], positions[o + 2] - positions[p + 2]
+    ) << k1;
+}
+
+/**
+ * Most edges one edge of a T-junction is matched against, end to end along it: the far side of a
+ * T-junction split into this many pieces at most.
+ * @type {number}
+ */
+const T_JUNCTION_MAX_PIECES = 16;
+
+/** The pieces of the T-junction being matched, as half-edges. */
+const t_pieces = new Int32Array(T_JUNCTION_MAX_PIECES);
+
+/**
+ * Per-triangle {@link TriangleEdgeFlags} of an indexed triangle surface: for each of a triangle's
+ * edges, whether the neighbour across it lies in the same plane (FLAT), bends up (CONCAVE), or the
+ * edge is a real one — a ridge, a rim, or an edge more than two triangles share; and for each of its
+ * corners, whether every edge meeting there is flat (FLAT), or a real edge does.
+ *
+ * Neighbours are found by POSITION, not by index: vertices within the weld's tolerance of one another
+ * ({@link weld_tolerance}: 2^-20 of the mesh's scale, never a quarter of its shortest edge) are one
+ * vertex, so a surface whose buffer splits vertices for normals or UVs — every triangle its own three,
+ * as exporters produce — has the adjacency it looks like it has, float rounding and all. An edge is shared when exactly two triangles have it. A
+ * triangle with two corners at one point has no area and no edges: it is left out, and the triangles
+ * around it meet across it.
+ *
+ * An edge no other triangle has may still have neighbours: a T-junction, where one triangle's edge
+ * runs along two or more shorter edges of the triangles on its other side, ending at a vertex in the
+ * middle of it. The shorter edges are found end to end along it (up to {@link T_JUNCTION_MAX_PIECES})
+ * and the edges are classified against one another: the long edge is FLAT when every piece is, so is
+ * each piece against it.
+ *
+ * Box3D cooks the same edge flags into its meshes (mesh.c `b3IdentifyEdges`, MIT, Erin Catto), from
+ * which this is ported, adjacency by position and T-junctions aside.
+ *
+ * ## Cost
+ *
+ * Linear in the triangles at any vertex valence — a half-edge's partners are found by binary search
+ * in its vertices' runs, sorted by end vertex — once per surface; the result, 2 bytes a triangle, is
+ * meant to be kept. Measured: a 1M-triangle grid, 0.47 s; 180k triangles, 0.07 s indexed and 0.1 s
+ * with every triangle its own three vertices, against 311 s for {@link shape3_mesh_from_geometry} to
+ * build the shape; a fan of 100k triangles round one vertex, 0.05–0.07 s (scanning each vertex's
+ * half-edges instead took 86 s there). Only the T-junction walk scans a vertex's lone half-edges, so
+ * rim edges by the thousand meeting at one vertex stay quadratic (10k loose triangles sharing one
+ * corner: 0.8 s). Transient arrays: the welded index and its table, 8 to 20 bytes a vertex; the
+ * half-edges sorted twice, 8 bytes a vertex and 24 a triangle — about 40 MB for 1M indexed
+ * triangles. (An edge hash table here cost 168 MB and 0.65 s.)
+ *
+ * @param {ArrayLike<number>} positions flat `(x, y, z)` per vertex
+ * @param {ArrayLike<number>} indices three per triangle, wound CCW seen from outside
+ * @returns {Uint16Array} one entry per triangle
+ */
+export function mesh_compute_triangle_edge_flags(positions, indices) {
+    const tri_count = (indices.length / 3) | 0;
+    const flags = new Uint16Array(tri_count);
+
+    if (tri_count === 0) {
+        return flags;
+    }
+
+    const vertex_count = (positions.length / 3) | 0;
+
+    const tolerance = weld_tolerance(positions, indices, tri_count);
+
+    const welded = weld_by_position(positions, vertex_count, tolerance);
+
+    // The half-edges h = 3t + k, corner k to corner k + 1 of triangle t, of the triangles with three
+    // distinct welded corners, listed by their start and, within a start, by their end:
+    // outgoing[first[v] .. first[v + 1]) for vertex v. Two counting sorts, by end and then (stably) by
+    // start, so a half-edge's partners are found by binary search, at any vertex valence.
+    const first = new Int32Array(vertex_count + 1);
+    const cursor = new Int32Array(vertex_count + 1);
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = welded[indices[t * 3]], b = welded[indices[t * 3 + 1]], c = welded[indices[t * 3 + 2]];
+
+        if (a === b || b === c || c === a) {
+            continue;
+        }
+
+        // each corner starts one half-edge and ends one
+        first[a + 1]++;
+        first[b + 1]++;
+        first[c + 1]++;
+    }
+
+    for (let v = 0; v < vertex_count; v++) {
+        first[v + 1] += first[v];
+    }
+
+    const half_edge_count = first[vertex_count];
+
+    // by end (as many end at a vertex as start there: the same offsets)
+    const by_end = new Int32Array(half_edge_count);
+    cursor.set(first);
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = welded[indices[t * 3]], b = welded[indices[t * 3 + 1]], c = welded[indices[t * 3 + 2]];
+
+        if (a === b || b === c || c === a) {
+            continue;
+        }
+
+        by_end[cursor[b]++] = t * 3;
+        by_end[cursor[c]++] = t * 3 + 1;
+        by_end[cursor[a]++] = t * 3 + 2;
+    }
+
+    // then by start, keeping that order
+    const outgoing = new Int32Array(half_edge_count);
+    cursor.set(first);
+
+    for (let i = 0; i < half_edge_count; i++) {
+        const h = by_end[i];
+        outgoing[cursor[welded[indices[h]]]++] = h;
+    }
+
+    // half-edges with no other along them: rims, or one side of a T-junction
+    const lone = [];
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = welded[indices[t * 3]], b = welded[indices[t * 3 + 1]], c = welded[indices[t * 3 + 2]];
+
+        if (a === b || b === c || c === a) {
+            continue;
+        }
+
+        for (let k = 0; k < 3; k++) {
+            const h = t * 3 + k;
+            const p = k === 0 ? a : k === 1 ? b : c;
+            const q = k === 0 ? b : k === 1 ? c : a;
+
+            // the other half-edges along p–q: q → p, as a neighbour wound the same way has it, or p → q
+            // (h itself among the latter)
+            const reverse = lower_end(welded, indices, outgoing, first[q], first[q + 1], p);
+            const reverse_end = lower_end(welded, indices, outgoing, reverse, first[q + 1], p + 1);
+            const same = lower_end(welded, indices, outgoing, first[p], first[p + 1], q);
+            const same_end = lower_end(welded, indices, outgoing, same, first[p + 1], q + 1);
+
+            const sharers = (reverse_end - reverse) + (same_end - same - 1);
+            const partner = reverse_end > reverse ? outgoing[reverse] : outgoing[same] === h ? outgoing[same + 1] : outgoing[same];
+
+            if (sharers === 1) {
+                const t2 = (partner / 3) | 0;
+                flags[t] |= classify_side(positions, indices, t, k, t2, partner - t2 * 3);
+            } else if (sharers === 0) {
+                lone.push(h);
+            }
+        }
+    }
+
+    // the lone half-edges listed by their start (each start's in descending order, as they are taken),
+    // the only candidates for the pieces of a T-junction
+    const lone_first = first;
+    const lone_count = lone.length;
+    lone_first.fill(0);
+
+    for (let i = 0; i < lone_count; i++) {
+        lone_first[welded[indices[lone[i]]] + 1]++;
+    }
+
+    for (let v = 0; v < vertex_count; v++) {
+        lone_first[v + 1] += lone_first[v];
+    }
+
+    const lone_outgoing = new Int32Array(lone_count);
+    cursor.set(lone_first);
+
+    for (let i = lone_count - 1; i >= 0; i--) {
+        const h = lone[i];
+        lone_outgoing[cursor[welded[indices[h]]]++] = h;
+    }
+
+    for (let i = 0; i < lone_count; i++) {
+        match_t_junction(positions, indices, welded, lone_first, lone_outgoing, flags, lone[i], tolerance);
+    }
+
+    // vertices a real edge meets, by welded index
+    const real_vertex = new Uint8Array(vertex_count);
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = welded[indices[t * 3]], b = welded[indices[t * 3 + 1]], c = welded[indices[t * 3 + 2]];
+
+        if (a === b || b === c || c === a) {
+            continue;
+        }
+
+        if ((flags[t] & TriangleEdgeFlags.FlatAB) === 0) { real_vertex[a] = 1; real_vertex[b] = 1; }
+        if ((flags[t] & TriangleEdgeFlags.FlatBC) === 0) { real_vertex[b] = 1; real_vertex[c] = 1; }
+        if ((flags[t] & TriangleEdgeFlags.FlatCA) === 0) { real_vertex[c] = 1; real_vertex[a] = 1; }
+    }
+
+    for (let t = 0; t < tri_count; t++) {
+        const a = welded[indices[t * 3]], b = welded[indices[t * 3 + 1]], c = welded[indices[t * 3 + 2]];
+
+        if (a === b || b === c || c === a) {
+            continue;
+        }
+
+        if (real_vertex[a] === 0) flags[t] |= TriangleEdgeFlags.FlatVertexA;
+        if (real_vertex[b] === 0) flags[t] |= TriangleEdgeFlags.FlatVertexB;
+        if (real_vertex[c] === 0) flags[t] |= TriangleEdgeFlags.FlatVertexC;
+    }
+
+    return flags;
+}
+
+/**
+ * Match half-edge `h`, P → Q, which no other half-edge runs along, against the T-junction pieces on its
+ * other side: half-edges Q → V1, V1 → V2, …, Vn → P, as the triangles across it wind them, each with
+ * no partner of its own, end to end along P–Q within `tolerance`. When the pieces reach P, `h` is
+ * classified against them, and each of them against `h`. `lone_outgoing[lone_first[v] ..
+ * lone_first[v + 1])` are the half-edges without a partner that start at vertex v.
+ */
+function match_t_junction(positions, indices, welded, lone_first, lone_outgoing, flags, h, tolerance) {
+    const t = (h / 3) | 0;
+    const k = h - t * 3;
+    const p = welded[indices[h]];
+    const q = welded[indices[t * 3 + (k + 1) % 3]];
+
+    // from Q toward P
+    const qx = positions[q * 3], qy = positions[q * 3 + 1], qz = positions[q * 3 + 2];
+    let dx = positions[p * 3] - qx, dy = positions[p * 3 + 1] - qy, dz = positions[p * 3 + 2] - qz;
+    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+
+    if (!(length > 2 * tolerance)) {
+        return;
+    }
+
+    dx /= length; dy /= length; dz /= length;
+
+    let at = q;
+    let reach = 0;
+    let pieces = 0;
+
+    while (at !== p) {
+        if (pieces === T_JUNCTION_MAX_PIECES) {
+            return;
+        }
+
+        let next = -1;
+
+        for (let i = lone_first[at], end = lone_first[at + 1]; i < end; i++) {
+            const g = lone_outgoing[i];
+            const tg = (g / 3) | 0;
+
+            if (tg === t || (flags[tg] & (TriangleEdgeFlags.FlatAB | TriangleEdgeFlags.ConcaveAB) << (g - tg * 3)) !== 0) {
+                // h's own triangle, or a piece already matched
+                continue;
+            }
+
+            const v = half_edge_end(welded, indices, g);
+            const ex = positions[v * 3] - qx, ey = positions[v * 3 + 1] - qy, ez = positions[v * 3 + 2] - qz;
+            const along = ex * dx + ey * dy + ez * dz;
+
+            // forward along P–Q, not past P, and on it
+            if (!(along > reach + tolerance) || along > length + tolerance) {
+                continue;
+            }
+
+            const ox = ex - dx * along, oy = ey - dy * along, oz = ez - dz * along;
+
+            if (ox * ox + oy * oy + oz * oz > tolerance * tolerance) {
+                continue;
+            }
+
+            next = g;
+            reach = along;
+            at = v;
+            break;
+        }
+
+        if (next === -1) {
+            return;
+        }
+
+        t_pieces[pieces++] = next;
+    }
+
+    if (pieces < 2) {
+        // a single piece from Q to P would be h's partner, and h has none
+        return;
+    }
+
+    // h against every piece: FLAT when all are, CONCAVE when all are, real otherwise
+    const flat_bit = TriangleEdgeFlags.FlatAB << k;
+    const concave_bit = TriangleEdgeFlags.ConcaveAB << k;
+    let all_flat = true, all_concave = true;
+
+    for (let i = 0; i < pieces; i++) {
+        const g = t_pieces[i];
+        const tg = (g / 3) | 0;
+        const kg = g - tg * 3;
+
+        const side = classify_side(positions, indices, t, k, tg, kg);
+
+        if (side !== flat_bit) all_flat = false;
+        if (side !== concave_bit) all_concave = false;
+
+        flags[tg] |= classify_side(positions, indices, tg, kg, t, k);
+    }
+
+    if (all_flat) {
+        flags[t] |= flat_bit;
+    } else if (all_concave) {
+        flags[t] |= concave_bit;
+    }
+}
+
+/**
+ * First position in `outgoing[lo .. hi)` — a run sorted by end vertex — whose half-edge ends at or
+ * after vertex `target`.
+ */
+function lower_end(welded, indices, outgoing, lo, hi, target) {
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+
+        if (half_edge_end(welded, indices, outgoing[mid]) < target) {
+            lo = mid + 1;
+        } else {
+            hi = mid;
+        }
+    }
+
+    return lo;
+}
+
+/**
+ * Welded end vertex of half-edge `h` (corner `h % 3` to the next of triangle `h / 3`).
+ */
+function half_edge_end(welded, indices, h) {
+    const t = (h / 3) | 0;
+    return welded[indices[t * 3 + (h - t * 3 + 1) % 3]];
+}

package/src/core/geom/3d/sphere/harmonics/sh_basis_at.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Real spherical harmonic basis of any band count, at a unit direction.
+ *
+ * The engine's convention, the one {@link sh3_basis_at} and the WGSL `sh2_basis_at`/`sh3_basis_at`
+ * chunks write: orthonormal real SH with **no** Condon-Shortley phase (every sectoral term is
+ * positive along +x), band-major with coefficient `(l, m)` at `l * (l + 1) + m` (`sh_index`), so the
+ * first nine slots are `[1, y, z, x, xy, yz, 3z²-1, xz, x²-y²]` up to their constants. The zonal axis
+ * is +Z; the direction goes in unswizzled.
+ *
+ * Built from the fully normalized associated Legendre recurrence, which is stable at any band count:
+ *
+ *     Q(m, m)   = sqrt((2m+1)/4π · (2m-1)!!/(2m)!!)
+ *     Q(m+1, m) = sqrt(2m+3) · z · Q(m, m)
+ *     Q(l, m)   = a · (z · Q(l-1, m) - b · Q(l-2, m)),  a = sqrt((4l²-1)/(l²-m²)), b = sqrt(((l-1)²-m²)/(4(l-1)²-1))
+ *
+ * and the azimuthal factor from `(x + iy)^m = C(m) + i·S(m)`, so no trigonometry is evaluated:
+ * `Y(l, 0) = Q(l, 0)`, `Y(l, +m) = √2 · Q(l, m) · C(m)`, `Y(l, -m) = √2 · Q(l, m) · S(m)`.
+ * See Sloan, "Efficient Spherical Harmonic Evaluation", JCGT 2(2), 2013, for the same construction.
+ *
+ * The WGSL twins are `sh_basis_function` (one coefficient, any band) and the generated
+ * `sh{N}_basis_at` chunks, both pinned against this function.
+ *
+ * @param {number[]|Float32Array|Float64Array} output written at `[output_offset, output_offset + band_count²)`
+ * @param {number} output_offset
+ * @param {number} band_count number of bands, `l` runs over `[0, band_count)`
+ * @param {number} x unit direction
+ * @param {number} y
+ * @param {number} z
+ */
+export function sh_basis_at(output: number[] | Float32Array | Float64Array, output_offset: number, band_count: number, x: number, y: number, z: number): void;
+//# sourceMappingURL=sh_basis_at.d.ts.map

package/src/core/geom/3d/sphere/harmonics/sh_basis_at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_basis_at.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh_basis_at.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oCAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,cACN,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAuDhB"}

package/src/core/geom/3d/sphere/harmonics/sh_basis_at.js

@@ -0,0 +1,85 @@
+import { assert } from "../../../../assert.js";
+
+/**
+ * Real spherical harmonic basis of any band count, at a unit direction.
+ *
+ * The engine's convention, the one {@link sh3_basis_at} and the WGSL `sh2_basis_at`/`sh3_basis_at`
+ * chunks write: orthonormal real SH with **no** Condon-Shortley phase (every sectoral term is
+ * positive along +x), band-major with coefficient `(l, m)` at `l * (l + 1) + m` (`sh_index`), so the
+ * first nine slots are `[1, y, z, x, xy, yz, 3z²-1, xz, x²-y²]` up to their constants. The zonal axis
+ * is +Z; the direction goes in unswizzled.
+ *
+ * Built from the fully normalized associated Legendre recurrence, which is stable at any band count:
+ *
+ *     Q(m, m)   = sqrt((2m+1)/4π · (2m-1)!!/(2m)!!)
+ *     Q(m+1, m) = sqrt(2m+3) · z · Q(m, m)
+ *     Q(l, m)   = a · (z · Q(l-1, m) - b · Q(l-2, m)),  a = sqrt((4l²-1)/(l²-m²)), b = sqrt(((l-1)²-m²)/(4(l-1)²-1))
+ *
+ * and the azimuthal factor from `(x + iy)^m = C(m) + i·S(m)`, so no trigonometry is evaluated:
+ * `Y(l, 0) = Q(l, 0)`, `Y(l, +m) = √2 · Q(l, m) · C(m)`, `Y(l, -m) = √2 · Q(l, m) · S(m)`.
+ * See Sloan, "Efficient Spherical Harmonic Evaluation", JCGT 2(2), 2013, for the same construction.
+ *
+ * The WGSL twins are `sh_basis_function` (one coefficient, any band) and the generated
+ * `sh{N}_basis_at` chunks, both pinned against this function.
+ *
+ * @param {number[]|Float32Array|Float64Array} output written at `[output_offset, output_offset + band_count²)`
+ * @param {number} output_offset
+ * @param {number} band_count number of bands, `l` runs over `[0, band_count)`
+ * @param {number} x unit direction
+ * @param {number} y
+ * @param {number} z
+ */
+export function sh_basis_at(output, output_offset, band_count, x, y, z) {
+    assert.isNonNegativeInteger(output_offset, 'output_offset');
+    assert.isNonNegativeInteger(band_count, 'band_count');
+
+    // (x + iy)^m, advanced one m at a time
+    let c = 1;
+    let s = 0;
+
+    // Q(m, m) / sqrt(2m + 1), advanced one m at a time
+    let sectoral = 0.28209479177387814; // 1 / sqrt(4π)
+
+    for (let m = 0; m < band_count; m++) {
+
+        if (m > 0) {
+            const c_next = x * c - y * s;
+            s = x * s + y * c;
+            c = c_next;
+
+            sectoral *= Math.sqrt((2 * m - 1) / (2 * m));
+        }
+
+        // the real basis carries √2 on every m > 0 term; folding it into the start of the recurrence
+        // carries it through every band, which is linear in the start
+        const scale = m === 0 ? 1 : Math.SQRT2;
+
+        let q_previous = 0;
+        let q = sectoral * Math.sqrt(2 * m + 1) * scale;
+
+        for (let l = m; l < band_count; l++) {
+
+            if (l === m + 1) {
+                q_previous = q;
+                q = Math.sqrt(2 * m + 3) * z * q;
+            } else if (l > m + 1) {
+                const a = Math.sqrt((4 * l * l - 1) / (l * l - m * m));
+                const b = Math.sqrt(((l - 1) * (l - 1) - m * m) / (4 * (l - 1) * (l - 1) - 1));
+
+                const q_next = a * (z * q - b * q_previous);
+
+                q_previous = q;
+                q = q_next;
+            }
+
+            const zonal = output_offset + l * (l + 1);
+
+            if (m === 0) {
+                output[zonal] = q;
+            } else {
+                output[zonal + m] = q * c;
+                output[zonal - m] = q * s;
+            }
+        }
+    }
+}

package/src/core/geom/3d/sphere/harmonics/sh_vmf_window.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Band `l`'s attenuation under convolution with a von Mises-Fisher lobe of concentration `kappa`:
+ * `exp(-l(l+1) / (2 kappa))`.
+ *
+ * The large-kappa form of the vMF's zonal coefficients, which is what Ref-NeRF's integrated
+ * directional encoding uses (Verbin et al., "Ref-NeRF", CVPR 2022 — [VHM*22]) and what
+ * Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai use to encode roughness continuously in
+ * "Spherical Harmonic Exponentials for Efficient Glossy Reflections" (HPG 2025,
+ * https://doi.org/10.1111/cgf.70219), with `kappa = 1 / alpha`. Band 0 is never attenuated.
+ *
+ * WGSL twin: `sh_vmf_window` (`shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js`).
+ *
+ * @param {number} l band
+ * @param {number} kappa concentration, > 0; larger is sharper
+ * @returns {number} in (0, 1]
+ */
+export function sh_vmf_window(l: number, kappa: number): number;
+//# sourceMappingURL=sh_vmf_window.d.ts.map

package/src/core/geom/3d/sphere/harmonics/sh_vmf_window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh_vmf_window.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh_vmf_window.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,iCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB"}