spine-parts 0.2.0 → 0.3.0

package/README.md

@@ -85,7 +85,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` and gated under both profiles |
-| `parts/*.png`, `parts.json`, `recomposite_rig.png` | the loose parts, each cropped to its alpha box; the record of where every part came from and how many of its pixels were re-taken from the painting; the flat stack of parts |
+| `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 spine-rigc's spec, `mesh_report.json`, the padded `images/` |
 | `check/` | both gate files verbatim, the idle's frames, `contact.png`, `motion_heat.png`, `check.json` |
 | `idle.png`, `idle-indexed.png`, `idle.gif` | with `--loop`: the idle as a lossless APNG (the exactness record), an indexed APNG with one shared palette (the small one) and a GIF; the last two print their palette error |
@@ -168,9 +168,9 @@ than queueing behind someone else's job.
 ## The loop, for an agent
 
 ```sh
-spine-parts inputs --source painting.png --config config.json --out inputs   # st_input_full.png; the config needs only key, seethrough, assemble.rig_scale
+spine-parts inputs --source painting.png --config config.json --out inputs   # st_input_full.png
 #    See-through on st_input_full.png (external, or `spine-parts comfy seethrough`) -> layers/full
-spine-parts layers layers/full                      # every layer: box, opaque px, depth
+spine-parts layers layers/full                      # every layer: box, opaque px, depth, plausibility figures; WARN lines
 spine-parts propose --head-box --full layers/full --canvas 1664x2432
 #    -> seethrough.head_box into config.json
 spine-parts inputs --source painting.png --config config.json --out inputs   # now st_input_head.png too
@@ -179,6 +179,10 @@ spine-parts sheet --source painting.png --layers layers/full --layers layers/hea
 spine-parts assemble --propose-plan --source painting.png --full layers/full --head layers/head --config config.json
 #    -> assemble.plan and extend_below_crop
 spine-parts assemble --source painting.png --full layers/full --head layers/head --config config.json --out work
+#    -> work/rig: parts.json and parts/; the config holds no bones, meshes, regions or motion yet
+#    -> read the `uncovered hole N:` lines and look at work/render/recomposite_error_rig.png:
+#       red is painting that no part holds, and no later gate can see it
+#    -> a large red hole neither run holds? add an assemble.patches entry (cut from the painting) and assemble again
 spine-parts propose --parts work/rig --source painting.png --out work
 #    -> proposal.json and render/landmarks.png; correct it, copy bones/meshes/regions/motion into config.json
 spine-parts propose --parts work/rig --source painting.png --out work --from-config config.json
@@ -187,6 +191,11 @@ spine-parts build --config config.json --source painting.png --full layers/full
 #    -> read out/check/check.json; every FAIL line names what has to change
 ```
 
+At each step the config holds only what that step reads; the one table of what
+that is, step by step, is [docs/AUTHORING.md §4](docs/AUTHORING.md#4-the-command-order).
+The selftest runs this block in order, command by command, on each fetched example,
+from a config holding only what the first step reads (`RL01`).
+
 `propose` is deliberately not a step of `build`: the proposal is a draft to correct
 against its overlay, and a config with bones is `build`'s input. `rig`, `check` and
 `loop` are the same stages one at a time. [docs/AUTHORING.md](docs/AUTHORING.md) is
@@ -202,15 +211,15 @@ agent skill.
 | `inputs --source <png> --config <json> --out <dir>` | the two images See-through is fed: the painting on a white square, and the head box's crop once the config has one |
 | `comfy paint --config --out [--host]` | optional: generate the painting on a ComfyUI box from the config's `generation` block |
 | `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 |
+| `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 |
-| `assemble --source --full --head --config --out [--seam] [--project]` | merge the two runs into rig-space parts, `parts.json` and the recomposite |
+| `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 --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 |
 | `propose … --from-config <config>` | draw and LINT the config's current bones |
 | `rig --config --parts --out` | author `rig.json` + `motion.json`, written only after spine-rigc's round trip is green |
-| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam, loop and the five judgement lines |
+| `check --rig --out [--parts]` | build packed, gate under both profiles, render the idle, measure seam, loop and the five judgement lines, and report the recomposite's holes from `parts.json` |
 | `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]` | assemble, rig and check in one process, stopping at the first refusal |
 
@@ -239,7 +248,9 @@ These are limits of the approach, stated so nobody reads more into a green run:
   encoder, which this package does not carry.
 - **The proposer reads tags, not pictures.** A swinging element painted inside another
   layer (a sash tail in the skirt), hair that is none of the shapes it knows, and
-  whether an accessory swings are the corrector's to add.
+  whether an accessory swings are the corrector's to add. The one accessory shape it
+  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.
 
 ### How much of a rig the model painted
 

package/cli.ts

@@ -16,16 +16,16 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, wri
 import { tmpdir } from 'node:os';
 import { basename, dirname, extname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
-import { assembleStage, build, checkStage, loopStage, readRuns, readSource, rigStage } from './src/build.ts';
-import { findRigc, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK } from './src/check.ts';
+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 { findRigc, PARTS_HOME_SENTENCE, type RigcRunner, SEAM_MEAN_BAR, SEAM_PX_BAR, SEAM_PX_LEVEL, SPINEBOY_YARDSTICK } from './src/check.ts';
 import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
 import { type CharacterConfig, loadConfig, loadEarlyConfig } from './src/config.ts';
 import { PartsError, problemLine } from './src/errors.ts';
 import { proposeHeadBox } from './src/headbox.ts';
 import { makeInputs } from './src/inputs.ts';
-import { type LayerSet, readLayers } from './src/layers.ts';
-import { checkProposal, compare, compareLines, drawLandmarks, lint, lintLine, type PartSet, propose, readPartSet, serializeProposal } from './src/propose.ts';
+import { figuresPhrase, implausibleRules, layerFigures, type LayerSet, pct, readLayers, ruleSummary, times } from './src/layers.ts';
+import { checkProposal, compare, compareLines, drawLandmarks, HIP_MIN_FRACTION, lint, lintLine, type PartSet, propose, readPartSet, serializeProposal } from './src/propose.ts';
 import { readPng, writePng } from './src/raster/png.ts';
 import { buildSheet, defaultCaption, type Tile, tilesFrom } from './src/sheet.ts';
 
@@ -52,9 +52,14 @@ usage:
   spine-parts layers <dir | layers.json | file.psd>
       Read a See-through decomposition — the ComfyUI wrapper form (a directory
       holding layers.json and one PNG per layer) or an upstream .psd — and print
-      every layer: draw order, name, tag group, box, size, opaque pixels, depth.
-      Refuses, by name, a missing file, an unknown tag, a PNG whose size is not
-      its box, and anything else outside the input contract.
+      every layer: draw order, name, tag group, box, size, opaque pixels, depth,
+      and three plausibility figures over its opaque pixels — translucent share
+      (alpha below 128), background share (min channel above 235) and area as a
+      multiple of the rest of the figure (the other layers' union). A layer that
+      crosses a plausibility rule gets a WARN line naming the rule and the bar;
+      --propose-plan leaves it out. Refuses, by name, a missing file, an
+      unknown tag, a PNG whose size is not its box, and anything else outside
+      the input contract — never a WARN.
 
   spine-parts sheet --source <painting.png> --layers <path> [--layers <path> ...]
                     --out <sheet.png> [--cell <px>] [--cols <n>]
@@ -68,9 +73,15 @@ usage:
       Propose bones, meshes, regions and an idle from the assembled parts (<dir>
       holds parts.json and parts/). Roles come from each part's See-through tag,
       never its name. Writes <out>/proposal.json (config-shaped: bones, meshes,
-      regions, motion with its blink, and notes) and the overlay to correct
-      against, <out>/render/landmarks.png and landmarks_head.png. Prints every
-      note and a LINT line for each chain link that lies off its mesh's art.
+      regions, motion with its blink — and a blink.still cut for a lash that
+      reaches far above its eyewhite, when a clear row allows one — and notes)
+      and the overlay to correct against, <out>/render/landmarks.png and
+      landmarks_head.png. Prints every
+      note and a LINT line for each chain link that lies off its mesh's art, for a
+      hip that is not below the chest, and for a hip above ${HIP_MIN_FRACTION} of the figure's
+      height (the shoulders); a headwear/earwear layer with hanging strands
+      gets one pendulum chain per strand and a note with each strand's x, rows
+      and width ("-- no chain proposed" is the one to act on; AUTHORING §3).
       --compare prints each shared bone's distance, proposal to config, in px.
 
   spine-parts propose --parts <dir> --source <painting.png> --out <dir> --from-config <config.json>
@@ -86,7 +97,9 @@ usage:
       Author the rig: unrotated bones at the config's landmarks (a chain makes
       <chain>0..n), a square lattice mesh over every part in config.meshes
       weighted by distance to its candidate bone segments, a region for every
-      part in config.regions, and one idle of sines and a blink. --parts is the
+      part in config.regions (a motion.blink.still part as two: the rows above
+      its row on a second slot <part>_still, which the blink does not move),
+      and one idle of sines and a blink. --parts is the
       directory holding parts.json and parts/<name>.png. The result is built
       through spine-rigc (profile spine-html, packed, then validated under
       profile spine) in a scratch directory first, and --out receives
@@ -95,8 +108,9 @@ usage:
   spine-parts check --rig <dir> --out <dir> [--parts <dir>]
       Build, gate, render and measure a rig through spine-rigc's CLI (the rigc at
       node_modules/.bin/rigc, or on PATH). --rig holds rig.json and motion.json
-      (with an "idle"); --parts holds parts.json and parts/ and defaults to
-      --rig. Both are only read. Into --out:
+      (with an "idle").
+      ${PARTS_HOME_SENTENCE}.
+      Both are only read. Into --out:
       build/ (rigc build --profile spine-html --pack: the packed atlas is the
       artifact), gate_spine-html.txt and gate_spine.txt (the gate lines
       verbatim), idle_frames/ (rigc render --animation idle --fps 12 --max 640),
@@ -114,7 +128,11 @@ usage:
       STILL_REGIONS_DARK (the heat map over the face outline and the feet).
       Regions come from parts.json's See-through tags; a line with nothing to
       read says SKIP and why — neither a pass nor a failure — and PASS needs
-      every line that measured to be PASS. Prints the pack line
+      every line that measured to be PASS. Then RECOMPOSITE_HOLES: REPORTED,
+      read from parts.json's recomposite block (uncovered error px, hole count,
+      the largest hole's box and the parts bordering it) — a line with no bar,
+      never a FAIL, because a pixel no part holds is missing from both sides of
+      the seam; SKIP when parts.json has no such block. Prints the pack line
       beside the spineboy yardstick (${SPINEBOY_YARDSTICK}), a reference and not
       a bar. Exit 0 on PASS, 1 on FAIL — every FAIL line names the bar, the value
       and the value required.
@@ -137,14 +155,25 @@ usage:
                        --config <config.json> --out <dir> [--seam near-white|silhouette]
                        [--project core|visible]
       Merge the full-body and head-crop See-through runs into rig-space parts:
-      <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json
-      and <out>/render/recomposite_rig.png. Reads config.seethrough.head_box and
-      .resolution and config.assemble.rig_scale, .plan and .extend_below_crop.
+      <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json,
+      <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
+      .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:
+      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
       (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
-      part has alpha above 128). Writes nothing unless every check passed.
+      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.
+      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
       opaque area by 5x5 first, so a part a few pixels wide takes none; visible
@@ -154,8 +183,11 @@ usage:
   spine-parts assemble --propose-plan --source <painting.png> --full <dir|psd>
                        --head <dir|psd> --config <config.json>
       Print {plan, extend_below_crop, notes} for config.assemble, from the two
-      runs. Reads only config.seethrough.head_box, config.seethrough.resolution
-      and config.assemble.rig_scale — the rest of the config need not exist yet.
+      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,
+      config.seethrough.resolution and config.assemble.rig_scale — the rest of
+      the config need not exist yet.
 
   spine-parts inputs --source <painting.png> --config <config.json> --out <dir>
       Cut the two images See-through is fed: <out>/st_input_full.png (the
@@ -194,7 +226,8 @@ usage:
       stops the build with its own FAIL lines. The config must already carry
       bones, meshes, regions and motion — propose is not a step of build: run it,
       correct the proposal against its overlay, and write the result into the
-      config. Into --out: parts/ + parts.json + recomposite_rig.png (assemble),
+      config. Into --out: parts/ + parts.json + recomposite_rig.png +
+      ${ERROR_MAP_FILE} (assemble),
       rig/ (rig), check/ (check, with the packed build in check/build/), and with
       --loop idle.png (lossless APNG), idle-indexed.png (indexed APNG) and
       idle.gif from check/idle_frames/, then one loop: line with the three sizes
@@ -233,7 +266,8 @@ function fixed(v: number | null): string {
 function printLayerTable(set: LayerSet): void {
   console.log(`spine-parts layers: ${set.form === 'wrapper' ? 'ComfyUI wrapper form' : 'PSD'}, ${set.source}`);
   console.log(`  canvas ${set.canvas.w}x${set.canvas.h}, ${set.layers.length} layer(s), back to front`);
-  const rows = set.layers.map((l) => [
+  const figures = layerFigures(set);
+  const rows = set.layers.map((l, i) => [
     String(l.drawOrder),
     l.name,
     l.tag.group,
@@ -242,14 +276,26 @@ function printLayerTable(set: LayerSet): void {
     `${l.pixels.width}x${l.pixels.height}`,
     String(l.opaquePx),
     fixed(l.depth),
+    pct(figures[i].translucent),
+    pct(figures[i].background),
+    times(figures[i].areaRatio),
   ]);
-  const head = ['order', 'name', 'group', 'left,top', 'right,bottom', 'size', 'opaque_px', 'depth'];
+  const head = ['order', 'name', 'group', 'left,top', 'right,bottom', 'size', 'opaque_px', 'depth', 'translucent', 'background', 'area'];
   const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
   const line = (cells: string[]): string => `  ${cells.map((c, i) => c.padEnd(widths[i])).join('  ')}`.trimEnd();
   console.log(line(head));
   for (const r of rows) console.log(line(r));
   const painted = set.layers.filter((l) => l.opaquePx > 0).length;
   console.log(`  ${set.layers.length} layer(s): ${painted} with opaque pixels, ${set.layers.length - painted} with none`);
+  // A reader refuses nothing on plausibility: it says what --propose-plan will leave out, and why.
+  let warned = 0;
+  for (const f of figures) {
+    for (const rule of implausibleRules(f)) {
+      console.log(`  WARN  ${rule}: layer "${f.name}" — ${figuresPhrase(f)}; ${ruleSummary(rule)} is required, so --propose-plan leaves it out`);
+      warned++;
+    }
+  }
+  console.log(`  ${warned} WARN line(s)`);
 }
 
 function cmdLayers(args: string[]): number {
@@ -298,6 +344,9 @@ function cmdSheet(args: string[]): number {
     const tiles: Tile[] = [{ name: 'source', image: src, caption: basename(source) }];
     for (const path of layers) tiles.push(...tilesFrom(path));
     const sheet = buildSheet(tiles, cols, cell);
+    // The README's loop writes sheets/layers.png into a folder nothing made yet;
+    // every other command creates its --out, so this one does too.
+    mkdirSync(dirname(out), { recursive: true });
     writePng(out, sheet);
     console.log(`spine-parts sheet: ${out}`);
     console.log(`  ${tiles.length} tile(s) in ${cols} column(s) of ${cell} px, sheet ${sheet.width}x${sheet.height}`);
@@ -396,7 +445,8 @@ function printLint(P: PartSet, spec: { bones: CharacterConfig['bones']; meshes:
   const res = lint(P, spec);
   for (const f of res.findings) console.log(lintLine(f));
   for (const m of res.unknownMeshes) console.log(`note: mesh ${JSON.stringify(m)} names no part in parts.json, so it was not linted`);
-  console.log(`${res.findings.length} LINT line(s) over ${Object.keys(spec.meshes).length - res.unknownMeshes.length} mesh(es)`);
+  for (const b of res.missingTorsoBones) console.log(`note: no single bone named ${JSON.stringify(b)}, so the hip was not linted against the chest${b === 'hip' ? ' or the figure height' : ''}`);
+  console.log(`${res.findings.length} LINT line(s) over ${Object.keys(spec.meshes).length - res.unknownMeshes.length} mesh(es) and the hip`);
   return res.findings.length;
 }
 
@@ -541,7 +591,7 @@ function cmdAssemble(args: string[]): number {
     const out = flags.get('--out') as string;
     assembleStage(
       { source, full, head, config, seam: seam as SeamRule, project: project as ProjectRule },
-      { partsJson: join(out, 'rig', 'parts.json'), partsDir: join(out, 'rig', 'parts'), recomposite: join(out, 'render', 'recomposite_rig.png') },
+      { partsJson: join(out, 'rig', 'parts.json'), partsDir: join(out, 'rig', 'parts'), recomposite: join(out, 'render', 'recomposite_rig.png'), errorMap: join(out, 'render', ERROR_MAP_FILE) },
       console.log,
     );
     return EXIT_OK;