spine-rigc 0.7.0 → 0.8.0

package/README.md

@@ -531,6 +531,10 @@ They complement each other rather than overlap. `render` is offline, determinist
 and measurable — its pixels are the ones `check` reports on. `preview` is the
 interop proof: what plays there was played by Esoteric's own runtime, not by ours.
 
+🎞️ **Authoring the movement that these two show you** — key poses, in-betweening,
+and how to spread candidates so a ballot informs — is
+[docs/MOTION.md](docs/MOTION.md).
+
 ### Letting someone choose — `rigc vote`
 
 Sometimes looking is not enough on its own, because there is more than one
@@ -584,6 +588,51 @@ by the next agent rather than by a reader:
 Same player, same posture as `preview`: referenced from a CDN, never vendored,
 and the file contains only your own art ([NOTICE.md](NOTICE.md)).
 
+## Reading a pose you were given — `rigc pose`
+
+```bash
+rigc pose --images parts/ --frame poseA.png [--out pose.json]
+```
+
+Every command above takes something you authored and tells you about it. This one
+runs the other way: it takes a **picture the user already has** — one key pose —
+and reports where each loose part PNG sits in it, so an agent can write those
+coordinates into a rig and a motion **by construction** and spend its effort on the
+part no instrument can measure, the movement between two poses.
+
+```
+  PLACE  torso.png    x=   44.4  y=   65.4  rot=    0.0°  scale=1.118  residual=0.0770  unexplained= 19%
+  AMBIG  arm.png      x=   27.1  y=   56.3  rot=  -35.2°  scale=1.111  residual=0.0262  unexplained=  2%
+                      alt 2: x=   61.5  y=   56.3  rot=   35.4°  scale=1.116  residual=0.0279  unexplained=  2%
+  PLACE  ball.png     x=   44.3  y=  104.6  rot=    0.0°  scale=1.144  residual=0.0203  unexplained=  3%
+                      rotation is a FREE degree of freedom — the 0° above is a placeholder
+  REFUSE foreign.png  no-match: the best placement found has residual 0.4245, above --max-residual 0.25
+```
+
+🚨 **Nothing here is a score, and no pass bar attaches to any of it.** `check` and
+`bench` measure a build against a reference, so their numbers mean *how close*. A
+pose frame is not a reference — it is a **given condition**, and once the spec
+states those coordinates there is nothing left to be close to. The residual says
+how far to trust a placement and where two answers are equally good, which is a
+different job and needs the opposite defaults:
+
+- a part that matches nowhere is **refused by name**, with its best guess still in
+  the JSON — a refusal tells you not to trust a number rather than hiding it;
+- two near-equal optima are reported as **both**, flagged `ambiguous`, never
+  silently resolved. Two identical limbs look exactly like that;
+- a part whose rotation genuinely does not matter — a ball — reports rotation as a
+  **free degree of freedom** rather than as a failure;
+- a part the canvas cannot contain at any tested scale, and a part with no material
+  in it at all, each get their own named refusal.
+
+⚠️ **Residuals degrade under occlusion and there is no depth solver here.** A part
+drawn behind another has the occluder's pixels where its own should be, so its
+residual rises at the *correct* placement; `unexplained` is the share of the part
+that disagrees, and a middling residual beside a high `unexplained` usually means
+*right place, seen through something else*. The output carries its own `caveats`
+block saying so. Fields, coordinate contract and the rest of the limits:
+**[AUTHORING.md §11](docs/AUTHORING.md)**.
+
 ## Run viewer — watching a *run* instead of reading it
 
 🔎 **This is the ladder's instrument, not the way to look at your own rig** — that
@@ -825,6 +874,7 @@ bun cli.ts render  --candidate path/to/spine                # PNG frames + a con
 bun cli.ts preview --candidate path/to/spine                # one .html that plays it
 bun cli.ts vote    --candidate path/to/a --candidate path/to/b   # one .html that asks which
 bun cli.ts vote    --record vote-<id>.json                  # check the answer into votes.jsonl
+bun cli.ts pose    --images path/to/parts --frame poseA.png # read a pose OUT of a picture
 ```
 
 `validate` on a bare directory checks what it can see. Adding `--cut`/`--cuts` lets
@@ -837,7 +887,9 @@ archetype policy on top.
 [Looking at a rig](#looking-at-a-rig--rigc-render-and-rigc-preview). Run either
 straight after a green `build`, on the same directory `--out` wrote. `vote` is the
 same idea with more than one candidate in the page and an answer coming back —
-see [Letting someone choose](#letting-someone-choose--rigc-vote).
+see [Letting someone choose](#letting-someone-choose--rigc-vote). `pose` is the
+one command that runs *before* a spec exists rather than after — see
+[Reading a pose you were given](#reading-a-pose-you-were-given--rigc-pose).
 
 ## Checks
 
@@ -934,7 +986,7 @@ nothing substantive executed exits 2 rather than printing green.
 
 ```
 tsconfig.json   type-check config (noEmit); eslint.config.js — the no-any gate
-cli.ts          build / validate / explain / diff / check / bench / render / preview / vote
+cli.ts          build / validate / explain / diff / check / bench / render / preview / vote / pose
 selftest.ts     the validator's own negative controls, and diff's and check's
 fixtures/       public.ts — the three synthetic cuts the selftest breaks
 src/
@@ -951,6 +1003,9 @@ src/
                 stand between a saved vote and the ledger
   check.ts      a candidate against rendered frames — pixels and per-slot drift,
                 and it never opens the reference skeleton
+  pose.ts       the other direction: loose part PNGs against ONE pose frame, and
+                where each part sits in it. An entry instrument — it reads a given
+                condition into spec coordinates and grades nothing
   ladder.ts     which example is which rung, and which file in it is the reference
   timelines.ts  the 4.3 timeline catalogue and its walker (shared, pure JSON)
   mesh.ts       ring and ribbon mesh builders, weighted-vertex encoding

package/cli.ts

@@ -54,6 +54,15 @@ import { diffLines, diffSkeletons, sectionFigures, type DiffReport } from './src
 import { copyAtlasImages } from './src/emit.ts';
 import { parseJsonWithPosition } from './src/json-position.ts';
 import { findRung, RUNG_IDS, type RungSkeleton } from './src/ladder.ts';
+import {
+  DEFAULT_MAX_RESIDUAL,
+  DEFAULT_SCALE_MAX,
+  DEFAULT_SCALE_MIN,
+  estimatePose,
+  PoseError,
+  poseLines,
+  type PoseOptions,
+} from './src/pose.ts';
 import { buildPreview, PLAYER_LINE, type PreviewPage } from './src/preview.ts';
 import {
   atlasPageNames,
@@ -773,6 +782,71 @@ function cmdPreview(flags: Record<string, string>): void {
   console.log(`rigc: wrote ${out}  (${(html.length / 1024).toFixed(1)} KiB — open it in a browser)`);
 }
 
+// ---------------------------------------------------------------------------
+// reading a given condition — pose
+// ---------------------------------------------------------------------------
+//
+// ⭐ Every other command here takes a spec and looks at what came out. This one
+// runs the other way: it takes a PICTURE the user already has — a key pose — and
+// reads spec coordinates out of it, so an agent can state those poses in a rig and
+// a motion by construction and spend its loops on the part nobody can measure, the
+// movement between them.
+//
+// 🚫 It grades nothing, and the distinction is load-bearing rather than modest.
+// `check` and `bench` compare a build against a reference and their numbers mean
+// "how close"; a pose frame is not a reference, it is an INPUT, and once the spec
+// states it there is nothing left to be close to. So the residual here is a trust
+// signal — how much of the frame this placement actually explains — and the only
+// threshold in `src/pose.ts` is the one that decides whether to print an answer at
+// all, which the caller can move.
+//
+//   rigc pose --images parts/ --frame poseA.png [--out pose.json]
+
+const DEFAULT_POSE_OUT = 'pose.json';
+
+/** `--scale 0.5,2` / `--rotation -30,30` — a pair of numbers, low first. */
+function readRange(flags: Record<string, string>, key: string): { low: number; high: number } | undefined {
+  const raw = flags[key];
+  if (raw === undefined) return undefined;
+  const parts = raw.split(',').map((s) => Number(s.trim()));
+  if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n))) {
+    throw new UsageError(`--${key} takes two numbers: <min>,<max>`);
+  }
+  if (parts[1] < parts[0]) throw new UsageError(`--${key} ${JSON.stringify(raw)}: the minimum must not exceed the maximum`);
+  return { low: parts[0], high: parts[1] };
+}
+
+function cmdPose(flags: Record<string, string>): void {
+  if (flags.images === undefined) throw new UsageError('pose needs --images <dir> — the directory the loose part PNGs are in');
+  if (flags.frame === undefined) throw new UsageError('pose needs --frame <path> — one pose frame to read the placements out of');
+  const options: PoseOptions = { imagesDir: flags.images, framePath: flags.frame };
+  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 };
+  }
+  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;
+  }
+
+  console.log('rigc pose');
+  const report = estimatePose(options);
+  for (const line of poseLines(report)) console.log(line);
+
+  // Same `--out` shape as `preview` and `vote`: one file, and a directory means
+  // "the default name in here" rather than a report written over a directory.
+  const target = resolve(flags.out ?? DEFAULT_POSE_OUT);
+  const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_POSE_OUT) : target;
+  writeJson(out, report);
+}
+
 // ---------------------------------------------------------------------------
 // choosing between results — vote
 // ---------------------------------------------------------------------------
@@ -1390,6 +1464,12 @@ const FLAG_MEANINGS: Record<string, string> = {
   as: 'the candidate animation to play, when it is named differently from the frame set',
   'all-frames': 'print every frame, not just the worst by MAE',
   json: 'also write the whole report to this path',
+  frame: 'one pose frame — a picture of the pose to read the part placements out of',
+  scale: `the scale window to search, as frame pixels per part pixel (default \`${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}\`)`,
+  rotation: 'the rotation window to search, in screen degrees (default `-180,180`, a full turn)',
+  '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',
   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',
@@ -1417,6 +1497,10 @@ const FLAG_VALUES: Record<string, string> = {
   framing: 'per-shot|shared',
   as: '<name>',
   json: '<out>',
+  frame: '<path>',
+  scale: '<min,max>',
+  rotation: '<min,max>',
+  'max-residual': '<0..1>',
   animation: '<name>',
   max: '<px>',
   record: '<result.json>',
@@ -1505,6 +1589,20 @@ const COMMANDS: CommandDoc[] = [
       },
     },
   },
+  {
+    name: 'pose',
+    usage: [
+      `rigc pose --images <dir> --frame <path> [--scale ${DEFAULT_SCALE_MIN},${DEFAULT_SCALE_MAX}] [--rotation -180,180] [--out ${DEFAULT_POSE_OUT}]`,
+    ],
+    flags: ['images', 'frame', 'scale', 'rotation', 'max-residual', 'out'],
+    overrides: {
+      images: { value: '<dir>', meaning: 'the loose part PNGs to place; every `.png` in it is a part, in name order' },
+      out: {
+        value: '<file>',
+        meaning: `the .json report to write (default \`${DEFAULT_POSE_OUT}\`); a directory means "the default name in here"`,
+      },
+    },
+  },
   {
     name: 'vote',
     usage: [
@@ -1582,6 +1680,16 @@ const USAGE = [
   'draws with rigc\'s own rasteriser; preview embeds the artifact in a page that plays',
   'it in the official Spine Web Player, which is also the interop proof.',
   '',
+  'pose runs the other way round from everything above: it reads a picture you already',
+  'have — one key pose — and reports where each loose part PNG sits in it (x, y, rotation,',
+  'scale) so an agent can state those poses in a spec by construction:',
+  '  rigc pose --images parts/ --frame poseA.png       pose.json, one entry per part',
+  'It grades nothing and no pass bar attaches to its numbers. The residual is a trust',
+  'signal, and where two placements are equally good it reports BOTH rather than picking —',
+  'two identical limbs look exactly like that. A part that matches nowhere, a part the',
+  'canvas cannot contain and a part whose rotation is a free degree of freedom are each',
+  'named as such. See `rigc pose --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',
@@ -1626,6 +1734,7 @@ try {
   else if (command === 'bench') cmdBench(flags, positional);
   else if (command === 'render') cmdRender(flags);
   else if (command === 'preview') cmdPreview(flags);
+  else if (command === 'pose') cmdPose(flags);
   else if (command === 'vote') cmdVote(flags, lists.candidate ?? []);
 } catch (err) {
   if (err instanceof UsageError) {
@@ -1646,5 +1755,12 @@ try {
     console.error(`rigc check error: ${err.message}`);
     process.exit(1);
   }
+  // Like a usage error in kind — a missing directory, an unreadable frame — but
+  // its messages name a path and a reason, and reprinting the whole usage under
+  // them buries that.
+  if (err instanceof PoseError) {
+    console.error(`rigc pose: ${err.message}`);
+    process.exit(2);
+  }
   throw err;
 }

package/docs/AUTHORING.md

@@ -70,6 +70,12 @@ can see where Spine stops.
 ```bash
 bun install                                   # once
 
+# …but if what you were HANDED is a picture of the pose rather than numbers, read
+# the numbers out of it first. This one runs BEFORE the loop, not inside it:
+bun cli.ts pose --images path/to/parts --frame path/to/poseA.png --out poseA.json
+#   ↳ one entry per part PNG: where it sits, how confident that is, and where two
+#     answers are equally good — §11
+
 bun cli.ts build \
   --rig    path/to/my.rig.json \
   --motion path/to/my.motion.json \
@@ -127,7 +133,7 @@ What the flags mean:
 | `--motion` | the motion spec — time |
 | `--out` | directory for `skeleton.json` + `skeleton.atlas`; atlas page paths are written relative to it |
 | `--copy-images` | `build` only: also copies every referenced page PNG into `--out` and rewrites the atlas to the copies, so the directory is self-contained enough to zip or commit on its own. Default is unchanged — page paths still point at the source art (issue #217) |
-| `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory) |
+| `--images` | where the rig spec's `image` names resolve (overrides the rig's own `images` field, and is relative to your working directory). For `pose` it is the directory of **loose part PNGs to place** — every `.png` in it is a part, in name order |
 | `--manifest` | a cut manifest. Only for a rig with **measured art** behind it; a foreign skeleton has none |
 | `--profile` | `spine` = the 22 validity rules (**the default**) · `spine-html` = all 36, opt-in |
 | `--candidate` | `check`, `bench`, `render`, `preview` and `vote` only: a **compiled** artifact — the directory `build --out` wrote, or a `skeleton.json` path. `--atlas <path>` names the atlas when it does not sit beside the skeleton. **`vote` is the one command that takes it more than once** — repeat it 2–4 times, one per pane, labelled A, B, C, D in the order given; everywhere else a repeat is a typo and is refused |
@@ -136,6 +142,10 @@ What the flags mean:
 | `--ballot` | `vote --record` only: the ballot the vote answers (default `ballot.html`). Its embedded manifest is what the vote is checked against, so the ballot file is the record of the question |
 | `--ledger` | `vote --record` only: the append-only JSONL the vote lands in (default `votes.jsonl`), one vote per line |
 | `--again` | `vote --record` only: record a second vote on a ballot the ledger already has. Without it a repeat is refused by name rather than doubled |
+| `--frame` | `pose` only: one pose frame — the picture to read part placements out of. One frame per call; several key poses are several calls, and correlating them is yours (§11) |
+| `--scale` | `pose` only: the scale window to search, as **frame pixels per part pixel**, `<min>,<max>` (default `0.5,2`). The report states what it searched, and a window that does not contain the truth does not reliably refuse — §11 |
+| `--rotation` | `pose` only: the rotation window to search, in screen degrees, `<min>,<max>` (default `-180,180`, a full turn). Narrow it when you know the art is upright |
+| `--max-residual` | `pose` only: above this residual a placement is **refused by name** instead of reported flat (default `0.25`). A reporting threshold, not a pass bar — the placement is still in the JSON |
 
 `render` also takes `--fps <n>` (the rate it samples at, default 12 — the same
 protocol rate the reference frames use) and `--max <px>` (the long side of a
@@ -164,6 +174,7 @@ bun cli.ts render   --candidate path/to/spine [--animation …] [--fps 12] [--ma
 bun cli.ts preview  --candidate path/to/spine [--animation …] [--out preview.html]
 bun cli.ts vote     --candidate path/to/a --candidate path/to/b [--out ballot.html]
 bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger votes.jsonl]
+bun cli.ts pose     --images path/to/parts --frame poseA.png [--out pose.json]
 ```
 
 - **`explain`** is the one to reach for when a rig compiles but looks wrong. It
@@ -197,6 +208,14 @@ bun cli.ts vote     --record vote-<id>.json [--ballot ballot.html] [--ledger vot
   double-clicking it is also the interop proof — what plays there was played by
   Esoteric Software's runtime, not by rigc's. The player is loaded from a CDN
   rather than copied into the file, so the first open needs a network.
+- 📐 **`pose` is the only command here that reads an INPUT rather than a result.**
+  Everything else takes a spec or a build and tells you something about it; `pose`
+  takes a picture the user already has — a key pose — and reports where each loose
+  part PNG sits in it, so you can write those coordinates into a rig and a motion
+  **by construction**. Nothing about it grades anything: at that point the pose is
+  a given condition, not a target, and the residual it reports is how far to trust
+  a placement rather than how good the placement is. Reach for it the moment a
+  request arrives as *"make it go from this picture to this one"*. **§11.**
 - 🗳️ **`vote` is `preview` with more than one candidate in it and an answer
   coming back**, and it is the one step of this loop you cannot run yourself.
   Reach for it where the instruments have run out: two builds that `check` and
@@ -3053,3 +3072,119 @@ answer read off the exports:
 
 If one of those turns out to matter, it belongs in the run's `log.md` as something
 the frames had to teach you — not here.
+
+---
+
+## 11. Reading a pose you were given — `rigc pose`
+
+```bash
+bun cli.ts pose --images path/to/parts --frame path/to/poseA.png [--out pose.json]
+```
+
+Every other command in this guide takes something you wrote and tells you about
+it. This one runs the other way: it takes a **picture the user already has** and
+reports, for each loose part PNG, where that part sits in it — `x`, `y`,
+`rotationDeg`, `scale` — plus a residual saying how well the placed part explains
+the frame's pixels underneath it.
+
+Reach for it when a request arrives as *"make it go from this picture to this
+one"*. Read both frames, write the two key poses into the rig and the motion from
+the numbers it gives you, and spend your loops on the part no instrument can
+measure: the movement between them.
+
+📘 **The recipe that consumes this report is [MOTION.md](MOTION.md)** — how these
+placements become a rig and a motion, what goes between two key poses when nothing
+was given for the in-betweens, and how to spread candidates so a `vote` ballot
+informs.
+
+### 11.1 It measures an input, so nothing here is a score
+
+🚨 **No number in this report has a pass bar, and none of them is a grade.** The
+distinction is not modesty, it decides how to read the output. `check` and `bench`
+compare a build against a reference, so their numbers mean *how close*. A pose
+frame is not a reference — it is a **given condition**, and once the spec states
+those coordinates there is nothing left to be close to. The residual exists so you
+know **how far to trust each placement** and **where two answers are equally
+good**.
+
+That is why the command's output is shaped as help rather than as a verdict:
+
+- a placement that matches nowhere is **refused by name** and its best guess is
+  still printed, because a refusal tells you not to trust a number rather than
+  hiding it;
+- two near-equal optima are reported as **both**, flagged `ambiguous`, never
+  silently resolved;
+- a part whose rotation genuinely does not matter is reported as having a **free
+  degree of freedom**, not as a failure.
+
+### 11.2 The coordinate contract
+
+Placements are in the **frame's own pixels: y down, origin top-left** — the same
+convention a cut manifest uses, and the `space` field of every report repeats it.
+
+- `x`, `y` — where the part image's own centre, `(width / 2, height / 2)`, lands.
+- `rotationDeg` — **screen** degrees, positive turning **clockwise** on screen.
+- `scale` — uniform, as **frame pixels per part pixel**.
+
+Reconstruct a part pixel `p` as `centre + scale · R(rotationDeg) · (p − (width/2,
+height/2))`. To get to Spine's y-up, counter-clockwise world, use the two
+conversions that already exist and open-code neither:
+`screenToSpineDegrees(rotationDeg)` and `cropToSpineY(y, frameHeight)`
+([`src/transform.ts`](../src/transform.ts)).
+
+### 11.3 The fields, and what each one is for
+
+Per part:
+
+| Field | Meaning |
+| --- | --- |
+| `part`, `path`, `width`, `height` | the PNG, by the name every message uses |
+| `placement` | the best placement found — `null` **only** for `empty-part` and `larger-than-canvas`, where nothing was searched |
+| `alternates` | other optima worth reporting, best first. Non-empty means the answer was not unique |
+| `ambiguous` | at least one alternate is inside the ambiguity margin. **Choose with something this instrument cannot see** — anatomy, the other frame, or `rigc vote` |
+| `rotationFree` | the part is self-similar under rotation, so `rotationDeg` is a placeholder and the value is yours |
+| `rotationSelfSimilarity` | the number `rotationFree` is a threshold on. A part just over the line is worth a look |
+| `refusal` | `{ reason, detail }` or `null`. Reasons: `no-match`, `larger-than-canvas`, `empty-part` |
+| `coarse` | the grid this part was actually searched on. A handful of cells means the part is small relative to the frame and the first pass had little to go on |
+| `notes` | the same facts in prose, in the order they were found |
+
+Per placement:
+
+| Field | Meaning |
+| --- | --- |
+| `residual` | alpha-weighted mean absolute colour error over the part's own footprint, `0..1`. **Lower is better explained** — that is all it means |
+| `unexplained` | the share of the part's material that disagrees with the frame at this placement. **Read this next to the residual** — see §11.4 |
+| `offCanvas` | the share of the part's material that falls outside the frame at this placement |
+| `footprint` | frame pixels of material the placement accounts for; the tie-break between two equal residuals |
+| `bbox` | the axis-aligned box the placed part occupies, in frame pixels |
+
+The report also carries `frame.background` (how the picture's empty space was
+identified — a flat colour, transparency, or `unknown`), `search` (every window
+and threshold that was applied), and `caveats`.
+
+### 11.4 What it cannot see — read this before using the numbers
+
+- ⚠️ **Residuals degrade under occlusion, and there is no depth solver here.** A
+  part drawn *behind* another has the occluder's pixels where its own should be, so
+  its residual rises **at the correct placement**. `unexplained` separates the two
+  readings: a middling residual with a high `unexplained` usually means *right
+  place, seen through something else*, not *wrong place*. The only robustness in
+  the objective is that it is measured on the part's **own alpha footprint** — a
+  part is never charged for pixels of the picture it does not claim. Weigh
+  accordingly; do not treat either number as a verdict.
+- ⚠️ **A search window that does not contain the truth does not reliably refuse.**
+  A part shrunk inside the region it came from still explains those pixels, so the
+  answer is the best placement available *inside* `--scale` / `--rotation` and its
+  residual can look reasonable. This is why the window is a reported field: if the
+  numbers surprise you, check `search` before you trust them.
+- ⚠️ **A frame whose border has no dominant colour reports `background.unknown`.**
+  Every pixel then counts as material, the silhouette signal is gone, and the
+  residual is colour agreement alone. The report says so rather than being quietly
+  weaker.
+- **An `ambiguous` part is genuinely ambiguous.** Two identical limbs, a part that
+  fits its own silhouette at more than one angle, and a shape whose interior is one
+  flat colour all look like this. The instrument has run out; that is what
+  `rigc vote` is for.
+- **One frame per call.** Several key poses are several calls, and correlating A
+  with B — which placement of a repeated part belongs to which limb, across two
+  frames — is the authoring job, not this tool's.