@woosh/meep-engine 2.154.0 → 2.156.0

package/src/core/geom/3d/mat4/m4_multiply_alphatensor.js

@@ -7,7 +7,13 @@
  * @param {number[]|Float32Array} b
  * @returns {number[]|Float32Array} `out` parameter
  */
-export function m4_multiply_alphatensor(out, a, b) {
+export function m4_multiply_alphatensor(out, a_in, b_in) {
+    // The AlphaTensor factorization transcribed below computes the transpose of (b_in * a_in). To return
+    // out = a_in * b_in we feed the operands swapped (the a* locals read b_in, the b* locals read a_in) and
+    // write each computed element to its transposed output slot.
+    const a = b_in;
+    const b = a_in;
+
     // read out matricies
     const a11 = a[0];
     const a13 = a[2];
@@ -112,38 +118,38 @@ export function m4_multiply_alphatensor(out, a, b) {
     const c14 = -h16 + h17 - h20 - h21 + h22 - h23 + h25 + h26 - h29 - h32 - h33 + h34 + h38 - h41 + h42 + h43
 
     out[0] = c11;
-    out[1] = c12;
-    out[2] = c13;
-    out[3] = c14;
+    out[4] = c12;
+    out[8] = c13;
+    out[12] = c14;
 
     const c21 = -h7 + h8 - h10 + h11 - h14 + h15 + h16 - h17 + h18 + h21 - h31 + h33 - h35 - h36
     const c22 = h7 - h8 + h10 - h11 - h15 - h16 + h17 - h18 - h21 + h22 - h23 + h26 - h33 + h44
     const c23 = -h7 + h8 + h11 + h12 - h16 + h17 - h20 - h21 - h29 - h33 + h34 + h36 + h38 + h46
     const c24 = -h7 + h8 + h11 + h12 - h16 + h17 - h20 - h21 + h22 - h23 + h25 + h26 - h29 - h33 + h34 + h38
 
-    out[4] = c21;
+    out[1] = c21;
     out[5] = c22;
-    out[6] = c23;
-    out[7] = c24;
+    out[9] = c23;
+    out[13] = c24;
 
     const c31 = h1 - h2 + h3 - h5 + h33 - h34 + h37 - h40
     const c32 = h17 - h18 - h19 - h21 - h23 + h24 + h26 - h33 + h34 - h37 + h40 - h43 + h44 + h45 - h47 + h49
     const c33 = h4 + h5 - h29 - h33 + h34 + h40
     const c34 = -h21 + h26 - h27 + h28 - h29 - h32 - h33 + h34 + h40 - h47
 
-    out[8] = c31;
-    out[9] = c32;
+    out[2] = c31;
+    out[6] = c32;
     out[10] = c33;
-    out[11] = c34;
+    out[14] = c34;
 
     const c41 = h8 - h10 + h11 - h13 + h17 - h18 - h19 - h21 + h31 - h33 + h34 + h35 + h36 - h37 - h39 + h40
     const c42 = -h8 + h10 - h11 + h13 - h17 + h18 + h19 + h21 + h23 - h24 - h26 + h33 - h34 + h37 - h40 - h44
     const c43 = h11 + h21 - h28 + h29 + h30 + h33 - h34 - h35 - h36 + h39 - h40 + h48
     const c44 = h11 + h21 - h26 + h27 - h28 + h29 + h33 - h34 - h40 + h48
 
-    out[12] = c41;
-    out[13] = c42;
-    out[14] = c43;
+    out[3] = c41;
+    out[7] = c42;
+    out[11] = c43;
     out[15] = c44;
 
     return out;

package/src/core/geom/3d/octahedra/octahedral_direction_to_uv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"octahedral_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_direction_to_uv.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,mDALW,MAAM,EAAE,cACR,MAAM,gBACN,MAAM,EAAE,aACR,MAAM,QAsChB"}
+{"version":3,"file":"octahedral_direction_to_uv.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/octahedra/octahedral_direction_to_uv.js"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,mDALW,MAAM,EAAE,cACR,MAAM,gBACN,MAAM,EAAE,aACR,MAAM,QAuChB"}

package/src/core/geom/3d/octahedra/octahedral_direction_to_uv.js

@@ -43,6 +43,7 @@ export function octahedral_direction_to_uv(
         octahedron_z = octant_z * (1 - absolute_x);
     }
 
-    out_uv[out_offset + 0] = octahedron_x;
-    out_uv[out_offset + 1] = octahedron_z;
+    // map octahedron coordinates from [-1,1] into [0,1] UV space; this exactly inverts the decode's `*2 - 1`.
+    out_uv[out_offset + 0] = octahedron_x * 0.5 + 0.5;
+    out_uv[out_offset + 1] = octahedron_z * 0.5 + 0.5;
 }

package/src/core/geom/3d/plane/plane3_compute_plane_intersection.js

@@ -64,13 +64,14 @@ function solveIntersectingPoint(zeroCoord, A, B, p1, p2, result) {
 
     const a1 = nP1[A];
     const b1 = nP1[B];
-    const d1 = p1.constant;
+    // plane equation is dot(normal, p) + constant = 0, so the linear-system RHS is -constant
+    const d1 = -p1.constant;
 
     const nP2 = p2.normal;
 
     const a2 = nP2[A];
     const b2 = nP2[B];
-    const d2 = p2.constant;
+    const d2 = -p2.constant;
 
     const A0 = ((b2 * d1) - (b1 * d2)) / ((a1 * b2 - a2 * b1));
     const B0 = ((a1 * d2) - (a2 * d1)) / ((a1 * b2 - a2 * b1));

package/src/core/geom/3d/shape/MeshShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MeshShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/MeshShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IAKQ;;;;;OAKG;IACH,WAFU,YAAY,CAEc;IAEpC;;;;OAIG;IACH,SAFU,WAAW,CAEY;IAEjC;;;;;;;OAOG;IACH,UAFU,eAAe,CAEY;IAErC;;;;;;;;OAQG;IACH,eAFU,YAAY,CAEkB;IAExC;;;;;;OAMG;IACH,SAFU,GAAG,CAEW;IAExB;;;;;OAKG;IACH,eAAkD;IAElD;;;;;OAKG;IACH,iBAAiB;IAEjB;;;;OAIG;IACH,uBAAuB;IAW3B,wCAIC;IAED;;;;;OAKG;IACH,yBAmDC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,QA0BhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAkCnB;IAED;;;;;;;;;OASG;IACH,iCAHW,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,EAAE,GAAC,YAAY,QA4C/B;IAED;;;;;;;;OAQG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAsClB;IAED;;;;;;;;;OASG;IACH,sCAJW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,gBACK,MAAM,QAuB3B;IAED;;;;;;OAMG;IACH,0CAJW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAiBlB;IAED;;;;;;OAMG;IACH,cAHW,WAAW,GACT,OAAO,CAanB;IAkBL;;;;OAIG;IACH,wBAFU,OAAO,CAEkB;CAPlC;gCAje+B,sBAAsB;gCADtB,kCAAkC;oBAJ9C,2BAA2B"}
+{"version":3,"file":"MeshShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/MeshShape3D.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;IAKQ;;;;;OAKG;IACH,WAFU,YAAY,CAEc;IAEpC;;;;OAIG;IACH,SAFU,WAAW,CAEY;IAEjC;;;;;;;OAOG;IACH,UAFU,eAAe,CAEY;IAErC;;;;;;;;OAQG;IACH,eAFU,YAAY,CAEkB;IAExC;;;;;;OAMG;IACH,SAFU,GAAG,CAEW;IAExB;;;;;OAKG;IACH,eAAkD;IAElD;;;;;OAKG;IACH,iBAAiB;IAEjB;;;;OAIG;IACH,uBAAuB;IAW3B,wCAIC;IAED;;;;;OAKG;IACH,yBAmDC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBANW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,eACN,MAAM,eACN,MAAM,eACN,MAAM,QA0BhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,sBAHW,MAAM,EAAE,GAAC,YAAY,GACnB,OAAO,CAyCnB;IAED;;;;;;;;;OASG;IACH,iCAHW,MAAM,EAAE,GAAC,YAAY,aACrB,MAAM,EAAE,GAAC,YAAY,QA4C/B;IAED;;;;;;;;OAQG;IACH,gCAHW,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAsClB;IAED;;;;;;;;;OASG;IACH,sCAJW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,gBACK,MAAM,QAuB3B;IAED;;;;;;OAMG;IACH,0CAJW,MAAM,EAAE,GAAC,YAAY,SACrB,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAiBlB;IAED;;;;;;OAMG;IACH,cAHW,WAAW,GACT,OAAO,CAanB;IAkBL;;;;OAIG;IACH,wBAFU,OAAO,CAEkB;CAPlC;gCAxe+B,sBAAsB;gCADtB,kCAAkC;oBAJ9C,2BAA2B"}

package/src/core/geom/3d/shape/MeshShape3D.js

@@ -273,6 +273,13 @@ export class MeshShape3D extends AbstractShape3D {
         scratch_query_aabb[0] = px; scratch_query_aabb[1] = py; scratch_query_aabb[2] = pz;
         scratch_query_aabb[3] = px; scratch_query_aabb[4] = py; scratch_query_aabb[5] = pz;
 
+        // Ensure the shared (module-static) candidate buffer can hold every possible hit. A single point can
+        // overlap at most `count` tet AABBs, so this is a guaranteed-safe upper bound; without it the query
+        // silently truncates at the fixed 64-slot size and contains_point can miss the containing tet.
+        if (scratch_candidates.length < this.tet_mesh.count) {
+            scratch_candidates = new Uint32Array(this.tet_mesh.count);
+        }
+
         const n = bvh_query_user_data_overlaps_aabb(
             scratch_candidates, 0, this.tet_bvh, scratch_query_aabb
         );

package/src/core/geom/3d/shape/UnionShape3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA2BA;IAqII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAhJG;;;OAGG;IACH,UAFU,eAAe,EAAE,CAET;IAElB;;;;;OAKG;IACH,kCAAmC;IAEnC,qBAAsB;IACtB,qBAAuB;IACvB,uBAAyB;IAG7B,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA8CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;CAcJ;gCAxV+B,sBAAsB"}
+{"version":3,"file":"UnionShape3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/UnionShape3D.js"],"names":[],"mappings":"AA2BA;IAsII;;;;OAIG;IACH,sBAHW,eAAe,EAAE,GACf,YAAY,CAYxB;IAjJG;;;OAGG;IACH,UAFU,eAAe,EAAE,CAET;IAElB;;;;;OAKG;IACH,kCAAmC;IAEnC,qBAAsB;IACtB,qBAAuB;IACvB,uBAAyB;IAG7B,wCAgCC;IAED;;;OAGG;IACH,mCAkBC;IAED;;;OAGG;IACH,2CA+CC;IA2DD,mEAEC;IAED,6CAaC;IAED,oCAYC;IAED,kFAoDC;IAED,qGAyBC;IAED;;;;OAIG;IACH,cAHW,YAAY,GACV,OAAO,CAKnB;CAcJ;gCAzV+B,sBAAsB"}

package/src/core/geom/3d/shape/UnionShape3D.js

@@ -135,7 +135,7 @@ export class UnionShape3D extends AbstractShape3D {
 
             const child_0 = children[target_child_index];
 
-            for (j = 0; j < VOLUME_OVERLAP_ESTIMATION_SUB_TAPS; j++, i++) {
+            for (j = 0; j < VOLUME_OVERLAP_ESTIMATION_SUB_TAPS; j++) {
 
                 child_0.sample_random_point_in_volume(scratch_array, 0, random);
 
@@ -155,7 +155,8 @@ export class UnionShape3D extends AbstractShape3D {
             }
         }
 
-        this.__volume_overlap_fraction = tap_overlaps / (VOLUME_OVERLAP_ESTIMATION_TAPS);
+        // total samples taken = outer taps * sub-taps (the inner loop no longer corrupts the outer counter)
+        this.__volume_overlap_fraction = tap_overlaps / (VOLUME_OVERLAP_ESTIMATION_TAPS * VOLUME_OVERLAP_ESTIMATION_SUB_TAPS);
     }
 
     /**

package/src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape3d_voxelize_to_grid.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,gFAVW,YAAY,GAAC,MAAM,EAAE,iBAErB,YAAY,GAAC,MAAM,EAAE,QAErB,UAAU,MAEV,MAAM,MACN,MAAM,MACN,MAAM,QA6EhB"}
+{"version":3,"file":"shape3d_voxelize_to_grid.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/shape/util/shape3d_voxelize_to_grid.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,gFAVW,YAAY,GAAC,MAAM,EAAE,iBAErB,YAAY,GAAC,MAAM,EAAE,QAErB,UAAU,MAEV,MAAM,MACN,MAAM,MACN,MAAM,QAkFhB"}

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

@@ -1,148 +1,153 @@
-import { assert } from "../../../../assert.js";
-import { v3_length } from "../../../vec3/v3_length.js";
-import { v3_matrix4_multiply } from "../../../vec3/v3_matrix4_multiply.js";
-import { aabb3_matrix4_project } from "../../aabb/aabb3_matrix4_project.js";
-
-// Reusable per-call scratch — keeps the function allocation-free under repeat
-// invocations (which is the expected pattern: re-voxelize the scene every frame
-// before stepping a simulation).
-const _scratch_aabb_world = new Float32Array(6);
-const _scratch_aabb_grid = new Float32Array(6);
-const _scratch_grid_pt = new Float32Array(3);
-const _scratch_world_pt = new Float32Array(3);
-
-/**
- * Rasterize an {@link AbstractShape3D} into a cell-centered Uint8 grid mask.
- *
- * For each integer cell `(i, j, k)` in `[0, rx) × [0, ry) × [0, rz)`, the cell's
- * center is recovered as the world-space point `grid_to_world * (i, j, k)`. If
- * that point lies inside the shape — or close enough to its surface (see below)
- * — the corresponding cell in `grid` is written as `1`.
- *
- * The grid is **not** cleared first. Cells outside the shape (and outside its
- * proximity band) are left exactly as they were, which lets the caller compose
- * multiple shapes into the same buffer by calling this function repeatedly. The
- * caller is responsible for `grid.fill(0)` if a fresh mask is desired.
- *
- * **Proximity test.** A cell whose centre is outside the shape is still marked
- * solid if `signed_distance_at_point(centre) < half_cell_diagonal`. This catches
- * features that pass through a cell without containing its centre — e.g. a thin
- * sheet bisecting a cubic cell at 45°. The threshold is the largest possible
- * distance from a cell's centre to any point inside the cell, so any shape that
- * intersects the cell at all is captured. Cheap fast path: `contains_point` is
- * tested first (no sqrt for most shapes); the more expensive signed-distance
- * call only runs for cells whose centre is outside.
- *
- * **Volume guard.** If the shape's total volume is less than half the volume of
- * a single cell, the function returns immediately without writing anything. A
- * shape that small can't be meaningfully represented as a unit-cell solid — the
- * obstacle would end up perceptibly larger than the shape itself. Callers with
- * sub-cell shapes should either refine the grid or use a different
- * representation (e.g. a point-velocity effector).
- *
- * **Coord space.** `shape.contains_point` / `signed_distance_at_point` are
- * called with **world** coordinates. For shapes that have their own local frame
- * (e.g. `UnitSphereShape3D` centred at the origin), wrap them in a
- * {@link TransformedShape3D} so they sit at the right world position before
- * passing in. The voxelizer is otherwise agnostic to how the shape interprets
- * its inputs.
- *
- * **Grid orientation.** `world_to_grid` and `grid_to_world` are full 4×4
- * column-major affines, so the grid can be translated, scaled, or rotated in
- * world space; the algorithm makes no axis-aligned assumption. Cell size per
- * axis is recovered from the column lengths of `grid_to_world`, which is exact
- * for orthogonal grids and an overestimate of cell volume for skewed ones — the
- * latter only widens the volume-guard threshold, which is conservative.
- *
- * Designed to feed e.g. a fluid simulator's solid mask, but lives outside any
- * specific package: anything that needs "rasterize a shape into a cell-centered
- * boolean grid" can use it.
- *
- * @param {AbstractShape3D} shape  shape to voxelize; `contains_point` and
- *     `signed_distance_at_point` are invoked with world-space points.
- * @param {Float32Array|number[]} world_to_grid  column-major 4×4 affine;
- *     world point → grid (cell-index) coords.
- * @param {Float32Array|number[]} grid_to_world  column-major 4×4 affine;
- *     grid (cell-index) coords → world cell center.
- * @param {Uint8Array} grid  output mask, length must be ≥ `rx * ry * rz`.
- *     Cells that don't pass the test are left untouched.
- * @param {number} rx  positive integer.
- * @param {number} ry  positive integer.
- * @param {number} rz  positive integer.
- */
-export function shape3d_voxelize_to_grid(shape, world_to_grid, grid_to_world, grid, rx, ry, rz) {
-    assert.defined(shape, "shape");
-    assert.isArrayLike(world_to_grid, "world_to_grid");
-    assert.greaterThanOrEqual(world_to_grid.length, 16, "world_to_grid.length");
-    assert.isArrayLike(grid_to_world, "grid_to_world");
-    assert.greaterThanOrEqual(grid_to_world.length, 16, "grid_to_world.length");
-    assert.defined(grid, "grid");
-    assert.isPositiveInteger(rx, "rx");
-    assert.isPositiveInteger(ry, "ry");
-    assert.isPositiveInteger(rz, "rz");
-    assert.greaterThanOrEqual(grid.length, rx * ry * rz, "grid.length");
-
-    // Recover per-axis cell size from the column lengths of grid_to_world. For
-    // an axis-aligned uniform grid these are just the cell spacings; for an
-    // oriented grid they're the post-rotation lengths, which still bound the
-    // cell extent correctly.
-    const cs_x = v3_length(grid_to_world[0], grid_to_world[1], grid_to_world[2]);
-    const cs_y = v3_length(grid_to_world[4], grid_to_world[5], grid_to_world[6]);
-    const cs_z = v3_length(grid_to_world[8], grid_to_world[9], grid_to_world[10]);
-    const cell_volume = cs_x * cs_y * cs_z;
-
-    // Volume guard. See docstring — sub-cell shapes are skipped wholesale.
-    if (shape.volume < cell_volume * 0.5) {
-        return;
-    }
-
-    // Proximity threshold = half the cell diagonal in world units. Any shape
-    // whose surface comes within this radius of a cell centre might intersect
-    // the cell; this is the tightest threshold that won't miss grazing
-    // features.
-    const proximity_threshold = Math.sqrt(cs_x * cs_x + cs_y * cs_y + cs_z * cs_z) * 0.5;
-
-    // Restrict iteration to the shape's bounding box transformed into grid
-    // space, with a 1-cell expansion to cover the proximity band (the band is
-    // at most ~0.87 cells wide, so +1 cell on each side fully contains it).
-    shape.compute_bounding_box(_scratch_aabb_world);
-    aabb3_matrix4_project(_scratch_aabb_grid, _scratch_aabb_world, world_to_grid);
-
-    const i_min = Math.max(0, Math.floor(_scratch_aabb_grid[0]) - 1);
-    const j_min = Math.max(0, Math.floor(_scratch_aabb_grid[1]) - 1);
-    const k_min = Math.max(0, Math.floor(_scratch_aabb_grid[2]) - 1);
-    const i_max = Math.min(rx - 1, Math.ceil(_scratch_aabb_grid[3]) + 1);
-    const j_max = Math.min(ry - 1, Math.ceil(_scratch_aabb_grid[4]) + 1);
-    const k_max = Math.min(rz - 1, Math.ceil(_scratch_aabb_grid[5]) + 1);
-
-    // Bounding box lies entirely outside the grid → nothing to do.
-    if (i_min > i_max || j_min > j_max || k_min > k_max) {
-        return;
-    }
-
-    const rx_ry = rx * ry;
-    const grid_pt = _scratch_grid_pt;
-    const world_pt = _scratch_world_pt;
-
-    for (let k = k_min; k <= k_max; k++) {
-        grid_pt[2] = k;
-        const k_offset = k * rx_ry;
-        for (let j = j_min; j <= j_max; j++) {
-            grid_pt[1] = j;
-            const j_offset = k_offset + j * rx;
-            for (let i = i_min; i <= i_max; i++) {
-                grid_pt[0] = i;
-                v3_matrix4_multiply(world_pt, 0, grid_pt, 0, grid_to_world);
-
-                // contains_point is the cheap fast path (no sqrt for most
-                // shapes). Only fall through to signed_distance for cells whose
-                // centre is outside the shape, where we still might mark them
-                // for the proximity rule.
-                if (shape.contains_point(world_pt)
-                    || shape.signed_distance_at_point(world_pt) < proximity_threshold) {
-                    grid[j_offset + i] = 1;
-                }
-            }
-        }
-    }
-}
+import { assert } from "../../../../assert.js";
+import { v3_length } from "../../../vec3/v3_length.js";
+import { v3_matrix4_multiply } from "../../../vec3/v3_matrix4_multiply.js";
+import { aabb3_matrix4_project } from "../../aabb/aabb3_matrix4_project.js";
+
+// Reusable per-call scratch — keeps the function allocation-free under repeat
+// invocations (which is the expected pattern: re-voxelize the scene every frame
+// before stepping a simulation).
+const _scratch_aabb_world = new Float32Array(6);
+const _scratch_aabb_grid = new Float32Array(6);
+const _scratch_grid_pt = new Float32Array(3);
+const _scratch_world_pt = new Float32Array(3);
+
+/**
+ * Rasterize an {@link AbstractShape3D} into a cell-centered Uint8 grid mask.
+ *
+ * For each integer cell `(i, j, k)` in `[0, rx) × [0, ry) × [0, rz)`, the cell's
+ * center is recovered as the world-space point `grid_to_world * (i, j, k)`. If
+ * that point lies inside the shape — or close enough to its surface (see below)
+ * — the corresponding cell in `grid` is written as `1`.
+ *
+ * The grid is **not** cleared first. Cells outside the shape (and outside its
+ * proximity band) are left exactly as they were, which lets the caller compose
+ * multiple shapes into the same buffer by calling this function repeatedly. The
+ * caller is responsible for `grid.fill(0)` if a fresh mask is desired.
+ *
+ * **Proximity test.** A cell whose centre is outside the shape is still marked
+ * solid if `signed_distance_at_point(centre) < half_cell_diagonal`. This catches
+ * features that pass through a cell without containing its centre — e.g. a thin
+ * sheet bisecting a cubic cell at 45°. The threshold is the largest possible
+ * distance from a cell's centre to any point inside the cell, so any shape that
+ * intersects the cell at all is captured. Cheap fast path: `contains_point` is
+ * tested first (no sqrt for most shapes); the more expensive signed-distance
+ * call only runs for cells whose centre is outside.
+ *
+ * **Volume guard.** If the shape's total volume is less than half the volume of
+ * a single cell, the function returns immediately without writing anything. A
+ * shape that small can't be meaningfully represented as a unit-cell solid — the
+ * obstacle would end up perceptibly larger than the shape itself. Callers with
+ * sub-cell shapes should either refine the grid or use a different
+ * representation (e.g. a point-velocity effector).
+ *
+ * **Coord space.** `shape.contains_point` / `signed_distance_at_point` are
+ * called with **world** coordinates. For shapes that have their own local frame
+ * (e.g. `UnitSphereShape3D` centred at the origin), wrap them in a
+ * {@link TransformedShape3D} so they sit at the right world position before
+ * passing in. The voxelizer is otherwise agnostic to how the shape interprets
+ * its inputs.
+ *
+ * **Grid orientation.** `world_to_grid` and `grid_to_world` are full 4×4
+ * column-major affines, so the grid can be translated, scaled, or rotated in
+ * world space; the algorithm makes no axis-aligned assumption. Cell size per
+ * axis is recovered from the column lengths of `grid_to_world`, which is exact
+ * for orthogonal grids and an overestimate of cell volume for skewed ones — the
+ * latter only widens the volume-guard threshold, which is conservative.
+ *
+ * Designed to feed e.g. a fluid simulator's solid mask, but lives outside any
+ * specific package: anything that needs "rasterize a shape into a cell-centered
+ * boolean grid" can use it.
+ *
+ * @param {AbstractShape3D} shape  shape to voxelize; `contains_point` and
+ *     `signed_distance_at_point` are invoked with world-space points.
+ * @param {Float32Array|number[]} world_to_grid  column-major 4×4 affine;
+ *     world point → grid (cell-index) coords.
+ * @param {Float32Array|number[]} grid_to_world  column-major 4×4 affine;
+ *     grid (cell-index) coords → world cell center.
+ * @param {Uint8Array} grid  output mask, length must be ≥ `rx * ry * rz`.
+ *     Cells that don't pass the test are left untouched.
+ * @param {number} rx  positive integer.
+ * @param {number} ry  positive integer.
+ * @param {number} rz  positive integer.
+ */
+export function shape3d_voxelize_to_grid(shape, world_to_grid, grid_to_world, grid, rx, ry, rz) {
+    assert.defined(shape, "shape");
+    assert.isArrayLike(world_to_grid, "world_to_grid");
+    assert.greaterThanOrEqual(world_to_grid.length, 16, "world_to_grid.length");
+    assert.isArrayLike(grid_to_world, "grid_to_world");
+    assert.greaterThanOrEqual(grid_to_world.length, 16, "grid_to_world.length");
+    assert.defined(grid, "grid");
+    assert.isPositiveInteger(rx, "rx");
+    assert.isPositiveInteger(ry, "ry");
+    assert.isPositiveInteger(rz, "rz");
+    assert.greaterThanOrEqual(grid.length, rx * ry * rz, "grid.length");
+
+    // Recover per-axis cell size from the column lengths of grid_to_world. For
+    // an axis-aligned uniform grid these are just the cell spacings; for an
+    // oriented grid they're the post-rotation lengths, which still bound the
+    // cell extent correctly.
+    const cs_x = v3_length(grid_to_world[0], grid_to_world[1], grid_to_world[2]);
+    const cs_y = v3_length(grid_to_world[4], grid_to_world[5], grid_to_world[6]);
+    const cs_z = v3_length(grid_to_world[8], grid_to_world[9], grid_to_world[10]);
+    const cell_volume = cs_x * cs_y * cs_z;
+
+    // Volume guard. See docstring — sub-cell shapes are skipped wholesale.
+    if (shape.volume < cell_volume * 0.5) {
+        return;
+    }
+
+    // Proximity threshold = half the cell diagonal in world units. Any shape
+    // whose surface comes within this radius of a cell centre might intersect
+    // the cell; this is the tightest threshold that won't miss grazing
+    // features.
+    const proximity_threshold = Math.sqrt(cs_x * cs_x + cs_y * cs_y + cs_z * cs_z) * 0.5;
+
+    // Restrict iteration to the shape's bounding box transformed into grid space, expanded by the proximity
+    // band. The band is `proximity_threshold` WORLD units wide, which is a different number of cells along each
+    // axis when the grid is anisotropic/skewed, so pad per-axis by ceil(threshold / cell_size). A fixed +1 cell
+    // under-covers the band along thin axes and would miss grazing features there.
+    shape.compute_bounding_box(_scratch_aabb_world);
+    aabb3_matrix4_project(_scratch_aabb_grid, _scratch_aabb_world, world_to_grid);
+
+    const pad_i = Math.ceil(proximity_threshold / cs_x);
+    const pad_j = Math.ceil(proximity_threshold / cs_y);
+    const pad_k = Math.ceil(proximity_threshold / cs_z);
+
+    const i_min = Math.max(0, Math.floor(_scratch_aabb_grid[0]) - pad_i);
+    const j_min = Math.max(0, Math.floor(_scratch_aabb_grid[1]) - pad_j);
+    const k_min = Math.max(0, Math.floor(_scratch_aabb_grid[2]) - pad_k);
+    const i_max = Math.min(rx - 1, Math.ceil(_scratch_aabb_grid[3]) + pad_i);
+    const j_max = Math.min(ry - 1, Math.ceil(_scratch_aabb_grid[4]) + pad_j);
+    const k_max = Math.min(rz - 1, Math.ceil(_scratch_aabb_grid[5]) + pad_k);
+
+    // Bounding box lies entirely outside the grid → nothing to do.
+    if (i_min > i_max || j_min > j_max || k_min > k_max) {
+        return;
+    }
+
+    const rx_ry = rx * ry;
+    const grid_pt = _scratch_grid_pt;
+    const world_pt = _scratch_world_pt;
+
+    for (let k = k_min; k <= k_max; k++) {
+        grid_pt[2] = k;
+        const k_offset = k * rx_ry;
+        for (let j = j_min; j <= j_max; j++) {
+            grid_pt[1] = j;
+            const j_offset = k_offset + j * rx;
+            for (let i = i_min; i <= i_max; i++) {
+                grid_pt[0] = i;
+                v3_matrix4_multiply(world_pt, 0, grid_pt, 0, grid_to_world);
+
+                // contains_point is the cheap fast path (no sqrt for most
+                // shapes). Only fall through to signed_distance for cells whose
+                // centre is outside the shape, where we still might mark them
+                // for the proximity rule.
+                if (shape.contains_point(world_pt)
+                    || shape.signed_distance_at_point(world_pt) < proximity_threshold) {
+                    grid[j_offset + i] = 1;
+                }
+            }
+        }
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"sh3_dering_optimize_positive.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js"],"names":[],"mappings":"AA0SA;;;;;;;GAOG;AACH,qDANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,oBAClC,MAAM,oBACN,MAAM,QAIhB"}
+{"version":3,"file":"sh3_dering_optimize_positive.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js"],"names":[],"mappings":"AAiTA;;;;;;;GAOG;AACH,qDANW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,iBAClC,MAAM,aACN,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,oBAClC,MAAM,oBACN,MAAM,QAIhB"}

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

@@ -249,6 +249,13 @@ function windowSH(
 
                 const m = 0.5 * (l + r);
 
+                // Re-window the ORIGINAL coefficients on every iteration. windowing() mutates scratch_sh3 in
+                // place, so without re-filling we would cumulatively window an already-windowed buffer; the
+                // reference (Filament) windows a fresh copy each time (pass-by-value).
+                for (let b = 0; b < numBands * numBands; b++) {
+                    scratch_sh3[b] = input[input_offset + b * channel_count + channel];
+                }
+
                 windowing(scratch_sh3, m, numBands);
 
                 if (sh3_min(scratch_sh3) < 0) {

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

@@ -1 +1 @@
-{"version":3,"file":"sh3_sample_by_direction.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_sample_by_direction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,gDARW,MAAM,EAAE,iBACR,MAAM,aACN,MAAM,EAAE,oBACR,MAAM,mBACN,MAAM,aACN,MAAM,EAAE,oBACR,MAAM,QAmChB"}
+{"version":3,"file":"sh3_sample_by_direction.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/sphere/harmonics/sh3_sample_by_direction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,gDARW,MAAM,EAAE,iBACR,MAAM,aACN,MAAM,EAAE,oBACR,MAAM,mBACN,MAAM,aACN,MAAM,EAAE,oBACR,MAAM,QAsChB"}

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

@@ -27,22 +27,25 @@ export function sh3_sample_by_direction(
     let channel_value;
 
     for (let i = 0; i < dimension_count; i++) {
-        const offset = harmonics_offset + dimension_count * i;
+        // coefficients are interleaved by band: the value for (band k, dimension i) lives at
+        // harmonics_offset + dimension_count * k + i (matching sh3_sample_irradiance_by_direction /
+        // sh3_vector_accumulate). The previous `dimension_count * i + band` indexing overlapped channels.
+        const base = harmonics_offset + i;
 
         // band 0
-        channel_value = harmonics[offset] * SH3_COEFFICIENTS[0];
+        channel_value = harmonics[base] * SH3_COEFFICIENTS[0];
 
         // band 1
-        channel_value += harmonics[offset + 1] * SH3_COEFFICIENTS[1] * y;
-        channel_value += harmonics[offset + 2] * SH3_COEFFICIENTS[2] * z;
-        channel_value += harmonics[offset + 3] * SH3_COEFFICIENTS[3] * x;
+        channel_value += harmonics[base + dimension_count] * SH3_COEFFICIENTS[1] * y;
+        channel_value += harmonics[base + dimension_count * 2] * SH3_COEFFICIENTS[2] * z;
+        channel_value += harmonics[base + dimension_count * 3] * SH3_COEFFICIENTS[3] * x;
 
         // band 2
-        channel_value += harmonics[offset + 4] * SH3_COEFFICIENTS[4] * (x * y);
-        channel_value += harmonics[offset + 5] * SH3_COEFFICIENTS[5] * (y * z);
-        channel_value += harmonics[offset + 6] * SH3_COEFFICIENTS[6] * (3.0 * z * z - 1.0);
-        channel_value += harmonics[offset + 7] * SH3_COEFFICIENTS[7] * (x * z);
-        channel_value += harmonics[offset + 8] * SH3_COEFFICIENTS[8] * (x * x - y * y);
+        channel_value += harmonics[base + dimension_count * 4] * SH3_COEFFICIENTS[4] * (x * y);
+        channel_value += harmonics[base + dimension_count * 5] * SH3_COEFFICIENTS[5] * (y * z);
+        channel_value += harmonics[base + dimension_count * 6] * SH3_COEFFICIENTS[6] * (3.0 * z * z - 1.0);
+        channel_value += harmonics[base + dimension_count * 7] * SH3_COEFFICIENTS[7] * (x * z);
+        channel_value += harmonics[base + dimension_count * 8] * SH3_COEFFICIENTS[8] * (x * x - y * y);
 
         // write out
         result[result_offset + i] = channel_value;

package/src/core/geom/3d/sphere/sphere_projected_sphere_radius_sqr.d.ts

@@ -1,5 +1,5 @@
 /**
- *
+ * @see sphere_project
  * @param {number} fl
  * @param {number[]} matrix
  * @param {number[]} sph

package/src/core/geom/3d/sphere/sphere_projected_sphere_radius_sqr.js

@@ -3,7 +3,7 @@ import { v4_multiply_mat4 } from "../../vec4/v4_multiply_mat4.js";
 
 const v4 = [];
 /**
- *
+ * @see sphere_project
  * @param {number} fl
  * @param {number[]} matrix
  * @param {number[]} sph
@@ -31,7 +31,7 @@ export function sphere_projected_sphere_radius_sqr(fl, matrix, sph) {
     const y = v4_y;
     const z = v4_z;
 
-    const z2 = z * x;
+    const z2 = z * z;
 
     const l2 = v3_dot(x, y, z, x, y, z);
 

package/src/core/geom/3d/sphere/sphere_raycast.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Ray ↔ sphere intersection in the sphere's LOCAL frame: the sphere is centred
+ * at the origin with radius `r`, and the ray is expressed in that frame. Returns
+ * the hit distance `t` along the ray and writes the outward unit surface normal
+ * into `outNormal[outOffset .. outOffset+2]`.
+ *
+ * Conventions (shared with {@link box3_raycast} / {@link capsule_raycast}):
+ *  - the ray direction is assumed UNIT length, so `t` is a true distance;
+ *  - the first surface crossing at or after the origin within `tMax` is
+ *    returned; a ray starting INSIDE the sphere returns its exit crossing;
+ *  - on a miss the function returns `Infinity` and leaves `outNormal` untouched.
+ *
+ * Distinct from {@link sphere_intersects_ray}, which is a boolean predicate;
+ * this yields the distance and the surface normal — what a raycast query /
+ * narrowphase needs.
+ *
+ * @param {Float64Array|number[]} outNormal destination for the unit normal
+ * @param {number} outOffset offset into `outNormal` (3 floats are written)
+ * @param {number} ox ray origin x (local)
+ * @param {number} oy ray origin y (local)
+ * @param {number} oz ray origin z (local)
+ * @param {number} dx ray direction x (local, unit)
+ * @param {number} dy ray direction y (local, unit)
+ * @param {number} dz ray direction z (local, unit)
+ * @param {number} tMax maximum ray distance
+ * @param {number} r sphere radius
+ * @returns {number} hit distance `t`, or `Infinity` on a miss
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function sphere_raycast(outNormal: Float64Array | number[], outOffset: number, ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, tMax: number, r: number): number;
+//# sourceMappingURL=sphere_raycast.d.ts.map

package/src/core/geom/3d/sphere/sphere_raycast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sphere_raycast.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/sphere/sphere_raycast.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,0CAfW,YAAY,GAAC,MAAM,EAAE,aACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,KACN,MAAM,GACJ,MAAM,CAoBlB"}