spine-rigc 0.7.0 → 0.8.1

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.