spine-rigc 1.2.2 → 1.3.0

package/src/mesh.ts

@@ -99,7 +99,7 @@ export interface MeshVertexWeight {
 }
 
 /** Which builder in this file made a mesh's geometry. */
-export type MeshKind = 'ring' | 'ribbon' | 'contour' | 'grid';
+export type MeshKind = 'ring' | 'ribbon' | 'contour' | 'grid' | 'segments';
 
 export interface MeshGeometry {
   kind: MeshKind;
@@ -1795,3 +1795,407 @@ export function meshEdges(vertexCount: number, triangles: readonly number[], hul
   for (const [a, b] of interior) out.push(2 * a, 2 * b);
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// segments — a lattice over the part's alpha, weighted by distance to bones
+// ---------------------------------------------------------------------------
+//
+// The generator for "an arbitrary layer pulled by a chosen set of bones". Its
+// one authored input is WHICH segments may pull the part; the geometry is read
+// off the art and the weights off the distance between the two, so a pipeline
+// that used to re-implement distance weighting outside the compiler states the
+// segment list and nothing else.
+//
+// The algorithm is a port of `spine-parts`' lattice mesh and segment weights
+// (MIT, same owner). What it does, in order:
+//
+//   1. **Cells.** A square lattice of `cell`-pixel squares over the part; the
+//      last column and row are clipped to the image. A cell is kept when any
+//      pixel inside it reaches the alpha threshold, so the triangles cover
+//      every art pixel by construction.
+//   2. **One loop.** Spine's `hull` is one closed outline, and a layer is often
+//      two islands or has a hole. So the kept cells are made one simply
+//      connected region: holes filled, every other island bridged to the
+//      largest by a straight run of cells, every diagonal pinch filled, and the
+//      three repeated until a pass changes nothing. Every pass that does not
+//      settle adds at least one cell, so the loop is bounded by the lattice and
+//      needs no pass limit of its own. The added cells hold no art.
+//   3. **Triangles.** Vertices numbered in the order the kept cells first touch
+//      them (cells row-major; corners top-left, top-right, bottom-right,
+//      bottom-left), each cell two triangles with the diagonal alternating by
+//      `(i + j) % 2`, so the lattice has no preferred shear. Emitted
+//      counter-clockwise in Spine world, the winding every generator here
+//      writes (GR02 holds the grid to it).
+//   4. **Outline first.** The boundary is walked from the edges used by exactly
+//      one triangle, in first-seen order, and every interior vertex follows in
+//      index order — the arrangement `checkHullOrder` requires.
+//   5. **Weights.** Per vertex and per candidate segment, `w = 1 / (d + r)^p`
+//      where `d` is the distance to the segment's nearest point; a bone two
+//      segments name keeps the larger; the strongest `maxBones` are kept and
+//      normalised, a share under `minWeight` is dropped, and the rest are
+//      normalised again. Ties keep the order the bones first appear in.
+
+/** What the lattice step did, for the report and for the refusals. */
+export interface SegmentsLatticeReport {
+  /** Cells across and down. */
+  cols: number;
+  rows: number;
+  /** Cells holding an art pixel, and cells kept after the one-loop passes. */
+  artCells: number;
+  keptCells: number;
+  /** Passes of hole-fill, island-join and pinch-fill until one changed nothing. */
+  passes: number;
+  /** 4-connected islands of art cells before the joins. */
+  islands: number;
+}
+
+export interface SegmentsLattice {
+  /** Vertex positions in part-local pixels, y down, outline first. */
+  points: Array<[number, number]>;
+  uvs: number[];
+  /** Counter-clockwise in Spine world. */
+  triangles: number[];
+  hullVertices: number;
+  report: SegmentsLatticeReport;
+}
+
+/** `np.rint`: to the nearest integer, exact halves to even — the bridge's rounding. */
+function rintEven(x: number): number {
+  const f = Math.floor(x);
+  const frac = x - f;
+  if (frac < 0.5) return f;
+  if (frac > 0.5) return f + 1;
+  return f % 2 === 0 ? f : f + 1;
+}
+
+/** Fill every background cell the lattice border cannot reach through 4-connected background. */
+function fillCellHoles(cells: Uint8Array, nx: number, ny: number): Uint8Array {
+  const outside = new Uint8Array(nx * ny);
+  const stack: number[] = [];
+  const seed = (i: number): void => {
+    if (cells[i] === 0 && outside[i] === 0) {
+      outside[i] = 1;
+      stack.push(i);
+    }
+  };
+  for (let x = 0; x < nx; x++) {
+    seed(x);
+    seed((ny - 1) * nx + x);
+  }
+  for (let y = 0; y < ny; y++) {
+    seed(y * nx);
+    seed(y * nx + nx - 1);
+  }
+  while (stack.length > 0) {
+    const i = stack.pop()!;
+    const x = i % nx;
+    const y = (i - x) / nx;
+    if (x > 0) seed(i - 1);
+    if (x < nx - 1) seed(i + 1);
+    if (y > 0) seed(i - nx);
+    if (y < ny - 1) seed(i + nx);
+  }
+  const out = new Uint8Array(nx * ny);
+  for (let i = 0; i < out.length; i++) out[i] = outside[i] === 1 ? 0 : 1;
+  return out;
+}
+
+/**
+ * 4-connected components of the kept cells, numbered in raster order of each
+ * component's first cell, each with its cells in raster order.
+ */
+function cellIslands(cells: Uint8Array, nx: number, ny: number): Array<Array<[number, number]>> {
+  const label = new Int32Array(nx * ny).fill(-1);
+  const islands: Array<Array<[number, number]>> = [];
+  for (let start = 0; start < cells.length; start++) {
+    if (cells[start] === 0 || label[start] >= 0) continue;
+    const id = islands.length;
+    const stack = [start];
+    label[start] = id;
+    while (stack.length > 0) {
+      const i = stack.pop()!;
+      const x = i % nx;
+      const y = (i - x) / nx;
+      const visit = (j: number): void => {
+        if (cells[j] !== 0 && label[j] < 0) {
+          label[j] = id;
+          stack.push(j);
+        }
+      };
+      if (x > 0) visit(i - 1);
+      if (x < nx - 1) visit(i + 1);
+      if (y > 0) visit(i - nx);
+      if (y < ny - 1) visit(i + nx);
+    }
+    islands.push([]);
+  }
+  for (let i = 0; i < cells.length; i++) if (label[i] >= 0) islands[label[i]].push([(i - (i % nx)) / nx, i % nx]);
+  return islands;
+}
+
+/**
+ * The lattice over one part's alpha: cells, one loop, triangles, outline first.
+ *
+ * Refuses a part that keeps no cell and a cell that is not a whole number of
+ * pixels of at least 1; everything else about the geometry follows from the art.
+ */
+export function buildSegmentsLattice(input: { mask: AlphaMask; threshold: number; cell: number }): SegmentsLattice {
+  const { mask, threshold, cell } = input;
+  const { width: w, height: h } = mask;
+  if (!Number.isInteger(cell) || cell < 1) {
+    throw new MeshError(`"cell" is ${JSON.stringify(cell)}; it is the lattice's square, a whole number of pixels of at least 1`);
+  }
+  if (!Number.isInteger(threshold) || threshold < 1 || threshold > 255) {
+    throw new MeshError(`the alpha threshold must be a whole number in 1..255, got ${threshold}`);
+  }
+  const nx = Math.ceil(w / cell);
+  const ny = Math.ceil(h / cell);
+  const xs = Array.from({ length: nx + 1 }, (_, i) => Math.min(i * cell, w));
+  const ys = Array.from({ length: ny + 1 }, (_, j) => Math.min(j * cell, h));
+  let cells: Uint8Array = new Uint8Array(nx * ny);
+  let artCells = 0;
+  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 (mask.alpha[y * w + x] >= threshold) {
+            any = 1;
+            break;
+          }
+        }
+      }
+      cells[j * nx + i] = any;
+      artCells += any;
+    }
+  }
+  if (artCells === 0) {
+    throw new MeshError(
+      `no pixel of the ${w}x${h} part reaches alpha ${threshold}, so a lattice at cell ${cell} keeps no cell — ` +
+        'there is no art to cover. Lower "alpha", or point at the image this mesh is meant to draw',
+    );
+  }
+  const islands = cellIslands(cells, nx, ny).length;
+
+  // 2. one loop, until a pass changes nothing.
+  let passes = 0;
+  for (;;) {
+    passes++;
+    cells = fillCellHoles(cells, nx, ny);
+    const found = cellIslands(cells, nx, ny);
+    if (found.length > 1) {
+      let main = 0;
+      for (let k = 1; k < found.length; k++) if (found[k].length > found[main].length) main = k;
+      const mainCells = found[main];
+      for (let k = 0; k < found.length; k++) {
+        if (k === main) continue;
+        const other = found[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 steps = 2 * (Math.abs(j1 - j0) + Math.abs(i1 - i0)) + 2;
+        const stride = 1 / (steps - 1);
+        for (let s = 0; s < steps; s++) {
+          const t = s === steps - 1 ? 1 : s * stride;
+          cells[rintEven(j0 + (j1 - j0) * t) * nx + i0] = 1;
+          cells[j1 * nx + rintEven(i0 + (i1 - i0) * t)] = 1;
+          cells[rintEven(j0 + (j1 - j0) * t) * nx + rintEven(i0 + (i1 - i0) * t)] = 1;
+        }
+      }
+      continue;
+    }
+    const snap = new Uint8Array(cells);
+    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[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[j * nx + i] = 1;
+          pinch = true;
+        }
+      }
+    }
+    if (!pinch) break;
+  }
+
+  // 3. triangles, in the lattice's own winding (top-left, top-right, bottom-right).
+  const vid = new Int32Array((nx + 1) * (ny + 1)).fill(-1);
+  const pts: Array<[number, number]> = [];
+  const tri: number[] = [];
+  let keptCells = 0;
+  for (let j = 0; j < ny; j++) {
+    for (let i = 0; i < nx; i++) {
+      if (cells[j * nx + i] === 0) continue;
+      keptCells++;
+      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]);
+    }
+  }
+
+  // 4. the outline, walked from the boundary edges in first-seen order.
+  const edgeUses = new Map<number, { a: number; b: number; n: number }>();
+  const V = pts.length;
+  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 * V + b;
+      const e = edgeUses.get(key);
+      if (e === undefined) edgeUses.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 edgeUses.values()) {
+    if (n !== 1) continue;
+    link(a, b);
+    link(b, a);
+  }
+  const order: number[] = [];
+  const seen = new Set<number>();
+  for (const s of adj.keys()) {
+    if (seen.has(s)) continue;
+    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];
+    }
+  }
+  const hullVertices = order.length;
+  for (let v = 0; v < V; v++) if (!seen.has(v)) order.push(v);
+  const remap = new Int32Array(V);
+  order.forEach((v, i) => (remap[v] = i));
+  const points = order.map((v) => pts[v]);
+  // Emitted counter-clockwise in Spine world: the lattice's corners were taken
+  // clockwise on the y-down page, so each triangle's last two are swapped.
+  const triangles: number[] = [];
+  for (let t = 0; t < tri.length; t += 3) triangles.push(remap[tri[t]], remap[tri[t + 2]], remap[tri[t + 1]]);
+  const uvs: number[] = [];
+  for (const [x, y] of points) uvs.push(r6(x / w), r6(y / h));
+  return {
+    points,
+    uvs,
+    triangles,
+    hullVertices,
+    report: { cols: nx, rows: ny, artCells, keptCells, passes, islands },
+  };
+}
+
+/** One candidate segment, in Spine world, and which of the mesh's bones it belongs to. */
+export interface WorldSegment {
+  /** Index into the mesh's distinct bone list. */
+  bone: number;
+  a: readonly [number, number];
+  b: readonly [number, number];
+}
+
+/** The four numbers the falloff reads, every one of them from the spec. */
+export interface SegmentsFalloff {
+  power: number;
+  radius: number;
+  maxBones: number;
+  minWeight: number;
+}
+
+/**
+ * Distance from `p` to the segment `a -> b`, a zero-length segment being its point.
+ *
+ * `sqrt(dx*dx + dy*dy)` rather than `Math.hypot`, whose last bit can differ:
+ * a weight is written on a 6-decimal grid, and that is where one ulp becomes a
+ * different number in the file.
+ */
+export function segmentDistance(p: readonly [number, number], a: readonly [number, number], b: readonly [number, number]): number {
+  const abx = b[0] - a[0];
+  const aby = b[1] - a[1];
+  const len2 = abx * abx + aby * aby;
+  let t = 0;
+  if (len2 > 0) {
+    t = ((p[0] - a[0]) * abx + (p[1] - a[1]) * aby) / len2;
+    t = t < 0 ? 0 : t > 1 ? 1 : t;
+  }
+  const dx = p[0] - (a[0] + t * abx);
+  const dy = p[1] - (a[1] + t * aby);
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * The shares on one vertex, strongest first and closing at exactly 1 on the
+ * generator's 6-decimal grid — or, when every share the kept bones carry is
+ * under `minWeight`, the unrounded shares that were dropped, for the refusal to
+ * print. A vertex is never given a bone the falloff did not choose.
+ */
+export function segmentShares(
+  p: readonly [number, number],
+  segments: readonly WorldSegment[],
+  falloff: SegmentsFalloff,
+): { weights: MeshVertexWeight[] } | { dropped: Array<{ bone: number; share: number }> } {
+  const byBone = new Map<number, number>();
+  for (const s of segments) {
+    const reach = segmentDistance(p, s.a, s.b) + falloff.radius;
+    const w = 1 / Math.pow(reach, falloff.power);
+    const was = byBone.get(s.bone);
+    byBone.set(s.bone, was === undefined ? w : Math.max(was, w));
+  }
+  // `sort` is stable, so equal pulls keep the order the bones first appeared in.
+  const top = [...byBone.entries()].sort((x, y) => y[1] - x[1]).slice(0, falloff.maxBones);
+  let sum = 0;
+  for (const [, v] of top) sum += v;
+  const shares = top.map(([bone, v]) => ({ bone, share: v / sum }));
+  const kept = shares.filter((e) => e.share >= falloff.minWeight);
+  if (kept.length === 0) return { dropped: shares };
+  let sum2 = 0;
+  for (const e of kept) sum2 += e.share;
+  const weights: MeshVertexWeight[] = [];
+  let others = 0;
+  kept.forEach((e, k) => {
+    const weight = k === kept.length - 1 ? r6(1 - others) : r6(e.share / sum2);
+    others += weight;
+    weights.push({ bone: 'control', control: e.bone, weight });
+  });
+  return { weights };
+}

package/src/pose.ts

@@ -196,6 +196,87 @@ const MAX_ALTERNATES = 3;
 
 const DEG = Math.PI / 180;
 
+/**
+ * The detail below which `pose` has been MEASURED to almost never place a part
+ * — the floor a refusal or an ambiguity is read against (issue #857).
+ *
+ * 📏 Measured, not chosen: `tools/pose_floor.ts` builds the grid and derives
+ * `detail` (`deriveFloor`: the largest rung of a fixed ladder under which at
+ * most a tenth of the grid's trials were found), and `docs/AUTHORING.md` §11.5
+ * carries the grid, the method and what it rejected. A part is BELOW the floor
+ * when its `detail` is under `detail`, or its longest side, in its own pixels,
+ * under `span` — the grid cut its parts at scale 1, so its sizes are both.
+ *
+ * ⚠️ Two things this is not. It is not a size found to matter: `span` is the
+ * smallest size the grid measured, and over 24–192 px no texture level placed
+ * measurably better when larger — a part under it is below the floor because
+ * nothing was measured there, not because it was measured to fail. And it is
+ * not a line above which `pose` is reliable: over it, on IDEAL cuts (parts cut
+ * from the frame's own render, residual at the truth near zero), `rateAbove`
+ * of the trials were found. A generated cut also disagrees with its picture,
+ * which can only make that lower. So "above the floor" means "plainness does
+ * not explain this refusal", which is the question the issue asked, and never
+ * "this part will place".
+ */
+export const POSE_FLOOR = {
+  material: 'examples/spineboy, cut from its own render (tools/pose_floor.ts)',
+  withinPx: 2,
+  span: 24,
+  detail: 0.5,
+  /** Found share of the grid's trials under `detail`, and over it — both measured by `deriveFloor`. */
+  rateBelow: 0.066,
+  rateAbove: 0.594,
+};
+
+/** Which side of `POSE_FLOOR` a part is on, from its own longest side in part pixels and its detail. */
+export function floorSide(side: number, detail: number): 'below' | 'above' {
+  return side >= POSE_FLOOR.span && detail >= POSE_FLOOR.detail ? 'above' : 'below';
+}
+
+/** The floor as one clause, for the sentences that cite it. */
+export function floorClause(): string {
+  return `detail ${POSE_FLOOR.detail}, measured from ${POSE_FLOOR.span} px up`;
+}
+
+/**
+ * The sentence that tells "the part is wrong" from "the part is too small or too
+ * plain for `pose`", with every figure it rests on (issue #857).
+ *
+ * ⭐ Exported for the reason `windowEdgeNote` is: the guide quotes it, and a
+ * message and the document teaching it must be built from one place.
+ */
+export function legibilityReading(l: Omit<PoseLegibility, 'reading'>, verdict: 'refused' | 'ambiguous'): string {
+  const figures =
+    `part is ${l.width}x${l.height} px (span ${l.span} frame px, opaque ${l.opaqueShare}) with texture ${l.texture}, ` +
+    `detail ${l.detail}; ` +
+    `${l.candidates} candidate(s), best ${l.best.toFixed(4)}` +
+    (l.next === null || l.spread === null ? '' : `, next ${l.next.toFixed(4)}, spread ${l.spread.toFixed(4)}`);
+  if (l.floor === 'below') {
+    const why =
+      Math.max(l.width, l.height) < POSE_FLOOR.span
+        ? `smaller than the smallest size the floor was measured at, so nothing measured says pose can ` +
+          `${verdict === 'refused' ? 'place' : 'separate'} it`
+        : `pose placed ${Math.round(POSE_FLOOR.rateBelow * 100)}% of the measured parts this plain, so this part is too ` +
+          `plain for pose to ${verdict === 'refused' ? 'place' : 'tell its placements apart'}`;
+    return (
+      `${figures} — below the measured floor (AUTHORING §11.5: ${floorClause()}): ${why}; that says nothing about ` +
+      'whether the cut is right'
+    );
+  }
+  // ⚠️ "Above the floor" is not "the search found the right hill". Measured on
+  // the floor's own material, a part above it came back ambiguous between two
+  // equally WRONG placements (residual 0.148 each, 173 px off) while the truth
+  // scored 0.035 — a basin the coarse pass never sent down. So the sentence
+  // names that reading too, with the one remedy that separates it: a window.
+  return (
+    `${figures} — above the measured floor (AUTHORING §11.5: ${floorClause()}), so size and texture do not explain this; ` +
+    (verdict === 'refused'
+      ? 'the cut (or the search window) is the suspect'
+      : 'either the frame holds more than one place this part fits, or every candidate missed the true one — ' +
+        'a narrower --scale or --rotation window around what you know of the part tells the two apart')
+  );
+}
+
 // ---------------------------------------------------------------------------
 // the report
 // ---------------------------------------------------------------------------
@@ -307,10 +388,69 @@ export interface PosePart {
    * the part is small relative to the frame and the first pass had little to go on.
    */
   coarse: { reduction: number; cols: number; rows: number; stride: number } | null;
+  /**
+   * What the part itself gave the search to work with, and how the search's
+   * answers stood against each other — `null` only when nothing was searched
+   * (`empty-part`, `larger-than-canvas`). See `PoseLegibility`.
+   */
+  legibility: PoseLegibility | null;
   /** Plain-language versions of everything above, in the order they were found. */
   notes: string[];
 }
 
+/**
+ * The facts that tell "this part is wrong" from "this part is too small or too
+ * plain for `pose`" (issue #857).
+ *
+ * ⭐ Both readings end in the same refusal or the same ambiguity, and nothing in
+ * a residual separates them: a correct cut of a plain sleeve and a foreign part
+ * can print the same number. What separates them is the part's own evidence —
+ * how big it is in the frame and how much pattern it carries — held against a
+ * floor measured on parts whose placement was known (`POSE_FLOOR`). So every
+ * searched part carries these, whatever its verdict, and a refusal or an
+ * ambiguity quotes them in a sentence that says which of the two it is.
+ */
+export interface PoseLegibility {
+  /** The part's material box, part pixels — the PNG less its transparent margin. */
+  width: number;
+  height: number;
+  /**
+   * Longest side of the material box at the best placement's scale, frame pixels.
+   * ⚠️ Not what `floor` is read from — the part's own `width`/`height` are, since
+   * this one moves with a placement that may be wrong.
+   */
+  span: number;
+  /** The part's alpha weight over its material box's area, 0..1. A thin diagonal limb reads low; a filled block reads 1. */
+  opaqueShare: number;
+  /** Mean colour step between neighbouring material pixels, 0..1 — see `partTexture`. */
+  texture: number;
+  /**
+   * `texture` times the material box's longest side in PART pixels: the colour
+   * change a walk along the part's length accumulates. The figure the floor is
+   * stated in — see `POSE_FLOOR` for why it and not `texture` alone.
+   */
+  detail: number;
+  /** Distinct placements the search measured at full resolution, the best included. */
+  candidates: number;
+  /** The best placement's residual, and the second distinct one's — `null` when there was no second. */
+  best: number;
+  next: number | null;
+  /** `next − best`: how far the search's second answer was from its first. `null` with no second. */
+  spread: number | null;
+  /**
+   * Where the part stands against `POSE_FLOOR` — `below` when its span or its
+   * detail is under the floor's. A reading of the part, not of the answer: it is set on accepted
+   * parts too, and it is what a refusal's sentence is chosen by.
+   */
+  floor: 'below' | 'above';
+  /**
+   * The sentence a refused or ambiguous part carries, saying which of the two
+   * readings its figures support — `null` on a part that was placed. Built by
+   * `legibilityReading`, and the console prints the same text.
+   */
+  reading: string | null;
+}
+
 export interface PoseSearch {
   scale: { min: number; max: number; steps: number };
   /**
@@ -550,6 +690,45 @@ function materialBox(part: Plate): { minX: number; minY: number; maxX: number; m
   return { minX, minY, maxX: maxX + 1, maxY: maxY + 1, weight };
 }
 
+/**
+ * The part's texture figure: the mean colour step between neighbouring material
+ * pixels, 0..1, in the residual's own units.
+ *
+ * Every pair of a pixel and its right or lower neighbour, both with material,
+ * contributes its mean absolute channel difference over 255, weighted by the
+ * smaller of the two alphas. A part filled with one colour reads exactly 0.
+ *
+ * ⭐ Why this figure rather than a colour variance: it is, to first order, what a
+ * one-pixel shift costs. Moving a part by a pixel inside material that continues
+ * under it compares each of its pixels against its neighbour's colour, so the
+ * residual rises by about this much per pixel of shift — and a part whose
+ * residual cannot rise when it moves cannot be told apart from itself moved.
+ * A variance does not see that: a part half one colour and half another has a
+ * large variance and one edge. The silhouette is deliberately not counted — it
+ * is what the material term already reads, and only where the frame is ground.
+ */
+export function partTexture(part: Plate): number {
+  const w = part.width;
+  const d = part.data;
+  let weight = 0;
+  let acc = 0;
+  const pair = (i: number, j: number): void => {
+    const k = Math.min(d[i + 3], d[j + 3]) / 255;
+    if (k <= 0) return;
+    weight += k;
+    acc += (k * (Math.abs(d[i] - d[j]) + Math.abs(d[i + 1] - d[j + 1]) + Math.abs(d[i + 2] - d[j + 2]))) / 765;
+  };
+  for (let y = 0; y < part.height; y++) {
+    for (let x = 0; x < w; x++) {
+      const i = (y * w + x) * 4;
+      if (d[i + 3] === 0) continue;
+      if (x + 1 < w) pair(i, i + 4);
+      if (y + 1 < part.height) pair(i, i + w * 4);
+    }
+  }
+  return weight === 0 ? 0 : acc / weight;
+}
+
 // ---------------------------------------------------------------------------
 // the objective
 // ---------------------------------------------------------------------------
@@ -1347,6 +1526,7 @@ function placePart(
       rotationFree: false,
       rotationSelfSimilarity: 1,
       coarse: null,
+      legibility: null,
       notes: [`${name} could not be decoded, so it was not placed.`],
     };
   }
@@ -1363,6 +1543,7 @@ function placePart(
     rotationFree: false,
     rotationSelfSimilarity: 1,
     coarse: null,
+    legibility: null,
     notes: [],
   };
 
@@ -1579,6 +1760,26 @@ function placePart(
   }
 
   const best = distinct[0].placement;
+  const second = distinct.length > 1 ? distinct[1].placement.residual : null;
+  base.legibility = {
+    width: tw,
+    height: th,
+    span: roundTo(span * best.scale, 1),
+    opaqueShare: roundTo(box.weight / (tw * th), 4),
+    texture: roundTo(partTexture(part), 4),
+    detail: roundTo(partTexture(part) * span, 3),
+    candidates: distinct.length,
+    best: best.residual,
+    next: second,
+    spread: second === null ? null : roundTo(second - best.residual, 5),
+    floor: 'above',
+    reading: null,
+  };
+  // The part's OWN size, not `span`: `span` is scaled by the best placement,
+  // and on the parts this reading exists for that placement is the one in
+  // doubt — a gun cut at 32 px read as 16 px under the half-scale optimum it
+  // wrongly settled on. The floor was measured at scale 1, where the two agree.
+  base.legibility.floor = floorSide(Math.max(tw, th), base.legibility.detail);
   const margin = Math.max(AMBIGUITY_ABSOLUTE, best.residual * AMBIGUITY_RELATIVE);
   const close = distinct.slice(1).filter((d) => d.placement.residual - best.residual <= margin);
   base.placement = best;
@@ -1653,6 +1854,17 @@ function placePart(
         `${base.walls.map((wall) => wallClause(wall.axis, wall.edge, wall.window)).join('; ')}.`,
     );
   }
+  // ⭐ Which of the two readings a refusal or an ambiguity is (issue #857),
+  // in the refusal's own detail and in a note, from the figures `legibility`
+  // already carries. After the walls on purpose: a wall is the first thing to
+  // move, and this sentence is about what moving it cannot change.
+  if (base.refusal !== null || base.ambiguous) {
+    const verdict = base.refusal !== null ? 'refused' : 'ambiguous';
+    const reading = legibilityReading(base.legibility, verdict);
+    base.legibility.reading = reading;
+    if (base.refusal !== null) base.refusal.detail += `; ${reading}`;
+    base.notes.push(`${name}: ${reading}.`);
+  }
   if (best.unexplained > 0.25 && best.residual <= maxResidual) {
     base.notes.push(
       `${roundTo(best.unexplained * 100, 1)}% of ${name}'s material disagrees with the frame at this placement. ` +
@@ -1728,6 +1940,7 @@ export function poseLines(report: PoseReport): string[] {
       lines.push(`         ${' '.repeat(width)}  alt ${i + 2}: ${placementLine(alt)}`);
     });
     if (part.refusal !== null) lines.push(`         ${' '.repeat(width)}  ${part.refusal.reason}: ${part.refusal.detail}`);
+    else if (part.legibility?.reading) lines.push(`         ${' '.repeat(width)}  ambiguous: ${part.legibility.reading}`);
   }
   lines.push('');
   lines.push('  ..    residuals are a trust signal, not a score — nothing here has a pass bar.');