rig-parts 1.5.4 → 1.6.0

package/NOTICE.md

@@ -96,16 +96,29 @@ ships none and downloads none, and the terms that govern an image they produce
 are the terms of those models. A painting from any other source works the same
 way.
 
-The images this repository ships — `assets/demo-*` and `assets/sample-parts.png`
-— and the public examples' paintings were generated with
-`ponyDiffusionV6XL_v6StartWithThisOne.safetensors`,
-[Pony Diffusion V6 XL](https://civitai.com/models/257749), with no LoRA. The
-checkpoint itself is not redistributed. **[observed 2026-09-27]** CivitAI's model
-API reported for it `allowCommercialUse: ["Image", "RentCivit"]`,
-`allowNoCredit: false`, `allowDerivatives: true` and
-`allowDifferentLicense: false`: generated images may be used commercially and
-the model must be credited, which this line and the
-[spine-parts-examples](https://github.com/firejune/spine-parts-examples) README do.
+The images this repository ships, and the public examples' paintings, were
+generated with one of two checkpoints, with no LoRA; neither checkpoint is
+redistributed.
+
+- `assets/demo-*` and the `demo` example's painting (since issue #227):
+  `hassakuXLIllustrious_v13StyleA.safetensors`,
+  [Hassaku XL (Illustrious)](https://civitai.com/models/140272) v1.3 Style A, by
+  Ikena. Credit, as sharing it requires: *Painted with Hassaku XL (Illustrious)
+  v1.3 Style A by Ikena (https://civitai.com/models/140272), Fair AI Public
+  License 1.0-SD.* **[observed 2026-10-11]** The model page's version and licence
+  section reads "All Models using the Fair AI Public License 1.0-SD license", and
+  CivitAI's model API reported `allowCommercialUse: ["RentCivit", "Rent", "Image"]`,
+  `allowNoCredit: false`, `allowDerivatives: true` and `allowDifferentLicense: false`.
+- `assets/sample-parts.png` and the `scarf`, `reference-sample` and `reference-demo`
+  paintings: `ponyDiffusionV6XL_v6StartWithThisOne.safetensors`,
+  [Pony Diffusion V6 XL](https://civitai.com/models/257749). **[observed
+  2026-09-27]** CivitAI's model API reported for it `allowCommercialUse: ["Image",
+  "RentCivit"]`, `allowNoCredit: false`, `allowDerivatives: true` and
+  `allowDifferentLicense: false`: generated images may be used commercially and
+  the model must be credited, which this line does.
+
+The [parts-examples](https://github.com/rig-c/parts-examples) README records
+both, beside each character's generation record.
 
 ## 4. Behaviour reimplemented, not code copied
 

package/README.md

@@ -14,57 +14,45 @@ input is silent.
 ## What you get
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/demo-source.png" alt="The demo painting: a generated full-body character in a white and pink frilled dress with long pink twin tails, standing with her hands clasped" height="420" />
+  <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/demo-source.png" alt="The demo painting: a generated full-body character in a white and pink idol dress with a layered skirt and long pink twin tails, standing with her arms held away from her body and her hands open" height="420" />
   <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/demo-idle.png" alt="The same character rigged, breathing, blinking once and swaying her hair, sleeves and skirt in a four-second loop" height="420" />
 </p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/demo-parts.png" alt="Contact sheet of the painting and the 22 assembled parts it was split into: hair, dress, sleeves, shoes, face, eyes, brows, mouth and ornaments" width="100%" />
+  <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/demo-parts.png" alt="Contact sheet of the painting and the 23 assembled parts it was split into: hair, sleeves, legs, boots, neck, skirt, bodice, earrings, hair ornaments, ears, face, brows, mouth and eyes" width="100%" />
 </p>
 
 <p align="center"><em>
-The painting was generated for this repository with a public checkpoint (Pony
-Diffusion V6 XL) and no LoRA; its generation record, See-through layers and licence
-are in <a href="https://github.com/firejune/spine-parts-examples">spine-parts-examples</a>
-(that repository keeps the name it was published under before this package's rename).
+The painting was generated for this repository with a public checkpoint (Hassaku XL
+(Illustrious) v1.3 Style A, by Ikena, Fair AI Public License 1.0-SD) and no LoRA, on a
+pose that holds the hands apart, then given one hand-detailer pass; its generation
+record, See-through layers and licence are in
+<a href="https://github.com/rig-c/parts-examples">parts-examples</a>.
 See-through ran twice, once on the whole figure and once on a square head crop.
-Then one command: <code>rig-parts build --seam silhouette --loop</code>. The
-proposer's bones, meshes, regions and motion were used <b>unedited</b>. Two input-stage
-edits were made by hand for the reference run this example reproduces: the head box
-was shifted down into the canvas (its proposal ran 118 px above the top edge;
-<code>propose --head-box</code> now makes that shift itself), and <code>hair_back</code>
-is taken from the full run, because the twin tails leave the head crop sideways
-(a plan edit). <code>check</code> printed, verbatim:<br/>
-<code>50 assertions: 24 measured (24 passed, 0 failed), 26 skipped, 0 not in profile "spine-html"</code><br/>
+Then one command: <code>rig-parts build --loop</code>. The proposer's bones, meshes,
+regions and motion were used as proposed but for one correction, written in the
+config beside the values it replaced: the two outer skirt chains were moved out to
+0.8 of the skirt's half-width (the proposal's, within 90 px of the centre of a skirt
+449 px wide, swung it about its middle and failed <code>TIP_OVER_ROOT</code>, 0.442
+against 1.4725; moved, 2.425). One input-stage edit: <code>hair_back</code> is taken
+from the full run, because the twin tails leave the head crop sideways (a plan edit).
+<code>check</code> printed, verbatim:<br/>
+<code>50 assertions: 25 measured (25 passed, 0 failed), 25 skipped, 0 not in profile "spine-html"</code><br/>
 <code>loop: idle 49 frame(s) at 12 fps, f0000 vs f0048 (t = 4s): max |d| 0 (0 required)</code><br/>
-<code>seam: setup pose at 714x1216, scale 0.9422: mean |d| 0.234 (&lt;= 1.0), 2 px over 40, 2.25 rig px (the count / s²; &lt;= 50), 0 px over 80 (reported)</code><br/>
-<code>pack: skeleton.png 922x1348, 22 region(s), 94.9% covered, padding 2, page edges free, shape polygon</code><br/>
-<code>--seam silhouette</code> repaired the navy blobs the default rule leaves on the white
-blouse (recomposite error pixels 10,340 → 8,644); the default stays
-<code>near-white</code>, the reference implementation's rule, so the examples stay
-comparable with it. The loop is <code>rig-parts loop --palette</code>'s indexed APNG, 48 frames at
-12 fps, 1,706,719 bytes, one 256-entry palette at a measured error of max 57, mean 1.601
+<code>seam: setup pose at 654x1216, scale 0.9438: mean |d| 0.147 (&lt;= 1.0), 0 px over 40, 0.00 rig px (the count / s²; &lt;= 50), 0 px over 80 (reported)</code><br/>
+<code>pack: skeleton.png 1051x972, 23 region(s), 96.9% covered, padding 2, page edges free, shape polygon</code><br/>
+The loop is <code>rig-parts loop --palette</code>'s indexed APNG, 48 frames at
+12 fps, 827,857 bytes, one 256-entry palette at a measured error of max 65, mean 0.879
 per channel over every frame (the lossless APNG beside it, the exactness record, is
-13,645,503 bytes; the GIF, at the same error, 1,812,288). Frame 29 (2.417 s) is the
-closed eye: the blink holds for 0.084 s, one 12 fps frame rounded up, where the
-reference implementation held 0.04 s and no frame of its loop showed the eyes shut
-(issue #32); the painting is shown at half size, resampled and written
-by this package's PNG codec (nothing here encodes JPEG). <code>rig-parts sheet</code>
-made the contact sheet.
+5,832,634 bytes; the GIF, at the same error, 889,063). Frame 29 (2.417 s) is the
+closed eye: the blink holds for 0.084 s, one 12 fps frame rounded up; the painting is
+shown at half size, resampled and written by this package's PNG codec (nothing here
+encodes JPEG). <code>rig-parts sheet</code> made the contact sheet. Its
+<code>expected/</code> is this port's own build (<a href="examples/demo/README.md">examples/demo</a>).
 </em></p>
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/rig-c/parts/main/assets/sample-parts.png" alt="Contact sheet of the sample character's painting and its 20 parts" width="560" />
-</p>
-
 <p align="center"><em>
-The plain fixture, <code>examples/sample</code>: same checkpoint, no LoRA, and a rig
-built from its own proposal with no hand edit at all —
-<code>seam: setup pose at 379x1216, scale 1.0116: mean |d| 0.204 (&lt;= 1.0), 2 px over 40, 1.95 rig px (the count / s²; &lt;= 50), 0 px over 80 (reported)</code>, loop max |d| 0.
-</em></p>
-
-<p align="center"><em>
-The hanging element, <code>examples/scarf</code>: same checkpoint, no LoRA, a very long
+The hanging element, <code>examples/scarf</code>: Pony Diffusion V6 XL, no LoRA, a very long
 red scarf whose ends hang free, and the first character run through this pipeline
 with its proposal used unedited — the only hand corrections are four
 <code>assemble.patches</code>, each answering an <code>uncovered hole</code> line.
@@ -73,6 +61,15 @@ switched to the contour mode. It has no reference output: its <code>expected/</c
 is this port's own build (<a href="examples/scarf/README.md">examples/scarf</a>).
 </em></p>
 
+<p align="center"><em>
+Two more characters are tracked as fixtures and not shown:
+<code>examples/reference-demo</code> and <code>examples/reference-sample</code>, the two
+the reference implementation ran (published as <code>demo</code> and <code>sample</code>
+until issue #227, which took the clasped-hands painting off display). Their
+<code>expected/</code> is that implementation's own output, which the selftest holds
+this port to.
+</em></p>
+
 ## What it takes in
 
 - **One painting** — a PNG of one character, front-facing, full body, taller than
@@ -102,7 +99,7 @@ page** (issue #2):
 
 | path under `--out` | what |
 | --- | --- |
-| `check/build/skeleton.json`, `skeleton.atlas`, `skeleton.png` | **the artifact** — Spine 4.3 skeleton data and one packed page, written by `rigc build --pack --page-edges free --pack-shape polygon` and gated under `spine-html`, which holds every rule `spine` measures (on the demo, rigc 2.1.3 and 2.10.1: the 14 rules `validate --profile spine` measures are among the build's 24; 16 are not in `spine`) |
+| `check/build/skeleton.json`, `skeleton.atlas`, `skeleton.png` | **the artifact** — Spine 4.3 skeleton data and one packed page, written by `rigc build --pack --page-edges free --pack-shape polygon` and gated under `spine-html`, which holds every rule `spine` measures (on reference-demo, rigc 2.1.3 and 2.10.1: the 14 rules `validate --profile spine` measures are among the build's 24; 16 are not in `spine`) |
 | `parts/*.png`, `parts.json`, `recomposite_rig.png`, `recomposite_error_rig.png` | the loose parts, each cropped to its alpha box; the record of where every part came from, how many of its pixels were re-taken from the painting, and the recomposite's uncovered holes with their boxes; the flat stack of parts; its error map — red where no part covers a pixel the painting has, blue where a part covers it in the wrong colour |
 | `rig/` | `rig.json` and `motion.json` in rig-c's spec, `mesh_report.json`, the padded `images/` |
 | `check/` | both gate files verbatim, the idle's frames and their `geometry.json` (skinned vertices per frame), `contact.png`, `motion_heat.png`, `check.json` (with `pack_mode`, the `--page-edges` and `--pack-shape` the page was packed under) |
@@ -110,7 +107,7 @@ page** (issue #2):
 
 The last lines of a green build are the pack line, printed beside the Spine example
 export's `spineboy.png` as a yardstick (a reference, not a bar), and the three
-artifact paths — here for `examples/sample`:
+artifact paths — here for `examples/reference-sample`:
 
 ```
 build: PASS — the packed atlas is the artifact; parts/ and rig/ are the intermediates it was made from
@@ -121,7 +118,7 @@ build: PASS — the packed atlas is the artifact; parts/ and rig/ are the interm
 ```
 
 The page's edges are free by default: rigc picks the least-area page the parts need,
-not the next power of two. On the two examples, packed by rectangles, that is 967x1338
+not the next power of two. On the two reference examples, packed by rectangles, that is 967x1338
 and 479x1166, where a power-of-two page is 1024x2048 and 512x2048, and covered goes from 56.3 % to 91.2 % and
 from 49.7 % to 93.4 %. The cost is the one rigc's help states: *"region attachments
 sampling within 1 LSB of the loose build rather than exactly"*. Measured on both
@@ -192,8 +189,8 @@ head run on `st_input_head.png` is what gives the eyes more pixels
 **See-through is required; ComfyUI is not.** The wrapper is one route among
 four, and `rig-parts comfy` is only a convenience for that route: every
 stage after See-through reads files, whichever route wrote them. On the two
-public examples each run took 171–199 s through the wrapper (each run's
-`meta.json`, in [spine-parts-examples](https://github.com/firejune/spine-parts-examples)).
+reference examples each run took 171–199 s through the wrapper, and on the demo 179 s (each run's
+`meta.json`, in [parts-examples](https://github.com/rig-c/parts-examples)).
 
 ### The two images See-through is fed: `inputs`
 
@@ -277,7 +274,7 @@ agent skill.
 | `comfy seethrough --image --out [--host]` | optional: run the ComfyUI See-through wrapper on one image and write the form `layers` reads |
 | `layers <dir \| layers.json \| file.psd>` | print every layer of a decomposition: draw order, name, tag group, box, size, opaque pixels, depth, and its translucent, background and area figures; a `WARN` line for a layer `--propose-plan` will leave out |
 | `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
-| `assemble --propose-plan …` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule |
+| `assemble --propose-plan …` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, and naming in a note any full-run body no planned part covers |
 | `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json`, the recomposite and its error map, and list the uncovered holes |
 | `propose --head-box --full <run> --canvas WxH` | propose `seethrough.head_box` from the full run, held inside the painting |
 | `propose --parts --source --out [--compare <config>]` | propose bones, meshes, regions and an idle; draw the overlay; print, per bone, which check read it or that none did and why (its role, its kind of segment), and write `basis.json` beside the proposal — what each bone rests on (a joint, a part's mask, a ratio, other bones) and, with `--compare`, whether the config's bone differs |
@@ -336,7 +333,9 @@ These are limits of the approach, stated so nobody reads more into a green run:
 ### 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
+both, and the config has a field for each; `examples/demo` and `examples/scarf` carry a worked
+set of each (issue #224: a tilt, two looks, a smile, a startle, a wave or a bow and a hop,
+with physics on the hair, the skirt, the sleeves and the scarf ends). [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):
@@ -346,9 +345,9 @@ for each — a config fragment, the `check` lines it passes with, and its limit:
   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
+  and a `physics` constraint on it; `examples/reference-sample` carries one. Under its 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
+  faster keys on the body. Its `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.
 
@@ -357,15 +356,16 @@ for each — a config fragment, the `check` lines it passes with, and its limit:
 `parts.json` splits each part's opaque pixels (`opaque_px`) into `visible_px` — no
 later layer of its See-through run is opaque in front of them — and `occluded_px`,
 and counts the visible ones whose colour was not taken from the painting
-(`visible_not_projected_px`). On the three public examples, from the totals of their
+(`visible_not_projected_px`). On the four examples, from the totals of their
 `expected/parts.json` (the default `--project core`; `scarf`'s painting patches are
 whole painting pixels, so they count as taken):
 
 | | opaque px | occluded | visible, not projected | taken from the painting |
 | --- | --- | --- | --- | --- |
-| `sample` | 298,363 | 79,122 (26.5 %) | 35,979 (12.1 %) | 183,262 (61.4 %) |
-| `demo` | 765,924 | 202,343 (26.4 %) | 75,626 (9.9 %) | 487,955 (63.7 %) |
+| `demo` | 362,441 | 69,098 (19.1 %) | 67,164 (18.5 %) | 226,179 (62.4 %) |
 | `scarf` | 283,813 | 78,503 (27.7 %) | 56,699 (20.0 %) | 148,611 (52.4 %) |
+| `reference-sample` | 298,363 | 79,122 (26.5 %) | 35,979 (12.1 %) | 183,262 (61.4 %) |
+| `reference-demo` | 765,924 | 202,343 (26.4 %) | 75,626 (9.9 %) | 487,955 (63.7 %) |
 
 The occluded share is art the painting does not show — a back-hair layer, a neck, the
 parts of an ear under the hair — and is See-through's synthesis by necessity; it is
@@ -373,18 +373,19 @@ what the decomposition is for. The visible-but-not-projected share is synthesis
 the painting was there to be taken: a part too thin for the reference rule's 5x5
 eroded core, an anti-aliased fringe below alpha 250, a rim beside a layer in front, a
 pixel refused for drift. `--project visible` keeps the erosion only along a rim with a
-layer in front, which takes that share to 22,476 (7.5 %) on `sample` and 49,672 (6.5 %)
-on `demo` (from the `parts.json` of a `--project visible` build). On the eleven thin
+layer in front, which takes that share to 22,476 (7.5 %) on `reference-sample` and 49,672 (6.5 %)
+on `reference-demo` (from the `parts.json` of a `--project visible` build). On the eleven thin
 head parts — brows, lashes, irises, eye whites, ears, mouth — it takes 296 of
-`sample`'s 1,289 visible pixels where `core` takes 110, and 824 of `demo`'s 2,162
+`reference-sample`'s 1,289 visible pixels where `core` takes 110, and 824 of `reference-demo`'s 2,162
 where `core` takes 343. What neither rule takes is the fringe: a per-pixel
 classification of those parts under `visible`, recorded with the change that added
-the flag, puts 813 of `sample`'s 993 still-unprojected pixels and 879 of `demo`'s
+the flag, puts 813 of `reference-sample`'s 993 still-unprojected pixels and 879 of `reference-demo`'s
 1,338 below alpha 250. Where such a fringe keeps the stack off the painting and a part
 beneath holds the pixel in the painting's colour, `assemble` clears it instead, and
 the assemble line and `parts.json` say how many pixels, of which part, over which
 (AUTHORING §5, *The fringe push-back*; the figures in this section were measured
-before it, at v0.14.0).
+before it, at v0.14.0, but for the `demo` row, which is its `expected/parts.json`
+as this port wrote it in issue #227).
 
 ## Requirements
 

package/cli.ts

@@ -358,7 +358,11 @@ usage:
       mean channel; error px: max channel > 40; uncovered: of those, where no
       part has alpha above 128), then the uncovered holes (8-connected) and the
       largest ${HOLES_LISTED}, each \`uncovered hole N: <px> px at x,y wxh (between
-      "<part>" <px> px, …)\` — the list parts.json holds under recomposite.
+      "<part>" <px> px, …)\` — the list parts.json holds under recomposite —
+      and one \`uncovered:\` line per full-run layer the plan does not take from
+      the full run whose uncovered error holds a body (5x5-opened, 8-connected,
+      at least 150 full-run px in rig px), naming the layer, its pixels and the
+      rule that left it out.
       Writes nothing unless every check passed.
       --seam defaults to ${DEFAULT_SEAM_RULE}. --project says where a layer takes
       the painting's pixel: core (the reference's) erodes every layer's top-most
@@ -371,7 +375,11 @@ usage:
       Print {plan, extend_below_crop, notes} for config.assemble, from the two
       runs. A layer \`layers\` WARNs about (PLAN_LAYER_TRANSLUCENT,
       PLAN_LAYER_BACKGROUND, PLAN_LAYER_OVERSIZED) is not proposed, and a note
-      names it, its figures and the rule. Reads only config.seethrough.head_box,
+      names it, its figures and the rule. A full-run layer holding a body no
+      planned part covers (a lock the head run's part does not reach and
+      extend_below_crop cannot continue) is named in a note with the body, the
+      rule that skipped it and the continuation; the plan itself is not
+      changed. Reads only config.seethrough.head_box,
       config.seethrough.resolution and config.assemble.rig_scale — the rest of
       the config need not exist yet.