@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,33 @@
+/**
+ * Perform a 3-2 flip: three tetrahedra sharing a common edge collapse into
+ * two tetrahedra sharing the triangle face that was previously bounded by
+ * the edge. Inverse of the 2-3 flip.
+ *
+ * The three input tets must share exactly one edge (v_a, v_b); together
+ * they form a triangular bipyramid whose central edge is (v_a, v_b) and
+ * whose equator is the triangle (v_X, v_Y, v_missing) — the three "ring"
+ * vertices, one in each pair of adjacent input tets. After the flip, the
+ * (v_a, v_b) edge is gone and the (v_X, v_Y, v_missing) face is the only
+ * interior face left.
+ *
+ * Slot reuse: t1's storage becomes the v_a-side new tet, t2's becomes the
+ * v_b-side new tet, t3's slot is freed.
+ *
+ * As with the 2-3 flip, geometric validity (positive volume of each new
+ * tet under any specific embedding) is NOT checked — the new tets'
+ * orientations follow the canonical winding of t1, so if t1 had a positive
+ * signed volume the new tets do too. The caller is responsible for
+ * ensuring the flip is geometrically meaningful for its use case (the
+ * bipyramid must be convex, which is implicit in "three tets share an
+ * edge").
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} t1 — first of three tets sharing the central edge
+ * @param {number} t2 — second; must share the same edge as t1
+ * @param {number} t3 — third; must share the same edge as t1 and t2
+ * @param {Uint32Array|number[]} out — caller-provided storage. out[0]
+ *        receives the v_a-side new tet ID, out[1] the v_b-side. Must have
+ *        length ≥ 2.
+ */
+export function tetrahedral_mesh_flip_32(mesh: TetrahedralMesh, t1: number, t2: number, t3: number, out: Uint32Array | number[]): void;
+//# sourceMappingURL=tetrahedral_mesh_flip_32.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_flip_32.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_flip_32.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,oEAPW,MAAM,MACN,MAAM,MACN,MAAM,OACN,WAAW,GAAC,MAAM,EAAE,QAqM9B"}

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

@@ -0,0 +1,255 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * Face-vertex layout for a positively-oriented tet: for vertex slot i, the
+ * face opposite has these slot indices in counter-clockwise-from-outside
+ * order. Identical to the table in tetrahedral_mesh_flip_23.js; kept local
+ * for module independence.
+ */
+const FACE_VERTICES_BY_OPPOSITE = [
+    [1, 3, 2], // opposite v0
+    [0, 2, 3], // opposite v1
+    [0, 3, 1], // opposite v2
+    [0, 1, 2], // opposite v3
+];
+
+/**
+ * Perform a 3-2 flip: three tetrahedra sharing a common edge collapse into
+ * two tetrahedra sharing the triangle face that was previously bounded by
+ * the edge. Inverse of the 2-3 flip.
+ *
+ * The three input tets must share exactly one edge (v_a, v_b); together
+ * they form a triangular bipyramid whose central edge is (v_a, v_b) and
+ * whose equator is the triangle (v_X, v_Y, v_missing) — the three "ring"
+ * vertices, one in each pair of adjacent input tets. After the flip, the
+ * (v_a, v_b) edge is gone and the (v_X, v_Y, v_missing) face is the only
+ * interior face left.
+ *
+ * Slot reuse: t1's storage becomes the v_a-side new tet, t2's becomes the
+ * v_b-side new tet, t3's slot is freed.
+ *
+ * As with the 2-3 flip, geometric validity (positive volume of each new
+ * tet under any specific embedding) is NOT checked — the new tets'
+ * orientations follow the canonical winding of t1, so if t1 had a positive
+ * signed volume the new tets do too. The caller is responsible for
+ * ensuring the flip is geometrically meaningful for its use case (the
+ * bipyramid must be convex, which is implicit in "three tets share an
+ * edge").
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} t1 — first of three tets sharing the central edge
+ * @param {number} t2 — second; must share the same edge as t1
+ * @param {number} t3 — third; must share the same edge as t1 and t2
+ * @param {Uint32Array|number[]} out — caller-provided storage. out[0]
+ *        receives the v_a-side new tet ID, out[1] the v_b-side. Must have
+ *        length ≥ 2.
+ */
+export function tetrahedral_mesh_flip_32(mesh, t1, t2, t3, out) {
+    assert.defined(mesh, 'mesh');
+    assert.equal(mesh.isTetrahedralMesh, true, 'mesh.isTetrahedralMesh !== true');
+    assert.isNonNegativeInteger(t1, 't1');
+    assert.isNonNegativeInteger(t2, 't2');
+    assert.isNonNegativeInteger(t3, 't3');
+    assert.notEqual(t1, t2, 't1 must not equal t2');
+    assert.notEqual(t1, t3, 't1 must not equal t3');
+    assert.notEqual(t2, t3, 't2 must not equal t3');
+    assert.defined(out, 'out');
+
+    // -----------------------------------------------------------------
+    // Step 1: find the edge (v_a, v_b) shared by all three tets.
+    // -----------------------------------------------------------------
+    const t1_verts = [
+        mesh.getVertexIndex(t1, 0),
+        mesh.getVertexIndex(t1, 1),
+        mesh.getVertexIndex(t1, 2),
+        mesh.getVertexIndex(t1, 3),
+    ];
+
+    let v_a = -1;
+    let v_b = -1;
+    for (let i = 0; i < 4; i++) {
+        const v = t1_verts[i];
+        if (mesh.tetContainsVertex(t2, v) && mesh.tetContainsVertex(t3, v)) {
+            if (v_a === -1) v_a = v;
+            else if (v_b === -1) v_b = v;
+            else throw new Error(`tets ${t1}, ${t2}, ${t3} share more than two vertices — input is not a valid 3-2 configuration`);
+        }
+    }
+    if (v_b === -1) {
+        throw new Error(`tets ${t1}, ${t2}, ${t3} do not share a common edge`);
+    }
+
+    // -----------------------------------------------------------------
+    // Step 2: identify the three ring vertices.
+    //   t1 has (v_X, v_Y); the third ring vertex (v_missing) is in t2 and t3.
+    // The order (v_X, v_Y) within t1 is determined by t1's face opposite
+    // v_b in CCW-from-outside order — see step 3.
+    // -----------------------------------------------------------------
+    let slot_a_in_t1 = -1;
+    let slot_b_in_t1 = -1;
+    for (let i = 0; i < 4; i++) {
+        if (t1_verts[i] === v_a) slot_a_in_t1 = i;
+        else if (t1_verts[i] === v_b) slot_b_in_t1 = i;
+    }
+
+    // -----------------------------------------------------------------
+    // Step 3: derive ring order from t1's canonical winding.
+    //
+    // t1's face opposite v_b reads (in CCW-from-outside order) as a triple
+    // containing v_a and t1's two ring vertices. Reading the triple as a
+    // cycle (V0 → V1 → V2 → V0) and taking the two ring vertices in the
+    // order they appear after v_a gives them in CCW-from-v_a's-view ring
+    // direction. v_missing then sits between v_Y and v_X in that same CCW
+    // cycle (i.e. it's v_X's CCW-prev, or equivalently v_Y's CCW-next).
+    // -----------------------------------------------------------------
+    const face_opp_b = FACE_VERTICES_BY_OPPOSITE[slot_b_in_t1];
+    const face_v = [
+        mesh.getVertexIndex(t1, face_opp_b[0]),
+        mesh.getVertexIndex(t1, face_opp_b[1]),
+        mesh.getVertexIndex(t1, face_opp_b[2]),
+    ];
+    let pos_a_in_face = -1;
+    for (let i = 0; i < 3; i++) {
+        if (face_v[i] === v_a) { pos_a_in_face = i; break; }
+    }
+    const v_X = face_v[(pos_a_in_face + 1) % 3];
+    const v_Y = face_v[(pos_a_in_face + 2) % 3];
+
+    // -----------------------------------------------------------------
+    // Step 4: find v_missing — the ring vertex in t2 or t3 but not in t1.
+    // Then label which of (t2, t3) is "v_X-side" (carries the (v_X, v_missing)
+    // ring) vs "v_Y-side" (carries (v_Y, v_missing)). Needed so we know
+    // which input tet supplies which external face.
+    // -----------------------------------------------------------------
+    let v_missing = -1;
+    {
+        // v_missing is in t2 (it's the t2 vertex that's not v_a, v_b, and
+        // not in t1).
+        for (let i = 0; i < 4; i++) {
+            const v = mesh.getVertexIndex(t2, i);
+            if (v !== v_a && v !== v_b && v !== v_X && v !== v_Y) {
+                v_missing = v;
+                break;
+            }
+        }
+    }
+    if (v_missing === -1) {
+        throw new Error(`tets ${t1}, ${t2}, ${t3} do not form a valid 3-2 configuration (couldn't identify ring vertex)`);
+    }
+
+    let v_X_side_tet;
+    let v_Y_side_tet;
+    if (mesh.tetContainsVertex(t2, v_X)) {
+        // t2 has v_X and v_missing → v_X-side
+        v_X_side_tet = t2;
+        v_Y_side_tet = t3;
+    } else {
+        v_X_side_tet = t3;
+        v_Y_side_tet = t2;
+    }
+
+    // Sanity: the labeling implies specific membership. If not, the input
+    // is malformed.
+    if (!mesh.tetContainsVertex(v_X_side_tet, v_X) || !mesh.tetContainsVertex(v_X_side_tet, v_missing) ||
+        !mesh.tetContainsVertex(v_Y_side_tet, v_Y) || !mesh.tetContainsVertex(v_Y_side_tet, v_missing)) {
+        throw new Error(`tets ${t1}, ${t2}, ${t3} do not form a valid 3-2 ring around edge (${v_a}, ${v_b})`);
+    }
+
+    // -----------------------------------------------------------------
+    // Step 5: find the slot of v_a and v_b in each of the 3 input tets.
+    // Needed to read the external face neighbours (face opp v_a / v_b).
+    // -----------------------------------------------------------------
+    const slot_a_in_X = find_slot(mesh, v_X_side_tet, v_a);
+    const slot_b_in_X = find_slot(mesh, v_X_side_tet, v_b);
+    const slot_a_in_Y = find_slot(mesh, v_Y_side_tet, v_a);
+    const slot_b_in_Y = find_slot(mesh, v_Y_side_tet, v_b);
+
+    // -----------------------------------------------------------------
+    // Step 6: snapshot the 6 external neighbours.
+    //   3 faces opp v_b → become external faces of new_tet_a (v_a-side)
+    //   3 faces opp v_a → become external faces of new_tet_b (v_b-side)
+    // -----------------------------------------------------------------
+    const ext_b_t1 = mesh.getNeighbour(t1,           slot_b_in_t1); // → new_tet_a opp v_missing
+    const ext_b_X  = mesh.getNeighbour(v_X_side_tet, slot_b_in_X);  // → new_tet_a opp v_Y
+    const ext_b_Y  = mesh.getNeighbour(v_Y_side_tet, slot_b_in_Y);  // → new_tet_a opp v_X
+    const ext_a_t1 = mesh.getNeighbour(t1,           slot_a_in_t1); // → new_tet_b opp v_missing
+    const ext_a_X  = mesh.getNeighbour(v_X_side_tet, slot_a_in_X);  // → new_tet_b opp v_Y
+    const ext_a_Y  = mesh.getNeighbour(v_Y_side_tet, slot_a_in_Y);  // → new_tet_b opp v_X
+
+    // -----------------------------------------------------------------
+    // Step 7: reuse t1 → new_tet_a, t2 → new_tet_b; free t3.
+    // -----------------------------------------------------------------
+    const new_tet_a = t1;
+    const new_tet_b = t2;
+    mesh.delete(t3);
+
+    // -----------------------------------------------------------------
+    // Step 8: vertex layouts (canonical positive volume).
+    //   new_tet_a = (v_X, v_missing, v_Y, v_a)  → face opp v_a is
+    //               (v_X, v_missing, v_Y) CCW from outside (= CCW from v_b view)
+    //   new_tet_b = (v_X, v_Y, v_missing, v_b)  → face opp v_b is
+    //               (v_X, v_Y, v_missing) CCW from outside (= CCW from v_a view)
+    // -----------------------------------------------------------------
+    mesh.setVertexIndex(new_tet_a, 0, v_X);
+    mesh.setVertexIndex(new_tet_a, 1, v_missing);
+    mesh.setVertexIndex(new_tet_a, 2, v_Y);
+    mesh.setVertexIndex(new_tet_a, 3, v_a);
+
+    mesh.setVertexIndex(new_tet_b, 0, v_X);
+    mesh.setVertexIndex(new_tet_b, 1, v_Y);
+    mesh.setVertexIndex(new_tet_b, 2, v_missing);
+    mesh.setVertexIndex(new_tet_b, 3, v_b);
+
+    // -----------------------------------------------------------------
+    // Step 9: neighbour links.
+    //
+    //  new_tet_a = (v_X, v_missing, v_Y, v_a):
+    //    slot 0 (opp v_X)       face {v_missing, v_Y, v_a} — ext, from v_Y_side
+    //    slot 1 (opp v_missing) face {v_X, v_Y, v_a}       — ext, from t1
+    //    slot 2 (opp v_Y)       face {v_X, v_missing, v_a} — ext, from v_X_side
+    //    slot 3 (opp v_a)       face {v_X, v_missing, v_Y} — INTERNAL ↔ new_tet_b
+    //
+    //  new_tet_b = (v_X, v_Y, v_missing, v_b):
+    //    slot 0 (opp v_X)       face {v_Y, v_missing, v_b} — ext, from v_Y_side
+    //    slot 1 (opp v_Y)       face {v_X, v_missing, v_b} — ext, from v_X_side
+    //    slot 2 (opp v_missing) face {v_X, v_Y, v_b}       — ext, from t1
+    //    slot 3 (opp v_b)       face {v_X, v_Y, v_missing} — INTERNAL ↔ new_tet_a
+    // -----------------------------------------------------------------
+    mesh.setNeighbour(new_tet_a, 0, ext_b_Y);
+    mesh.setNeighbour(new_tet_a, 1, ext_b_t1);
+    mesh.setNeighbour(new_tet_a, 2, ext_b_X);
+    mesh.setNeighbour(new_tet_a, 3, (new_tet_b << 2) | 3);
+
+    mesh.setNeighbour(new_tet_b, 0, ext_a_Y);
+    mesh.setNeighbour(new_tet_b, 1, ext_a_X);
+    mesh.setNeighbour(new_tet_b, 2, ext_a_t1);
+    mesh.setNeighbour(new_tet_b, 3, (new_tet_a << 2) | 3);
+
+    // -----------------------------------------------------------------
+    // Step 10: rewrite the 6 external neighbours' back-pointers.
+    // -----------------------------------------------------------------
+    rewrite_back_pointer(mesh, ext_b_Y,  new_tet_a, 0);
+    rewrite_back_pointer(mesh, ext_b_t1, new_tet_a, 1);
+    rewrite_back_pointer(mesh, ext_b_X,  new_tet_a, 2);
+    rewrite_back_pointer(mesh, ext_a_Y,  new_tet_b, 0);
+    rewrite_back_pointer(mesh, ext_a_X,  new_tet_b, 1);
+    rewrite_back_pointer(mesh, ext_a_t1, new_tet_b, 2);
+
+    out[0] = new_tet_a;
+    out[1] = new_tet_b;
+}
+
+function find_slot(mesh, tet, vertex_id) {
+    for (let i = 0; i < 4; i++) {
+        if (mesh.getVertexIndex(tet, i) === vertex_id) return i;
+    }
+    throw new Error(`vertex ${vertex_id} not found in tet ${tet}`);
+}
+
+function rewrite_back_pointer(mesh, encoded, new_tet, new_slot) {
+    if (encoded === INVALID_NEIGHBOUR) return;
+    const ext_tet = encoded >>> 2;
+    const back_slot = encoded & 3;
+    mesh.setNeighbour(ext_tet, back_slot, (new_tet << 2) | new_slot);
+}

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

@@ -0,0 +1,68 @@
+/**
+ * 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: TetrahedralMesh, points: Float32Array | number[], options?: {
+    target_quality?: number;
+    max_passes?: number;
+    smoothing_weight?: number;
+    enable_flips?: boolean;
+    enable_smoothing?: boolean;
+}): {
+    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;
+};
+//# sourceMappingURL=tetrahedral_mesh_improve_quality.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_improve_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_improve_quality.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,gFApBW,YAAY,GAAC,MAAM,EAAE;qBAEV,MAAM;iBACV,MAAM;uBACA,MAAM;mBACV,OAAO;uBACH,OAAO;IAElB;IACZ,UAAc,EAAE,MAAM,CAAC;IACvB,oBAAwB,EAAE,MAAM,CAAC;IACjC,mBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAqB,EAAE,MAAM,CAAC;CAC3B,CAuOH"}