@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,232 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * For a tet stored as (v0, v1, v2, v3), the vertices of the face opposite
+ * vertex i, in counter-clockwise order viewed from outside the tet (i.e. the
+ * standard outward-facing winding for a positively-oriented tet whose signed
+ * volume is positive under the engine's `compute_tetrahedron_volume`).
+ *
+ * Derived from the volume formula vol = (1/6)·det[v0-v3, v1-v3, v2-v3]:
+ *   - Face opposite v3 is the canonical case (v0, v1, v2).
+ *   - Other faces follow by even-permutation parity to keep the implied tet
+ *     (face, opposite_vertex) positively wound.
+ */
+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 2-3 flip on two tetrahedra that share a face.
+ *
+ * Input two tets t1, t2 sharing a triangle face. The flip removes that face
+ * and replaces it with a new edge connecting the two "apex" vertices (the
+ * vertex of each tet that's NOT on the shared face). The shared bipyramid is
+ * re-tetrahedralised into three new tets, each containing the new edge plus
+ * one edge of the original shared face.
+ *
+ * Counts go from (2 tets, 5 vertices total, 1 internal face) to (3 tets, 5
+ * vertices, 3 internal faces). No vertex IDs change; the operation is purely
+ * topological — it doesn't touch the points array.
+ *
+ * Geometric validity (positive volume of each new tet under any specific
+ * embedding) is the caller's responsibility. The flip preserves orientation
+ * — if t1 was positively wound the new tets are too — but the new edge
+ * (d, e) must actually lie inside the convex region formed by the original
+ * two tets for the result to be a valid embedding. Outside Delaunay /
+ * constraint-recovery contexts this is the caller's domain knowledge.
+ *
+ * Implementation notes:
+ *   - t1's storage slot is reused for one of the new tets ("T_alpha")
+ *   - t2's slot for another ("T_beta")
+ *   - one fresh slot is allocated for the third ("T_gamma")
+ *   - all four external neighbour back-pointers around each of t1 and t2
+ *     are rewritten to point at the right new tet/slot
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} t1
+ * @param {number} t2 must share a face with t1
+ * @param {Uint32Array|number[]} out output storage; out[0..2] receive the 3
+ *        new tet IDs. Caller provides — the function performs no allocation.
+ *        Must have length ≥ 3.
+ */
+export function tetrahedral_mesh_flip_23(mesh, t1, t2, out) {
+    assert.defined(mesh, 'mesh');
+    assert.equal(mesh.isTetrahedralMesh, true, 'mesh.isTetrahedralMesh !== true');
+    assert.isNonNegativeInteger(t1, 't1');
+    assert.isNonNegativeInteger(t2, 't2');
+    assert.notEqual(t1, t2, 't1 must not equal t2');
+    assert.defined(out, 'out');
+
+    // -----------------------------------------------------------------
+    // Step 1: locate the shared face.
+    // -----------------------------------------------------------------
+    let shared_i1 = -1;
+    let shared_i2 = -1;
+    for (let i = 0; i < 4; i++) {
+        const enc = mesh.getNeighbour(t1, i);
+        if (enc === INVALID_NEIGHBOUR) continue;
+        if ((enc >>> 2) === t2) {
+            shared_i1 = i;
+            shared_i2 = enc & 3;
+            break;
+        }
+    }
+    if (shared_i1 < 0) {
+        throw new Error(`tets ${t1} and ${t2} do not share a face`);
+    }
+
+    // -----------------------------------------------------------------
+    // Step 2: identify the 5 distinct vertices.
+    //   d = apex of t1 (opposite the shared face)
+    //   e = apex of t2
+    //   (p, q, r) = shared face vertices, in CCW order seen from outside t1
+    //               (i.e. the standard "outward face" ordering)
+    // -----------------------------------------------------------------
+    const d = mesh.getVertexIndex(t1, shared_i1);
+    const e = mesh.getVertexIndex(t2, shared_i2);
+
+    const face_t1 = FACE_VERTICES_BY_OPPOSITE[shared_i1];
+    const pos_p_in_t1 = face_t1[0];
+    const pos_q_in_t1 = face_t1[1];
+    const pos_r_in_t1 = face_t1[2];
+
+    const p = mesh.getVertexIndex(t1, pos_p_in_t1);
+    const q = mesh.getVertexIndex(t1, pos_q_in_t1);
+    const r = mesh.getVertexIndex(t1, pos_r_in_t1);
+
+    // Find where p, q, r live in t2's vertex array. Needed to look up which
+    // of t2's external neighbours sits opposite each of p, q, r.
+    let pos_p_in_t2 = -1, pos_q_in_t2 = -1, pos_r_in_t2 = -1;
+    for (let i = 0; i < 4; i++) {
+        const v = mesh.getVertexIndex(t2, i);
+        if (v === p) pos_p_in_t2 = i;
+        else if (v === q) pos_q_in_t2 = i;
+        else if (v === r) pos_r_in_t2 = i;
+    }
+    if (pos_p_in_t2 < 0 || pos_q_in_t2 < 0 || pos_r_in_t2 < 0) {
+        throw new Error(
+            `tets ${t1} and ${t2} are recorded as neighbours but their shared face vertices don't match — mesh integrity broken`
+        );
+    }
+
+    // -----------------------------------------------------------------
+    // Step 3: snapshot external neighbours BEFORE we start writing.
+    //   t1's faces opposite p, q, r are external (the face opposite d is t2).
+    //   Same for t2.
+    // -----------------------------------------------------------------
+    const ext_p_t1 = mesh.getNeighbour(t1, pos_p_in_t1);
+    const ext_q_t1 = mesh.getNeighbour(t1, pos_q_in_t1);
+    const ext_r_t1 = mesh.getNeighbour(t1, pos_r_in_t1);
+    const ext_p_t2 = mesh.getNeighbour(t2, pos_p_in_t2);
+    const ext_q_t2 = mesh.getNeighbour(t2, pos_q_in_t2);
+    const ext_r_t2 = mesh.getNeighbour(t2, pos_r_in_t2);
+
+    // -----------------------------------------------------------------
+    // Step 4: allocate the third slot. Reuse t1 → T_alpha, t2 → T_beta.
+    // -----------------------------------------------------------------
+    const T_alpha = t1;
+    const T_beta = t2;
+    const T_gamma = mesh.allocate();
+
+    // -----------------------------------------------------------------
+    // Step 5: write vertices in canonical positive-volume order.
+    //   T_alpha = (r, q, d, e)  — covers edge (q, r), missing p
+    //   T_beta  = (p, r, d, e)  — covers edge (r, p), missing q
+    //   T_gamma = (q, p, d, e)  — covers edge (p, q), missing r
+    // Each ordering was derived (and verified) to keep the new tet's signed
+    // volume the same sign as the original t1/t2 under the engine's
+    // convention.
+    // -----------------------------------------------------------------
+    mesh.setVertexIndex(T_alpha, 0, r);
+    mesh.setVertexIndex(T_alpha, 1, q);
+    mesh.setVertexIndex(T_alpha, 2, d);
+    mesh.setVertexIndex(T_alpha, 3, e);
+
+    mesh.setVertexIndex(T_beta, 0, p);
+    mesh.setVertexIndex(T_beta, 1, r);
+    mesh.setVertexIndex(T_beta, 2, d);
+    mesh.setVertexIndex(T_beta, 3, e);
+
+    mesh.setVertexIndex(T_gamma, 0, q);
+    mesh.setVertexIndex(T_gamma, 1, p);
+    mesh.setVertexIndex(T_gamma, 2, d);
+    mesh.setVertexIndex(T_gamma, 3, e);
+
+    // -----------------------------------------------------------------
+    // Step 6: internal neighbour links between the three new tets.
+    //
+    // Walking each new tet's faces:
+    //   T_alpha = (r, q, d, e):
+    //     slot 0 (opp r) face {q,d,e} — shared with T_gamma's slot 1 (opp p)
+    //     slot 1 (opp q) face {r,d,e} — shared with T_beta's slot 0 (opp p)
+    //     slot 2 (opp d) face {r,q,e} — external, was opposite p in t2
+    //     slot 3 (opp e) face {r,q,d} — external, was opposite p in t1
+    //
+    //   T_beta = (p, r, d, e):
+    //     slot 0 (opp p) face {r,d,e} — shared with T_alpha's slot 1 (opp q)
+    //     slot 1 (opp r) face {p,d,e} — shared with T_gamma's slot 0 (opp q)
+    //     slot 2 (opp d) face {p,r,e} — external, was opposite q in t2
+    //     slot 3 (opp e) face {p,r,d} — external, was opposite q in t1
+    //
+    //   T_gamma = (q, p, d, e):
+    //     slot 0 (opp q) face {p,d,e} — shared with T_beta's slot 1 (opp r)
+    //     slot 1 (opp p) face {q,d,e} — shared with T_alpha's slot 0 (opp r)
+    //     slot 2 (opp d) face {q,p,e} — external, was opposite r in t2
+    //     slot 3 (opp e) face {q,p,d} — external, was opposite r in t1
+    // -----------------------------------------------------------------
+    mesh.setNeighbour(T_alpha, 0, (T_gamma << 2) | 1);
+    mesh.setNeighbour(T_alpha, 1, (T_beta  << 2) | 0);
+    mesh.setNeighbour(T_beta,  0, (T_alpha << 2) | 1);
+    mesh.setNeighbour(T_beta,  1, (T_gamma << 2) | 0);
+    mesh.setNeighbour(T_gamma, 0, (T_beta  << 2) | 1);
+    mesh.setNeighbour(T_gamma, 1, (T_alpha << 2) | 0);
+
+    // -----------------------------------------------------------------
+    // Step 7: external neighbour links. The new tet inherits the SAME
+    // encoded value the old tet held — the neighbour tet ID and its
+    // back-slot don't change. Only the new tet's own slot needs the value.
+    // -----------------------------------------------------------------
+    mesh.setNeighbour(T_alpha, 2, ext_p_t2);
+    mesh.setNeighbour(T_alpha, 3, ext_p_t1);
+    mesh.setNeighbour(T_beta,  2, ext_q_t2);
+    mesh.setNeighbour(T_beta,  3, ext_q_t1);
+    mesh.setNeighbour(T_gamma, 2, ext_r_t2);
+    mesh.setNeighbour(T_gamma, 3, ext_r_t1);
+
+    // -----------------------------------------------------------------
+    // Step 8: rewrite the external neighbours' back-pointers. Each one
+    // currently points at t1 or t2; now they should point at the
+    // corresponding new tet and slot.
+    // -----------------------------------------------------------------
+    rewrite_back_pointer(mesh, ext_p_t2, T_alpha, 2);
+    rewrite_back_pointer(mesh, ext_p_t1, T_alpha, 3);
+    rewrite_back_pointer(mesh, ext_q_t2, T_beta,  2);
+    rewrite_back_pointer(mesh, ext_q_t1, T_beta,  3);
+    rewrite_back_pointer(mesh, ext_r_t2, T_gamma, 2);
+    rewrite_back_pointer(mesh, ext_r_t1, T_gamma, 3);
+
+    out[0] = T_alpha;
+    out[1] = T_beta;
+    out[2] = T_gamma;
+}
+
+/**
+ * Given an encoded neighbour reference (as stored in a tet's neighbour slot)
+ * that used to point at some old tet, rewrite the OTHER end of that link so
+ * it points at `new_tet` at `new_slot` instead. The low 2 bits of the
+ * encoded value tell us the slot in the external tet that holds the
+ * back-pointer.
+ *
+ * No-op if the encoded reference is INVALID_NEIGHBOUR (the old tet had no
+ * neighbour on that face).
+ */
+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_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":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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,CA8OH"}