spine-rigc 1.2.3 → 1.4.0

package/src/pose.ts

@@ -116,15 +116,63 @@ export const COARSE_LONG_SIDE = 40;
  */
 export const COARSE_PART_SPAN = 10;
 
+/**
+ * Pixels the part's SHORT side must still span at the coarse level — the same
+ * argument as `COARSE_PART_SPAN`, applied to the axis that rule does not read.
+ *
+ * ⚠️ Found by the change that tightened the coarse grid (issue #865), not by the
+ * floor grid, whose parts are none of them thin enough to reach it. MOTION.md
+ * §6's 60x14 signal arm is 3.5 px thick at the 4x level its length chose; on the
+ * quarter-span grid an anchor cell happened to sit where refinement found its
+ * truth (residual 0.0305), and on the eighth-span grid none did, so pose B
+ * reported a placement 15 px down the arm at 0.1482. A part three pixels thick
+ * at the coarse level has no across-the-part signal for any grid to read. 4, 5
+ * and 6 were each measured to move that arm up one level and place it; 4 is the
+ * least, and at 4 no trial of the floor grid moves at all.
+ */
+const COARSE_PART_THICKNESS = 4;
+
 /**
  * Coarse anchor positions are stepped at a fraction of the part's own size.
  *
- * The objective varies over distances of order the part, not of order a pixel, so
- * scanning every pixel of the coarse level buys resolution the refinement stages
- * supply anyway — and it is what makes the scan's cost grow with the frame's area
- * instead of with the number of places the part could plausibly be.
+ * Scanning every pixel of the coarse level would make the scan's cost grow with
+ * the frame's area instead of with the number of places the part could plausibly
+ * be, so the anchors are strided. How far apart is the part's own business.
+ *
+ * ⚠️ An eighth, not the quarter it was, and the reason is measured rather than
+ * assumed (issue #865). "The objective varies over distances of order the part"
+ * is true of a solid part and false of a thin or holey one: a gun whose material
+ * is a third of its box, or a fist with gaps between the fingers, loses most of
+ * its fit a quarter-span off its truth. On `tools/pose_floor.ts`'s grid, 65
+ * failed trials had a truth that scored better than the answer reported and was
+ * missing from the final list; in 38 of them the truth, evaluated exactly at the
+ * coarse level, beat every cell of its scale rung, and the anchor CELL holding it
+ * did not — the basin fell between two anchors. A cutoff on how many minima
+ * survive (3 of the 65) was not what lost them. At an eighth the grid found
+ * 226 of 420 trials against 185 (with `MINIMA_PER_SCALE` still at three), and
+ * the search misses fell from 65 to 15, for 10–14% more CPU over the grid.
+ *
+ * 🔸 Not free of losses, and they are stated rather than averaged away: 9 trials
+ * that placed on the quarter grid do not on this one. Five of them are blurred
+ * parts that now come back ambiguous between two scales at the same spot, or
+ * 2.0 px off against a 2 px bar; three are a basin reached and then polished
+ * onto a worse placement beside it, and one a basin ranked out of the
+ * refinement's twelve — the refinement, not this grid.
  */
-export const COARSE_STRIDE_FRACTION = 0.25;
+export const COARSE_STRIDE_FRACTION = 0.125;
+
+/**
+ * Grid cells around a coarse cell that must not beat it for it to be a minimum,
+ * and the spacing kept between the minima one scale rung sends down.
+ *
+ * Four at an eighth-span stride is, nominally, the half-span the old two cells
+ * at a quarter held (the stride is rounded to whole level pixels, so only
+ * nominally). Measured on the grid: leaving it at two when the stride halved let one
+ * wrong hill fill a rung's `MINIMA_PER_SCALE` with its own neighbours — 223
+ * trials found rather than 226, and 12 that placed on the old grid lost rather
+ * than 9 (both at three minima per rung).
+ */
+const COARSE_SUPPRESSION_CELLS = 4;
 
 /** How many scale rungs one octave gets in the coarse ladder. */
 export const SCALE_STEPS_PER_OCTAVE = 3;
@@ -180,8 +228,20 @@ export const BACKGROUND_TOLERANCE = 10;
 /** Share of the frame's border ring one colour must hold before it is called the background. */
 export const BACKGROUND_BORDER_SHARE = 0.6;
 
-/** How many distinct places each coarse scale rung sends down for refinement. */
-const MINIMA_PER_SCALE = 3;
+/**
+ * How many distinct places each coarse scale rung sends down for refinement.
+ *
+ * ⚠️ Five rather than three, and read off the grid rather than off a probe
+ * (issue #865). The card's own probe raised this to ten and recovered the fist it
+ * was chasing; on the full grid that bought 2 trials net (3 gained, 1 lost),
+ * because only 3 of the 65 trials the search missed had their truth's basin
+ * ranked under the cutoff — the rest had fallen between anchor cells, which is
+ * `COARSE_STRIDE_FRACTION`'s job. With the stride fixed, one miss of that kind was
+ * left (a 48 px fist, its basin fifth on its rung), and five is the count that
+ * carries it: 227 trials found against 226 at three, none lost, and a CPU cost
+ * inside the grid's run-to-run noise.
+ */
+const MINIMA_PER_SCALE = 5;
 
 /** How many candidates survive each refinement level. */
 const REFINE_CANDIDATES = 12;
@@ -196,6 +256,92 @@ 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.082,
+  rateAbove: 0.728,
+};
+
+/** 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. Issue #865 fixed
+  // that one (the coarse grid had stepped over it), and the reading still
+  // occurs: on the grid after it, 10 ambiguous trials above the floor had a
+  // truth scoring better than both answers — native 24 px gun and shin, 48 px
+  // arm, 96 px goggles twice, and blurred gun, goggles and rear shin from 48 px
+  // up. Nine of the ten sat 2–6 px from the truth rather than on another hill. 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 +453,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 +755,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 +1591,7 @@ function placePart(
       rotationFree: false,
       rotationSelfSimilarity: 1,
       coarse: null,
+      legibility: null,
       notes: [`${name} could not be decoded, so it was not placed.`],
     };
   }
@@ -1363,6 +1608,7 @@ function placePart(
     rotationFree: false,
     rotationSelfSimilarity: 1,
     coarse: null,
+    legibility: null,
     notes: [],
   };
 
@@ -1442,9 +1688,18 @@ function placePart(
   // only about the frame. The pyramid stops when the frame fits in
   // COARSE_LONG_SIDE; this then walks back UP it until the part still spans
   // COARSE_PART_SPAN pixels there, because a level that has reduced the part to
-  // three pixels cannot say where the part is at any price.
+  // three pixels cannot say where the part is at any price — and until its short
+  // side still spans COARSE_PART_THICKNESS, which is the same sentence about a
+  // part that is long and thin.
   let coarseIndex = levels.length - 1;
-  while (coarseIndex > 0 && (span * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_SPAN) coarseIndex--;
+  const thickness = Math.min(tw, th);
+  while (
+    coarseIndex > 0 &&
+    ((span * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_SPAN ||
+      (thickness * scaleReference) / levels[coarseIndex].reduction < COARSE_PART_THICKNESS)
+  ) {
+    coarseIndex--;
+  }
   const coarse = levels[coarseIndex];
   const spanAtCoarse = (span * scaleReference) / coarse.reduction;
   const stride = Math.max(1, Math.round(spanAtCoarse * COARSE_STRIDE_FRACTION));
@@ -1454,7 +1709,7 @@ function placePart(
   for (const scale of scales) {
     const field = coarseScan(coarse, coarseSamples, scale, searchRotations, stride);
     grid = { reduction: coarse.reduction, cols: field.cols, rows: field.rows, stride };
-    candidates.push(...localMinima(field, 2, MINIMA_PER_SCALE));
+    candidates.push(...localMinima(field, COARSE_SUPPRESSION_CELLS, MINIMA_PER_SCALE));
   }
   base.coarse = grid;
   candidates.sort((a, b) => a.residual - b.residual);
@@ -1579,6 +1834,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 +1928,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 +2014,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.');