@rig-c/parts 0.0.0-stage → 1.5.4

package/src/localweights.ts

@@ -0,0 +1,217 @@
+/**
+ * Local deformation regions' weights (issue #84, step 2): a declared region
+ * takes a share of a vertex for its own control bone, and the rest of the
+ * vertex is shared among the mesh's segment bones by `influences()`
+ * (`src/weights.ts`) exactly as the lattice shares it.
+ *
+ * ## The falloff, as a definition
+ *
+ * A region's bone takes the weight
+ *
+ *     g = 1                      inside the region (its boundary included)
+ *     g = 1 − d / band           at a distance d from the region, 0 < d < band
+ *     g = 0                      at d ≥ band (for band 0: everywhere outside)
+ *
+ * where d is the Euclidean distance to the circle (|p − c| − r) or to the
+ * nearest point of the polygon's edges. That is the declared falloff — linear,
+ * no smoothstep, no tuned curve. The two decisions that are not a value in
+ * between — "inside" (g = 1) and "at or past the band" (g = 0) — are made
+ * EXACTLY: every region number is a multiple of 1/256 px (the config loader
+ * refuses anything else) and every vertex this package writes is too
+ * (`src/contour.ts`'s grid, moved by a whole-pixel offset), so both run on
+ * integers — squared distances compared without a square root, the polygon's
+ * inside by the crossing rule on integer orientations, its distance to an edge
+ * compared squared in `BigInt`. Only a value strictly in between is computed
+ * in doubles (`Math.sqrt` and the reference's segment arithmetic), and it is
+ * clamped to [0, 1].
+ *
+ * ## The vertex's weights (see {@link localInfluences})
+ *
+ * With `S = influences(p, segments, r, limits, exponent)` — today's, under the
+ * mesh's declared exponent (issue #161; 2 where none is declared). The
+ * cap and the floor are `limits`: `MAX_INFLUENCES` (4) and `MIN_WEIGHT`
+ * (0.03) for the contour mode, the author's `influences` for the automatic
+ * mode (issue #126, P19):
+ *
+ * - **no region reaches the vertex** (every g = 0): the weights are `S`, and
+ *   the rig stage rounds them exactly as the lattice does — a contour mesh
+ *   with no region is weighted as the lattice would weight the same points;
+ * - **g = 1**: the region's bone alone, weight 1;
+ * - **0 < g < 1**: the region's bone takes g and the segment bones share
+ *   1 − g in `S`'s proportions. A region bone that is also a segment bone
+ *   takes g + (1 − g)·S(bone), one entry. **The cap:** when the region's bone
+ *   is not in `S` and `S` already holds the cap's count of bones, `S`'s
+ *   lightest bone (its last) is dropped and the rest renormalised before the
+ *   scaling, so g itself is never cut. **The floor:** the minimum weight is
+ *   applied inside `S` (as today) and not again to the scaled shares — a
+ *   share (1 − g)·S(b) under 0.03 is the declared falloff near the region, not
+ *   noise to drop, and dropping it would put a step into the linear ramp.
+ *   The rounding: see `roundShares` in `src/rig.ts`.
+ *
+ * ## Overlapping regions
+ *
+ * Refused where it would decide a weight: a vertex that two regions both give
+ * g > 0 is named, with both regions and both g (`RIG_CONTOUR_REGIONS_OVERLAP`
+ * in the rig stage). Rejected: (a) a geometric test that two supports
+ * (region ∪ band) are disjoint — exact for two circles, but for a polygon the
+ * band's outer edge is a curve at every convex corner, and comparing it with
+ * another region is a sum of square roots, not decidable exactly on the grid;
+ * (b) a combination (a sum renormalised when it passes 1, or the larger g) —
+ * definable, but either rewrites the declared g = 1 inside one region wherever
+ * another's band reaches it. The rule as tested is what the weights need:
+ * each vertex holds one region's falloff. Two supports that overlap only
+ * between vertices are not refused, and there the mesh interpolates between
+ * vertices that each hold one region.
+ */
+import type { Point } from './config.ts';
+import { GRID } from './contour.ts';
+import { DEFAULT_LIMITS, DISTANCE_EXPONENT, type Influence, influences, type InfluenceLimits, type Segment, segmentDistance } from './weights.ts';
+
+/**
+ * A region as the weights read it: rig px (or any frame, as long as the point
+ * is in the same one), y down — the fields a contour region and an automatic
+ * mode's weight-and-density region (`src/automesh.ts`) both carry; a
+ * density-only automatic region (issue #155) has no bone and is never read here.
+ */
+export type WeightRegion =
+  | { name: string; shape: 'circle'; cx: number; cy: number; r: number; band: number; bone: string }
+  | { name: string; shape: 'polygon'; points: Point[]; band: number; bone: string };
+
+const units = (v: number, what: string): number => {
+  const u = v * GRID;
+  if (!Number.isInteger(u) || !Number.isSafeInteger(u * u * 4)) throw new Error(`localweights: ${what} ${v} is not a multiple of 1/${GRID} px within the exact range; the config loader refuses such a region`);
+  return u;
+};
+
+/** Twice the signed area of a, b, c on integer units: exact while every difference is under 2^25. */
+function orient(ax: number, ay: number, bx: number, by: number, cx: number, cy: number): number {
+  return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+}
+
+/** Is p on the segment a–b (exact, integer units)? */
+function onSegment(px: number, py: number, ax: number, ay: number, bx: number, by: number): boolean {
+  if (orient(ax, ay, bx, by, px, py) !== 0) return false;
+  return px >= Math.min(ax, bx) && px <= Math.max(ax, bx) && py >= Math.min(ay, by) && py <= Math.max(ay, by);
+}
+
+/** Is the squared distance from p to a–b at least `r2`? Exact, integer units, `BigInt` where a product could pass 2^53. */
+function atLeast(px: number, py: number, ax: number, ay: number, bx: number, by: number, r2: bigint): boolean {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const vx = px - ax;
+  const vy = py - ay;
+  const along = BigInt(vx) * BigInt(dx) + BigInt(vy) * BigInt(dy);
+  const len2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy);
+  const sq = (x: number, y: number): bigint => BigInt(x) * BigInt(x) + BigInt(y) * BigInt(y);
+  if (along <= 0n) return sq(vx, vy) >= r2;
+  if (along >= len2) return sq(px - bx, py - by) >= r2;
+  const cross = BigInt(dx) * BigInt(vy) - BigInt(dy) * BigInt(vx);
+  return cross * cross >= r2 * len2;
+}
+
+/** Strictly inside the ring by the crossing rule, on integer units (a point on an edge is asked separately). */
+function insideRing(px: number, py: number, xs: readonly number[], ys: readonly number[]): boolean {
+  let inside = false;
+  for (let i = 0, j = xs.length - 1; i < xs.length; j = i++) {
+    if (ys[j] > py === ys[i] > py) continue;
+    const o = orient(xs[j], ys[j], xs[i], ys[i], px, py);
+    if (ys[i] > ys[j] ? o > 0 : o < 0) inside = !inside;
+  }
+  return inside;
+}
+
+/**
+ * The declared falloff: the weight a region's bone takes at `p` (same frame as
+ * the region). `p` must be on the 1/256 px grid; see the module header for
+ * which decisions are exact.
+ */
+export function regionWeight(p: Point, reg: WeightRegion): number {
+  const px = units(p[0], 'point x');
+  const py = units(p[1], 'point y');
+  const B = units(reg.band, 'band');
+  if (reg.shape === 'circle') {
+    const dx = px - units(reg.cx, 'cx');
+    const dy = py - units(reg.cy, 'cy');
+    const R = units(reg.r, 'r');
+    const d2 = BigInt(dx) * BigInt(dx) + BigInt(dy) * BigInt(dy);
+    if (d2 <= BigInt(R) * BigInt(R)) return 1;
+    if (B === 0 || d2 >= BigInt(R + B) * BigInt(R + B)) return 0;
+    const d = Math.sqrt(Number(d2)) / GRID - reg.r;
+    return Math.min(1, Math.max(0, 1 - d / reg.band));
+  }
+  const xs = reg.points.map((q) => units(q[0], 'polygon x'));
+  const ys = reg.points.map((q) => units(q[1], 'polygon y'));
+  const n = xs.length;
+  for (let i = 0; i < n; i++) if (onSegment(px, py, xs[i], ys[i], xs[(i + 1) % n], ys[(i + 1) % n])) return 1;
+  if (insideRing(px, py, xs, ys)) return 1;
+  if (B === 0) return 0;
+  const B2 = BigInt(B) * BigInt(B);
+  let far = true;
+  for (let i = 0; i < n && far; i++) far = atLeast(px, py, xs[i], ys[i], xs[(i + 1) % n], ys[(i + 1) % n], B2);
+  if (far) return 0;
+  let d = Infinity;
+  for (let i = 0; i < n; i++) d = Math.min(d, segmentDistance(p, reg.points[i], reg.points[(i + 1) % n]));
+  return Math.min(1, Math.max(0, 1 - d / reg.band));
+}
+
+/** A vertex that two regions both reach: the two, by index in the mesh's list, with each one's g. */
+export interface RegionOverlap {
+  first: number;
+  second: number;
+  g1: number;
+  g2: number;
+}
+
+export interface LocalInfluence {
+  /** Unrounded; they sum to 1 up to the doubles' rounding. Order: see {@link localInfluences}. */
+  influences: Influence[];
+  /** The region that reached the vertex (g > 0), by index, or -1. */
+  region: number;
+  g: number;
+}
+
+/**
+ * A vertex's weights under the mesh's regions (module header). `shares`, when
+ * given, is `S` from another rule — bone heat's shares at the vertex
+ * (`src/heat.ts`, issue #161), already capped and floored by `limits` — and
+ * the regions apply to it exactly as to the distance rule's. Returns the
+ * overlap instead when two regions both reach the vertex. Order: with no
+ * region, `S`'s own order; with a region, the region's bone first, then `S`'s
+ * bones in `S`'s order.
+ */
+export function localInfluences(
+  p: Point,
+  segments: readonly Segment[],
+  r: number,
+  regions: readonly WeightRegion[],
+  limits: InfluenceLimits = DEFAULT_LIMITS,
+  exponent: number = DISTANCE_EXPONENT,
+  shares?: Influence[],
+): LocalInfluence | RegionOverlap {
+  let region = -1;
+  let g = 0;
+  for (let k = 0; k < regions.length; k++) {
+    const gk = regionWeight(p, regions[k]);
+    if (gk <= 0) continue;
+    if (region >= 0) return { first: region, second: k, g1: g, g2: gk };
+    region = k;
+    g = gk;
+  }
+  const S = shares ?? influences(p, segments, r, limits, exponent);
+  if (region < 0) return { influences: S, region, g: 0 };
+  const bone = regions[region].bone;
+  if (g >= 1) return { influences: [{ bone, weight: 1 }], region, g };
+  let base = S;
+  if (!S.some((e) => e.bone === bone) && S.length >= limits.maxInfluences) {
+    const kept = S.slice(0, limits.maxInfluences - 1);
+    let s = 0;
+    for (const e of kept) s += e.weight;
+    base = kept.map((e) => ({ bone: e.bone, weight: e.weight / s }));
+  }
+  const out: Influence[] = [{ bone, weight: g }];
+  for (const e of base) {
+    if (e.bone === bone) out[0] = { bone, weight: out[0].weight + (1 - g) * e.weight };
+    else out.push({ bone: e.bone, weight: (1 - g) * e.weight });
+  }
+  return { influences: out, region, g };
+}

package/src/mesh.ts

@@ -0,0 +1,362 @@
+/**
+ * The lattice mesh: one square grid over a part, every cell that holds an art
+ * pixel kept as two triangles, so the mesh covers 100 % of the art by
+ * construction.
+ *
+ * Ported from the reference implementation's `build_mesh` / `one_loop`. What
+ * it does, in order:
+ *
+ * 1. **Cells.** A grid of `grid`-pixel squares over the (padded) part image;
+ *    the last column and row are clipped to the image. A cell is kept when any
+ *    pixel inside it has alpha above {@link ART_ALPHA}.
+ * 2. **One loop.** rig-c refuses a mesh whose triangles' outline is not
+ *    one closed loop, and a See-through layer is often two islands (a hairpin
+ *    head and its tassel) or has a hole. So the kept cells are made one
+ *    simply-connected region: holes filled (`scipy.ndimage.binary_fill_holes`,
+ *    `fillHoles` here), every other 4-connected island bridged to the largest
+ *    by a straight run of cells, and every diagonal pinch filled. The extra
+ *    cells hold no art and draw nothing. The reference stopped after
+ *    {@link ONE_LOOP_PASSES} passes and returned whatever it had; this port
+ *    then CHECKS the outline and refuses a lattice that is still not one loop
+ *    (`RIG_LATTICE_ONE_LOOP`), rather than hand rigc a mesh it would refuse
+ *    with less to say about why.
+ * 3. **Triangles.** Vertices are numbered in the order the kept cells first
+ *    touch them (row-major cells, corners top-left, top-right, bottom-right,
+ *    bottom-left); each cell is two triangles with the diagonal alternating by
+ *    `(i + j) % 2` so the lattice has no preferred shear. Each triangle is
+ *    built clockwise on screen (top-left, top-right, bottom-right), the
+ *    reference's order, and written with its last two corners swapped
+ *    ({@link counterClockwiseInSpineWorld}): the y flip to Spine's world does
+ *    not turn a loop over, so a triangle clockwise on screen is clockwise in
+ *    Spine world, and the winding rig-c reads a mesh in is
+ *    counter-clockwise there (issue #126; rigc#1236). The swap is made after
+ *    the boundary walk below, so no vertex index and no hull moves with it.
+ * 4. **Boundary first.** Spine's `hull` is a count: the first `hull` vertices
+ *    are the outline, in order. The outline is walked from the edges used by
+ *    exactly one triangle, then every interior vertex follows in index order.
+ * 5. **Coverage.** Every triangle is rasterised (`cv2.fillPoly`, `fillPoly`
+ *    here) and the fraction of art pixels it covers is reported. By
+ *    construction it is 1; it is measured anyway, because a claim that holds
+ *    by construction is exactly the kind nobody re-reads.
+ *
+ * Every tie and every scan order above is the reference's, because each one
+ * decides a vertex index, and a vertex index is what a weight is written
+ * against.
+ */
+import { type Problem } from './errors.ts';
+import { connectedComponents, fillHoles, fillPoly, type Mask, newMask } from './raster/index.ts';
+import { rint } from './round.ts';
+
+/** A pixel counts as art when its alpha is above this — the reference's `im[..., 3] > 8`. */
+export const ART_ALPHA = 8;
+
+/** How many hole-fill / bridge / pinch passes `oneLoop` makes before it stops — the reference's `range(50)`. */
+export const ONE_LOOP_PASSES = 50;
+
+export interface Lattice {
+  /** Cells across and down. */
+  nx: number;
+  ny: number;
+  /** Column and row edges in image pixels, `nx + 1` and `ny + 1` of them, the last clipped to the image. */
+  xs: number[];
+  ys: number[];
+  /** `ny` rows of `nx` cells, 1 = kept. */
+  cells: Mask;
+}
+
+/** The grid over an image and which of its cells hold an art pixel. */
+export function latticeCells(art: Mask, grid: number): Lattice {
+  const { width: w, height: h } = art;
+  const nx = Math.ceil(w / grid);
+  const ny = Math.ceil(h / grid);
+  const xs = Array.from({ length: nx + 1 }, (_, i) => Math.min(i * grid, w));
+  const ys = Array.from({ length: ny + 1 }, (_, j) => Math.min(j * grid, h));
+  const cells = newMask(nx, ny);
+  for (let j = 0; j < ny; j++) {
+    for (let i = 0; i < nx; i++) {
+      let any = 0;
+      for (let y = ys[j]; y < ys[j + 1] && any === 0; y++) {
+        for (let x = xs[i]; x < xs[i + 1]; x++) {
+          if (art.data[y * w + x] !== 0) {
+            any = 1;
+            break;
+          }
+        }
+      }
+      cells.data[j * nx + i] = any;
+    }
+  }
+  return { nx, ny, xs, ys, cells };
+}
+
+/** `np.linspace(0, 1, num)` element by element: `k * (1 / (num - 1))`, the last exactly 1. */
+function linspace01(num: number): number[] {
+  const step = 1 / (num - 1);
+  return Array.from({ length: num }, (_, k) => (k === num - 1 ? 1 : k * step));
+}
+
+export interface OneLoopResult {
+  cells: Mask;
+  /** Passes made; a pass that changes nothing ends the loop. */
+  passes: number;
+  /** Whether the last pass changed nothing — false when the pass limit ran out first. */
+  settled: boolean;
+}
+
+/**
+ * The reference's `one_loop`: fill holes, bridge islands to the largest,
+ * fill diagonal pinches, repeat until a pass changes nothing or `maxPasses`
+ * run out.
+ *
+ * A bridge from island cell (j0, i0) to main cell (j1, i1) — the pair at the
+ * least squared distance, first in row-major order of island then main —
+ * sets, at every `t` of `linspace(0, 1, 2 * (|dj| + |di|) + 2)`, the cells
+ * (round(j0 + dj t), i0), (j1, round(i0 + di t)) and (round(j0 + dj t),
+ * round(i0 + di t)), with NumPy's half-to-even rounding. The first two are an
+ * L-shaped 4-connected run, so the bridge always connects.
+ */
+export function oneLoop(start: Mask, maxPasses: number = ONE_LOOP_PASSES): OneLoopResult {
+  const nx = start.width;
+  const ny = start.height;
+  let cells: Mask = { width: nx, height: ny, data: new Uint8Array(start.data) };
+  for (let pass = 0; pass < maxPasses; pass++) {
+    cells = fillHoles(cells);
+    const comp = connectedComponents(cells, 4);
+    const islands = comp.count - 1;
+    if (islands > 1) {
+      let main = 1;
+      for (let k = 2; k < comp.count; k++) if (comp.stats[k].area > comp.stats[main].area) main = k;
+      const members = (label: number): Array<[number, number]> => {
+        const out: Array<[number, number]> = [];
+        for (let j = 0; j < ny; j++) for (let i = 0; i < nx; i++) if (comp.labels[j * nx + i] === label) out.push([j, i]);
+        return out;
+      };
+      const mainCells = members(main);
+      for (let k = 1; k < comp.count; k++) {
+        if (k === main) continue;
+        const other = members(k);
+        let best = Infinity;
+        let a = 0;
+        let b = 0;
+        for (let p = 0; p < other.length; p++) {
+          for (let q = 0; q < mainCells.length; q++) {
+            const dj = other[p][0] - mainCells[q][0];
+            const di = other[p][1] - mainCells[q][1];
+            const d = dj * dj + di * di;
+            if (d < best) {
+              best = d;
+              a = p;
+              b = q;
+            }
+          }
+        }
+        const [j0, i0] = other[a];
+        const [j1, i1] = mainCells[b];
+        const set = (j: number, i: number): void => {
+          cells.data[j * nx + i] = 1;
+        };
+        for (const t of linspace01(2 * (Math.abs(j1 - j0) + Math.abs(i1 - i0)) + 2)) {
+          set(rint(j0 + (j1 - j0) * t), i0);
+          set(j1, rint(i0 + (i1 - i0) * t));
+          set(rint(j0 + (j1 - j0) * t), rint(i0 + (i1 - i0) * t));
+        }
+      }
+      continue;
+    }
+    const snap = new Uint8Array(cells.data);
+    const at = (j: number, i: number): number => snap[j * nx + i];
+    let pinch = false;
+    for (let j = 0; j < ny - 1; j++) {
+      for (let i = 0; i < nx - 1; i++) {
+        if (at(j, i) && at(j + 1, i + 1) && !at(j, i + 1) && !at(j + 1, i)) {
+          cells.data[j * nx + i + 1] = 1;
+          pinch = true;
+        } else if (at(j, i + 1) && at(j + 1, i) && !at(j, i) && !at(j + 1, i + 1)) {
+          cells.data[j * nx + i] = 1;
+          pinch = true;
+        }
+      }
+    }
+    if (!pinch) return { cells, passes: pass + 1, settled: true };
+  }
+  return { cells, passes: maxPasses, settled: false };
+}
+
+/**
+ * Each triple `[a, b, c]` written `[a, c, b]`: the same triangles over the same
+ * vertices, wound the other way round. A triangle list built clockwise on
+ * screen (positive area in crop pixels, y down) is clockwise in Spine world as
+ * well — flipping y changes the sign of a signed area, but Spine's world is
+ * drawn with y up, so the loop turns the same way on screen as there — and
+ * rig-c reads every mesh as counter-clockwise in Spine world (its
+ * `MQ_ORIENTATION`; rigc#1236 turned its own `contour` and `ring` generators
+ * for the same reason). The lattice ({@link triangulate}) and the contour mesh
+ * (`src/contour.ts`) both build clockwise on screen and write through this,
+ * once, at their output; nothing downstream turns them again (issue #126).
+ */
+export function counterClockwiseInSpineWorld(triangles: readonly number[]): number[] {
+  const out: number[] = [];
+  for (let t = 0; t < triangles.length; t += 3) out.push(triangles[t], triangles[t + 2], triangles[t + 1]);
+  return out;
+}
+
+export interface LatticeMesh {
+  /** Vertex positions in image pixels, boundary first. */
+  vertices: Array<[number, number]>;
+  /** Three vertex indices per triangle, into `vertices`, each counter-clockwise in Spine world. */
+  triangles: number[];
+  /** The first `hull` vertices are the outline. */
+  hull: number;
+  /** Closed outlines the triangles make — 1 for a mesh rigc will take. */
+  loops: number;
+  /** Boundary vertices touched by more or fewer than two boundary edges — 0 for a mesh rigc will take. */
+  pinchedVertices: number;
+  cells: number;
+  passes: number;
+}
+
+/**
+ * Triangles over the kept cells, boundary vertices first. Returns the loop
+ * count and the pinched-vertex count rather than refusing, so the caller names
+ * the part in its refusal.
+ */
+export function triangulate(lattice: Lattice, cells: Mask, passes: number): LatticeMesh {
+  const { nx, ny, xs, ys } = lattice;
+  const vid = new Int32Array((nx + 1) * (ny + 1)).fill(-1);
+  const pts: Array<[number, number]> = [];
+  const tri: number[] = [];
+  let kept = 0;
+  for (let j = 0; j < ny; j++) {
+    for (let i = 0; i < nx; i++) {
+      if (cells.data[j * nx + i] === 0) continue;
+      kept++;
+      const c: number[] = [];
+      for (const [jj, ii] of [
+        [j, i],
+        [j, i + 1],
+        [j + 1, i + 1],
+        [j + 1, i],
+      ]) {
+        const k = jj * (nx + 1) + ii;
+        if (vid[k] < 0) {
+          vid[k] = pts.length;
+          pts.push([xs[ii], ys[jj]]);
+        }
+        c.push(vid[k]);
+      }
+      if ((i + j) % 2 === 0) tri.push(c[0], c[1], c[2], c[0], c[2], c[3]);
+      else tri.push(c[0], c[1], c[3], c[1], c[2], c[3]);
+    }
+  }
+  // Boundary edges: used by exactly one triangle, counted in first-seen order
+  // (the reference's Counter), then adjacency in that same order.
+  const edgeCount = new Map<string, { a: number; b: number; n: number }>();
+  for (let t = 0; t < tri.length; t += 3) {
+    for (const [p, q] of [
+      [tri[t], tri[t + 1]],
+      [tri[t + 1], tri[t + 2]],
+      [tri[t + 2], tri[t]],
+    ]) {
+      const a = Math.min(p, q);
+      const b = Math.max(p, q);
+      const key = `${a},${b}`;
+      const e = edgeCount.get(key);
+      if (e === undefined) edgeCount.set(key, { a, b, n: 1 });
+      else e.n++;
+    }
+  }
+  const adj = new Map<number, number[]>();
+  const link = (p: number, q: number): void => {
+    const list = adj.get(p);
+    if (list === undefined) adj.set(p, [q]);
+    else list.push(q);
+  };
+  for (const { a, b, n } of edgeCount.values()) {
+    if (n !== 1) continue;
+    link(a, b);
+    link(b, a);
+  }
+  const order: number[] = [];
+  const seen = new Set<number>();
+  let loops = 0;
+  for (const s of adj.keys()) {
+    if (seen.has(s)) continue;
+    loops++;
+    let cur = s;
+    let prev = -1;
+    while (!seen.has(cur)) {
+      seen.add(cur);
+      order.push(cur);
+      const next = (adj.get(cur) ?? []).filter((v) => v !== prev && !seen.has(v));
+      if (next.length === 0) break;
+      prev = cur;
+      cur = next[0];
+    }
+  }
+  let pinchedVertices = 0;
+  for (const list of adj.values()) if (list.length !== 2) pinchedVertices++;
+  const hull = order.length;
+  for (let v = 0; v < pts.length; v++) if (!seen.has(v)) order.push(v);
+  const remap = new Int32Array(pts.length);
+  order.forEach((v, i) => (remap[v] = i));
+  return {
+    vertices: order.map((v) => pts[v]),
+    triangles: counterClockwiseInSpineWorld(tri.map((v) => remap[v])),
+    hull,
+    loops,
+    pinchedVertices,
+    cells: kept,
+    passes,
+  };
+}
+
+/** The fraction of art pixels the triangles cover, rasterised as `cv2.fillPoly` would. */
+export function artCoverage(mesh: LatticeMesh, art: Mask): number {
+  const ras = newMask(art.width, art.height);
+  for (let t = 0; t < mesh.triangles.length; t += 3) {
+    const corner = (k: number): [number, number] => {
+      const [x, y] = mesh.vertices[mesh.triangles[t + k]];
+      return [rint(x), rint(y)];
+    };
+    fillPoly(ras, [corner(0), corner(1), corner(2)]);
+  }
+  let artPx = 0;
+  let covered = 0;
+  for (let i = 0; i < art.data.length; i++) {
+    if (art.data[i] === 0) continue;
+    artPx++;
+    if (ras.data[i] !== 0) covered++;
+  }
+  return artPx === 0 ? 0 : covered / artPx;
+}
+
+/**
+ * The whole lattice step for one part: cells, one loop, triangles. Refusals
+ * name the part: a part with no art pixel has no cell to keep, and a lattice
+ * still not one closed outline after the passes is refused rather than handed on.
+ */
+export function latticeMesh(part: string, art: Mask, grid: number, maxPasses: number = ONE_LOOP_PASSES): LatticeMesh | Problem {
+  const lattice = latticeCells(art, grid);
+  let any = false;
+  for (let i = 0; i < lattice.cells.data.length && !any; i++) any = lattice.cells.data[i] !== 0;
+  if (!any) {
+    return {
+      code: 'RIG_PART_HAS_ART',
+      object: `mesh "${part}"`,
+      detail: `its ${art.width}x${art.height} image has no pixel with alpha above ${ART_ALPHA}, so the lattice keeps no cell; a mesh needs at least one art pixel`,
+    };
+  }
+  const loop = oneLoop(lattice.cells, maxPasses);
+  const mesh = triangulate(lattice, loop.cells, loop.passes);
+  if (mesh.loops !== 1 || mesh.pinchedVertices !== 0) {
+    return {
+      code: 'RIG_LATTICE_ONE_LOOP',
+      object: `mesh "${part}"`,
+      detail:
+        `after ${loop.passes} pass(es) of hole-fill, island-join and pinch-fill (${loop.settled ? 'settled' : `the limit of ${maxPasses} ran out`}) ` +
+        `its ${lattice.nx}x${lattice.ny} lattice at grid ${grid} has ${mesh.loops} outline loop(s) and ${mesh.pinchedVertices} pinched boundary vertex(es); ` +
+        'exactly one closed loop and none pinched are required (rig-c refuses any other outline)',
+    };
+  }
+  return mesh;
+}