@rig-c/core 2.41.0 → 2.42.0

package/README.md

@@ -41,7 +41,7 @@ installed.
 | the same, and one texture instead of many | `rigc build --pack` | the parts arranged onto shared atlas pages, written beside the skeleton — losslessly, so the picture is the picture |
 | a pack somebody already made | `rigc build --atlas-in` | the same skeleton, with every part resolved to a region of that atlas — or a named refusal, never a part that silently does not draw |
 | a compiled rig | `rigc render` | every animation as PNG frames, plus one labelled contact sheet of the whole shot |
-| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot — and a legend that puts every mark back in world units |
+| a compiled rig and a question about its geometry | `rigc inspect` | one picture of its bones, axes, mesh edges and hulls, one bone's weights, the draw order, a world grid or a declared axis over the art — at the setup pose, one time or a sheet of several, zoomed to a bone or a slot, or beside a second build on one transform — and a legend that puts every mark back in world units |
 | 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)) |
@@ -410,10 +410,14 @@ rigc inspect --candidate spine --show art,bones,names --dim   # inspect.png + in
 bone where the art is*, *which way does it squash*, *where in rig units is this
 point*, *is this axis held*. It draws the build's art, framed as `render` frames it,
 and over it any of `bones` (origin to tip, a bone of length 0 marked as one),
-`names`, `axes` (each bone's world x and y), `grid` (in world units) and `declared`
+`names` (one label per pixel), `axes` (each bone's world x and y), `mesh` and `hull`
+(each mesh's edges and outline), `weights:<bone>` (what that bone moves, as a heat),
+`slots` (the draw order at the pose), `grid` (in world units) and `declared`
 (each `invariants.axes` line and the bones held to it), at the setup pose, at
 `--animation <name> --at <s[,s…]>` — one picture, or a sheet — or zoomed with
-`--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`. Beside the PNG it writes a legend:
+`--zoom <bone|slot>[:pad]` or `--viewport x,y,w,h`; `--bone`/`--hide-bone` pick the
+bones by glob, and `--compare <dir>` draws a second build beside the first on one
+transform, to see what a change moved. Beside the PNG it writes a legend:
 the world-to-pixel transform both ways, what each colour means, and every bone's
 origin and tip in world units and in pixels, so a position read off the picture goes
 straight back into the spec. [AUTHORING §13](docs/AUTHORING.md#13-asking-the-picture-a-question--rigc-inspect)

package/docs/AUTHORING.md

@@ -10093,12 +10093,10 @@ pixel (`IN09`).
 | Where in rig units is this point? | `--show art,grid --zoom <bone or slot>` or `--viewport x,y,w,h` | grid lines at whole multiples of a step in **world units**, each labelled with its value, the lines through 0 darker. The legend's transform converts any pixel exactly; the grid is for reading by eye |
 | Is this axis declared, and held? | `--show art,declared,bones` | each `invariants.axes` line (§3.7) through its two bones' origins, drawn across the whole tile, and the bones it holds drawn in their own colour; the legend states each held bone's world x axis and how far off the line it lies, as `A51` measures it, at the pose drawn |
 | Did it break during the move? | any of the above `--animation <name> --at <s,s,…>` | one tile per time, left to right on one grid, each labelled with its time and frame |
-
-Two questions are not this cut's: **what does this bone move** (its weights over
-the meshes it skins, the mesh edges and hulls, the slots' draw order) and **did this
-change move anything** (two builds side by side on one grid). `--show mesh`,
-`hull`, `weights:<bone>`, `slots` and `--compare` are refused as any unknown word
-or flag is, naming what this version draws.
+| What does this bone move? | `--show art,mesh,weights:<bone> --dim` | the bone's weight over every region and mesh it moves, as a heat: a pixel whose centre lies in a triangle is painted the ramp's colour at the blend of its corners' weights — blue near 0, yellow at 0.5, red at 1 (the stops are in the legend) — and a weight of 0 is not painted, so the art shows where the bone does not reach. A region and an unweighted mesh are moved whole by their slot's bone. The weights are read off `skeleton.json`, the file both posers skin from; a bone that weights nothing paints nothing and the run says so on a line of its own |
+| How is this part triangulated? | `--show art,mesh,hull --zoom slot:<slot>` | each mesh's triangle edges, and over them its hull — vertex 0 to 1 to … to `hull − 1` and back. Regions are not drawn: a region is not a mesh. The legend lists every vertex in world units and in pixels |
+| Which is drawn over which? | `--show art,slots` | each slot that shows a region or mesh numbered by its place in the draw order **at the pose drawn** (0 is drawn first), on a white box at the centre of its attachment's box — so a `drawOrder` key (§4.7) shows from the first frame `render` draws it on |
+| Did this change move anything? | `--compare <dir>` beside any view | the same view of a second build beside the first, at the same times, on **one** world box and one transform, each half labelled `A`/`B` with the poser that posed it. A mark on a different pixel in the two halves is at a different place in the two rigs |
 
 ### 13.2 Where it looks
 
@@ -10119,11 +10117,40 @@ or flag is, naming what this version draws.
   (default a quarter of the box's longer side). A name that is both a bone and a slot
   is refused until it is written `bone:<name>` or `slot:<name>`; a bone of length 0
   with no pad is one point, and is refused asking for one.
+- **Two builds** — `--compare <dir | skeleton.json>`. The second build is loaded as
+  the first is (its own poser, chosen by what it carries, on a `poser    B:` line),
+  posed at the same times, and drawn beside it: one time is two halves side by side,
+  several are pairs, four to a row. The box is the one `--viewport` names, or the
+  union of what `--zoom` names in **both** builds, or — with neither — the union of
+  `render`'s framing of each, so a half is `render`'s frame of its build only where
+  the two framings agree. A name either build lacks is refused naming that build.
 - `--max` is each tile's longer side in pixels (default 256), as on `render`.
 - `--dim` fades the art toward white (each channel keeps 0.4 of its distance from
   white) so what is drawn over it reads.
 
-### 13.3 The legend
+### 13.3 Labels, and which bones are drawn
+
+- **One label per pixel.** Bones whose origins land on one pixel — a `_ctl` bone and
+  its identity child, a chain's joint — are one label: the first by declaration
+  order, then `+N` for the rest (`leg0_ctl +2`). The pixel is the unit because it is
+  what overprints: two origins a third of a pixel apart print their names on each
+  other as surely as two that coincide. The legend's `labels` lists every bone of
+  each label, and `bones` keeps every bone.
+- **No label over another.** Labels are placed in declaration order (slot numbers
+  first); one that would touch an earlier label moves down a text line at a time
+  until it is clear, and a grey leader joins it to its origin. After 16 lines it
+  stays where it began and the legend marks it `overlaps`.
+- **`--bone <glob[,glob…]>`** draws only the bones a pattern matches, and
+  **`--hide-bone <glob[,glob…]>`** none of the ones it matches, applied after
+  `--bone` — so `--bone 'bang_*' --hide-bone '*_ctl,*_px'` is the fringe chains
+  without their control bones. A pattern is a glob — `*` any run of characters, `?`
+  one, matched against the whole name — rather than a regular expression: bone names
+  are identifiers, the patterns are comma-separated, and a glob needs no escaping in
+  the shell. The filter is on `bones`, `axes` and `names`; every bone stays in the
+  legend, and a left-out one says which flag left it out in `undrawn`. A pattern
+  that matches no bone is refused naming the bones there are.
+
+### 13.4 The legend
 
 `<out>.json` beside `<out>.png`, `rigc-inspect/1`. What it states:
 
@@ -10139,29 +10166,48 @@ or flag is, naming what this version draws.
   top-left pixel), and `bones[]` — every bone in declaration order with its
   `parent`, `length`, `zeroLength`, `origin` and `tip` each as `{ world, pixel }`,
   `undrawn` (why it is not drawn — its world matrix is 0 at this time, unposed by the
-  skin or scaled to 0 — or `null`), and with `axes` shown, the two axis ends. With
-  `grid`, the step and every line's value; with `declared`, each entry's line in
-  degrees, its two points, and each held bone's angle and how far off the line it is.
+  skin or scaled to 0, or a `--bone`/`--hide-bone` pattern left it out — or `null`),
+  and with `axes` shown, the two axis ends. With `grid`, the step and every line's
+  value; with `declared`, each entry's line in degrees, its two points, and each held
+  bone's angle and how far off the line it is. With `names`, `labels[]`: each label's
+  `text`, the `bones` it stands for, its `anchor` pixel, the `box` it is drawn in,
+  and whether it was `moved` or `overlaps`. With `mesh`, `hull` or `weights`,
+  `meshes[]`: every region and mesh the pose shows, in draw order, with its `kind`,
+  `vertexCount`, `triangleCount`, `hull` (a mesh's hull vertex count), its unique
+  triangle `edges` as vertex pairs, every posed vertex in `world` and `pixel`, and
+  with `weights` the bone's weight at each vertex. With `slots`, `slots[]`: each
+  slot's `order`, `slot`, `attachment`, `bone`, its `anchor` and number's `box`.
+  On a sheet or a compare, `label` — the tile's label text and box; with `--compare`,
+  `build` — `A` or `B`.
 - `colours` — every colour the picture draws, as RGBA, with what it means.
 - `poser`, `show`, `dim`, `skin`, `animation`, `fps` and `framing` — what was drawn
   and how it was framed (`shot`, `zoom` with the bone or slot, the pad and whether it
   was stated, or `viewport`).
+- `weights` — with `weights:<bone>`: the bone, the ramp's stops as RGBA, the floor
+  below which nothing is painted, and how a pixel's weight is read.
+- `boneFilter` — `--bone` and `--hide-bone` as given.
+- `builds` — with `--compare`: each build (`A`, `B`), the poser that posed it, and
+  its `skeleton.json`'s sha256. `poser` is build `A`'s.
 
 Every number is `JSON.stringify`'s, the double the pose produced, not a rounding of
 it. The same build and flags write the same bytes (`IN10`).
 
-### 13.4 What it refuses
+### 13.5 What it refuses
 
 Each of these exits 2, writes nothing, and names what exists: a bone or slot the
 build does not have (both rosters listed), an animation or skin it does not declare,
 a `--show` word it does not draw, a flag it does not take, a time off the frame grid
 or past the end, `--at` without `--animation` and the reverse, `--zoom` beside
-`--viewport`, and `--show declared` on a skeleton with no `skeleton.model.json`
-beside it whose `spine.sha256` is its own — a Spine export states no rig invariants.
+`--viewport`, `--show declared` on a skeleton with no `skeleton.model.json`
+beside it whose `spine.sha256` is its own — a Spine export states no rig invariants —
+`weights` with no bone or with a bone the build lacks (the bones listed), a
+`--bone`/`--hide-bone` pattern that matches no bone (the bones listed), and, with
+`--compare`, any of these that holds of the second build, said as `the --compare
+build: …`.
 A rig that declares no `invariants.axes` is not refused: the picture draws nothing
 for `declared` and the run says so on a line of its own.
 
-### 13.5 What it is not
+### 13.6 What it is not
 
 - **Not a score.** Nothing in it is a pass bar; the picture is read, and what is read
   is acted on in the spec.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/core",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "description": "AI-authored 2D rigging and animation, verified before it is written. rigc compiles a rig spec into skeleton data in the Spine 4.3 format, gates it with named assertions held to a spine-core round trip's verdicts, and emits nothing that fails. Ships as an agent skill.",
   "type": "module",
   "bin": {

package/src/cli/core_commands.ts

@@ -30,7 +30,7 @@ import { ingest, INGEST_GUTTERS, type IngestFinding, IngestSpecRefused, type Ing
 import { PARSER_DEFAULTS, parserReading } from '../keyorder.ts';
 import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
-import { type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readShowWords, readTimes, readZoom } from '../inspect.ts';
+import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
 import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
@@ -676,7 +676,10 @@ export function cmdInspect(flags: Record<string, string>): void {
   if (flags.zoom !== undefined && flags.viewport !== undefined) {
     throw new InspectError('--zoom and --viewport both choose the box the picture is of; give one of them');
   }
-  const show = readShowWords(flags.show);
+  const { show, weightsBone } = readShow(flags.show);
+  const include = readBonePatterns('bone', flags.bone);
+  const exclude = readBonePatterns('hide-bone', flags['hide-bone']);
+  const boneFilter = include === undefined && exclude === undefined ? undefined : { ...(include === undefined ? {} : { include }), ...(exclude === undefined ? {} : { exclude }) };
   const times = readTimes(flags.at);
   const fps = readPositiveNumber(flags, 'fps', INSPECT_DEFAULT_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
@@ -709,14 +712,42 @@ export function cmdInspect(flags: Record<string, string>): void {
   const animation = readAnimationFlag(flags, [...candidate.facts.animations]) ?? null;
   readPoserFlag(flags);
   refuseUnchosen(candidate.choice);
+  // `--compare`: the second build, loaded the way the first was — its own poser chosen by what it carries, and said.
+  let compare: InspectCompare | undefined;
+  if (flags.compare !== undefined) {
+    const other = resolveDrawable(flags.compare, undefined);
+    const otherText = readSkeletonText(other.skeletonPath);
+    console.log(`  ..    compare  ${other.skeletonPath}`);
+    const otherCandidate = loadCandidate(
+      { skeletonText: otherText, atlasText: other.atlasText, atlasDir: dirname(other.atlasPath), label: other.skeletonPath },
+      { skeleton: other.skeletonPath, atlas: other.atlasPath },
+      posersAsked(flags),
+    );
+    refuseUnchosen(otherCandidate.choice);
+    compare = { candidate: otherCandidate, texts: { skeletonText: otherText, modelText: modelTextBeside(other.skeletonPath, otherText) } };
+  }
   const result = inspectCandidate(
     candidate,
     { skeletonText, modelText: modelTextBeside(skeletonPath, skeletonText) },
-    { show, dim: flags.dim !== undefined, animation, times, fps, skin: flags.skin, frame, maxSide },
+    {
+      show,
+      ...(weightsBone === undefined ? {} : { weightsBone }),
+      ...(boneFilter === undefined ? {} : { boneFilter }),
+      dim: flags.dim !== undefined,
+      animation,
+      times,
+      fps,
+      skin: flags.skin,
+      frame,
+      maxSide,
+    },
+    {},
+    compare,
   );
   const { legend } = result;
-  console.log(`  ..    poser    ${result.poserNote}`);
-  const when = animation === null ? 'the setup pose' : `${animation} at ${legend.tiles.map((t) => `${t.time.toFixed(4)}s (frame ${t.frame})`).join(', ')}, ${fps} fps grid`;
+  console.log(`  ..    poser    ${compare === undefined ? '' : 'A: '}${result.poserNote}`);
+  if (result.comparePoserNote !== undefined) console.log(`  ..    poser    B: ${result.comparePoserNote}`);
+  const when = animation === null ? 'the setup pose' : `${animation} at ${legend.tiles.filter((t) => t.build !== 'B').map((t) => `${t.time.toFixed(4)}s (frame ${t.frame})`).join(', ')}, ${fps} fps grid`;
   console.log(`  ..    view     ${legend.show.join(',')}${legend.dim ? ' over dimmed art' : ''} — ${when}`);
   const v = legend.viewport;
   // Four places for reading; the legend carries every number exactly.

package/src/cli/shared.ts

@@ -56,7 +56,7 @@ import { BallotError } from '../ballot.ts';
 import { ChainFitError } from '../chainfit.ts';
 import { CheckError } from '../check.ts';
 import { IngestError, type IngestStage } from '../ingest.ts';
-import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAMES, SHOW_WORDS } from '../inspect.ts';
+import { InspectError, DEFAULT_SHOW, DIM_KEEP, INSPECT_DEFAULT_FPS, ON_GRID_FRAMES, SHOW_SPELLINGS } from '../inspect.ts';
 import { NotAPngError } from '../png.ts';
 import { PoseError } from '../pose.ts';
 import { RepackError } from '../repack.ts';
@@ -1063,10 +1063,13 @@ const FLAG_MEANINGS: Record<string, string> = {
     'refused the same way. Not with `--slot`: the two are one statement',
   max: 'longest side of a rendered frame, in pixels (default 256)',
   show:
-    `what \`inspect\` draws, comma-separated, from [${SHOW_WORDS.join(', ')}] (default \`${DEFAULT_SHOW.join(',')}\`): art = the ` +
-    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; declared = each invariants.axes " +
+    `what \`inspect\` draws, comma-separated, from [${SHOW_SPELLINGS.join(', ')}] (default \`${DEFAULT_SHOW.join(',')}\`): art = the ` +
+    "build's own frame; grid = lines at whole multiples of a step in world units, labelled; weights:<bone> = that bone's " +
+    'weight over every region and mesh it moves, as a heat on a ramp the legend states; mesh = each mesh\'s triangle edges; ' +
+    "hull = each mesh's hull outline; declared = each invariants.axes " +
     "line through its two bones' origins, its held bones drawn in their own colour; bones = each bone from origin to tip, " +
-    'a bone of length 0 marked as one; axes = each bone\'s world x and y axes; names = each bone\'s name. Any other word ' +
+    'a bone of length 0 marked as one; axes = each bone\'s world x and y axes; slots = each slot\'s place in the posed ' +
+    'draw order; names = the bones\' names, one label per pixel (bones sharing an origin pixel are "first +N"). Any other word ' +
     'is refused naming these',
   dim: `fade the art toward white (each channel keeps ${DIM_KEEP} of its distance from white), so what is drawn over it reads`,
   at:
@@ -1078,6 +1081,17 @@ const FLAG_MEANINGS: Record<string, string> = {
     'frame the picture to one bone (origin to tip) or one slot (its attachment\'s vertices) over every time drawn, padded ' +
     'by <pad> world units on every side (default: a quarter of the box\'s longer side). A name that is both a bone and a ' +
     'slot is refused until written bone:<name> or slot:<name>; a name that is neither lists both rosters. Not with --viewport',
+  bone:
+    "draw only the bones these globs match (`*` any run of characters, `?` one, the whole name; comma-separated) — on `inspect`, " +
+    "for bones, axes and names; every bone stays in the legend, a left-out one saying why in `undrawn`. A pattern that matches no " +
+    'bone is refused naming the bones there are',
+  'hide-bone':
+    "draw none of the bones these globs match — `--bone` the other way round, applied after it, so `--bone 'bang_*' " +
+    "--hide-bone '*_ctl'` is the fringe chains without their control bones",
+  compare:
+    'a second build to draw beside --candidate, the same view at the same times on one world box and one transform — the union ' +
+    'of both framings unless --zoom or --viewport pins it — each half labelled with its build and the poser that posed it. A ' +
+    'name, animation or skin the second build lacks is refused naming it',
   record: 'a saved vote to check against its ballot and append to the ledger, instead of writing a ballot',
   ballot: `the ballot the --record'd vote answers (default \`${DEFAULT_BALLOT}\`); its embedded manifest is what the vote is checked against`,
   ledger: `the append-only JSONL the vote lands in (default \`${DEFAULT_LEDGER}\`)`,
@@ -1178,6 +1192,9 @@ const FLAG_VALUES: Record<string, string> = {
   show: '<view[,view…]>',
   at: '<s[,s…]>',
   zoom: '<name>[:<pad>]',
+  bone: '<glob[,glob…]>',
+  'hide-bone': '<glob[,glob…]>',
+  compare: '<dir|skeleton.json>',
   record: '<result.json>',
   ballot: '<ballot.html>',
   ledger: '<votes.jsonl>',
@@ -1564,8 +1581,10 @@ export const COMMANDS: CommandDoc[] = [
       'rigc inspect --candidate <dir | skeleton.json> [--show art,bones,…] [--dim] [--max 256] [--poser core|spine] [--out inspect.png]   (the setup pose)',
       'rigc inspect … --animation <name> --at <s[,s…]> [--fps 12] [--skin <name>]   (one time, or a sheet of several on one grid)',
       'rigc inspect … --zoom <bone|slot>[:<pad>] | --viewport <x,y,w,h>   (a box, in world units)',
+      "rigc inspect … --bone 'bang_*' --hide-bone '*_ctl'   (which bones bones, axes and names draw)",
+      'rigc inspect … --compare <dir | skeleton.json>   (a second build beside the first, on one transform)',
     ],
-    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'max', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'show', 'dim', 'animation', 'at', 'fps', 'skin', 'zoom', 'viewport', 'bone', 'hide-bone', 'compare', 'max', 'poser', 'out'],
     overrides: {
       animation: { meaning: 'the animation --at reads its times from (default: the setup pose, with no --at)' },
       fps: { meaning: `the frame grid --at is read on, which is the grid \`render --fps\` draws (default ${INSPECT_DEFAULT_FPS})` },