rig-parts 1.3.0 → 1.5.0

package/README.md

@@ -288,7 +288,7 @@ agent skill.
 | `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `spine-html`, render the idle, measure seam, loop and the six judgement lines (mesh texture stretch among them, from the idle's `render --geometry`), and report the recomposite's holes from `parts.json`; on a rig spec with no `parts.json` or no `idle` (a merged rig, issue #77) the gate still runs and every line that needs the missing input says SKIP by name; `--source <painting.png>` adds `SETUP_POSE_VS_SOURCE`, the setup pose against the painting by assemble's recomposite figures; `--requirements <scene.json>` measures what a scene declares of the motion — a contact, a follow fraction, an aim, a joint range, a mesh's stretch, the seam between two parts over the motion — each against the author's own bar, from rig-c's posed frames, one line each, PASS, FAIL or NOT MEASURABLE (AUTHORING §7, *Declared requirements*) |
 | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
 | `build --config --source --full --head --out [--seam] [--project] [--loop] [--requirements] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements` is forwarded to check, `--idle-keys` to rig |
-| `compose --scene <scene.json> --out [--requirements]` | bind several characters' green builds into one rig: every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
+| `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](docs/AUTHORING.md), *Composing several characters*) |
 
 `rig-parts --help` has every flag. Exit codes: 0 done, 1 input refused (every
 reason is a FAIL line), 2 a usage error or a command this version does not implement.

package/cli.ts

@@ -17,16 +17,16 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
 import { assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage } from './src/build.ts';
-import { DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
+import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, type RigcRunner, NO_PARTS_SENTENCE, SEAM_MEAN_BAR, SOURCE_SENTENCE, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK, TEXTURE_STRETCH_CEILING } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
-import { type CharacterConfig, loadConfig, loadEarlyConfig } from './src/config.ts';
+import { type CharacterConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
 import { PartsError, problemLine } from './src/errors.ts';
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
 import { idleKeysOf, isIdleKeys } from './src/rig.ts';
 import { figuresPhrase, implausibleRules, layerFigures, type LayerSet, pct, readLayers, ruleSummary, times } from './src/layers.ts';
 import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJoints, toRigJoints } from './src/keypoints.ts';
-import { basisLines, checkProposal, compare, compareLines, drawLandmarks, HIP_MIN_FRACTION, lint, lintLine, type PartSet, proposeWithBasis, readPartSet, serializeProposal } from './src/propose.ts';
+import { basisLines, checkProposal, compare, compareLines, drawLandmarks, HIP_MIN_FRACTION, lint, lintLine, type PartSet, proposeWithBasis, readPartSet, serializeProposal, WRIST_ON_PART_PX } from './src/propose.ts';
 import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, serializeBasis } from './src/diagnostics.ts';
 import { readPng, writePng } from './src/raster/png.ts';
 import { REQUIREMENTS_SENTENCE } from './src/requirements.ts';
@@ -108,7 +108,7 @@ usage:
       bone differs (origin, tip, parent; how far, in px). No confidence is
       computed. It prints "wrote ${BASIS_FILE} (…)" after the coverage lines.
 
-  rig-parts propose … [--keypoints <keypoints.json> [--person <id>]]
+  rig-parts propose … [--keypoints <keypoints.json> [--person <id>] [--wrist-snap <px>]]
       Read the figure's pose from one explicit file (spec "${KEYPOINTS_SPEC}"):
       its space (painting-px, origin top-left, y down — another is refused),
       the image's width and height (held to --source's, KEYPOINTS_IMAGE_SIZE),
@@ -124,7 +124,11 @@ usage:
       the rule. One note per joint says which. LINT then reads the torso along
       the neck -> hips line and each sleeve chain along shoulder -> wrist
       instead of by screen y, and prints the rule set it used first. Without
-      --keypoints nothing changes.
+      --keypoints nothing changes. A wrist holds a part when it lies within
+      ${WRIST_ON_PART_PX} px of its art (the larger of the x and y gaps);
+      --wrist-snap <px>, an integer above ${WRIST_ON_PART_PX}, binds a wrist on no
+      part to the one nearest part within <px>, said in a "wrist snap:" note
+      (with --keypoints, not with --from-config). Without it nothing changes.
 
   rig-parts propose --parts <dir> --source <painting.png> --out <dir> --from-config <config.json>
       Draw the config's CURRENT bones instead (<out>/render/landmarks_config.png
@@ -205,7 +209,7 @@ usage:
       rounding, and so is the per-frame mesh work (AUTHORING §5).
   rig-parts check --rig <dir> --out <dir> [--parts <dir>] [--source <painting.png>]
                     [--page-edges pot|free] [--pack-shape rect|polygon]
-                    [--requirements <file.json>]
+                    [--requirements <file.json>] [--seam-pairs] [--keep-stills]
       Build, gate, render and measure a rig through rig-c's CLI (the rigc at
       node_modules/.bin/rigc, or on PATH). --rig holds rig.json and motion.json:
       a rig spec, which rigc build compiles, not a compiled skeleton.json.
@@ -222,7 +226,13 @@ usage:
       entry that gated the build, and pack_mode, the two pack flags). PASS needs every gate summary
       "0 failed", the seam (setup pose vs the flat composite of parts/) at mean
       |d| <= ${SEAM_MEAN_BAR.toFixed(1)} with <= ${SEAM_PX_BAR} px over ${SEAM_PX_LEVEL}, and the loop (idle frame 0 vs the
-      frame at t = duration) at max |d| 0. Then six judgement lines, each in
+      frame at t = duration) at max |d| 0. A failing seam, or any seam under
+      --seam-pairs, is split by the pair of parts each counted pixel lies
+      between: one "seam pair" line each, worst first, with its count, frame
+      and rig boxes and a picture under seam/, and check.json's seam_pairs
+      (AUTHORING §7). --keep-stills leaves the setup-pose still the seam reads,
+      rigc's render directory with its frames.json (viewport and background),
+      under setup_still/. Then six judgement lines, each in
       check.json and on the console as NAME: PASS|FAIL|SKIP with its figures and
       bars (AUTHORING §7): BREATH_VISIBLE (the topwear moves, the footwear does
       not, each rendered alone), BLINK_NO_HOLE (the setup pose with the blink
@@ -421,13 +431,18 @@ usage:
       rigc refuses the pair a control splits, and the RIG_RIGC_GREEN line
       names the flag on the command that ran.
 
-  rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>]
+  rig-parts compose --scene <scene.json> --out <dir> [--requirements <file.json>] [--accept <bar>[,<bar>...]]
       Bind several finished characters into one rig. The scene file (spec
       "${SCENE_SPEC}") states the canvas {width, height}, an optional plate
       {image, provenance: ${PROVENANCES.join(' | ')}, note?}, the characters
-      [{id, build, offset: [x, y]}] — each build the --out of a green
+      [{id, build, offset: [x, y], scale?}] — each build the --out of a green
       \`rig-parts build\` (its check/check.json PASS), each offset a
-      translation from its rig px to canvas px — and order: the draw order,
+      translation from its rig px to canvas px, each scale (a positive
+      number, 1 when absent) the character's size about its stage's top-left
+      corner: every length it carries is scaled as Spine's loader scales a
+      skeleton (bones, regions, weight binds, constraint lengths, translate
+      keys), and a physics wind or gravity, which no per-character value
+      can scale, is refused (SCENE_SCALE_EXACT) — and order: the draw order,
       back to front, of character ids (that character's remaining slots, in
       its own order) and "<id>:<slot>" entries, every slot exactly once.
       Paths are relative to the scene file. Every bone, slot, attachment,
@@ -453,7 +468,7 @@ usage:
       rig-c as rig gates its own (build --profile spine-html --pack, the
       compile and the packed pages on disk); --out receives rig/ (rig.json,
       motion.json, images/) and ${SCENE_REPORT_FILE} (spec "${SCENE_REPORT_SPEC}":
-      every setting, each character's offset, bounds and shift (and what it
+      every setting, each character's offset, scale, bounds and shift (and what it
       moved),
       the plate's provenance, the declared and the composed order) only when
       it is green; then check runs over rig/ into check/, as on a rig it did
@@ -461,8 +476,14 @@ usage:
       TIP_OVER_ROOT, STILL_REGIONS_DARK and RECOMPOSITE_HOLES say SKIP and
       why), --requirements forwarded. Nothing is inferred: not the order, not
       an overlap, not a scale, not a person; the plate's provenance and the
-      order are the author's and judged by nothing. Exit 0 when the check is
-      PASS, 1 otherwise.
+      order are the author's and judged by nothing. --accept (or a
+      character's "accept": [...] in the scene file; the two lists are
+      joined, the command line's applying to every character) takes a build
+      whose own check failed only the bars named — ${ACCEPTABLE_BARS.join(', ')};
+      the gate, a declared requirement and an unknown name are refused
+      (SCENE_ACCEPT_KNOWN). It is for looking, not shipping: the [compose]
+      line and ${SCENE_REPORT_FILE} name what was accepted, and the run exits 1.
+      Exit 0 when the check is PASS and nothing was accepted, 1 otherwise.
 
   rig-parts --version
   rig-parts --help
@@ -688,7 +709,17 @@ function flags(args: string[], known: readonly string[], command: string, option
 }
 
 function cmdCheck(args: string[]): number {
-  const f = flags(args, ['--rig', '--out'], 'check', ['--parts', '--source', '--page-edges', '--pack-shape', '--requirements']);
+  // The two switches check takes (issues #202, #209): they carry no value, so they are taken out before the valued flags are read.
+  const seamPairs = args.filter((a) => a === '--seam-pairs').length;
+  if (seamPairs > 1) return usage('--seam-pairs is given twice');
+  const keepStills = args.filter((a) => a === '--keep-stills').length;
+  if (keepStills > 1) return usage('--keep-stills is given twice');
+  const f = flags(
+    args.filter((a) => a !== '--seam-pairs' && a !== '--keep-stills'),
+    ['--rig', '--out'],
+    'check',
+    ['--parts', '--source', '--page-edges', '--pack-shape', '--requirements'],
+  );
   if (typeof f === 'string') return usage(f);
   const rig = f.get('--rig') as string;
   const out = f.get('--out') as string;
@@ -698,7 +729,12 @@ function cmdCheck(args: string[]): number {
   if (!isPackShape(shape)) return usage(shape);
   try {
     const bin = findRigc(import.meta.dir, process.env.PATH ?? '');
-    const r = checkStage({ rig, parts: f.get('--parts'), source: f.get('--source'), out, pageEdges: edges, packShape: shape, requirements: f.get('--requirements') }, rigcRunner(bin), bin, console.log);
+    const r = checkStage(
+      { rig, parts: f.get('--parts'), source: f.get('--source'), out, pageEdges: edges, packShape: shape, requirements: f.get('--requirements'), seamPairs: seamPairs === 1, keepStills: keepStills === 1 },
+      rigcRunner(bin),
+      bin,
+      console.log,
+    );
     return r.figures.PASS ? EXIT_OK : EXIT_REFUSED;
   } catch (err) {
     return printRefusal(err);
@@ -732,7 +768,7 @@ function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes:
 function cmdPropose(args: string[]): number {
   const flags = new Map<string, string>();
   let headBox = false;
-  const valued = ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--canvas', '--keypoints', '--person'];
+  const valued = ['--parts', '--source', '--out', '--from-config', '--compare', '--full', '--canvas', '--keypoints', '--person', '--wrist-snap'];
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === '--head-box') {
@@ -775,6 +811,18 @@ function cmdPropose(args: string[]): number {
     if (out === undefined) return usage('propose needs --out <dir>');
     if (flags.has('--from-config') && flags.has('--compare')) return usage('--from-config and --compare are two modes; give one');
     if (flags.has('--person') && !flags.has('--keypoints')) return usage('--person names a person in the --keypoints file; give --keypoints <file>');
+    // Issue #199: a declared tolerance for a wrist on no handwear part. Whole px above the built-in one: the distance is
+    // counted in whole px, so a fraction would bind what its floor binds, and a value at or under the built-in binds nothing.
+    const snapArg = flags.get('--wrist-snap');
+    let wristSnap: number | null = null;
+    if (snapArg !== undefined) {
+      if (!flags.has('--keypoints')) return usage('--wrist-snap binds a wrist joint to a handwear part; give --keypoints <file>');
+      if (flags.has('--from-config')) return usage('--wrist-snap binds a wrist while proposing; --from-config proposes nothing');
+      if (!/^[0-9]+$/.test(snapArg) || Number(snapArg) <= WRIST_ON_PART_PX) {
+        return usage(`--wrist-snap ${snapArg} is not an integer above ${WRIST_ON_PART_PX}, the px within which a wrist already holds a part`);
+      }
+      wristSnap = Number(snapArg);
+    }
     const partsDir = existsSync(partsArg) && statSync(partsArg).isFile() ? dirname(partsArg) : partsArg;
     if (!existsSync(source)) {
       throw new PartsError([{ code: 'PROPOSE_SOURCE_PRESENT', object: source, detail: 'no such file; the painting is drawn under the overlay' }]);
@@ -802,7 +850,7 @@ function cmdPropose(args: string[]): number {
     }
     const cmpPath = flags.get('--compare');
     const cfg = cmpPath === undefined ? null : loadConfig(cmpPath);
-    const { proposal: prop, basis } = proposeWithBasis(P, joints);
+    const { proposal: prop, basis } = proposeWithBasis(P, joints, wristSnap);
     // Emit only after green: a proposal the config loader would refuse is not written, nor a basis record that does not hold to it.
     checkProposal(P, prop);
     const bfile = basisFile(P, prop, basis, cfg === null || cmpPath === undefined ? null : { where: cmpPath, config: cfg });
@@ -978,7 +1026,8 @@ async function cmdComfy(args: string[]): Promise<number> {
   try {
     // The config is a local file, so it is answered before any host is: a
     // config comfy paint cannot paint from is refused with no box named.
-    const cfg = sub === 'paint' ? loadEarlyConfig(configPath as string, 'paint') : null;
+    const paint = sub === 'paint' ? loadPaintConfig(configPath as string) : null;
+    const cfg = paint === null ? null : paint.config;
     const host = resolveHost(v.get('--host'), process.env.COMFY_HOST);
     const client = new ComfyClient(host, { poll: poll as number, request: 30 });
     if (sub === 'seethrough') {
@@ -1017,7 +1066,7 @@ async function cmdComfy(args: string[]): Promise<number> {
     if (typeof seed0 === 'string') return usage(seed0);
     console.log(`rig-parts comfy paint: ${cfg.key} -> ${out}`);
     console.log(`  ${seeds} seed(s) from ${seed0}${v.has('--seed0') ? '' : ' (generation.seed)'}; wait <= ${wait} s per seed, timeout ${timeout} s`);
-    const done = await runPainting(client, { config: cfg, out, seeds, seed0, wait: wait as number, timeout: timeout as number }, (l) => console.log(l));
+    const done = await runPainting(client, { config: cfg, pose: paint === null ? null : paint.pose, out, seeds, seed0, wait: wait as number, timeout: timeout as number }, (l) => console.log(l));
     console.log(`  wrote ${done.length} painting(s): ${done.map((d) => `${d.file} ${d.size[0]}x${d.size[1]} in ${d.elapsed.toFixed(1)} s`).join(', ')}; GPU job(s) ended`);
     return EXIT_OK;
   } catch (err) {
@@ -1105,7 +1154,7 @@ function cmdBuild(args: string[]): number {
 }
 
 function cmdCompose(args: string[]): number {
-  const f = flags(args, ['--scene', '--out'], 'compose', ['--requirements']);
+  const f = flags(args, ['--scene', '--out'], 'compose', ['--requirements', '--accept']);
   if (typeof f === 'string') return usage(f);
   let bin: string;
   try {
@@ -1116,8 +1165,9 @@ function cmdCompose(args: string[]): number {
   const scratch = mkdtempSync(join(tmpdir(), 'rig-parts-compose-'));
   try {
     const req = f.get('--requirements');
+    const accept = f.get('--accept');
     const r = composeStage(
-      { scene: f.get('--scene') as string, out: f.get('--out') as string, ...(req === undefined ? {} : { requirements: req }) },
+      { scene: f.get('--scene') as string, out: f.get('--out') as string, ...(req === undefined ? {} : { requirements: req }), ...(accept === undefined ? {} : { accept: accept.split(',') }) },
       { rig: rigcRunner(bin), check: rigcRunner(bin), checkBin: bin, scratch: join(scratch, 'gate') },
       console.log,
     );