@woosh/meep-engine 2.138.19 → 2.139.0

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

@@ -0,0 +1,365 @@
+import { assert } from "../../../assert.js";
+import { compute_tetrahedron_quality } from "./compute_tetrahedron_quality.js";
+import {
+    tetrahedral_mesh_find_tets_around_edge
+} from "./tetrahedral_mesh_find_tets_around_edge.js";
+import {
+    tetrahedral_mesh_find_tets_attached_to_vertex
+} from "./tetrahedral_mesh_find_tets_attached_to_vertex.js";
+import { tetrahedral_mesh_flip_23 } from "./tetrahedral_mesh_flip_23.js";
+import { tetrahedral_mesh_flip_32 } from "./tetrahedral_mesh_flip_32.js";
+import {
+    tetrahedral_mesh_smooth_vertex
+} from "./tetrahedral_mesh_smooth_vertex.js";
+import {
+    tetrahedral_mesh_vertex_is_boundary
+} from "./tetrahedral_mesh_vertex_is_boundary.js";
+import { tetrahedron_compute_quality } from "./tetrahedron_compute_quality.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+// Face-vertex layout for a positively-oriented tet (identical to the
+// table inside tetrahedral_mesh_flip_23.js). Inlined here so we can score
+// a hypothetical 2-3 flip without doing-and-undoing it on the live mesh.
+const FACE_VERTICES_BY_OPPOSITE = [
+    [1, 3, 2],
+    [0, 2, 3],
+    [0, 3, 1],
+    [0, 1, 2],
+];
+
+// Scratch for the 2-3 / 3-2 flip out-parameters and for collecting tets
+// during local quality re-evaluation. Module-level — the driver is not
+// re-entrant.
+const scratch_out_23 = new Uint32Array(3);
+const scratch_out_32 = new Uint32Array(2);
+const scratch_edge_ring = new Array(16);
+const scratch_ring_closed = [0];
+let scratch_local_tets = new Array(64);
+
+// The 6 unique vertex-pair (i, j) slots in a 4-vertex tet, enumerating
+// every edge once. Used to iterate the 6 edges of a candidate tet during
+// 3-2 flip search.
+const EDGE_SLOT_PAIRS = [
+    [0, 1], [0, 2], [0, 3], [1, 2], [1, 3], [2, 3],
+];
+
+/**
+ * Driver: improve the shape quality of an existing tetrahedral mesh by
+ * locally smoothing low-quality tets and applying 2-3 / 3-2 flips that
+ * monotonically increase the per-tet minimum quality.
+ *
+ * Algorithm — one pass:
+ *   1. Scan every live tet, compute its radius-ratio quality.
+ *   2. For each tet below `target_quality`, try in order:
+ *      a. Laplacian smoothing on each non-boundary vertex. Accept the
+ *         move only if the worst-of-the-1-ring quality strictly improves;
+ *         otherwise revert the position.
+ *      b. 2-3 flip across each of the tet's 4 internal faces. Tentatively
+ *         apply the flip, score the 3 new tets; accept only if the
+ *         minimum-of-three exceeds the original min-of-two. Otherwise
+ *         apply the inverse 3-2 flip to roll back.
+ *   3. Repeat until no operation in a pass improves anything, or
+ *      `max_passes` is reached.
+ *
+ * The "do then maybe undo" pattern for flips keeps the driver simple: no
+ * separate "preview the flip" code path. The cost is a wasted reverse-flip
+ * per rejected candidate. In practice most candidate flips on bad tets are
+ * either clearly beneficial (accepted) or clearly bad (rejected after one
+ * round-trip), so the overhead is small.
+ *
+ * Mesh topology and points are mutated in place. Surface vertices (any
+ * vertex incident to a face with INVALID_NEIGHBOUR) are NEVER moved by
+ * smoothing — moving them would change the surface shape, which is
+ * usually a hard constraint for the caller.
+ *
+ * @param {TetrahedralMesh} mesh — mutated in place
+ * @param {Float32Array|number[]} points — flat (x,y,z) positions, mutated
+ * @param {{
+ *   target_quality?: number,
+ *   max_passes?: number,
+ *   smoothing_weight?: number,
+ *   enable_flips?: boolean,
+ *   enable_smoothing?: boolean,
+ * }} [options]
+ * @returns {{
+ *   passes_run: number,
+ *   smoothings_committed: number,
+ *   smoothings_reverted: number,
+ *   flips_23_committed: number,
+ *   flips_23_rejected: number,
+ *   flips_32_committed: number,
+ *   flips_32_rejected: number,
+ *   initial_min_quality: number,
+ *   final_min_quality: number,
+ * }}
+ */
+export function tetrahedral_mesh_improve_quality(mesh, points, options = {}) {
+    assert.defined(mesh, 'mesh');
+    assert.defined(points, 'points');
+
+    const target_quality   = options.target_quality   ?? 0.1;
+    const max_passes       = options.max_passes       ?? 5;
+    const smoothing_weight = options.smoothing_weight ?? 0.5;
+    const enable_flips     = options.enable_flips     ?? true;
+    const enable_smoothing = options.enable_smoothing ?? true;
+
+    const stats = {
+        passes_run: 0,
+        smoothings_committed: 0,
+        smoothings_reverted: 0,
+        flips_23_committed: 0,
+        flips_23_rejected: 0,
+        flips_32_committed: 0,
+        flips_32_rejected: 0,
+        initial_min_quality: scan_min_quality(mesh, points),
+        final_min_quality: 1,
+    };
+
+    for (let pass = 0; pass < max_passes; pass++) {
+        let any_improvement = false;
+
+        // Snapshot the live tet IDs so iteration is stable even as flips
+        // delete and re-introduce tet IDs underneath us.
+        const live = mesh.getLive();
+
+        for (let li = 0; li < live.length; li++) {
+            const tet = live[li];
+            if (!mesh.exists(tet)) continue;
+
+            let q = compute_tetrahedron_quality(mesh, points, tet);
+            if (q >= target_quality) continue;
+
+            // ---- Smoothing ---------------------------------------------------
+            if (enable_smoothing) {
+                for (let i = 0; i < 4; i++) {
+                    if (!mesh.exists(tet)) break;
+                    const v_id = mesh.getVertexIndex(tet, i);
+                    if (tetrahedral_mesh_vertex_is_boundary(mesh, v_id)) continue;
+
+                    const v3 = v_id * 3;
+                    const old_x = points[v3];
+                    const old_y = points[v3 + 1];
+                    const old_z = points[v3 + 2];
+
+                    const old_min = local_min_quality_around_vertex(mesh, points, v_id);
+
+                    const moved = tetrahedral_mesh_smooth_vertex(mesh, points, v_id, smoothing_weight);
+                    if (!moved) continue;
+
+                    const new_min = local_min_quality_around_vertex(mesh, points, v_id);
+                    if (new_min > old_min) {
+                        stats.smoothings_committed++;
+                        any_improvement = true;
+                        // Re-fetch quality of `tet` — it may have improved.
+                        q = compute_tetrahedron_quality(mesh, points, tet);
+                        if (q >= target_quality) break;
+                    } else {
+                        points[v3]     = old_x;
+                        points[v3 + 1] = old_y;
+                        points[v3 + 2] = old_z;
+                        stats.smoothings_reverted++;
+                    }
+                }
+            }
+
+            if (!mesh.exists(tet)) continue;
+            q = compute_tetrahedron_quality(mesh, points, tet);
+            if (q >= target_quality) continue;
+
+            // ---- 2-3 flip across each internal face -------------------------
+            // We SCORE the candidate flip by computing what the 3 new tets'
+            // vertex IDs WOULD BE, evaluating quality from the indexed
+            // primitive — without touching mesh topology. The actual flip is
+            // only applied on accepted candidates, so the mesh never sees a
+            // bad transient state and we don't need to invert anything.
+            if (enable_flips) {
+                for (let face_slot = 0; face_slot < 4; face_slot++) {
+                    if (!mesh.exists(tet)) break;
+
+                    const enc = mesh.getNeighbour(tet, face_slot);
+                    if (enc === INVALID_NEIGHBOUR) continue;
+                    const neighbour_tet = enc >>> 2;
+                    if (!mesh.exists(neighbour_tet)) continue;
+                    const shared_i2 = enc & 3;
+
+                    const q_before = Math.min(
+                        compute_tetrahedron_quality(mesh, points, tet),
+                        compute_tetrahedron_quality(mesh, points, neighbour_tet)
+                    );
+
+                    // Derive the would-be vertex IDs of the 3 new tets.
+                    // d / e: the two apex vertices (the one opposite the
+                    // shared face in each of tet and neighbour). p / q / r:
+                    // the shared face's vertices in CCW-from-outside-tet
+                    // order.
+                    const d = mesh.getVertexIndex(tet,           face_slot);
+                    const e = mesh.getVertexIndex(neighbour_tet, shared_i2);
+                    const face = FACE_VERTICES_BY_OPPOSITE[face_slot];
+                    const p = mesh.getVertexIndex(tet, face[0]);
+                    const q = mesh.getVertexIndex(tet, face[1]);
+                    const r = mesh.getVertexIndex(tet, face[2]);
+
+                    // Canonical layouts: T_α = (r, q, d, e); T_β = (p, r, d, e);
+                    // T_γ = (q, p, d, e). Mirrors tetrahedral_mesh_flip_23.
+                    const q_alpha = tetrahedron_compute_quality(points, r, q, d, e);
+                    const q_beta  = tetrahedron_compute_quality(points, p, r, d, e);
+                    const q_gamma = tetrahedron_compute_quality(points, q, p, d, e);
+                    const q_after = Math.min(q_alpha, q_beta, q_gamma);
+
+                    if (q_after > q_before) {
+                        // Commit: actually perform the flip.
+                        tetrahedral_mesh_flip_23(mesh, tet, neighbour_tet, scratch_out_23);
+                        stats.flips_23_committed++;
+                        any_improvement = true;
+                        // `tet` may have been re-used and now represents a
+                        // different shape; stop probing its faces and let
+                        // the next outer loop iteration pick up the new
+                        // low-quality tets.
+                        break;
+                    }
+
+                    stats.flips_23_rejected++;
+                }
+            }
+
+            if (!mesh.exists(tet)) continue;
+            q = compute_tetrahedron_quality(mesh, points, tet);
+            if (q >= target_quality) continue;
+
+            // ---- 3-2 flip on each edge whose ring has exactly 3 tets --------
+            // For each of the 6 edges of `tet`, walk the surrounding ring.
+            // If exactly 3 tets sit around that edge, we have a valid 3-2
+            // candidate. Score it analytically (using the same "compute
+            // ring layout from t1's canonical winding" rule as
+            // tetrahedral_mesh_flip_32) and commit only if the new pair's
+            // min quality beats the old triple's.
+            if (enable_flips) {
+                for (let ep = 0; ep < EDGE_SLOT_PAIRS.length; ep++) {
+                    if (!mesh.exists(tet)) break;
+
+                    const slot_a = EDGE_SLOT_PAIRS[ep][0];
+                    const slot_b = EDGE_SLOT_PAIRS[ep][1];
+                    const v_a = mesh.getVertexIndex(tet, slot_a);
+                    const v_b = mesh.getVertexIndex(tet, slot_b);
+
+                    const ring_count = tetrahedral_mesh_find_tets_around_edge(
+                        scratch_edge_ring, 0, mesh, tet, v_a, v_b, scratch_ring_closed
+                    );
+                    // 3-2 flips are only defined on a CLOSED ring of
+                    // exactly 3 tets. The ring walker may return 3 tets
+                    // for an open chain on the mesh boundary (e.g. a
+                    // vertex where two boundary faces meet at an edge);
+                    // those aren't a valid 3-2 input — flip_32 would
+                    // throw on them.
+                    if (ring_count !== 3 || scratch_ring_closed[0] !== 1) continue;
+
+                    const r0 = scratch_edge_ring[0];
+                    const r1 = scratch_edge_ring[1];
+                    const r2 = scratch_edge_ring[2];
+
+                    const q_before_32 = Math.min(
+                        compute_tetrahedron_quality(mesh, points, r0),
+                        compute_tetrahedron_quality(mesh, points, r1),
+                        compute_tetrahedron_quality(mesh, points, r2)
+                    );
+
+                    // Compute the 3-2 flip's would-be new tet vertex IDs.
+                    // Mirrors the derivation in tetrahedral_mesh_flip_32:
+                    // read r0's face opposite v_b in CCW-from-outside order,
+                    // locate v_a within that triple, and the next two
+                    // cyclic positions give the t1-side ring (v_X, v_Y) in
+                    // CCW-from-v_a order. v_missing is the third ring vertex
+                    // — present in r1 or r2 but not r0.
+                    const slot_a_r0 = find_slot(mesh, r0, v_a);
+                    const slot_b_r0 = find_slot(mesh, r0, v_b);
+                    const face_opp_b = FACE_VERTICES_BY_OPPOSITE[slot_b_r0];
+                    const f0 = mesh.getVertexIndex(r0, face_opp_b[0]);
+                    const f1 = mesh.getVertexIndex(r0, face_opp_b[1]);
+                    const f2 = mesh.getVertexIndex(r0, face_opp_b[2]);
+                    let pos_a = -1;
+                    if (f0 === v_a) pos_a = 0;
+                    else if (f1 === v_a) pos_a = 1;
+                    else if (f2 === v_a) pos_a = 2;
+                    const face_array = [f0, f1, f2];
+                    const v_X = face_array[(pos_a + 1) % 3];
+                    const v_Y = face_array[(pos_a + 2) % 3];
+
+                    // v_missing is the only ring vertex not in r0. It's in
+                    // both r1 and r2; finding it requires walking another
+                    // tet's vertices.
+                    let v_missing = -1;
+                    for (let i = 0; i < 4; i++) {
+                        const v = mesh.getVertexIndex(r1, i);
+                        if (v !== v_a && v !== v_b && v !== v_X && v !== v_Y) {
+                            v_missing = v;
+                            break;
+                        }
+                    }
+                    if (v_missing < 0) continue; // shouldn't happen, but guard
+
+                    // Canonical new layouts (mirrors flip_32):
+                    //   new_tet_a = (v_X, v_missing, v_Y, v_a)
+                    //   new_tet_b = (v_X, v_Y, v_missing, v_b)
+                    const q_new_a = tetrahedron_compute_quality(points, v_X, v_missing, v_Y, v_a);
+                    const q_new_b = tetrahedron_compute_quality(points, v_X, v_Y, v_missing, v_b);
+                    const q_after_32 = Math.min(q_new_a, q_new_b);
+
+                    if (q_after_32 > q_before_32) {
+                        tetrahedral_mesh_flip_32(mesh, r0, r1, r2, scratch_out_32);
+                        stats.flips_32_committed++;
+                        any_improvement = true;
+                        break; // tet's identity may now be one of the new tets
+                    }
+
+                    stats.flips_32_rejected++;
+                }
+            }
+        }
+
+        stats.passes_run = pass + 1;
+        if (!any_improvement) break;
+    }
+
+    stats.final_min_quality = scan_min_quality(mesh, points);
+    return stats;
+}
+
+/**
+ * Index of `vertex_id` within `tet`'s 4 slots, or -1 if absent.
+ */
+function find_slot(mesh, tet, vertex_id) {
+    for (let i = 0; i < 4; i++) {
+        if (mesh.getVertexIndex(tet, i) === vertex_id) return i;
+    }
+    return -1;
+}
+
+/**
+ * Min quality across every live tet in the mesh.
+ */
+function scan_min_quality(mesh, points) {
+    let min_q = 1;
+    mesh.forEach((tet, m) => {
+        const q = compute_tetrahedron_quality(m, points, tet);
+        if (q < min_q) min_q = q;
+    });
+    return min_q;
+}
+
+/**
+ * Min quality across all tets containing `v_id`. Used to score the local
+ * effect of moving (or undoing the move of) a single vertex.
+ */
+function local_min_quality_around_vertex(mesh, points, v_id) {
+    if (scratch_local_tets.length < mesh.count) {
+        scratch_local_tets = new Array(Math.max(mesh.count, scratch_local_tets.length * 2));
+    }
+    const n = tetrahedral_mesh_find_tets_attached_to_vertex(scratch_local_tets, 0, mesh, v_id);
+
+    let min_q = 1;
+    for (let i = 0; i < n; i++) {
+        const q = compute_tetrahedron_quality(mesh, points, scratch_local_tets[i]);
+        if (q < min_q) min_q = q;
+    }
+    return min_q;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Move a vertex toward the centroid of its 1-ring neighbours (Laplacian
+ * smoothing), at the given weight: `w == 0` keeps the vertex where it is,
+ * `w == 1` snaps it to the centroid, `0 < w < 1` blends. Default `w = 1`.
+ *
+ * Mutates `points` in place. Does NOT touch the mesh topology.
+ *
+ * The 1-ring is computed by finding every tet that contains `vertex_id` and
+ * collecting the OTHER 3 vertices of each tet, deduplicated. For typical
+ * meshes this is fast; for very heavy use over many vertices in tight
+ * loops, build a vertex-to-tet adjacency map once and call a lower-level
+ * smoothing primitive instead.
+ *
+ * Does NOT check whether the vertex sits on the mesh boundary — the caller
+ * is responsible for skipping boundary vertices (via
+ * {@link tetrahedral_mesh_vertex_is_boundary}) if surface preservation
+ * matters. Moving a boundary vertex changes the mesh's external shape.
+ *
+ * Returns `true` if the vertex was actually moved (i.e. it had ≥ 1 neighbour
+ * and the centroid differs from the current position), `false` otherwise
+ * (isolated vertex, or w == 0, or already at the centroid). The boolean
+ * lets a quality-improvement driver short-circuit on "nothing happened".
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {Float32Array|number[]} points flat (x,y,z) positions — mutated in place
+ * @param {number} vertex_id
+ * @param {number} [weight] move fraction, default 1.0
+ * @returns {boolean} true if `points` was modified
+ */
+export function tetrahedral_mesh_smooth_vertex(mesh: TetrahedralMesh, points: Float32Array | number[], vertex_id: number, weight?: number): boolean;
+//# sourceMappingURL=tetrahedral_mesh_smooth_vertex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_smooth_vertex.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_smooth_vertex.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,8EALW,YAAY,GAAC,MAAM,EAAE,aACrB,MAAM,WACN,MAAM,GACJ,OAAO,CAyEnB"}

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

@@ -0,0 +1,112 @@
+import { assert } from "../../../assert.js";
+import {
+    tetrahedral_mesh_find_tets_attached_to_vertex
+} from "./tetrahedral_mesh_find_tets_attached_to_vertex.js";
+
+// Module-level scratch buffers, sized for typical vertex valence (~20-40
+// incident tets, ~30-60 1-ring neighbours). Grow on demand. Re-used across
+// calls — the function is therefore NOT re-entrant.
+let scratch_tets = new Array(64);
+let scratch_neighbours = new Array(128);
+
+/**
+ * Move a vertex toward the centroid of its 1-ring neighbours (Laplacian
+ * smoothing), at the given weight: `w == 0` keeps the vertex where it is,
+ * `w == 1` snaps it to the centroid, `0 < w < 1` blends. Default `w = 1`.
+ *
+ * Mutates `points` in place. Does NOT touch the mesh topology.
+ *
+ * The 1-ring is computed by finding every tet that contains `vertex_id` and
+ * collecting the OTHER 3 vertices of each tet, deduplicated. For typical
+ * meshes this is fast; for very heavy use over many vertices in tight
+ * loops, build a vertex-to-tet adjacency map once and call a lower-level
+ * smoothing primitive instead.
+ *
+ * Does NOT check whether the vertex sits on the mesh boundary — the caller
+ * is responsible for skipping boundary vertices (via
+ * {@link tetrahedral_mesh_vertex_is_boundary}) if surface preservation
+ * matters. Moving a boundary vertex changes the mesh's external shape.
+ *
+ * Returns `true` if the vertex was actually moved (i.e. it had ≥ 1 neighbour
+ * and the centroid differs from the current position), `false` otherwise
+ * (isolated vertex, or w == 0, or already at the centroid). The boolean
+ * lets a quality-improvement driver short-circuit on "nothing happened".
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {Float32Array|number[]} points flat (x,y,z) positions — mutated in place
+ * @param {number} vertex_id
+ * @param {number} [weight] move fraction, default 1.0
+ * @returns {boolean} true if `points` was modified
+ */
+export function tetrahedral_mesh_smooth_vertex(mesh, points, vertex_id, weight = 1.0) {
+    assert.defined(mesh, 'mesh');
+    assert.defined(points, 'points');
+    assert.isNonNegativeInteger(vertex_id, 'vertex_id');
+    assert.isNumber(weight, 'weight');
+
+    if (weight === 0) return false;
+
+    // 1. Find tets containing the vertex.
+    if (scratch_tets.length < mesh.count) {
+        scratch_tets = new Array(Math.max(mesh.count, scratch_tets.length * 2));
+    }
+    const tet_count = tetrahedral_mesh_find_tets_attached_to_vertex(
+        scratch_tets, 0, mesh, vertex_id
+    );
+
+    if (tet_count === 0) return false;
+
+    // 2. Collect 1-ring neighbours (the other 3 vertices of each incident
+    // tet), deduplicated. Linear search dedup — fine for typical valences
+    // (the neighbour list rarely exceeds a few dozen).
+    let neighbour_count = 0;
+    for (let i = 0; i < tet_count; i++) {
+        const tet = scratch_tets[i];
+        for (let j = 0; j < 4; j++) {
+            const v = mesh.getVertexIndex(tet, j);
+            if (v === vertex_id) continue;
+            let already = false;
+            for (let k = 0; k < neighbour_count; k++) {
+                if (scratch_neighbours[k] === v) { already = true; break; }
+            }
+            if (!already) {
+                if (neighbour_count >= scratch_neighbours.length) {
+                    scratch_neighbours.length = scratch_neighbours.length * 2;
+                }
+                scratch_neighbours[neighbour_count++] = v;
+            }
+        }
+    }
+
+    if (neighbour_count === 0) return false;
+
+    // 3. Compute 1-ring centroid.
+    let cx = 0, cy = 0, cz = 0;
+    for (let i = 0; i < neighbour_count; i++) {
+        const v3 = scratch_neighbours[i] * 3;
+        cx += points[v3];
+        cy += points[v3 + 1];
+        cz += points[v3 + 2];
+    }
+    const inv_n = 1 / neighbour_count;
+    cx *= inv_n;
+    cy *= inv_n;
+    cz *= inv_n;
+
+    // 4. Blend toward centroid.
+    const v3 = vertex_id * 3;
+    const old_x = points[v3];
+    const old_y = points[v3 + 1];
+    const old_z = points[v3 + 2];
+
+    const new_x = old_x + weight * (cx - old_x);
+    const new_y = old_y + weight * (cy - old_y);
+    const new_z = old_z + weight * (cz - old_z);
+
+    if (new_x === old_x && new_y === old_y && new_z === old_z) return false;
+
+    points[v3]     = new_x;
+    points[v3 + 1] = new_y;
+    points[v3 + 2] = new_z;
+    return true;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Return true if the given vertex lies on the boundary of the
+ * tetrahedral mesh — equivalently, if it sits on any face that has no
+ * neighbouring tet (INVALID_NEIGHBOUR).
+ *
+ * Used by quality-improvement passes to skip boundary vertices when
+ * smoothing or collapsing, because moving them would change the mesh's
+ * external surface (which usually represents some geometric constraint
+ * the caller wants preserved).
+ *
+ * Cost: O(N) over the live tets, same as
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} which it shares
+ * the same scan structure with. For repeated calls over many vertices,
+ * caller should precompute a boundary bitset rather than calling this in
+ * a loop.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} vertex_id
+ * @returns {boolean}
+ */
+export function tetrahedral_mesh_vertex_is_boundary(mesh: TetrahedralMesh, vertex_id: number): boolean;
+//# sourceMappingURL=tetrahedral_mesh_vertex_is_boundary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_vertex_is_boundary.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_vertex_is_boundary.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,sFAHW,MAAM,GACJ,OAAO,CAiCnB"}

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

@@ -0,0 +1,55 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * Return true if the given vertex lies on the boundary of the
+ * tetrahedral mesh — equivalently, if it sits on any face that has no
+ * neighbouring tet (INVALID_NEIGHBOUR).
+ *
+ * Used by quality-improvement passes to skip boundary vertices when
+ * smoothing or collapsing, because moving them would change the mesh's
+ * external surface (which usually represents some geometric constraint
+ * the caller wants preserved).
+ *
+ * Cost: O(N) over the live tets, same as
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} which it shares
+ * the same scan structure with. For repeated calls over many vertices,
+ * caller should precompute a boundary bitset rather than calling this in
+ * a loop.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} vertex_id
+ * @returns {boolean}
+ */
+export function tetrahedral_mesh_vertex_is_boundary(mesh, vertex_id) {
+    assert.defined(mesh, 'mesh');
+    assert.isNonNegativeInteger(vertex_id, 'vertex_id');
+
+    let is_boundary = false;
+
+    mesh.forEach((tet, m) => {
+        if (is_boundary) return;
+
+        // Find the slot of vertex_id in this tet (if any).
+        let v_slot = -1;
+        for (let i = 0; i < 4; i++) {
+            if (m.getVertexIndex(tet, i) === vertex_id) {
+                v_slot = i;
+                break;
+            }
+        }
+        if (v_slot < 0) return;
+
+        // The 3 faces containing vertex_id are the ones NOT opposite v_slot.
+        // (The face opposite v_slot is the only face that excludes vertex_id.)
+        for (let j = 0; j < 4; j++) {
+            if (j === v_slot) continue;
+            if (m.getNeighbour(tet, j) === INVALID_NEIGHBOUR) {
+                is_boundary = true;
+                return;
+            }
+        }
+    });
+
+    return is_boundary;
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Compute the radius-ratio shape quality of a tetrahedron given by 4 vertex
+ * indices into the points array. Normalised so a regular tet returns 1 and
+ * a degenerate (zero-volume) tet returns 0.
+ *
+ * Formula: 3 · r_in / r_circ where
+ *   r_in  = inscribed-sphere radius = 3·|V| / S_total
+ *   r_circ = circumscribed-sphere radius
+ *   S_total = sum of the 4 face areas
+ *   |V| = absolute signed volume
+ *
+ * Quality bands (rough rule of thumb for the radius-ratio metric):
+ *   1.0       regular tet
+ *   ≥ 0.5     well-shaped, safe for FEM / fluid
+ *   0.1–0.5   acceptable, may slow convergence
+ *   0.01–0.1  sliver — usually a target for flipping / smoothing
+ *   < 0.01    near-degenerate, almost flat
+ *
+ * Indexed form (not mesh-bound) so callers can score hypothetical tets
+ * during a flip-candidate search without committing the flip first. The
+ * existing mesh-form wrapper {@link compute_tetrahedron_quality} fetches
+ * the four vertex IDs and forwards here.
+ *
+ * @param {ArrayLike<number>} points flat (x,y,z) positions
+ * @param {number} a vertex index
+ * @param {number} b vertex index
+ * @param {number} c vertex index
+ * @param {number} d vertex index
+ * @returns {number} quality in [0, 1]
+ */
+export function tetrahedron_compute_quality(points: ArrayLike<number>, a: number, b: number, c: number, d: number): number;
+//# sourceMappingURL=tetrahedron_compute_quality.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedron_compute_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,oDAPW,UAAU,MAAM,CAAC,KACjB,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CA+BlB"}