@woosh/meep-engine 2.133.5 → 2.134.0

package/src/core/geom/3d/topology/simplify/simplifyTopoMesh.d.ts

@@ -8,10 +8,10 @@ export function extract_edge_cost(edge: EdgeCollapseCandidate): number;
  * @param {BinaryHeap<EdgeCollapseCandidate>} heap
  * @param {TopoMesh} mesh
  * @param {Map<TopoEdge, EdgeCollapseCandidate>} edge_to_collapse_map
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  * @param {Set<number>} restricted_vertices
  */
-export function collapse_edges(number_faces_to_remove: number, heap: BinaryHeap<EdgeCollapseCandidate>, mesh: TopoMesh, edge_to_collapse_map: Map<TopoEdge, EdgeCollapseCandidate>, vertex_quadratics: Map<number, Quadratic3>, restricted_vertices: Set<number>): void;
+export function collapse_edges(number_faces_to_remove: number, heap: BinaryHeap<EdgeCollapseCandidate>, mesh: TopoMesh, edge_to_collapse_map: Map<TopoEdge, EdgeCollapseCandidate>, vertex_quadratics: Map<number, Quadric3>, restricted_vertices: Set<number>): void;
 /**
  * Simplifies a given topology mesh by reducing number of faces. Preserves original vertices
  * NOTE: preserves outline of the mesh, that is the open edge

package/src/core/geom/3d/topology/simplify/simplifyTopoMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simplifyTopoMesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/simplify/simplifyTopoMesh.js"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wCAFW,qBAAqB,UAI/B;AAGD;;;;;;;GAOG;AACH,uDAPW,MAAM,QACN,WAAW,qBAAqB,CAAC,wCAEjC,cAAc,qBAAqB,CAAC,qBACpC,IAAI,MAAM,aAAa,uBACvB,IAAI,MAAM,CAAC,QAyKrB;AAED;;;;;;;GAOG;AACH,sEAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QAwDrB;sCAhQqC,4BAA4B;uBAL3C,2CAA2C"}
+{"version":3,"file":"simplifyTopoMesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/simplify/simplifyTopoMesh.js"],"names":[],"mappings":"AAcA;;;GAGG;AACH,wCAFW,qBAAqB,UAI/B;AAGD;;;;;;;GAOG;AACH,uDAPW,MAAM,QACN,WAAW,qBAAqB,CAAC,wCAEjC,cAAc,qBAAqB,CAAC,qBACpC,IAAI,MAAM,WAAW,uBACrB,IAAI,MAAM,CAAC,QAyKrB;AAED;;;;;;;GAOG;AACH,sEAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QAwDrB;sCAhQqC,4BAA4B;uBAL3C,2CAA2C"}

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

@@ -26,7 +26,7 @@ export function extract_edge_cost(edge) {
  * @param {BinaryHeap<EdgeCollapseCandidate>} heap
  * @param {TopoMesh} mesh
  * @param {Map<TopoEdge, EdgeCollapseCandidate>} edge_to_collapse_map
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  * @param {Set<number>} restricted_vertices
  */
 export function collapse_edges(
@@ -231,7 +231,7 @@ export function simplifyTopoMesh(mesh, num_faces_to_remove, restricted_vertices
 
     /**
      *
-     * @type {Map<number, Quadratic3>}
+     * @type {Map<number, Quadric3>}
      */
     const vertex_quadratics = new Map();
 

package/src/core/geom/3d/topology/simplify/simplifyTopoMesh2.d.ts

@@ -3,10 +3,10 @@
  * @param {Iterable<TopoEdge>} edges
  * @param {Set<number>} restricted_vertices
  * @param {Uint32Heap} heap
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  * @param {Map<number,TopoEdge>} edge_lookup
  */
-export function edge_collapse_populate_heap(edges: Iterable<TopoEdge>, restricted_vertices: Set<number>, heap: Uint32Heap, vertex_quadratics: Map<number, Quadratic3>, edge_lookup: Map<number, TopoEdge>): void;
+export function edge_collapse_populate_heap(edges: Iterable<TopoEdge>, restricted_vertices: Set<number>, heap: Uint32Heap, vertex_quadratics: Map<number, Quadric3>, edge_lookup: Map<number, TopoEdge>): void;
 /**
  *
  * @param {TopoMesh} mesh
@@ -14,9 +14,9 @@ export function edge_collapse_populate_heap(edges: Iterable<TopoEdge>, restricte
  * @param {Uint32Heap} heap
  * @param {Map<number,TopoEdge>} edge_lookup
  * @param {Set<number>} restricted_vertices
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  */
-export function edge_collapse_reduce_face_count(mesh: TopoMesh, num_faces_to_remove: number, heap: Uint32Heap, edge_lookup: Map<number, TopoEdge>, restricted_vertices: Set<number>, vertex_quadratics: Map<number, Quadratic3>): void;
+export function edge_collapse_reduce_face_count(mesh: TopoMesh, num_faces_to_remove: number, heap: Uint32Heap, edge_lookup: Map<number, TopoEdge>, restricted_vertices: Set<number>, vertex_quadratics: Map<number, Quadric3>): void;
 /**
  * Simplifies a given topology mesh by reducing number of faces. Preserves original vertices
  * NOTE: preserves outline of the mesh, that is the open edge

package/src/core/geom/3d/topology/simplify/simplifyTopoMesh2.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"simplifyTopoMesh2.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/simplify/simplifyTopoMesh2.js"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,mDANW,kBAAkB,uBAClB,IAAI,MAAM,CAAC,QACX,UAAU,qBACV,IAAI,MAAM,aAAa,eACvB,IAAI,MAAM,WAAU,QAsB9B;AAED;;;;;;;;GAQG;AACH,qFANW,MAAM,QACN,UAAU,eACV,IAAI,MAAM,WAAU,uBACpB,IAAI,MAAM,CAAC,qBACX,IAAI,MAAM,aAAa,QAgCjC;AAED;;;;;;;GAOG;AACH,uEAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QAgCrB;2BAtH0B,2CAA2C"}
+{"version":3,"file":"simplifyTopoMesh2.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/geom/3d/topology/simplify/simplifyTopoMesh2.js"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,mDANW,kBAAkB,uBAClB,IAAI,MAAM,CAAC,QACX,UAAU,qBACV,IAAI,MAAM,WAAW,eACrB,IAAI,MAAM,WAAU,QAsB9B;AAED;;;;;;;;GAQG;AACH,qFANW,MAAM,QACN,UAAU,eACV,IAAI,MAAM,WAAU,uBACpB,IAAI,MAAM,CAAC,qBACX,IAAI,MAAM,WAAW,QAgC/B;AAED;;;;;;;GAOG;AACH,uEAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QAgCrB;2BAtH0B,2CAA2C"}

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

@@ -1,18 +1,18 @@
 import { Uint32Heap } from "../../../../collection/heap/Uint32Heap.js";
-import { build_vertex_quadratics } from "./quadratic/build_vertex_quadratics.js";
+import { max2 } from "../../../../math/max2.js";
 import {
     compute_edge_collapse_cost,
     decimate_edge_collapse_snap,
     edge_collapse_pick_target_vertex
 } from "./decimate_edge_collapse_snap.js";
-import { max2 } from "../../../../math/max2.js";
+import { build_vertex_quadratics } from "./quadratic/build_vertex_quadratics.js";
 
 /**
  *
  * @param {Iterable<TopoEdge>} edges
  * @param {Set<number>} restricted_vertices
  * @param {Uint32Heap} heap
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  * @param {Map<number,TopoEdge>} edge_lookup
  */
 export function edge_collapse_populate_heap(edges, restricted_vertices, heap, vertex_quadratics, edge_lookup) {
@@ -44,7 +44,7 @@ export function edge_collapse_populate_heap(edges, restricted_vertices, heap, ve
  * @param {Uint32Heap} heap
  * @param {Map<number,TopoEdge>} edge_lookup
  * @param {Set<number>} restricted_vertices
- * @param {Map<number, Quadratic3>} vertex_quadratics
+ * @param {Map<number, Quadric3>} vertex_quadratics
  */
 export function edge_collapse_reduce_face_count(mesh, num_faces_to_remove, heap, edge_lookup, restricted_vertices, vertex_quadratics) {
     const mesh_faces = mesh.getFaces();
@@ -99,7 +99,7 @@ export function simplifyTopoMesh2(mesh, num_faces_to_remove, restricted_vertices
     const heap = new Uint32Heap(mesh.getEdges().size);
     /**
      *
-     * @type {Map<number, Quadratic3>}
+     * @type {Map<number, Quadric3>}
      */
     const vertex_quadratics = new Map();
 

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Compute face normals for all allocated triangular faces, overwriting any previous value.
+ * Non-triangular faces are left untouched.
+ *
+ * @param {BinaryTopology} mesh
+ */
+export function bt_mesh_compute_face_normals(mesh: BinaryTopology): void;
+//# sourceMappingURL=bt_mesh_compute_face_normals.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_compute_face_normals.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.js"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,yEAwCC"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.js

@@ -0,0 +1,56 @@
+import { assert } from "../../../../../../assert.js";
+import { v3_compute_triangle_normal } from "../../../../triangle/v3_compute_triangle_normal.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+const scratch_normal = new Float32Array(3);
+const scratch_coord_a = new Float32Array(3);
+const scratch_coord_b = new Float32Array(3);
+const scratch_coord_c = new Float32Array(3);
+
+/**
+ * Compute face normals for all allocated triangular faces, overwriting any previous value.
+ * Non-triangular faces are left untouched.
+ *
+ * @param {BinaryTopology} mesh
+ */
+export function bt_mesh_compute_face_normals(mesh) {
+    assert.defined(mesh, "mesh");
+    assert.notNull(mesh, "mesh");
+    assert.equal(mesh.isBinaryTopology, true, "mesh.isBinaryTopology !== true");
+
+    const face_pool = mesh.faces;
+    const face_count = face_pool.size;
+
+    for (let face_id = 0; face_id < face_count; face_id++) {
+        if (!face_pool.is_allocated(face_id)) {
+            continue;
+        }
+
+        const loop_a = mesh.face_read_loop(face_id);
+
+        if (loop_a === NULL_POINTER) {
+            continue;
+        }
+
+        const loop_b = mesh.loop_read_next(loop_a);
+        const loop_c = mesh.loop_read_next(loop_b);
+
+        // must be a triangle
+        if (mesh.loop_read_next(loop_c) !== loop_a) {
+            continue;
+        }
+
+        mesh.vertex_read_coordinate(scratch_coord_a, 0, mesh.loop_read_vertex(loop_a));
+        mesh.vertex_read_coordinate(scratch_coord_b, 0, mesh.loop_read_vertex(loop_b));
+        mesh.vertex_read_coordinate(scratch_coord_c, 0, mesh.loop_read_vertex(loop_c));
+
+        v3_compute_triangle_normal(
+            scratch_normal, 0,
+            scratch_coord_a[0], scratch_coord_a[1], scratch_coord_a[2],
+            scratch_coord_b[0], scratch_coord_b[1], scratch_coord_b[2],
+            scratch_coord_c[0], scratch_coord_c[1], scratch_coord_c[2]
+        );
+
+        mesh.face_write_normal(face_id, scratch_normal, 0);
+    }
+}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compute a per-vertex quadric error metric from every allocated triangular face.
+ *
+ * For each triangular face the supporting plane (n, d) is derived from its loop
+ * vertices; the corresponding quadric is then accumulated onto each of those
+ * three vertices' Quadric3. Non-triangular faces are skipped.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {Quadric3[]} Array indexed by vertex ID. Entries for unallocated
+ *     vertex slots are `undefined`.
+ */
+export function bt_mesh_compute_vertex_quadratics(mesh: BinaryTopology): Quadric3[];
+import { Quadric3 } from "../../../simplify/quadratic/Quadric3.js";
+//# sourceMappingURL=bt_mesh_compute_vertex_quadratics.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_compute_vertex_quadratics.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.js"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,yEAHa,QAAQ,EAAE,CA2EtB;yBA3FwB,yCAAyC"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadratics.js

@@ -0,0 +1,95 @@
+import { assert } from "../../../../../../assert.js";
+import { v3_dot } from "../../../../../vec3/v3_dot.js";
+import { v3_compute_triangle_normal } from "../../../../triangle/v3_compute_triangle_normal.js";
+import { Quadric3 } from "../../../simplify/quadratic/Quadric3.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+
+const scratch_coord_a = new Float32Array(3);
+const scratch_coord_b = new Float32Array(3);
+const scratch_coord_c = new Float32Array(3);
+const scratch_normal = new Float32Array(3);
+
+/**
+ * Compute a per-vertex quadric error metric from every allocated triangular face.
+ *
+ * For each triangular face the supporting plane (n, d) is derived from its loop
+ * vertices; the corresponding quadric is then accumulated onto each of those
+ * three vertices' Quadric3. Non-triangular faces are skipped.
+ *
+ * @param {BinaryTopology} mesh
+ * @returns {Quadric3[]} Array indexed by vertex ID. Entries for unallocated
+ *     vertex slots are `undefined`.
+ */
+export function bt_mesh_compute_vertex_quadratics(mesh) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+
+    const vertex_pool = mesh.vertices;
+    const vertex_count = vertex_pool.size;
+
+    const quadratics = new Array(vertex_count);
+
+    for (let v = 0; v < vertex_count; v++) {
+        if (vertex_pool.is_allocated(v)) {
+            quadratics[v] = new Quadric3();
+        }
+    }
+
+    const face_pool = mesh.faces;
+    const face_count = face_pool.size;
+
+    const q = new Quadric3();
+
+    for (let f = 0; f < face_count; f++) {
+        if (!face_pool.is_allocated(f)) {
+            continue;
+        }
+
+        const la = mesh.face_read_loop(f);
+
+        if (la === NULL_POINTER) {
+            continue;
+        }
+
+        const lb = mesh.loop_read_next(la);
+        const lc = mesh.loop_read_next(lb);
+
+        // Skip non-triangles
+        if (mesh.loop_read_next(lc) !== la) {
+            continue;
+        }
+
+        const va = mesh.loop_read_vertex(la);
+        const vb = mesh.loop_read_vertex(lb);
+        const vc = mesh.loop_read_vertex(lc);
+
+        mesh.vertex_read_coordinate(scratch_coord_a, 0, va);
+        mesh.vertex_read_coordinate(scratch_coord_b, 0, vb);
+        mesh.vertex_read_coordinate(scratch_coord_c, 0, vc);
+
+        v3_compute_triangle_normal(
+            scratch_normal, 0,
+            scratch_coord_a[0], scratch_coord_a[1], scratch_coord_a[2],
+            scratch_coord_b[0], scratch_coord_b[1], scratch_coord_b[2],
+            scratch_coord_c[0], scratch_coord_c[1], scratch_coord_c[2]
+        );
+
+        const nx = scratch_normal[0];
+        const ny = scratch_normal[1];
+        const nz = scratch_normal[2];
+
+        // Plane offset: d = -(n . v_a)
+        const d = -v3_dot(
+            nx, ny, nz,
+            scratch_coord_a[0], scratch_coord_a[1], scratch_coord_a[2]
+        );
+
+        q.setFromVector4(nx, ny, nz, d);
+
+        quadratics[va].add(q);
+        quadratics[vb].add(q);
+        quadratics[vc].add(q);
+    }
+
+    return quadratics;
+}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Simplify a mesh in-place by greedily collapsing the cheapest edges (per a quadric
+ * error metric) until the allocated face count drops to `target_face_count`.
+ *
+ * Vertices listed in `restricted_vertices` are pinned: they are neither moved nor
+ * removed. If the target cannot be reached (e.g. too many restricted vertices),
+ * simplification stops early without failing.
+ *
+ * At the end of the call the mesh is cleaned up so that no dangling loops, edges,
+ * or vertices remain in the topology.
+ *
+ * @param {BinaryTopology} mesh Mesh to simplify in-place.
+ * @param {number} target_face_count Desired face count after simplification.
+ * @param {Set<number>} [restricted_vertices] Vertices that must not move or be removed.
+ */
+export function bt_mesh_simplify(mesh: BinaryTopology, target_face_count: number, restricted_vertices?: Set<number>): void;
+//# sourceMappingURL=bt_mesh_simplify.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_simplify.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js"],"names":[],"mappings":"AAqLA;;;;;;;;;;;;;;GAcG;AACH,0EAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QA2HrB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js

@@ -0,0 +1,352 @@
+import { assert } from "../../../../../../assert.js";
+import { Uint32Heap } from "../../../../../../collection/heap/Uint32Heap.js";
+import { Quadric3 } from "../../../simplify/quadratic/Quadric3.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_loop_kill } from "./bt_loop_kill.js";
+import { bt_mesh_compute_vertex_quadratics } from "./bt_mesh_compute_vertex_quadratics.js";
+import { bt_edge_collapse } from "./edge/bt_edge_collapse.js";
+import { bt_edge_kill } from "./edge/bt_edge_kill.js";
+import { bt_edge_kill_parallels } from "./edge/bt_edge_kill_parallels.js";
+import { bt_vert_fuse_duplicate_edges } from "./vertex/bt_vert_fuse_duplicate_edges.js";
+import { bt_vert_kill } from "./vertex/bt_vert_kill.js";
+
+// Module-level scratch buffers to keep GC pressure low across calls.
+const scratch_coord_a = new Float32Array(3);
+const scratch_coord_b = new Float32Array(3);
+const scratch_target = new Float32Array(3);
+const scratch_combined_q = new Quadric3();
+
+/**
+ * Count the number of still-live faces attached to an edge via its radial loop cycle.
+ * Orphan loops (whose face was already killed by a prior collapse) are skipped so
+ * that callers tracking running face totals don't double-decrement.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @returns {number}
+ */
+function count_edge_faces(mesh, edge_id) {
+    const l0 = mesh.edge_read_loop(edge_id);
+
+    if (l0 === NULL_POINTER) {
+        return 0;
+    }
+
+    const face_pool = mesh.faces;
+
+    let count = 0;
+    let l = l0;
+
+    do {
+        const f = mesh.loop_read_face(l);
+
+        if (f !== NULL_POINTER && face_pool.is_allocated(f)) {
+            count++;
+        }
+
+        l = mesh.loop_read_radial_next(l);
+    } while (l !== l0 && l !== NULL_POINTER);
+
+    return count;
+}
+
+/**
+ * Swap the v1/v2 slots of an edge. Disk cycle pointers for the two slots are swapped
+ * alongside so that the disk cycles on both attached vertices remain valid.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ */
+function swap_edge_vertex_slots(mesh, edge_id) {
+    const v1 = mesh.edge_read_vertex1(edge_id);
+    const v2 = mesh.edge_read_vertex2(edge_id);
+
+    const v1_next = mesh.edge_read_v1_disk_next(edge_id);
+    const v1_prev = mesh.edge_read_v1_disk_prev(edge_id);
+    const v2_next = mesh.edge_read_v2_disk_next(edge_id);
+    const v2_prev = mesh.edge_read_v2_disk_prev(edge_id);
+
+    mesh.edge_write_vertex1(edge_id, v2);
+    mesh.edge_write_vertex2(edge_id, v1);
+
+    mesh.edge_write_v1_disk_next(edge_id, v2_next);
+    mesh.edge_write_v1_disk_prev(edge_id, v2_prev);
+    mesh.edge_write_v2_disk_next(edge_id, v1_next);
+    mesh.edge_write_v2_disk_prev(edge_id, v1_prev);
+}
+
+/**
+ * Evaluate a potential edge collapse: choose the optimal surviving vertex position
+ * and return the quadric-based cost. Returns Infinity if the edge cannot be collapsed.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ * @param {Quadric3[]} quadratics
+ * @param {Set<number>} restricted_vertices
+ * @param {Float32Array|number[]} out_target Target position is written here.
+ * @returns {number}
+ */
+function evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices, out_target) {
+    const v1 = mesh.edge_read_vertex1(edge_id);
+    const v2 = mesh.edge_read_vertex2(edge_id);
+
+    if (v1 === v2) {
+        // Degenerate self-loop, not collapsible
+        return Number.POSITIVE_INFINITY;
+    }
+
+    const v1_restricted = restricted_vertices.has(v1);
+    const v2_restricted = restricted_vertices.has(v2);
+
+    if (v1_restricted && v2_restricted) {
+        return Number.POSITIVE_INFINITY;
+    }
+
+    const q1 = quadratics[v1];
+    const q2 = quadratics[v2];
+
+    // Missing quadrics mean at least one endpoint was a prior victim that somehow
+    // persisted as a topology endpoint (e.g. via a self-loop produced from parallel
+    // edges). Such edges are not useful collapse candidates.
+    if (q1 === null || q2 === null || q1 === undefined || q2 === undefined) {
+        return Number.POSITIVE_INFINITY;
+    }
+
+    if (v1_restricted) {
+        mesh.vertex_read_coordinate(out_target, 0, v1);
+    } else if (v2_restricted) {
+        mesh.vertex_read_coordinate(out_target, 0, v2);
+    } else {
+        scratch_combined_q.copy(q1);
+        scratch_combined_q.add(q2);
+
+        if (!scratch_combined_q.optimize(out_target)) {
+            // Singular combined tensor: fall back to the midpoint
+            mesh.vertex_read_coordinate(scratch_coord_a, 0, v1);
+            mesh.vertex_read_coordinate(scratch_coord_b, 0, v2);
+
+            out_target[0] = (scratch_coord_a[0] + scratch_coord_b[0]) * 0.5;
+            out_target[1] = (scratch_coord_a[1] + scratch_coord_b[1]) * 0.5;
+            out_target[2] = (scratch_coord_a[2] + scratch_coord_b[2]) * 0.5;
+        }
+    }
+
+    const tx = out_target[0];
+    const ty = out_target[1];
+    const tz = out_target[2];
+
+    // Cost can drift slightly negative for near-zero values due to fp noise.
+    return Math.abs(q1.evaluate(tx, ty, tz) + q2.evaluate(tx, ty, tz));
+}
+
+/**
+ * Re-score every edge in the disk cycle of `survivor` that is currently in the heap.
+ * Edges that were never inserted (e.g. both endpoints restricted) are left untouched.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} survivor
+ * @param {Quadric3[]} quadratics
+ * @param {Set<number>} restricted_vertices
+ * @param {Uint32Heap} heap
+ */
+function update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices, heap) {
+    let curr_e = mesh.vertex_read_edge(survivor);
+
+    if (curr_e === NULL_POINTER) {
+        return;
+    }
+
+    const start_e = curr_e;
+
+    do {
+        // Grab the next edge in the disk cycle before we do anything that might
+        // make `curr_e` harder to reason about (the cycle itself is not mutated).
+        let next_e;
+        if (mesh.edge_read_vertex1(curr_e) === survivor) {
+            next_e = mesh.edge_read_v1_disk_next(curr_e);
+        } else {
+            next_e = mesh.edge_read_v2_disk_next(curr_e);
+        }
+
+        const idx = heap.find_index_by_id(curr_e);
+
+        if (idx !== -1) {
+            const cost = evaluate_edge_collapse(mesh, curr_e, quadratics, restricted_vertices, scratch_target);
+            heap.__update_score_by_index(idx, cost);
+        }
+
+        curr_e = next_e;
+    } while (curr_e !== start_e && curr_e !== NULL_POINTER);
+}
+
+/**
+ * Simplify a mesh in-place by greedily collapsing the cheapest edges (per a quadric
+ * error metric) until the allocated face count drops to `target_face_count`.
+ *
+ * Vertices listed in `restricted_vertices` are pinned: they are neither moved nor
+ * removed. If the target cannot be reached (e.g. too many restricted vertices),
+ * simplification stops early without failing.
+ *
+ * At the end of the call the mesh is cleaned up so that no dangling loops, edges,
+ * or vertices remain in the topology.
+ *
+ * @param {BinaryTopology} mesh Mesh to simplify in-place.
+ * @param {number} target_face_count Desired face count after simplification.
+ * @param {Set<number>} [restricted_vertices] Vertices that must not move or be removed.
+ */
+export function bt_mesh_simplify(
+    mesh,
+    target_face_count,
+    restricted_vertices = new Set()
+) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+    assert.equal(mesh.isBinaryTopology, true, 'mesh.isBinaryTopology !== true');
+    assert.isNonNegativeInteger(target_face_count, 'target_face_count');
+    assert.defined(restricted_vertices, 'restricted_vertices');
+    assert.notNull(restricted_vertices, 'restricted_vertices');
+
+    const face_pool = mesh.faces;
+
+    // Count allocated faces up front so we can track progress without scanning each iteration.
+    let current_face_count = 0;
+    for (let f = 0; f < face_pool.size; f++) {
+        if (face_pool.is_allocated(f)) {
+            current_face_count++;
+        }
+    }
+
+    if (current_face_count <= target_face_count) {
+        return;
+    }
+
+    const quadratics = bt_mesh_compute_vertex_quadratics(mesh);
+
+    const edge_pool = mesh.edges;
+    const heap = new Uint32Heap(edge_pool.size);
+
+    for (let e = 0; e < edge_pool.size; e++) {
+        if (!edge_pool.is_allocated(e)) {
+            continue;
+        }
+
+        const cost = evaluate_edge_collapse(mesh, e, quadratics, restricted_vertices, scratch_target);
+
+        if (cost === Number.POSITIVE_INFINITY) {
+            continue;
+        }
+
+        heap.insert(e, cost);
+    }
+
+    // Safety bound: every real collapse removes at least one face; the extra headroom
+    // accommodates no-op collapses on orphan edges that may appear after a collapse
+    // produces duplicate parallel edges.
+    const max_iterations = current_face_count * 10 + heap.size + 10;
+    let iterations = 0;
+
+    while (
+        !heap.is_empty()
+        && current_face_count > target_face_count
+        && iterations < max_iterations
+    ) {
+        iterations++;
+
+        const edge_id = heap.pop_min();
+
+        if (!edge_pool.is_allocated(edge_id)) {
+            // Edge was killed by an earlier collapse (e.g. adjacent face death).
+            continue;
+        }
+
+        const v1 = mesh.edge_read_vertex1(edge_id);
+        const v2 = mesh.edge_read_vertex2(edge_id);
+
+        if (v1 === v2) {
+            // Degenerate self-loop produced by a prior collapse of parallel edges.
+            continue;
+        }
+
+        const v1_restricted = restricted_vertices.has(v1);
+        const v2_restricted = restricted_vertices.has(v2);
+
+        if (v1_restricted && v2_restricted) {
+            continue;
+        }
+
+        const cost = evaluate_edge_collapse(mesh, edge_id, quadratics, restricted_vertices, scratch_target);
+
+        if (cost === Number.POSITIVE_INFINITY) {
+            continue;
+        }
+
+        const face_deaths = count_edge_faces(mesh, edge_id);
+
+        // bt_edge_collapse keeps v1 as the survivor. If v2 is the pinned endpoint,
+        // swap the edge's slots so the pinned vertex ends up in the v1 position.
+        if (v2_restricted) {
+            swap_edge_vertex_slots(mesh, edge_id);
+        }
+
+        const pre_survivor = mesh.edge_read_vertex1(edge_id);
+        const pre_victim = mesh.edge_read_vertex2(edge_id);
+
+        // Accumulate victim's quadric onto the survivor before the topology mutates.
+        quadratics[pre_survivor].add(quadratics[pre_victim]);
+        quadratics[pre_victim] = null;
+
+        // Kill any direct parallel edges between survivor and victim. Leaving them in
+        // place would cause bt_vertex_replace (inside bt_edge_collapse) to produce a
+        // self-loop edge (surv, surv), which corrupts the survivor's disk cycle.
+        current_face_count -= bt_edge_kill_parallels(mesh, edge_id);
+
+        const survivor = bt_edge_collapse(mesh, edge_id, scratch_target, 0);
+
+        current_face_count -= face_deaths;
+
+        // Link-vertex parallels produced by this collapse will become direct parallels
+        // at the next collapse that touches them, so fuse them now while disk cycles
+        // are still intact.
+        current_face_count -= bt_vert_fuse_duplicate_edges(mesh, survivor);
+
+        update_neighbor_costs(mesh, survivor, quadratics, restricted_vertices, heap);
+    }
+
+    // Drop any loose loops/edges/verts produced during collapses, preserving
+    // restricted vertices even if they ended up isolated.
+    cleanup_faceless_preserving_restricted(mesh, restricted_vertices);
+}
+
+/**
+ * Variant of bt_mesh_cleanup_faceless_references that never releases a restricted
+ * vertex even when it has no remaining edges.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {Set<number>} restricted_vertices
+ */
+function cleanup_faceless_preserving_restricted(mesh, restricted_vertices) {
+    const loop_pool = mesh.loops;
+    for (let l = 0; l < loop_pool.size; l++) {
+        if (!loop_pool.is_allocated(l)) continue;
+        if (mesh.loop_read_face(l) === NULL_POINTER) {
+            bt_loop_kill(mesh, l);
+        }
+    }
+
+    const edge_pool = mesh.edges;
+    for (let e = 0; e < edge_pool.size; e++) {
+        if (!edge_pool.is_allocated(e)) continue;
+        if (mesh.edge_read_loop(e) === NULL_POINTER) {
+            bt_edge_kill(mesh, e);
+        }
+    }
+
+    const vertex_pool = mesh.vertices;
+    for (let v = 0; v < vertex_pool.size; v++) {
+        if (!vertex_pool.is_allocated(v)) continue;
+        if (restricted_vertices.has(v)) continue;
+        if (mesh.vertex_read_edge(v) === NULL_POINTER) {
+            bt_vert_kill(mesh, v);
+        }
+    }
+}