spine-rigc 1.2.3 → 1.4.0

package/README.md

@@ -530,12 +530,12 @@ commands take it and what its default is.
 | Command | Does |
 | --- | --- |
 | `build --rig … --motion … --out …` | compiles, gates, and **writes only if the gate is green**. `--images <dir>` says where the rig spec's `image` names resolve, `--manifest` adds measured art, and `--copy-images` copies every page PNG into `--out` so the directory is self-contained, with `skeleton.images` pointing at it so the editor's import finds the parts |
-| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size` and `--padding` tune it |
+| `build … --pack` | the same build with every part arranged onto **shared** atlas pages, written into `--out` — losslessly, and gated a second time as the pair that ships. `--page-size`, `--padding` and `--page-edges` tune it |
 | `build … --atlas-in <file.atlas>` | the same build with every part resolved to a **region of an existing pack** instead of a loose PNG; a name the atlas lacks, a size the spec disagrees with or a rectangle off its page is refused by name |
 | `validate <dir>` | re-gates artifacts already on disk |
 | `ingest <skeleton.json> --out <dir>` | `build` run backwards: reads a Spine 4.3 skeleton and writes the rig spec and motion spec that **rebuild it**, plus a findings report naming everything it could not carry. a skeleton that declares no stage is carried as declaring none, `--stage x,y,w,h` adds a box to one — and is refused, rather than ignored, beside one that declares a box — and `--images <dir>` writes the spec's own images directory — the opposite direction from `build --images`, which overrides it — so the rebuild carries no flag at all |
 | `explain --rig … --motion …` | the compiled rig as a table — every bone with its resolved parent, the slots in draw order, every timeline key by key. Writes nothing. What to reach for when a rig compiles and still looks wrong |
-| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference |
+| `render --candidate <dir>` | PNG frames plus a contact sheet, in `render/`. `--hide <slot,…>` or `--slot <slot,…>` draws part of the rig on the **same grid** as the whole, so the two frames overlay and the difference is the part; `frames.json` records the subset and `check` refuses such a set as a reference. `--geometry` adds a `geometry.json` per set: every frame's bone world transforms and skinned attachment vertices, with the rest geometry, on the frames' own grid |
 | `preview --candidate <dir>` | one self-contained `.html` that plays it, headed by the line `validate <dir>` prints for it and the rigc version — a refused candidate is still previewed, and its header says so in the gate's words. Repeat `--candidate` for one page with a pane per candidate, in the order given; a green `build` ends by naming this command for its own `--out` |
 | `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 |

package/cli.ts

@@ -101,8 +101,12 @@ import { NotAPngError } from './src/png.ts';
 import { copyAtlasPages } from './src/emit.ts';
 import {
   DEFAULT_PADDING,
+  DEFAULT_PAGE_EDGES,
   DEFAULT_PAGE_SIZE,
+  FREE_EDGE_STEP,
+  PAGE_EDGES,
   packAtlas,
+  type PageEdges,
   pageFootprint,
   parseAtlasText,
   type AtlasRegion,
@@ -141,6 +145,10 @@ import {
   FRAMES_SIDECAR,
   FRAMES_SPEC,
   framingViewport,
+  GEOMETRY_FILE,
+  GeometryError,
+  geometryFileOf,
+  geometryText,
   loadPosable,
   PROTOCOL_FPS,
   renderFrame,
@@ -149,6 +157,7 @@ import {
   SETUP_POSE_DIR,
   SHEET_FILE,
   SHEET_TILE,
+  sidecarViewport,
   SlotSubsetError,
   slotSubsetOf,
   type Frame,
@@ -255,7 +264,7 @@ function repositoryUrl(): string {
  * needs a value` (issue #328). `CLI10`/`CLI11` in `selftest.ts` now hold the two
  * halves together by reading `--help` rather than by naming a flag.
  */
-const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy']);
+const BOOLEAN_FLAGS = new Set(['all-frames', 'all-bones', 'help', 'copy-images', 'again', 'pack', 'copy', 'geometry']);
 
 /**
  * The flags a command is allowed to spell more than once.
@@ -612,9 +621,37 @@ const MESH_KIND_NOTES: Record<CompileResult['meshes'][number]['kind'], string> =
   ribbon: 'ribbon    entry row pinned, rows share their weights so the strip lengthens without widening',
   contour: 'contour   the art\'s own silhouette, every vertex pinned to the slot bone (geometry, not a deformation)',
   grid: 'grid      a lattice over the part window at stated column and row positions, every vertex pinned to the slot bone',
+  segments: 'segments  a lattice over the part\'s alpha, every vertex weighted by distance to the bone segments it names',
   authored: 'authored  geometry rigc did not build; it assumes nothing about the topology',
 };
 
+/**
+ * The line under a `segments` mesh: how its bones share the vertices.
+ *
+ * ⭐ The weights are this generator's whole output, and the per-vertex numbers
+ * are nowhere a reader can see them — so the three figures that say whether the
+ * falloff did what was meant are printed where the mesh is: the most bones any
+ * vertex binds (against `maxBones`), the mean, and how many vertices a single
+ * bone owns outright. A named bone no vertex binds is said by name, because it
+ * is in no weight and so in no other figure either.
+ */
+function meshInfluenceNote(m: CompileResult['meshes'][number]): string {
+  const inf = m.influence;
+  if (inf === undefined) return '';
+  const unbound = m.bones.filter((b) => !inf.bound.includes(b));
+  const single = m.vertices === 0 ? 0 : (inf.singleBone / m.vertices) * 100;
+  const joined = inf.keptCells - inf.artCells;
+  return (
+    `\n        influence  max ${inf.maxBones} bone(s) per vertex, mean ${inf.meanBones.toFixed(2)}, ` +
+    `${inf.singleBone} of ${m.vertices} vertices (${single.toFixed(2)}%) on a single bone` +
+    (unbound.length ? `; named and bound by no vertex: ${unbound.join(', ')}` : '') +
+    `\n        lattice    cell ${inf.cell}px, ${inf.cols}x${inf.rows} cells, ${inf.artCells} with art, ${inf.keptCells} kept` +
+    (inf.islands > 1 || joined > 0
+      ? ` (${inf.islands} island(s) joined into one outline, ${joined} cell(s) added that hold no art)`
+      : '')
+  );
+}
+
 /**
  * Why a figure taken off a part's texels is withheld on a page whose file is
  * not the size its atlas declares — the tail of every line that withholds one
@@ -1260,6 +1297,21 @@ function readIntFlag(flags: Record<string, string>, name: string, fallback: numb
   return Number(raw);
 }
 
+/**
+ * Read `--page-edges`, or its default — `pot`.
+ *
+ * An unknown value is a usage error for `readProfile`'s reason: a typo that fell
+ * back to `pot` would hand the caller who asked for the smaller page the bigger
+ * one, green, and say nothing.
+ */
+function readPageEdges(flags: Record<string, string>): PageEdges {
+  const raw = flags['page-edges'];
+  if (raw === undefined) return DEFAULT_PAGE_EDGES;
+  const found = PAGE_EDGES.find((e) => e === raw);
+  if (!found) throw new UsageError(`--page-edges ${JSON.stringify(raw)}; known values: ${PAGE_EDGES.join(', ')}`);
+  return found;
+}
+
 /**
  * One `DROP` line, written once because two outcomes print it.
  *
@@ -1343,7 +1395,7 @@ function cmdBuild(flags: Record<string, string>): void {
   // now a build like any other — and it is the only one that puts the renderer's
   // own rulebook over shared-page sampling.
   if (!packing) {
-    for (const name of ['page-size', 'padding'] as const) {
+    for (const name of ['page-size', 'padding', 'page-edges'] as const) {
       if (flags[name] !== undefined) throw new UsageError(`--${name} only means something with --pack`);
     }
   }
@@ -1394,7 +1446,8 @@ function cmdBuild(flags: Record<string, string>): void {
     console.log(
       `  MESH  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
         `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]  attachments=[${m.attachments.join(', ')}]${meshFit(m)}` +
-        meshDepthNote(m),
+        meshDepthNote(m) +
+        meshInfluenceNote(m),
     );
   }
   for (const ph of result.physics) {
@@ -1445,6 +1498,7 @@ function cmdBuild(flags: Record<string, string>): void {
     const packOpts = {
       pageSize: readIntFlag(flags, 'page-size', DEFAULT_PAGE_SIZE),
       padding: readIntFlag(flags, 'padding', DEFAULT_PADDING),
+      pageEdges: readPageEdges(flags),
       pageStem: 'skeleton',
     };
     const inputs = result.images.map((img) => ({
@@ -1460,7 +1514,8 @@ function cmdBuild(flags: Record<string, string>): void {
       console.log(
         `  ..    pack: ${page.name} ${page.width}x${page.height}, ` +
           `${packed.placements.filter((p) => packed.pages[p.page].name === page.name).length} region(s), ` +
-          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}`,
+          `${(page.occupancy * 100).toFixed(1)}% covered, padding ${packed.padding}` +
+          (packOpts.pageEdges === 'free' ? ', page edges free' : ''),
       );
     }
     for (const place of packed.placements) {
@@ -1960,6 +2015,24 @@ function cmdRender(flags: Record<string, string>): void {
   const fps = readPositiveNumber(flags, 'fps', PROTOCOL_FPS, 1);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
   const outRoot = resolve(flags.out ?? 'render');
+  const geometry = flags.geometry !== undefined;
+  // Refused together rather than one of them ignored (issue #864). The export
+  // records every slot's whole geometry, because a subset is a statement about
+  // which pixels are DRAWN and the pose is the same whatever a picture leaves
+  // out — so a geometry.json beside a subset's frames would describe slots
+  // those frames do not draw, and one that dropped them would stop being the
+  // pose. The whole-rig run writes the same file either way.
+  if (geometry) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--geometry takes no --${flag}: it records every slot's whole geometry, which a subset of the drawn slots ` +
+            `does not change. Run \`rigc render --geometry\` on the whole rig for the file, and --${flag} ` +
+            `${flags[flag]} without --geometry for the pictures — both land on the same grid`,
+        );
+      }
+    }
+  }
 
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
@@ -1993,8 +2066,24 @@ function cmdRender(flags: Record<string, string>): void {
   // `sampleAll` covers the skeleton with no animation at all, which files its one
   // setup-pose frame under the reserved name. Narrowing to one animation reuses
   // the same sampler rather than a second path through it.
+  //
+  // `--geometry` rides on the SAME call (issue #864): the bones and the whole
+  // attachments are read off the skeleton at the step that drew each frame, so
+  // the export's grid is this frame set's by construction.
+  const sampling = geometry ? { ...pose, bones: true, geometry: true } : pose;
   const sampled: Map<string, Frame[]> =
-    only === undefined ? sampleAll(data, fps, pose) : new Map([[only, sampleAnimation(data, only, fps, pose)]]);
+    only === undefined
+      ? sampleAll(data, fps, sampling)
+      : new Map([[only, sampleAnimation(data, only, fps, sampling)]]);
+  // Every file's text before the first write, so a refused number leaves the
+  // output directory as it was rather than half of a frame set behind it.
+  const geometryTexts = new Map<string, string>();
+  if (geometry) {
+    for (const [name, frames] of sampled) {
+      const animation = name === SETUP_POSE_DIR && data.animations.length === 0 ? null : name;
+      geometryTexts.set(name, geometryText(geometryFileOf(data, animation, fps, frames, viewport, skin)));
+    }
+  }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!declaresSetupStage(data)) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
 
@@ -2017,6 +2106,8 @@ function cmdRender(flags: Record<string, string>): void {
     // would be the same picture with a border and a "0" on it.
     const sheet = frames.length > 1;
     if (sheet) contactSheet(frames, pages, viewport, SHEET_TILE).writePng(join(dir, SHEET_FILE));
+    const geometryOut = geometryTexts.get(name);
+    if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -2028,7 +2119,8 @@ function cmdRender(flags: Record<string, string>): void {
       duration,
     });
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
-    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${sheet ? ` + ${SHEET_FILE}` : ''} -> ${dir}`);
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}`;
+    console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:
@@ -2045,15 +2137,9 @@ function cmdRender(flags: Record<string, string>): void {
     // every slot says nothing and stays the bytes it always was (issue #835).
     ...subsetFields(subset),
     background: BACKGROUND,
-    viewport: {
-      x: viewport.minX,
-      y: viewport.minY,
-      width: viewport.maxX - viewport.minX,
-      height: viewport.maxY - viewport.minY,
-      scale: viewport.scale,
-      pixelWidth: viewport.width,
-      pixelHeight: viewport.height,
-    },
+    // The one spelling `geometry.json` repeats, so the two files cannot state
+    // two boxes for one grid.
+    viewport: sidecarViewport(viewport),
     sets: [...sets].sort((a, b) => a.dir.localeCompare(b.dir)),
   };
   writeFileSync(join(outRoot, FRAMES_SIDECAR), `${JSON.stringify(sidecar, null, 2)}\n`);
@@ -3327,7 +3413,8 @@ function cmdExplain(flags: Record<string, string>): void {
       console.log(
         `  ${m.slot.padEnd(12)} ${m.kind.padEnd(8)} ${m.vertices} vertices / ${m.triangles} triangles  ` +
           `${meshBudget(result.rig)}  bones=[${m.bones.join(', ')}]${meshFit(m)}` +
-          meshDepthNote(m),
+          meshDepthNote(m) +
+          meshInfluenceNote(m),
       );
     }
   }
@@ -3737,6 +3824,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     'one written is the smallest that holds the pack, spilling to more pages only when the set will not fit',
   padding: `gutter each region reserves on every side, --pack only (default ${DEFAULT_PADDING}); it is filled by ` +
     "extending the region's own edge pixels outwards, which is what stops a neighbour bleeding in",
+  'page-edges': `what a page's edges may be, --pack only (default ${DEFAULT_PAGE_EDGES}): pot is a power of two on ` +
+    `both; free tries every width on a ${FREE_EDGE_STEP}px step, takes the height the placement needs and keeps ` +
+    'the least area — a smaller page, at the cost of region attachments sampling within 1 LSB of the loose ' +
+    'build rather than exactly',
   'atlas-in':
     'resolve every part against the regions of this pre-packed .atlas instead of against loose PNGs — region ' +
     'geometry (bounds/offsets/rotate) is read from the file and the atlas is re-emitted into --out, re-anchored',
@@ -3753,6 +3844,10 @@ const FLAG_MEANINGS: Record<string, string> = {
     'derived: a candidate is entitled to its own vocabulary, so a mapping worked out here would be a guess reported ' +
     'as a measurement',
   'all-bones': 'print every bone pair, not just the worst by position',
+  geometry:
+    `also write ${GEOMETRY_FILE} into each frame directory: per frame, every bone's world transform and every ` +
+    "slot's region or mesh vertices in world units after skinning, plus each attachment's rest geometry — on the " +
+    'frames\' own grid and viewport. Not with --slot/--hide: the geometry is the whole pose whatever is drawn',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -3855,6 +3950,7 @@ const FLAG_VALUES: Record<string, string> = {
   'atlas-in': '<file.atlas>',
   'page-size': '<px>',
   padding: '<px>',
+  'page-edges': 'pot|free',
   'texture-from': '<path>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
@@ -3941,7 +4037,7 @@ const COMMANDS: CommandDoc[] = [
     name: 'build',
     usage: [
       'rigc build --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--profile spine|spine-html] [--copy-images]',
-      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}]   (parts onto shared pages, written into --out)`,
+      `rigc build … --pack [--page-size ${DEFAULT_PAGE_SIZE}] [--padding ${DEFAULT_PADDING}] [--page-edges pot|free]   (parts onto shared pages, written into --out)`,
       'rigc build … --atlas-in <skeleton.atlas>                    (resolve the parts against a pack somebody already made)',
       'rigc build --cut <name> --cuts <cuts.json>',
     ],
@@ -3955,6 +4051,7 @@ const COMMANDS: CommandDoc[] = [
       'pack',
       'page-size',
       'padding',
+      'page-edges',
       'atlas-in',
       'cut',
       'cuts',
@@ -3973,7 +4070,7 @@ const COMMANDS: CommandDoc[] = [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
       'command read what `ingest --art none` writes was reachable and undocumented, while',
-      '--pack, --page-size, --padding and --copy-images are build\'s and do nothing here —',
+      '--pack, --page-size, --padding, --page-edges and --copy-images are build\'s and do nothing here —',
       'they decide what is WRITTEN, and this command writes nothing. What it takes is listed',
       'above, and that is now the whole of it.',
     ],
@@ -4091,10 +4188,10 @@ const COMMANDS: CommandDoc[] = [
   {
     name: 'render',
     usage: [
-      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--out render/]',
+      'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
       fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
@@ -4442,6 +4539,13 @@ try {
   // the one reader's and already names the file, what it is and what rigc
   // reads; a stack under it is the tool describing its own internals instead.
   // Exit 1, like a compile error: the invocation was fine, a file was not.
+  // A pose the geometry export cannot write as numbers (issue #864): the
+  // invocation was fine and the skeleton posed a NaN or an infinity, so exit 1
+  // like a file that is not a PNG. Raised before the first file is written.
+  if (err instanceof GeometryError) {
+    console.error(`rigc render: ${err.message}`);
+    process.exit(1);
+  }
   if (err instanceof NotAPngError) {
     console.error(`rigc: ${err.message}`);
     process.exit(1);