@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,148 @@
+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;
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Tetrahedralize the volume enclosed by a triangle surface mesh. The result
+ * is a Delaunay tetrahedral mesh whose vertices are the surface's vertices
+ * (plus any hole-closing centroids and any opt-in interior Steiner points)
+ * and whose enclosed region approximates the surface's interior.
+ *
+ * The input is treated as airtight; any boundary holes are closed up front
+ * by fanning each boundary loop around its centroid (a Steiner vertex is
+ * added at each hole's centroid). The closed surface then drives the
+ * Delaunay input set and the inside/outside classification used to carve
+ * away exterior tets — non-convex shapes (e.g., Stanford bunny) are
+ * supported.
+ *
+ * The caller's surface mesh is not mutated; a clone is taken internally.
+ *
+ * Interior Steiner points are OFF by default. Pass a positive
+ * `interior_steiner_cells_per_dim` (e.g. ⌈cbrt(surface_vert_count)⌉) to
+ * fill the volume with interior detail — useful for FEM / simulation where
+ * thin sliver tets and surface-bound vertex distribution would hurt
+ * conditioning. Note that interior Steiner does NOT reduce the carving's
+ * volume gap (that comes from tets straddling the surface, and adding
+ * interior points doesn't shrink those); a tighter volume gap needs
+ * surface subdivision or true constraint-recovery, neither of which is
+ * implemented here.
+ *
+ * Interior Steiner can also HURT total volume on pathological inputs (two
+ * solids meeting at a single vertex, very thin hollow shells) — the
+ * Delaunay produces bridge tets across the pinch that carry legitimate
+ * interior on each side but whose centroids land in the void and get
+ * carved. Leave Steiner off (the default) for those cases.
+ *
+ * @param {TetrahedralMesh} tet_mesh empty, populated in place
+ * @param {BinaryTopology} surface triangle surface mesh, near-airtight
+ * @param {number} [interior_steiner_cells_per_dim] grid resolution along the
+ *        longest bbox axis for interior Steiner sampling; 0 disables
+ * @returns {Float32Array} flat (x,y,z) positions array indexed by tet vertex ID
+ */
+export function compute_tetrahedral_mesh_from_surface(tet_mesh: TetrahedralMesh, surface: BinaryTopology, interior_steiner_cells_per_dim?: number): Float32Array;
+//# sourceMappingURL=compute_tetrahedral_mesh_from_surface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute_tetrahedral_mesh_from_surface.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/compute_tetrahedral_mesh_from_surface.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,2IAJW,MAAM,GAEJ,YAAY,CA8ExB"}

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

@@ -0,0 +1,147 @@
+import { assert } from "../../../assert.js";
+import {
+    bt_mesh_fuse_duplicate_edges
+} from "../topology/struct/binary/io/edge/bt_mesh_fuse_duplicate_edges.js";
+import {
+    bt_mesh_kill_short_edges
+} from "../topology/struct/binary/io/edge/bt_mesh_kill_short_edges.js";
+import {
+    bt_mesh_cleanup_faceless_references
+} from "../topology/struct/binary/io/bt_mesh_cleanup_faceless_references.js";
+import {
+    bt_mesh_close_boundary_holes
+} from "../topology/struct/binary/io/bt_mesh_close_boundary_holes.js";
+import { bt_mesh_compact } from "../topology/struct/binary/io/bt_mesh_compact.js";
+import {
+    bt_mesh_sample_interior_grid_points
+} from "../topology/struct/binary/query/bt_mesh_sample_interior_grid_points.js";
+import {
+    bt_merge_verts_by_distance
+} from "../topology/struct/binary/io/vertex/bt_merge_verts_by_distance.js";
+import { compute_delaunay_tetrahedral_mesh } from "./delaunay/compute_delaunay_tetrahedral_mesh.js";
+import {
+    tetrahedral_mesh_carve_outside_surface
+} from "./tetrahedral_mesh_carve_outside_surface.js";
+
+// Default vertex-merge tolerance for the pre-tetrahedralization weld pass.
+// Two surface vertices closer than this collapse to one; below this scale
+// they would just create degenerate sliver tets anyway. Generous enough to
+// soak up float32 round-trip drift; tight enough not to swallow real
+// detail at typical model scales (Suzanne, cube, bunny, …).
+const VERTEX_MERGE_DISTANCE = 1e-4;
+
+
+/**
+ * Tetrahedralize the volume enclosed by a triangle surface mesh. The result
+ * is a Delaunay tetrahedral mesh whose vertices are the surface's vertices
+ * (plus any hole-closing centroids and any opt-in interior Steiner points)
+ * and whose enclosed region approximates the surface's interior.
+ *
+ * The input is treated as airtight; any boundary holes are closed up front
+ * by fanning each boundary loop around its centroid (a Steiner vertex is
+ * added at each hole's centroid). The closed surface then drives the
+ * Delaunay input set and the inside/outside classification used to carve
+ * away exterior tets — non-convex shapes (e.g., Stanford bunny) are
+ * supported.
+ *
+ * The caller's surface mesh is not mutated; a clone is taken internally.
+ *
+ * Interior Steiner points are OFF by default. Pass a positive
+ * `interior_steiner_cells_per_dim` (e.g. ⌈cbrt(surface_vert_count)⌉) to
+ * fill the volume with interior detail — useful for FEM / simulation where
+ * thin sliver tets and surface-bound vertex distribution would hurt
+ * conditioning. Note that interior Steiner does NOT reduce the carving's
+ * volume gap (that comes from tets straddling the surface, and adding
+ * interior points doesn't shrink those); a tighter volume gap needs
+ * surface subdivision or true constraint-recovery, neither of which is
+ * implemented here.
+ *
+ * Interior Steiner can also HURT total volume on pathological inputs (two
+ * solids meeting at a single vertex, very thin hollow shells) — the
+ * Delaunay produces bridge tets across the pinch that carry legitimate
+ * interior on each side but whose centroids land in the void and get
+ * carved. Leave Steiner off (the default) for those cases.
+ *
+ * @param {TetrahedralMesh} tet_mesh empty, populated in place
+ * @param {BinaryTopology} surface triangle surface mesh, near-airtight
+ * @param {number} [interior_steiner_cells_per_dim] grid resolution along the
+ *        longest bbox axis for interior Steiner sampling; 0 disables
+ * @returns {Float32Array} flat (x,y,z) positions array indexed by tet vertex ID
+ */
+export function compute_tetrahedral_mesh_from_surface(
+    tet_mesh,
+    surface,
+    interior_steiner_cells_per_dim = 0
+) {
+    assert.defined(tet_mesh, 'tet_mesh');
+    assert.equal(tet_mesh.isTetrahedralMesh, true, 'tet_mesh.isTetrahedralMesh !== true');
+    assert.defined(surface, 'surface');
+    assert.equal(surface.isBinaryTopology, true, 'surface.isBinaryTopology !== true');
+
+    const working_surface = surface.clone();
+
+    // Pre-pass: kill any edge whose endpoints are within VERTEX_MERGE_DISTANCE
+    // (and any pre-existing self-loops). If left in place, bt_merge_verts_by_distance
+    // would collapse the endpoints via bt_vertex_replace, which silently
+    // produces a self-loop edge (v1 === v2). That self-loop has its v1 and v2
+    // disk pointers in the same vertex's cycle, branching the cycle in a way
+    // that hangs the downstream bt_mesh_fuse_duplicate_edges walker. Killing
+    // the short edges up front (and cleaning the faceless rubble they leave)
+    // means the merge sees no direct-edge pairs and cannot make self-loops.
+    // The existing bt_mesh_simplify pipeline uses the same safety pattern via
+    // bt_edge_kill_parallels around each edge collapse.
+    bt_mesh_kill_short_edges(working_surface, VERTEX_MERGE_DISTANCE);
+    bt_mesh_cleanup_faceless_references(working_surface);
+
+    // GLTF (and most asset-pipeline outputs) duplicate per-corner attributes
+    // at smoothing/UV splits, so a "unit cube" arrives with 24 positions
+    // instead of 8 and every face-pair edge ends up as a boundary edge —
+    // hole closing then chokes on figure-8 pinch vertices and we yield zero
+    // tets. Merge coincident vertices; this is a no-op on a topology that
+    // already has unique positions.
+    bt_merge_verts_by_distance(working_surface, VERTEX_MERGE_DISTANCE);
+
+    // The merge only re-points edge endpoints; it doesn't fuse the now-parallel
+    // edges that share both endpoints. Without the fuse pass, each cube corner
+    // still has duplicate edges in its disk cycle and the boundary walker
+    // still sees it as a pinch. Fuse must follow merge.
+    bt_mesh_fuse_duplicate_edges(working_surface);
+
+    // Compact removes any dangling unallocated vertex / edge slots so vertex
+    // IDs are dense (required so the flat positions array index matches the
+    // BinaryTopology vertex ID after extraction).
+    bt_mesh_compact(working_surface);
+
+    bt_mesh_close_boundary_holes(working_surface);
+
+    const surface_vertex_count = working_surface.vertices.size;
+
+    // Interior Steiner points are opt-in. Caller chooses cells_per_dim — a
+    // sensible default for FEM-style usage is roughly cbrt(surface_vert_count)
+    // (interior point spacing matches surface vertex spacing).
+    const interior_positions = interior_steiner_cells_per_dim > 0
+        ? bt_mesh_sample_interior_grid_points(working_surface, interior_steiner_cells_per_dim)
+        : new Float32Array(0);
+    const interior_count = interior_positions.length / 3;
+
+    const total_count = surface_vertex_count + interior_count;
+    const positions = new Float32Array(total_count * 3);
+
+    const coord = [0, 0, 0];
+    for (let v = 0; v < surface_vertex_count; v++) {
+        working_surface.vertex_read_coordinate(coord, 0, v);
+        positions[v * 3] = coord[0];
+        positions[v * 3 + 1] = coord[1];
+        positions[v * 3 + 2] = coord[2];
+    }
+    positions.set(interior_positions, surface_vertex_count * 3);
+
+    const ok = compute_delaunay_tetrahedral_mesh(tet_mesh, positions, total_count);
+    if (!ok) {
+        return positions;
+    }
+
+    tetrahedral_mesh_carve_outside_surface(tet_mesh, positions, working_surface);
+
+    return positions;
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Mesh-form wrapper for {@link tetrahedron_compute_quality}: fetches the 4
+ * vertex IDs of `tet` and forwards to the indexed primitive.
+ *
+ * Sibling of {@link compute_tetrahedron_volume}; same convention (the
+ * `compute_*` prefix marks the mesh-bound form, the `tetrahedron_compute_*`
+ * prefix marks the indexed primitive).
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {ArrayLike<number>} points flat (x,y,z) positions
+ * @param {number} tet
+ * @returns {number} quality in [0, 1]
+ */
+export function compute_tetrahedron_quality(mesh: TetrahedralMesh, points: ArrayLike<number>, tet: number): number;
+//# sourceMappingURL=compute_tetrahedron_quality.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compute_tetrahedron_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/compute_tetrahedron_quality.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,2EAJW,UAAU,MAAM,CAAC,OACjB,MAAM,GACJ,MAAM,CAQlB"}

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

@@ -0,0 +1,22 @@
+import { tetrahedron_compute_quality } from "./tetrahedron_compute_quality.js";
+
+/**
+ * Mesh-form wrapper for {@link tetrahedron_compute_quality}: fetches the 4
+ * vertex IDs of `tet` and forwards to the indexed primitive.
+ *
+ * Sibling of {@link compute_tetrahedron_volume}; same convention (the
+ * `compute_*` prefix marks the mesh-bound form, the `tetrahedron_compute_*`
+ * prefix marks the indexed primitive).
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {ArrayLike<number>} points flat (x,y,z) positions
+ * @param {number} tet
+ * @returns {number} quality in [0, 1]
+ */
+export function compute_tetrahedron_quality(mesh, points, tet) {
+    const a = mesh.getVertexIndex(tet, 0);
+    const b = mesh.getVertexIndex(tet, 1);
+    const c = mesh.getVertexIndex(tet, 2);
+    const d = mesh.getVertexIndex(tet, 3);
+    return tetrahedron_compute_quality(points, a, b, c, d);
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"prototype_tetrahedrize_mesh.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/prototype_tetrahedrize_mesh.js"],"names":[],"mappings":""}