spine-rigc 0.10.0 → 0.12.0

package/README.md

@@ -36,6 +36,7 @@ parser and a list of named assertions all come back green.
 | a compiled rig | `rigc preview` | one self-contained `.html` that plays it in Spine's own web player |
 | two to four compiled rigs | `rigc vote` | one ballot page a human picks from, and the answer checked into a ledger |
 | a picture of a key pose | `rigc pose` | where each loose part PNG sits in it, in spec coordinates — the movement between two poses is then yours to key ([docs/MOTION.md](docs/MOTION.md)) |
+| the same picture, and a rig | `rigc chainfit` | the parts `pose` refuses because something is drawn over them — read through the candidate's own draw order and hierarchy, with the share of each part the answer was measured on |
 
 Everything in that table needs Bun and this package: no clone, no reference art, no
 art pipeline, no server.
@@ -353,6 +354,16 @@ self-contained `.html` that plays it in Spine's own web player; **`vote`** puts
 four candidates in one page and takes a human's answer back. Reach for them the moment
 a rig compiles green, because green says nothing at all about the picture.
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/firejune/rigc/main/assets/rigc-keypose.gif" alt="Two key poses read back by rigc pose, two candidate in-between motions compiled from them, and a rigc vote ballot picking one" width="600" />
+</p>
+
+<p align="center"><em>The whole loop on one character: two key poses are the given
+conditions, <code>rigc pose</code> reads where every part sits in each picture, two
+candidate in-betweenings are compiled from the same pair — and a real
+<code>rigc vote</code> ballot picks the winner, because the movement between the poses
+is the one thing no instrument here will grade.</em></p>
+
 Three properties of `vote` are worth stating, because they are what make its ledger
 usable by the next agent rather than by a reader: **a tie is a recorded outcome, not a
 missing one** — `both-unacceptable` is the tie that means *propose again*, and it is
@@ -371,7 +382,25 @@ it, so those coordinates go into the rig and the motion **by construction** and
 effort goes into the part no instrument can measure: the movement between two poses.
 A part that matches nowhere is refused by name, two near-equal placements are reported
 as both, and nothing it prints is a score. Fields, the coordinate contract and the
-limits: [AUTHORING.md §11](docs/AUTHORING.md).
+limits: [AUTHORING.md §11](docs/AUTHORING.md). The parts it refuses because
+something is drawn over them are `rigc chainfit`'s, once a candidate exists —
+[§12](docs/AUTHORING.md).
+
+## The gallery — four complete rigs over art that ships with them
+
+Each directory in [`gallery/`](https://github.com/firejune/rigc/tree/main/gallery) is
+one rig spec, one motion spec and the PNGs they name, small enough to read in one
+sitting. Each stars a single feature, so *how do I do X* has a working answer rather
+than a field table, and each README carries the frame rate it was authored at, what
+was verified, and what writing it cost. Repository material: a clone and
+`bun install` runs them.
+
+| Example | Stars | What it is |
+| --- | --- | --- |
+| [`gallery/walk`](https://github.com/firejune/rigc/tree/main/gallery/walk) | `ik` constraints + **`ik` timelines** | Two two-bone leg chains solved to foot targets — the planted leg nailed down, the swinging one let go at the top of its lift |
+| [`gallery/squash`](https://github.com/firejune/rigc/tree/main/gallery/squash) | **`deform` timelines** | A ball squashed about its contact point and stretched along its travel, from two affine transforms written out in the README |
+| [`gallery/flex`](https://github.com/firejune/rigc/tree/main/gallery/flex) | **`contour` meshes** | A swallow-tailed banner and a serrated leaf: four meshes traced off their own alpha, waved by bone timelines and rippled by a `deform` |
+| [`gallery/ride`](https://github.com/firejune/rigc/tree/main/gallery/ride) | `path` attachments + **path constraints** | A trolley coasting down a drawn rail and rolling back, driven by a `position` timeline, with `groups` + `stagger` keying the wheels and the ears |
 
 ## Commands
 
@@ -390,6 +419,7 @@ commands take it and what its default is.
 | `preview --candidate <dir>` | one self-contained `.html` that plays it |
 | `vote --candidate a --candidate b` | one `.html` that asks a human which; `vote --record <file>` checks the answer into `votes.jsonl` |
 | `pose --images <dir> --frame <png>` | reads part placements **out of** a picture |
+| `chainfit --candidate <dir> --images <dir> --frame <png>` | reads the parts `pose` refuses, through the candidate's own draw order and hierarchy: masked residuals over **visible** pixels, one hinge per child instead of four degrees of freedom, and the `rotate` key value each answer implies |
 | `diff <candidate.json> <reference.json>` | structural comparison of two skeletons, one ratio per measure and deliberately no combined score |
 | `check --candidate <dir> --frames <dir>` | the candidate against reference pictures — the only instrument here that can see a *wrong animation* |
 | `bench <rung> --candidate <dir>` | one rung of the benchmark ladder |

package/cli.ts

@@ -72,6 +72,18 @@ import {
   poseLines,
   type PoseOptions,
 } from './src/pose.ts';
+import {
+  ANCHOR_MAX_RESIDUAL,
+  ANCHOR_MAX_UNEXPLAINED,
+  chainFitLines,
+  ChainFitError,
+  DEFAULT_HINGE_MAX,
+  DEFAULT_HINGE_MIN,
+  DEFAULT_MIN_VISIBLE,
+  DEFAULT_PASSES,
+  estimateChainFit,
+  type ChainFitOptions,
+} from './src/chainfit.ts';
 import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
 import {
   atlasPageNames,
@@ -382,10 +394,41 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
-/** What a contour mesh measured about its own fit, or nothing for the others. */
+/**
+ * What a mesh measured about its own fit against the art it names, or nothing
+ * for a mesh with no art to measure against.
+ *
+ * Printed for authored geometry as well as for a `contour` (issue #277): the
+ * figure is a measurement between the emitted triangles and the PNG, so it means
+ * the same thing whoever drew the vertices, and the silence was the defect —
+ * an octagon rim placed on a round part's silhouette clips its own ink outline
+ * at 94.31% and used to print nothing at all.
+ *
+ * The hole is appended only when there is one, so the common line is unchanged.
+ * It is the one figure in the report that a hole moves: `coverage` and
+ * `overshoot` are both measured against the FILLED silhouette, so spanning an
+ * interior hole is neither missing coverage nor reaching past anything, and an
+ * unintentional hole — a gap in the art, a stroke that failed to join — bought
+ * fill over transparent pixels with nothing anywhere saying so (issue #275).
+ */
 function meshFit(m: CompileResult['meshes'][number]): string {
   if (m.coverage === undefined) return '';
-  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it`;
+  const hole = m.holePixels ? `, enclosing ${m.holePixels}px of hole` : '';
+  return `  covers ${(m.coverage * 100).toFixed(2)}% of the art, reaching ${m.overshoot?.toFixed(2) ?? '?'}px past it${hole}`;
+}
+
+/**
+ * The triangle budget a `MESH` line is read against: the rig's, or nothing.
+ *
+ * 📐 It used to be the literal `80`, which was nobody's budget — the rig quoted
+ * in issue #275 declared 64, `A13_MESH_BUDGET` measured against that 64
+ * correctly, and the line an author actually reads printed 80. Under the default
+ * `--profile spine` `A13` is `PROF`, so the printed number is the only budget
+ * figure in the output and it has to be the declared one. A rig that declares
+ * none says so in the same words `A13` SKIPs in, rather than being given a wall.
+ */
+function meshBudget(rig: CompileResult['rig']): string {
+  return rig.meshTriangleBudget === null ? '(no budget declared)' : `(budget ${rig.meshTriangleBudget})`;
 }
 
 /**
@@ -471,7 +514,7 @@ function cmdBuild(flags: Record<string, string>): void {
   for (const m of result.meshes) {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
-        `(budget 80)  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
+        `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}`,
     );
   }
   for (const ph of result.physics) {
@@ -1029,6 +1072,100 @@ function cmdPose(flags: Record<string, string>): void {
   writeJson(out, report);
 }
 
+// ---------------------------------------------------------------------------
+// reading the half a picture hides — chainfit
+// ---------------------------------------------------------------------------
+//
+// ⭐ `pose` above reads a picture with nothing but the loose parts, and refuses
+// the parts another part is drawn over — a residual measured through an occluder
+// rises AT the correct placement, so the honest answer is a refusal. This reads
+// those, and the whole difference is that it is also given the CANDIDATE: with a
+// draw order the covered pixels can be excluded from a part's objective instead
+// of charged to it, and with a hierarchy a child of a placed bone has one degree
+// of freedom — the hinge about its own pivot — where `pose` has four.
+//
+// 🚫 Same phase and the same framing as `pose`: it reads a given condition into
+// spec coordinates and grades nothing. Every residual is a trust signal, every
+// threshold is reported, and `visibleShare` is how much of the part the number
+// was even computed on.
+//
+//   rigc chainfit --candidate <dir> --images <dir> --frame poseA.png [--anchor pose.json]
+
+const DEFAULT_CHAINFIT_OUT = 'chainfit.json';
+
+function cmdChainFit(flags: Record<string, string>): void {
+  if (flags.candidate === undefined) {
+    throw new UsageError('chainfit needs --candidate <dir | skeleton.json> — the compiled rig to read the frame through');
+  }
+  if (flags.images === undefined) {
+    throw new UsageError("chainfit needs --images <dir> — where the candidate's attachment image names resolve to PNGs");
+  }
+  if (flags.frame === undefined) throw new UsageError('chainfit needs --frame <path> — one pose frame to read the placements out of');
+  // Refused rather than ignored. Every other --candidate command takes --atlas, so
+  // passing it here is a reasonable thing to try — and a flag that silently does
+  // nothing is worse than one that says why it cannot.
+  if (flags.atlas !== undefined) {
+    throw new UsageError(
+      'chainfit reads no atlas: the part art comes from --images, one PNG per attachment image name, and the ' +
+        'skeleton is all it needs of the candidate. Drop --atlas',
+    );
+  }
+  const options: ChainFitOptions = {
+    candidatePath: flags.candidate,
+    imagesDir: flags.images,
+    framePath: flags.frame,
+  };
+  if (flags.anchor !== undefined) options.anchorPath = flags.anchor;
+  const hinge = readRange(flags, 'hinge');
+  if (hinge) {
+    if (hinge.high - hinge.low > 360) throw new UsageError('--hinge cannot span more than a full turn');
+    options.hinge = { minDeg: hinge.low, maxDeg: hinge.high };
+  }
+  if (flags.stretch !== undefined) {
+    const value = Number(flags.stretch);
+    if (!Number.isFinite(value) || value < 1) throw new UsageError('--stretch must be a ratio of 1 or more, e.g. 1.25');
+    options.stretch = value;
+  }
+  if (flags['min-visible'] !== undefined) {
+    const value = Number(flags['min-visible']);
+    if (!Number.isFinite(value) || value < 0 || value > 1) throw new UsageError('--min-visible must be a number in [0, 1]');
+    options.minVisible = value;
+  }
+  if (flags['max-residual'] !== undefined) {
+    const value = Number(flags['max-residual']);
+    if (!Number.isFinite(value) || value <= 0 || value > 1) throw new UsageError('--max-residual must be a number in (0, 1]');
+    options.maxResidual = value;
+  }
+  if (flags.passes !== undefined) {
+    const value = Number(flags.passes);
+    if (!Number.isInteger(value) || value < 1 || value > 8) throw new UsageError('--passes must be a whole number in 1..8');
+    options.passes = value;
+  }
+  if (flags['anchor-residual'] !== undefined) {
+    const value = Number(flags['anchor-residual']);
+    if (!Number.isFinite(value) || value <= 0 || value > 1) throw new UsageError('--anchor-residual must be a number in (0, 1]');
+    options.anchorMaxResidual = value;
+  }
+  const scale = readRange(flags, 'scale');
+  if (scale) {
+    if (scale.low <= 0) throw new UsageError('--scale minimum must be greater than zero');
+    options.scale = { min: scale.low, max: scale.high };
+  }
+  const rotation = readRange(flags, 'rotation');
+  if (rotation) {
+    if (rotation.high - rotation.low > 360) throw new UsageError('--rotation cannot span more than a full turn');
+    options.rotation = { minDeg: rotation.low, maxDeg: rotation.high };
+  }
+
+  console.log('rigc chainfit');
+  const report = estimateChainFit(options);
+  for (const line of chainFitLines(report)) console.log(line);
+
+  const target = resolve(flags.out ?? DEFAULT_CHAINFIT_OUT);
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_CHAINFIT_OUT) : target;
+  writeJson(out, report);
+}
+
 // ---------------------------------------------------------------------------
 // choosing between results — vote
 // ---------------------------------------------------------------------------
@@ -1763,7 +1900,8 @@ function cmdExplain(flags: Record<string, string>): void {
     for (const kind of new Set(result.meshes.map((m) => m.kind))) console.log(`  ${MESH_KIND_NOTES[kind]}`);
     for (const m of result.meshes) {
       console.log(
-        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
+        `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
+          `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}`,
       );
     }
   }
@@ -1838,6 +1976,27 @@ const FLAG_MEANINGS: Record<string, string> = {
   'max-residual':
     `above this residual a placement is refused by name instead of reported flat (default ${DEFAULT_MAX_RESIDUAL}); ` +
     'it is a reporting threshold, not a pass bar',
+  anchor:
+    'a `rigc pose` report for THIS frame, whose confident placements become the anchors the chains hang off ' +
+    '(default: run that pass internally over exactly the parts the candidate draws)',
+  hinge:
+    `the window each child bone's local rotation is searched over, in Spine degrees about its setup value ` +
+    `(default \`${DEFAULT_HINGE_MIN},${DEFAULT_HINGE_MAX}\`, a full turn — one degree of freedom is cheap enough not ` +
+    'to risk a window that does not contain the truth)',
+  stretch:
+    'also search a uniform scale on every bone, over this ratio either way (e.g. 1.25). Without it the stretch ' +
+    "degree of freedom is searched only where the candidate's own animations key a `scale` timeline, because a rig " +
+    'that never scales a bone is a rig saying that bone does not stretch',
+  'min-visible':
+    `below this share of a part surviving the parts drawn over it, the placement is refused by name instead of ` +
+    `reported flat (default ${DEFAULT_MIN_VISIBLE}); the best one found is still printed, and it is a reporting ` +
+    'threshold, not a pass bar',
+  passes:
+    `how many times the occluder masks are rebuilt from the answers and the fit rerun (default ${DEFAULT_PASSES}); ` +
+    "pass 1 freezes each part's visible set where the RIG predicts it, later passes where the last one landed",
+  'anchor-residual':
+    `the residual a \`pose\` placement must be within to anchor a chain (default ${ANCHOR_MAX_RESIDUAL}, with ` +
+    `unexplained ≤ ${ANCHOR_MAX_UNEXPLAINED} and unambiguous — the 2026-09-03 measurement run's own clean-frame criterion)`,
   animation: 'which animation to show; the default is every one for `render` and the first for `preview`',
   max: 'longest side of a rendered frame, in pixels (default 256)',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
@@ -1876,6 +2035,12 @@ const FLAG_VALUES: Record<string, string> = {
   scale: '<min,max>',
   rotation: '<min,max>',
   'max-residual': '<0..1>',
+  anchor: '<pose.json>',
+  hinge: '<min,max>',
+  stretch: '<ratio>',
+  'min-visible': '<0..1>',
+  passes: '<n>',
+  'anchor-residual': '<0..1>',
   animation: '<name>',
   max: '<px>',
   record: '<result.json>',
@@ -2012,6 +2177,50 @@ const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'chainfit',
+    usage: [
+      `rigc chainfit --candidate <dir | skeleton.json> --images <dir> --frame <path> [--anchor pose.json] [--out ${DEFAULT_CHAINFIT_OUT}]`,
+    ],
+    flags: [
+      'candidate',
+      'images',
+      'frame',
+      'anchor',
+      'hinge',
+      'stretch',
+      'min-visible',
+      'max-residual',
+      'passes',
+      'anchor-residual',
+      'scale',
+      'rotation',
+      'out',
+    ],
+    overrides: {
+      images: {
+        value: '<dir>',
+        meaning:
+          "where each attachment's image name resolves to a loose PNG. ⚠️ NOT a part list the way `pose --images` " +
+          'is one — the candidate decides what the parts are, so extra PNGs in here are simply unused and a name ' +
+          'the directory lacks is refused by name',
+      },
+      scale: {
+        meaning:
+          'the scale window the INTERNAL anchor pass searches, as frame pixels per part pixel (default ' +
+          `\`${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}\`). Refused together with --anchor, which means there is no internal pass`,
+      },
+      rotation: {
+        meaning:
+          'the rotation window the INTERNAL anchor pass searches, in screen degrees (default `-180,180`). Refused ' +
+          'together with --anchor — the chains\' own window is --hinge',
+      },
+      out: {
+        value: '<file>',
+        meaning: `the .json report to write (default \`${DEFAULT_CHAINFIT_OUT}\`); a directory means "the default name in here"`,
+      },
+    },
+  },
   {
     name: 'vote',
     usage: [
@@ -2099,6 +2308,19 @@ const USAGE = [
   'canvas cannot contain and a part whose rotation is a free degree of freedom are each',
   'named as such. See `rigc pose --help`.',
   '',
+  'chainfit reads the half of that picture pose refuses. It is the same question with',
+  'one more input — the candidate rig — and that input buys two things: draw order, so',
+  'the pixels another part covers are EXCLUDED from a part\'s residual instead of',
+  'charged to it, and hierarchy, so a child of a placed bone is searched over one hinge',
+  'instead of four degrees of freedom:',
+  '  rigc chainfit --candidate build/ --images parts/ --frame poseA.png',
+  'Every residual is over the part\'s VISIBLE pixels and comes with the `visibleShare` it',
+  'was computed on, so a mostly-hidden answer carries its own uncertainty. It grades',
+  'nothing either: a part too far behind the others is refused by the visibility floor,',
+  'a limb with no trusted part on it or above it is refused `no-anchor`, and two hinge',
+  'answers that explain the picture equally well are both reported. See',
+  '`rigc chainfit --help`.',
+  '',
   'vote is the same page with two to four builds in it and an answer coming back:',
   '  rigc vote --candidate <build A> --candidate <build B>   ballot.html, panes labelled A and B',
   '  rigc vote --record vote-<id>.json --ballot ballot.html  check it, append it to votes.jsonl',
@@ -2145,6 +2367,7 @@ try {
   else if (command === 'render') cmdRender(flags);
   else if (command === 'preview') cmdPreview(flags);
   else if (command === 'pose') cmdPose(flags);
+  else if (command === 'chainfit') cmdChainFit(flags);
   else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
 } catch (err) {
   if (err instanceof UsageError) {
@@ -2176,5 +2399,12 @@ try {
     console.error(`rigc pose: ${err.message}`);
     process.exit(2);
   }
+  // Same kind as a PoseError, and printed the same way for the same reason: the
+  // messages name a path, a bone or an attachment, and reprinting the whole
+  // usage under them buries the one line that says what to change.
+  if (err instanceof ChainFitError) {
+    console.error(`rigc chainfit: ${err.message}`);
+    process.exit(2);
+  }
   throw err;
 }