@woosh/meep-engine 2.155.0 → 2.157.0

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"}

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

@@ -0,0 +1,47 @@
+/**
+ * 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, outOffset, ox, oy, oz, dx, dy, dz, tMax, r) {
+    // |o + t·d|² = r², d unit → t² + 2(o·d)t + (|o|² − r²) = 0.
+    const b = ox * dx + oy * dy + oz * dz;
+    const c = ox * ox + oy * oy + oz * oz - r * r;
+    const disc = b * b - c;
+    if (disc < 0) return Infinity;
+    const sq = Math.sqrt(disc);
+    let t = -b - sq;             // near root (entry)
+    if (t < 0) t = -b + sq;      // origin inside the sphere → far root (exit)
+    if (t < 0 || t > tMax) return Infinity;
+    const inv = 1 / r;
+    outNormal[outOffset] = (ox + dx * t) * inv;
+    outNormal[outOffset + 1] = (oy + dy * t) * inv;
+    outNormal[outOffset + 2] = (oz + dz * t) * inv;
+    return t;
+}

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Write the face-adjacent neighbour tetrahedra of `tet_id` into `out`,
+ * non-allocating, and return how many were written.
+ *
+ * A tetrahedron has up to four neighbours — one across each face — and a face on
+ * the mesh surface has none. {@link TetrahedralMesh} stores this adjacency
+ * directly: neighbour slot `i` is the tet across the face opposite vertex `i`,
+ * encoded as `[tet_id:30][opposite_corner:2]` (or {@link INVALID_NEIGHBOUR} for a
+ * surface face). This decodes the tet ids (`encoded >>> 2`, an UNSIGNED shift so
+ * 30-bit ids near the top of the range survive) and skips surface faces, packing
+ * the survivors contiguously from `out_offset`.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {Int32Array|Uint32Array|number[]} out destination for neighbour tet ids
+ *   (needs room for up to 4 entries from `out_offset`)
+ * @param {number} out_offset offset into `out` at which to start writing
+ * @param {number} tet_id tetrahedron whose neighbours to read
+ * @returns {number} number of neighbours written (0..4); surface faces are skipped
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function tetrahedral_mesh_tet_get_neighbours(mesh: TetrahedralMesh, out: Int32Array | Uint32Array | number[], out_offset: number, tet_id: number): number;
+//# sourceMappingURL=tetrahedral_mesh_tet_get_neighbours.d.ts.map

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_tet_get_neighbours.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,gFATW,UAAU,GAAC,WAAW,GAAC,MAAM,EAAE,cAE/B,MAAM,UACN,MAAM,GACJ,MAAM,CAkBlB"}

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_tet_get_neighbours.js

@@ -0,0 +1,39 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * Write the face-adjacent neighbour tetrahedra of `tet_id` into `out`,
+ * non-allocating, and return how many were written.
+ *
+ * A tetrahedron has up to four neighbours — one across each face — and a face on
+ * the mesh surface has none. {@link TetrahedralMesh} stores this adjacency
+ * directly: neighbour slot `i` is the tet across the face opposite vertex `i`,
+ * encoded as `[tet_id:30][opposite_corner:2]` (or {@link INVALID_NEIGHBOUR} for a
+ * surface face). This decodes the tet ids (`encoded >>> 2`, an UNSIGNED shift so
+ * 30-bit ids near the top of the range survive) and skips surface faces, packing
+ * the survivors contiguously from `out_offset`.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {Int32Array|Uint32Array|number[]} out destination for neighbour tet ids
+ *   (needs room for up to 4 entries from `out_offset`)
+ * @param {number} out_offset offset into `out` at which to start writing
+ * @param {number} tet_id tetrahedron whose neighbours to read
+ * @returns {number} number of neighbours written (0..4); surface faces are skipped
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function tetrahedral_mesh_tet_get_neighbours(mesh, out, out_offset, tet_id) {
+    assert.defined(mesh, 'mesh');
+    assert.equal(mesh.isTetrahedralMesh, true, 'mesh.isTetrahedralMesh !== true');
+
+    let count = 0;
+    for (let f = 0; f < 4; f++) {
+        const encoded = mesh.getNeighbour(tet_id, f);
+        if (encoded !== INVALID_NEIGHBOUR) {
+            out[out_offset + count] = encoded >>> 2;
+            count++;
+        }
+    }
+    return count;
+}

package/src/core/geom/3d/tetrahedra/triangle/trace_triangular_depth_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace_triangular_depth_map.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/tetrahedra/triangle/trace_triangular_depth_map.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,mDATW,WAAW,iBACX,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,UACrB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,gCA2GhB"}
+{"version":3,"file":"trace_triangular_depth_map.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/tetrahedra/triangle/trace_triangular_depth_map.js"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,mDATW,WAAW,iBACX,MAAM,UACN,MAAM,EAAE,GAAC,YAAY,UACrB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,gCA6GhB"}

package/src/core/geom/3d/tetrahedra/triangle/trace_triangular_depth_map.js

@@ -112,8 +112,10 @@ export function trace_triangular_depth_map(
 
             const depth_normalized = depth / distance_to_target;
 
-            // depth is quantized to closer value to be conservative
-            const depth_quantized = Math.floor(depth_normalized / 255);
+            // depth (normalized to [0,1]) is quantized to an 8-bit value, flooring to stay conservative (bias
+            // toward the closer occluder). Multiply by 255 to map into the [0,255] byte range, and clamp to guard
+            // against floating-point overshoot of 1.0 which would otherwise spill bits into the adjacent byte.
+            const depth_quantized = Math.min(255, Math.max(0, Math.floor(depth_normalized * 255)));
 
             result[result_offset + encoded_index_0] |= depth_quantized << (encoded_index_1 * 8);
         }

package/src/core/geom/3d/topology/bounds/computeTriangleClusterNormalBoundingCone.js

@@ -19,7 +19,7 @@ export function computeTriangleClusterNormalBoundingCone(result, faces) {
     for (let face of faces) {
 
         const face_normal = face.normal;
-        if (face_normal[0] === 0 && face_normal[1] === 0 && face_normal[1] === 0) {
+        if (face_normal[0] === 0 && face_normal[1] === 0 && face_normal[2] === 0) {
             // skip
             continue;
         }
@@ -70,8 +70,8 @@ export function computeTriangleClusterNormalBoundingCone(result, faces) {
         const i3 = i * 3;
 
         const normal_x = normal_data[i3];
-        const normal_y = normal_data[i3];
-        const normal_z = normal_data[i3];
+        const normal_y = normal_data[i3 + 1];
+        const normal_z = normal_data[i3 + 2];
 
         const angle = v3_angle_between(
             normal_x, normal_y, normal_z,

package/src/core/geom/3d/topology/simplify/decimate_edge_collapse_snap.js

@@ -244,7 +244,7 @@ export function decimate_edge_collapse_snap(
 
             const topoEdge = edges[j];
 
-            if (array_get_index_in_range(scratch_edges, topoEdge, 0, dirty_edge_count) === -1) {
+            if (array_get_index_in_range(scratch_edges, topoEdge, 0, dirty_edge_count - 1) === -1) {
                 scratch_edges[dirty_edge_count++] = topoEdge;
             }
         }

package/src/core/geom/3d/topology/tm_vertex_compute_normal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tm_vertex_compute_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/topology/tm_vertex_compute_normal.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,iDAJW,MAAM,EAAE,iBACR,MAAM,4BAgChB"}
+{"version":3,"file":"tm_vertex_compute_normal.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/topology/tm_vertex_compute_normal.js"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,iDAJW,MAAM,EAAE,iBACR,MAAM,4BAkChB"}

package/src/core/geom/3d/topology/tm_vertex_compute_normal.js

@@ -30,8 +30,10 @@ export function tm_vertex_compute_normal(result, result_offset, vertex) {
         _z += scratch_v3_0[2];
     }
 
-    // re-normalize
-    const len_inv = v3_length(_x,_y,_z);
+    // re-normalize: divide by length (multiply by its reciprocal), not by the length itself.
+    // Guard the fully-cancelling case (sum of face normals == 0) to avoid NaN.
+    const len = v3_length(_x, _y, _z);
+    const len_inv = len !== 0 ? 1 / len : 0;
 
     _x *= len_inv;
     _y *= len_inv;

package/src/core/geom/3d/util/make_justified_point_grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_justified_point_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/util/make_justified_point_grid.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,iEAJW,MAAM,kBAEJ,MAAM,CAyBlB"}
+{"version":3,"file":"make_justified_point_grid.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/util/make_justified_point_grid.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,iEAJW,MAAM,kBAEJ,MAAM,CAiClB"}