rig-parts 1.2.0 → 1.4.0

package/README.md

@@ -306,8 +306,10 @@ These are limits of the approach, stated so nobody reads more into a green run:
   layer that is in front of another in one place and behind it in another is drawn
   right in the still (the painting's own pixels are projected onto it) and wrong once
   it moves.
-- **No expression or lip-sync.** The mouth is one layer; there is no mouth-shape set
-  and no expression axis.
+- **No expression or lip-sync, and no jiggle.** The mouth is one layer; there is no
+  mouth-shape set and no expression axis, and nothing here proposes, keys or judges a
+  soft region. An expression that moves the face's parts, and a jiggle, can be built on
+  the rig it writes ([below](#what-can-be-built-on-top)); lip-sync cannot.
 - **Occluded pixels are See-through's synthesis**, not the artist's. How much of a rig
   that is, is below.
 - **No success rate is claimed.** Ten characters have been measured stage by stage
@@ -331,6 +333,25 @@ These are limits of the approach, stated so nobody reads more into a green run:
   measures is a hanging strand on a headwear or earwear layer: each gets a pendulum
   chain, and a strand it cannot chain is named in a note rather than left stiff.
 
+### What can be built on top
+
+This package makes no expression and no jiggle, but the rig it writes is the material for
+both, and the config has a field for each. [docs/AUTHORING.md](docs/AUTHORING.md) has a recipe
+for each — a config fragment, the `check` lines it passes with, and its limit:
+
+- [**Expressions and other named animations**](docs/AUTHORING.md#recipe-expressions-and-other-named-animations):
+  the face's parts are bones; animations written over them in rig-c's motion-spec shape and
+  named by `motion.animations_from` are built and gated beside the idle on every build. One
+  attachment per slot, so a part moves, turns and scales but is never swapped for another
+  image; `check` measures the idle alone.
+- [**A soft region driven by physics**](docs/AUTHORING.md#recipe-a-soft-region-driven-by-physics)
+  (a bust, the hips): a bone the config authors, a contour-mode region that hands it the patch,
+  and a `physics` constraint on it; `examples/sample` carries one. Under the sample's slow
+  4 s idle the bust moves at most 0.066 rig px and the hips not at all: the spring answers
+  faster keys on the body. The sample's `hop`, a named animation keying only `hip`, moves the
+  bust up to 6.583 and the hips up to 4.432 rig px; the region's `band` caps how far a patch may
+  go before the texture-stretch ceiling, and `check` measures the idle alone.
+
 ### How much of a rig the model painted
 
 `parts.json` splits each part's opaque pixels (`opaque_px`) into `visible_px` — no

package/cli.ts

@@ -205,7 +205,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]
       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 +222,11 @@ 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). 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
@@ -326,14 +330,18 @@ usage:
       <out>/render/recomposite_rig.png and <out>/render/${ERROR_MAP_FILE} (the error
       map: uncovered error px red, covered error px blue, the rest the painting in
       light grey). Reads config.seethrough.head_box and
-      .resolution and config.assemble.rig_scale, .plan, .extend_below_crop and
+      .resolution and config.assemble.rig_scale, .plan, .extend_below_crop,
       .patches — extra parts cut from the painting itself over a rig-pixel box
       (alpha "silhouette": the painting's figure inside it; "box": all of it),
       drawn "back", "front" or {"before": <plan part>}, recorded in parts.json
-      as from "painting:<name>" and counted 100 % source — and no rig section:
+      as from "painting:<name>" and counted 100 % source — and .cuts — a plan
+      part's pixels inside a rig-pixel polygon taken into a new part, drawn the
+      same way, recorded with the plan part's from — and no rig section:
       bones, meshes, regions and motion need not exist yet, because propose
       drafts them from these parts (AUTHORING §4, the table).
-      Prints one line per part, the seam override counts, the \`pixels:\` totals
+      Prints one line per part, one \`cut:\` line per part a cut split (its
+      opaque pixels = what it kept + what each cut took), the seam override
+      counts, the \`pixels:\` totals
       (opaque = visible + occluded; taken from the painting; visible but not
       projected), and \`recomposite vs source\` (mean |d| and % within 8 over the
       mean channel; error px: max channel > 40; uncovered: of those, where no
@@ -421,9 +429,14 @@ usage:
       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,
@@ -435,7 +448,9 @@ usage:
       shared, so a character whose idle keys it, or whose constraint names it,
       is refused. The plate is a region on bone "${PLATE}" under
       root, drawn first, its image at canvas (0, 0). One idle holds every
-      character's tracks. Refused by name, every problem at once: an id
+      character's tracks; an animation beside a character's idle (its
+      config's motion.animations_from) rides along as "<id>:<name>",
+      prefixed as the idle is and scheduled by nothing. Refused by name, every problem at once: an id
       repeated, empty or holding ":" (or "/", "\\", a leading "."); a build
       missing a file or whose own check is not green; characters built at
       different rig_scale; a character whose parts' boxes, placed, leave the
@@ -447,7 +462,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
@@ -682,7 +697,15 @@ 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 one switch check takes (issue #202): it carries no value, so it is 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 f = flags(
+    args.filter((a) => a !== '--seam-pairs'),
+    ['--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;
@@ -692,7 +715,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 },
+      rigcRunner(bin),
+      bin,
+      console.log,
+    );
     return r.figures.PASS ? EXIT_OK : EXIT_REFUSED;
   } catch (err) {
     return printRefusal(err);