@woosh/meep-engine 3.64.0 → 3.65.0

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

@@ -1,3 +1,6 @@
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_edge_get } from "../query/bt_edge_get.js";
+import { bt_edge_create } from "./edge/bt_edge_create.js";
 import { bt_face_poke } from "./face/bt_face_poke.js";
 import { bt_radial_loop_add } from "./bt_radial_loop_add.js";
 
@@ -11,9 +14,6 @@ import { bt_radial_loop_add } from "./bt_radial_loop_add.js";
  * PRECONDITION: `cycle` is a single closed loop in which every vertex has exactly two incident edges. That
  * is what the boundary-extraction pass produces; a figure-of-eight or an open chain would walk off.
  *
- * Shared by {@link bt_mesh_close_boundary_holes} and {@link bt_mesh_fill_small_holes}, which each carried
- * a byte-identical copy.
- *
  * @param {BinaryTopology} mesh
  * @param {number[]|Uint32Array} cycle unordered boundary edge ids
  * @param {number} start_vertex vertex to begin the walk at; must be an endpoint of some edge in `cycle`
@@ -74,101 +74,451 @@ export function bt_boundary_loop_order_from(mesh, cycle, start_vertex, out_verti
         e_prev = e_next;
     }
 }
-
-/**
- * Scratch for {@link bt_boundary_loop_fan_fill}. Module-static because the fill is called once per hole
- * and nothing it calls re-enters it.
- * @type {number[]}
- */
-const scratch_coord = [0, 0, 0];
-
-/** @type {number[]} */
-const scratch_ordered_vertices = [];
-
-/** @type {number[]} */
-const scratch_ordered_edges = [];
-
-/**
- * Close one boundary hole: order its cycle, allocate an n-gon face over it, and fan that face from the
- * hole's centroid, which adds a Steiner vertex and replaces the n-gon with n triangles.
- *
- * ## The winding, and what it depends on
- *
- * Each new loop on a boundary edge must wind **opposite** the existing loop, so the shared edge ends up
- * with consistent radial orientation. That is what the start-vertex choice below buys: the seed edge's
- * existing loop names one of its two endpoints, and the fill starts at the *other* one.
- *
- * It works because {@link bt_boundary_loop_order_from} takes `start_vertex`'s first incident edge out of
- * its bucket and walks from there, so the order it produces leaves `start_vertex` along an edge, in the
- * direction opposite to the existing loop's traversal of the seed edge. Change how that walk picks its
- * first edge and the fill face winds the wrong way — which is why the two live in one file.
- *
- * The face normal stays zero; downstream tetrahedralization is position-only.
- *
- * `bt_mesh_close_boundary_holes` and `bt_mesh_fill_small_holes` each carried a copy of this — forty
- * lines, identical in every step — and only the ordering walk above had been lifted out of them.
- *
- * @param {BinaryTopology} mesh
- * @param {number[]|Uint32Array} cycle unordered boundary edge ids forming one closed loop
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function bt_boundary_loop_fan_fill(mesh, cycle) {
-    const n = cycle.length;
-
-    const seed_edge = cycle[0];
-    const seed_loop = mesh.edge_read_loop(seed_edge);
-    const existing_loop_vertex = mesh.loop_read_vertex(seed_loop);
-    const seed_v1 = mesh.edge_read_vertex1(seed_edge);
-    const seed_v2 = mesh.edge_read_vertex2(seed_edge);
-    const start_vertex = (existing_loop_vertex === seed_v1) ? seed_v2 : seed_v1;
-
-    const ordered_vertices = scratch_ordered_vertices;
-    const ordered_edges = scratch_ordered_edges;
-
-    ordered_vertices.length = n;
-    ordered_edges.length = n;
-
-    bt_boundary_loop_order_from(mesh, cycle, start_vertex, ordered_vertices, ordered_edges);
-
-    // Compute centroid of the hole's vertices.
-    let cx = 0, cy = 0, cz = 0;
-
-    for (let i = 0; i < n; i++) {
-        mesh.vertex_read_coordinate(scratch_coord, 0, ordered_vertices[i]);
-
-        cx += scratch_coord[0];
-        cy += scratch_coord[1];
-        cz += scratch_coord[2];
-    }
-
-    cx /= n;
-    cy /= n;
-    cz /= n;
-
-    // Allocate a new face plus n loops, wire them into the face cycle and each boundary edge's radial
-    // cycle.
-    const new_face = mesh.face_create();
-
-    const loops = new Array(n);
-
-    for (let i = 0; i < n; i++) {
-        loops[i] = mesh.loop_create();
-
-        mesh.loop_write_vertex(loops[i], ordered_vertices[i]);
-        mesh.loop_write_face(loops[i], new_face);
-
-        bt_radial_loop_add(mesh, loops[i], ordered_edges[i]);
-    }
-
-    for (let i = 0; i < n; i++) {
-        mesh.loop_write_next(loops[i], loops[(i + 1) % n]);
-        mesh.loop_write_prev(loops[i], loops[(i - 1 + n) % n]);
-    }
-
-    mesh.face_write_loop(new_face, loops[0]);
-
-    // Fan from centroid — adds the Steiner vertex and replaces the n-gon face with n triangles.
-    bt_face_poke(mesh, new_face, cx, cy, cz);
-}
+
+/**
+ * Scratch for {@link bt_boundary_loop_fan_fill}. Module-static because the fill is called once per hole
+ * and nothing it calls re-enters it.
+ * @type {number[]}
+ */
+const scratch_coord = [0, 0, 0];
+
+/** @type {number[]} */
+const scratch_ordered_vertices = [];
+
+/** @type {number[]} */
+const scratch_ordered_edges = [];
+
+/**
+ * Close one boundary hole: order its cycle, allocate an n-gon face over it, and fan that face from the
+ * hole's centroid, which adds a Steiner vertex and replaces the n-gon with n triangles.
+ *
+ * ## The winding, and what it depends on
+ *
+ * Each new loop on a boundary edge must wind **opposite** the existing loop, so the shared edge ends up
+ * with consistent radial orientation. That is what the start-vertex choice below buys: the seed edge's
+ * existing loop names one of its two endpoints, and the fill starts at the *other* one.
+ *
+ * It works because {@link bt_boundary_loop_order_from} takes `start_vertex`'s first incident edge out of
+ * its bucket and walks from there, so the order it produces leaves `start_vertex` along an edge, in the
+ * direction opposite to the existing loop's traversal of the seed edge. Change how that walk picks its
+ * first edge and the fill face winds the wrong way — which is why the two live in one file.
+ *
+ * No face normal is computed; downstream tetrahedralization is position-only.
+ *
+ * The fan covers the hole, and only the hole, when every edge of the loop is visible from the centroid
+ * of its vertices. For any other loop use {@link bt_boundary_loop_min_area_fill}.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number[]|Uint32Array} cycle unordered boundary edge ids forming one closed loop
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_boundary_loop_fan_fill(mesh, cycle) {
+    const n = cycle.length;
+
+    const seed_edge = cycle[0];
+    const seed_loop = mesh.edge_read_loop(seed_edge);
+    const existing_loop_vertex = mesh.loop_read_vertex(seed_loop);
+    const seed_v1 = mesh.edge_read_vertex1(seed_edge);
+    const seed_v2 = mesh.edge_read_vertex2(seed_edge);
+    const start_vertex = (existing_loop_vertex === seed_v1) ? seed_v2 : seed_v1;
+
+    const ordered_vertices = scratch_ordered_vertices;
+    const ordered_edges = scratch_ordered_edges;
+
+    ordered_vertices.length = n;
+    ordered_edges.length = n;
+
+    bt_boundary_loop_order_from(mesh, cycle, start_vertex, ordered_vertices, ordered_edges);
+
+    // Compute centroid of the hole's vertices.
+    let cx = 0, cy = 0, cz = 0;
+
+    for (let i = 0; i < n; i++) {
+        mesh.vertex_read_coordinate(scratch_coord, 0, ordered_vertices[i]);
+
+        cx += scratch_coord[0];
+        cy += scratch_coord[1];
+        cz += scratch_coord[2];
+    }
+
+    cx /= n;
+    cy /= n;
+    cz /= n;
+
+    // Allocate a new face plus n loops, wire them into the face cycle and each boundary edge's radial
+    // cycle.
+    const new_face = mesh.face_create();
+
+    const loops = new Array(n);
+
+    for (let i = 0; i < n; i++) {
+        loops[i] = mesh.loop_create();
+
+        mesh.loop_write_vertex(loops[i], ordered_vertices[i]);
+        mesh.loop_write_face(loops[i], new_face);
+
+        bt_radial_loop_add(mesh, loops[i], ordered_edges[i]);
+    }
+
+    for (let i = 0; i < n; i++) {
+        mesh.loop_write_next(loops[i], loops[(i + 1) % n]);
+        mesh.loop_write_prev(loops[i], loops[(i - 1 + n) % n]);
+    }
+
+    mesh.face_write_loop(new_face, loops[0]);
+
+    // Fan from centroid — adds the Steiner vertex and replaces the n-gon face with n triangles.
+    bt_face_poke(mesh, new_face, cx, cy, cz);
+}
+
+// Scratch for bt_boundary_loop_min_area_fill, grown on demand and never shrunk. Module-static for the
+// same reason as the fan fill's: one call per hole, and nothing it calls re-enters it.
+
+/** (x, y, z) per loop vertex, in loop order. */
+let scratch_positions = new Float64Array(0);
+
+/** `n * n`: total area of the triangulation chosen for the chain `i .. j`, at `i * n + j`. */
+let scratch_cost = new Float64Array(0);
+
+/** `n * n`: summed {@link loop_triangle_shape} of the triangulation chosen for the chain `i .. j`. */
+let scratch_shape = new Float64Array(0);
+
+/** `n * n`: the apex `k` of the triangulation chosen for the chain `i .. j`. */
+let scratch_apex = new Uint32Array(0);
+
+/** `n * 3`: pending chains while the chosen triangulation is written out, as (i, j, edge joining them). */
+let scratch_stack = new Uint32Array(0);
+
+const ZERO_NORMAL = [0, 0, 0];
+
+/**
+ * How far from equilateral the triangle last given to {@link loop_triangle_area} is: the sum of its
+ * squared edge lengths over its area. Least for an equilateral triangle, and infinite for one with no
+ * area.
+ */
+let loop_triangle_shape = 0;
+
+/**
+ * Also leaves the triangle's shape in {@link loop_triangle_shape}.
+ *
+ * @param {number} i
+ * @param {number} k
+ * @param {number} j loop vertex indices into {@link scratch_positions}
+ * @returns {number} area of the triangle they span
+ */
+function loop_triangle_area(i, k, j) {
+    const p = scratch_positions;
+
+    const i3 = i * 3;
+    const k3 = k * 3;
+    const j3 = j * 3;
+
+    const ux = p[k3] - p[i3];
+    const uy = p[k3 + 1] - p[i3 + 1];
+    const uz = p[k3 + 2] - p[i3 + 2];
+
+    const vx = p[j3] - p[i3];
+    const vy = p[j3 + 1] - p[i3 + 1];
+    const vz = p[j3 + 2] - p[i3 + 2];
+
+    const wx = vx - ux;
+    const wy = vy - uy;
+    const wz = vz - uz;
+
+    const cx = uy * vz - uz * vy;
+    const cy = uz * vx - ux * vz;
+    const cz = ux * vy - uy * vx;
+
+    const area = 0.5 * Math.sqrt(cx * cx + cy * cy + cz * cz);
+
+    const squared_edges = ux * ux + uy * uy + uz * uz
+        + vx * vx + vy * vy + vz * vz
+        + wx * wx + wy * wy + wz * wz;
+
+    loop_triangle_shape = area > 0 ? squared_edges / area : Number.POSITIVE_INFINITY;
+
+    return area;
+}
+
+/**
+ * Add the triangle `a -> b -> c` on three edges that already exist.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} a
+ * @param {number} e_ab
+ * @param {number} b
+ * @param {number} e_bc
+ * @param {number} c
+ * @param {number} e_ca
+ */
+function add_triangle_on_edges(mesh, a, e_ab, b, e_bc, c, e_ca) {
+    const face = mesh.face_create();
+
+    const l_a = mesh.loop_create();
+    const l_b = mesh.loop_create();
+    const l_c = mesh.loop_create();
+
+    mesh.loop_write_vertex(l_a, a);
+    mesh.loop_write_vertex(l_b, b);
+    mesh.loop_write_vertex(l_c, c);
+
+    mesh.loop_write_face(l_a, face);
+    mesh.loop_write_face(l_b, face);
+    mesh.loop_write_face(l_c, face);
+
+    bt_radial_loop_add(mesh, l_a, e_ab);
+    bt_radial_loop_add(mesh, l_b, e_bc);
+    bt_radial_loop_add(mesh, l_c, e_ca);
+
+    mesh.loop_write_next(l_a, l_b);
+    mesh.loop_write_next(l_b, l_c);
+    mesh.loop_write_next(l_c, l_a);
+
+    mesh.loop_write_prev(l_a, l_c);
+    mesh.loop_write_prev(l_b, l_a);
+    mesh.loop_write_prev(l_c, l_b);
+
+    mesh.face_write_loop(face, l_a);
+
+    // the pool hands back whatever the slot last held; deriving the normal is the caller's business
+    mesh.face_write_normal(face, ZERO_NORMAL, 0);
+}
+
+/**
+ * Close one boundary hole with triangles over the hole's own vertices, choosing the triangulation of
+ * least total area. No vertex is added.
+ *
+ * ## Why least area
+ *
+ * A fill should cover what the loop encloses and nothing else. For a loop that is a simple polygon in a
+ * plane, every triangulation that stays inside it has the same total area — the polygon's — and any that
+ * puts a triangle outside has more, because that triangle then has to be paid back by another lying
+ * over the surface around the hole, wound the other way. So the least-area triangulation of such a loop
+ * IS a triangulation of the hole, whatever its shape, with no test for convexity or containment that
+ * could be got wrong. For a loop that is not flat it is the classic choice of closing surface, and no
+ * more than that.
+ *
+ * The fan in {@link bt_boundary_loop_fan_fill} does not have that property: it is a triangulation of the
+ * hole only when the whole loop is visible from the centroid of its vertices. For a crescent, an L, or
+ * a crack with more than one arm the centroid lies outside the hole, and the fan covers the surface
+ * between the two with triangles facing both ways.
+ *
+ * A loop need not be a simple polygon at all — a hairline crack encloses nothing, and two sheets that
+ * overlap by a sliver bound a loop that crosses itself. Least area is still the right answer there: it
+ * is the closure that adds as little surface as that loop permits, so the faces of a hole with no width
+ * have no area. Where the sheets overlap, some of those faces are wound against the surface: the loop
+ * itself is, and no closure made of faces alone can be otherwise.
+ *
+ * The search is the dynamic programme of Barequet and Sharir, "Filling gaps in the boundary of a
+ * polyhedron" (1995): the best triangulation of the chain `i .. j` is the best apex `k` between them
+ * plus the best of the two chains either side of it. It measures area in 3D, so the loop needs no plane
+ * to be projected onto. Time is cubic in the loop's edge count and memory quadratic.
+ *
+ * ## Equal areas
+ *
+ * Every triangulation of a flat hole has the same area, so area alone does not say which to take, and
+ * left to rounding the choice falls on triangles across three vertices of one straight side as readily
+ * as on any other — faces of no area, where faces with area would do. Among triangulations whose areas
+ * are equal to within what rounding can make of them, the one taken is the one whose triangles are
+ * nearest equilateral: least in the sum, over its triangles, of squared edge length over area. That is
+ * the measure a Delaunay triangulation minimises, and a triangle with no area makes it infinite.
+ *
+ * ## Edges
+ *
+ * A diagonal between two loop vertices that the mesh already joins by an edge is never used: the fill
+ * would put two more faces on a pair of vertices that already has its own, which is a non-manifold edge
+ * as soon as anything fuses the duplicates. When that rules out every triangulation the hole is left
+ * open and `false` is returned.
+ *
+ * ## Winding
+ *
+ * As in {@link bt_boundary_loop_fan_fill}, and for the reason given there: the loop is ordered from the
+ * seed edge's far endpoint, so every new face crosses each boundary edge against the face already on
+ * it.
+ *
+ * Face normals are written as zero.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number[]|Uint32Array} cycle unordered boundary edge ids forming one closed loop of at least 3 edges
+ * @returns {boolean} whether the hole was closed
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function bt_boundary_loop_min_area_fill(mesh, cycle) {
+    const n = cycle.length;
+
+    if (n < 3) {
+        return false;
+    }
+
+    const seed_edge = cycle[0];
+    const seed_loop = mesh.edge_read_loop(seed_edge);
+    const existing_loop_vertex = mesh.loop_read_vertex(seed_loop);
+    const seed_v1 = mesh.edge_read_vertex1(seed_edge);
+    const seed_v2 = mesh.edge_read_vertex2(seed_edge);
+    const start_vertex = (existing_loop_vertex === seed_v1) ? seed_v2 : seed_v1;
+
+    const vertices = scratch_ordered_vertices;
+    const edges = scratch_ordered_edges;
+
+    vertices.length = n;
+    edges.length = n;
+
+    bt_boundary_loop_order_from(mesh, cycle, start_vertex, vertices, edges);
+
+    if (n === 3) {
+        add_triangle_on_edges(mesh, vertices[0], edges[0], vertices[1], edges[1], vertices[2], edges[2]);
+
+        return true;
+    }
+
+    if (scratch_positions.length < n * 3) {
+        scratch_positions = new Float64Array(n * 3);
+        scratch_stack = new Uint32Array(n * 3);
+    }
+
+    if (scratch_cost.length < n * n) {
+        scratch_cost = new Float64Array(n * n);
+        scratch_shape = new Float64Array(n * n);
+        scratch_apex = new Uint32Array(n * n);
+    }
+
+    const positions = scratch_positions;
+    const cost = scratch_cost;
+    const shape = scratch_shape;
+    const apex = scratch_apex;
+
+    let min_x = Infinity, min_y = Infinity, min_z = Infinity;
+    let max_x = -Infinity, max_y = -Infinity, max_z = -Infinity;
+
+    for (let i = 0; i < n; i++) {
+        mesh.vertex_read_coordinate(positions, i * 3, vertices[i]);
+
+        const x = positions[i * 3];
+        const y = positions[i * 3 + 1];
+        const z = positions[i * 3 + 2];
+
+        if (x < min_x) min_x = x;
+        if (y < min_y) min_y = y;
+        if (z < min_z) min_z = z;
+        if (x > max_x) max_x = x;
+        if (y > max_y) max_y = y;
+        if (z > max_z) max_z = z;
+    }
+
+    // How far apart two sums of triangle areas can be and still be the same area. A triangle's area comes
+    // from products of coordinate differences no longer than the loop is across, each rounded to one part
+    // in 2^53 of a square that size, and a triangulation adds fewer than n of them.
+    const extent_x = max_x - min_x;
+    const extent_y = max_y - min_y;
+    const extent_z = max_z - min_z;
+
+    const same_area = 8 * n * Number.EPSILON * (extent_x * extent_x + extent_y * extent_y + extent_z * extent_z);
+
+    for (let i = 0; i + 1 < n; i++) {
+        // a chain of one edge has nothing to triangulate
+        cost[i * n + i + 1] = 0;
+        shape[i * n + i + 1] = 0;
+    }
+
+    for (let span = 2; span < n; span++) {
+        for (let i = 0; i + span < n; i++) {
+            const j = i + span;
+
+            // `least` is the smallest area any apex has offered; `best` and `best_shape` belong to the
+            // apex chosen, whose area is within `same_area` of it.
+            let least = Number.POSITIVE_INFINITY;
+            let best = Number.POSITIVE_INFINITY;
+            let best_shape = Number.POSITIVE_INFINITY;
+            let best_apex = i + 1;
+
+            // The chain 0 .. n-1 is closed by the loop's own last edge. Every other chain is closed by
+            // a diagonal, which has to be one the mesh does not already have.
+            const is_closed_by_loop = span === n - 1;
+
+            if (is_closed_by_loop || bt_edge_get(mesh, vertices[i], vertices[j]) === NULL_POINTER) {
+
+                for (let k = i + 1; k < j; k++) {
+                    const candidate = cost[i * n + k] + cost[k * n + j] + loop_triangle_area(i, k, j);
+
+                    if (!(candidate < Number.POSITIVE_INFINITY)) {
+                        // one side of this apex cannot be triangulated
+                        continue;
+                    }
+
+                    const candidate_shape = shape[i * n + k] + shape[k * n + j] + loop_triangle_shape;
+
+                    if (
+                        candidate < least - same_area
+                        || (candidate <= least + same_area && candidate_shape < best_shape)
+                    ) {
+                        best = candidate;
+                        best_shape = candidate_shape;
+                        best_apex = k;
+                    }
+
+                    if (candidate < least) {
+                        least = candidate;
+                    }
+                }
+
+            }
+
+            cost[i * n + j] = best;
+            shape[i * n + j] = best_shape;
+            apex[i * n + j] = best_apex;
+        }
+    }
+
+    if (cost[n - 1] === Number.POSITIVE_INFINITY) {
+        // every triangulation needs a diagonal the mesh already has
+        return false;
+    }
+
+    // Write the chosen triangulation out, chain by chain. Each entry is a chain and the edge that
+    // closes it, which exists by the time the entry is read: the loop's own for the first, and a
+    // diagonal made by the parent triangle for the rest.
+    const stack = scratch_stack;
+
+    stack[0] = 0;
+    stack[1] = n - 1;
+    stack[2] = edges[n - 1];
+
+    let stack_size = 1;
+
+    while (stack_size > 0) {
+        stack_size--;
+
+        const i = stack[stack_size * 3];
+        const j = stack[stack_size * 3 + 1];
+        const e_ji = stack[stack_size * 3 + 2];
+
+        const k = apex[i * n + j];
+
+        const e_ik = (k === i + 1) ? edges[i] : bt_edge_create(mesh, vertices[i], vertices[k]);
+        const e_kj = (j === k + 1) ? edges[k] : bt_edge_create(mesh, vertices[k], vertices[j]);
+
+        add_triangle_on_edges(mesh, vertices[i], e_ik, vertices[k], e_kj, vertices[j], e_ji);
+
+        if (k > i + 1) {
+            stack[stack_size * 3] = i;
+            stack[stack_size * 3 + 1] = k;
+            stack[stack_size * 3 + 2] = e_ik;
+
+            stack_size++;
+        }
+
+        if (j > k + 1) {
+            stack[stack_size * 3] = k;
+            stack[stack_size * 3 + 1] = j;
+            stack[stack_size * 3 + 2] = e_kj;
+
+            stack_size++;
+        }
+    }
+
+    return true;
+}

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

@@ -10,8 +10,10 @@
  * Throws if any boundary vertex has more than two boundary edges (figure-8 /
  * pinched boundaries). Mutates the mesh in place.
  *
- * The per-hole fill is {@link bt_boundary_loop_fan_fill}, which {@link bt_mesh_fill_small_holes} also
- * runs — the two used to carry a copy of it each, and the winding argument with it.
+ * The per-hole fill is {@link bt_boundary_loop_fan_fill}. A fan covers a hole exactly only when the
+ * whole loop is visible from the centroid of its vertices; around any other hole some of its triangles
+ * lie over the surface beside the hole, and {@link bt_boundary_loop_min_area_fill} is the fill to use
+ * where that matters.
  *
  * @param {BinaryTopology} mesh
  * @returns {number} number of boundary holes that were closed

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

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_close_boundary_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_close_boundary_holes.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,oEAFa,MAAM,CAWlB"}
+{"version":3,"file":"bt_mesh_close_boundary_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_close_boundary_holes.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oEAFa,MAAM,CAWlB"}

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

@@ -14,8 +14,10 @@ import { bt_mesh_walk_boundary_loops } from "../query/bt_mesh_walk_boundary_loop
  * Throws if any boundary vertex has more than two boundary edges (figure-8 /
  * pinched boundaries). Mutates the mesh in place.
  *
- * The per-hole fill is {@link bt_boundary_loop_fan_fill}, which {@link bt_mesh_fill_small_holes} also
- * runs — the two used to carry a copy of it each, and the winding argument with it.
+ * The per-hole fill is {@link bt_boundary_loop_fan_fill}. A fan covers a hole exactly only when the
+ * whole loop is visible from the centroid of its vertices; around any other hole some of its triangles
+ * lie over the surface beside the hole, and {@link bt_boundary_loop_min_area_fill} is the fill to use
+ * where that matters.
  *
  * @param {BinaryTopology} mesh
  * @returns {number} number of boundary holes that were closed

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

@@ -5,7 +5,14 @@
  * tiny boundary loop - that are numerical noise rather than meaningful openings. Such slivers inflate
  * the boundary length, the face count, and the loop count. This measures every boundary loop's mean
  * width (2*area/perimeter, the inradius of the area-equivalent disc) and fills each inner loop narrower
- * than `min_width`. The single largest-area loop is treated as the outer boundary and is never filled.
+ * than `min_width`.
+ *
+ * The largest-area loop of each island - each group of faces connected through shared edges - is that
+ * island's outline rather than a hole in it, and is never filled, however narrow the island is.
+ *
+ * Each hole is closed by {@link bt_boundary_loop_min_area_fill}: the triangles of least total area over
+ * the hole's own vertices. No vertex is added. A hole that cannot be closed without doubling an edge
+ * the mesh already has is left open and not counted.
  *
  * @param {BinaryTopology} mesh mesh whose boundary loops are inspected and (where too thin) filled in place
  * @param {number} min_width minimum mean width an inner loop must have to be kept; thinner loops are filled

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

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_fill_small_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;GAYG;AACH,0EAHW,MAAM,GACJ,MAAM,CA2ClB"}
+{"version":3,"file":"bt_mesh_fill_small_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0EAHW,MAAM,GACJ,MAAM,CAsElB"}