spine-parts 2.26.0 → 2.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/cli.ts CHANGED
@@ -24,7 +24,8 @@ import { proposeNeck } from './tools/neck-propose.ts';
24
24
  import { parseAltArg } from './tools/alternate-cli.ts';
25
25
  import { type AlternateCliInput, assembleStage, build, checkStage, ERROR_MAP_FILE, loopStage, readRuns, readSource, rigStage, suppliedCheckFlag } from './src/build.ts';
26
26
  import { ACCEPTABLE_BARS, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, findRigc, PACK_SHAPES, rigcRunnerAt, type PackShape, PAGE_EDGES, type PageEdges, PARTS_HOME_SENTENCE, RIGC_GEOMETRY_VERSION, rigcRanClause, 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';
27
- import { ComfyClient, resolveHost, runPainting, runSeeThrough } from './src/comfy/index.ts';
27
+ import { ComfyClient, resolveHost, runBackground, runPainting, runSeeThrough } from './src/comfy/index.ts';
28
+ import { DEFAULT_GROW_PX, runForeground } from './src/plate.ts';
28
29
  import { type CharacterConfig, loadClothConfig, loadConfig, loadEarlyConfig, loadPaintConfig } from './src/config.ts';
29
30
  import { configWriteLines, readConfigWriteTarget, separateConfigWriteTarget, stageConfigWrite, type StagedConfigWrite } from './tools/configwrite.ts';
30
31
  import { failLine, guidePointer, PartsError } from './src/errors.ts';
@@ -49,6 +50,7 @@ import { REQUIREMENTS_SENTENCE } from './src/requirements.ts';
49
50
  import { composeStage, IMAGE_SEP, PLATE, PROVENANCES, SCENE_REPORT_FILE, SCENE_REPORT_SPEC, SCENE_SPEC } from './src/scene.ts';
50
51
  import { buildSheet, defaultCaption, type Tile, tilesFrom } from './src/sheet.ts';
51
52
  import { loadComparison, requiredProblems, structureLines } from './src/structure.ts';
53
+ import { assembleOutputFiles, clearRunStamp, readPackageIdentity, rigOutputFiles, RUN_STAMP_FILE, RUN_STAMP_SPEC, writeRunStamp } from './src/runstamp.ts';
52
54
  import { authorLayerLine } from './src/tags.ts';
53
55
 
54
56
  const EXIT_OK = 0;
@@ -411,7 +413,7 @@ usage:
411
413
  through rig-c (profile rig-play, packed with --page-edges and
412
414
  --pack-shape as for check; rigc's build gates the compile and the packed pages on disk) in a
413
415
  scratch directory first, and --out receives images/*.png, rig.json,
414
- motion.json and mesh_report.json only when it is green. Prints one line
416
+ motion.json, mesh_report.json and ${RUN_STAMP_FILE} (spec "${RUN_STAMP_SPEC}") only when it is green. Prints one line
415
417
  per mesh and the rigc gate lines.
416
418
  --idle-keys says where the idle's keys on a bone a mesh is weighted to go:
417
419
  ctl (the default) keys a same-origin <bone>_ctl parent instead, which
@@ -762,9 +764,9 @@ usage:
762
764
  stack by name, ASSEMBLE_PINHOLES, before writing; otherwise prints its SKIP line.
763
765
  Merge the full-body and head-crop See-through runs into rig-space parts:
764
766
  <out>/rig/parts/<name>.png (each cropped to its alpha box), <out>/rig/parts.json,
765
- <out>/render/recomposite_rig.png and <out>/render/${ERROR_MAP_FILE} (the error
767
+ <out>/render/recomposite_rig.png, <out>/render/${ERROR_MAP_FILE} (the error
766
768
  map: uncovered error px red, covered error px blue, the rest the painting in
767
- light grey). Reads config.seethrough.head_box and
769
+ light grey) and <out>/${RUN_STAMP_FILE} (spec "${RUN_STAMP_SPEC}"). Reads config.seethrough.head_box and
768
770
  .resolution and config.assemble.rig_scale, .plan, .extend_below_crop,
769
771
  .patches — extra parts cut from the painting itself over a rig-pixel box
770
772
  (alpha "silhouette": the painting's figure inside it; "box": all of it),
@@ -864,6 +866,26 @@ usage:
864
866
  is set. The pose words are generation.pose, or the control skeleton's own.
865
867
  The config needs only key and generation here; the rest comes later.
866
868
 
869
+ rig-parts comfy plate --mode background|foreground --painting <png>
870
+ --mask-from seethrough:<dir>|figure-mask:<dir> --out <dir>
871
+ [--graph lama|core] [--model <name>] [--checkpoint-sha256 <hex>]
872
+ [--seed 0] [--grow 8] [--steps 30] [--prompt <text>] [--negative <text>]
873
+ [--host <url>] [--wait 1800] [--timeout 3600] [--poll 3]
874
+ A step-4 plate with a receipt: <out>/plate.png, mask.png and receipt.json
875
+ (spec rig-parts-plate-receipt/1). The mask comes from a source only — the
876
+ figure layers of a See-through run, or the figure_rig.png an assemble with
877
+ config.scene wrote — on the painting's own grid; with none, the command is
878
+ refused and writes nothing. background inpaints the grown mask on a ComfyUI
879
+ box (--graph lama, the default: the inpaint pack's LaMa model, --model
880
+ big-lama.pt unless named; --graph core: the checkpoint --model names, core
881
+ nodes only), checks every node and model against /object_info before
882
+ uploading, appends the job behind any other (never in front, nothing
883
+ cancelled; a job still pending after --wait s is refused with its queue
884
+ place), and pastes the result into the painting inside the mask only.
885
+ --checkpoint-sha256 is required for background and is recorded as declared.
886
+ foreground runs no box: the painting's pixels inside the mask, transparent
887
+ outside.
888
+
867
889
  rig-parts build --config <config.json> --source <painting.png> --full <dir|psd>
868
890
  [--head <dir|psd>] --out <dir> [--seam near-white|silhouette]
869
891
  [--project core|visible] [--page-edges pot|free]
@@ -1147,6 +1169,7 @@ const TAKES = {
1147
1169
  assemble: { valued: ['--source', '--full', '--head', '--config', '--out', '--seam', '--project', '--alt', '--write-config', '--requirements'], switches: ['--propose-plan'] },
1148
1170
  'comfy seethrough': { valued: ['--image', '--out', '--resolution', '--steps', '--seed', '--prefix', '--host', '--wait', '--timeout', '--poll', '--config', '--depth-run'], switches: ['--offload', '--no-offload', '--lama', '--nf4'] },
1149
1171
  'comfy paint': { valued: ['--config', '--out', '--seeds', '--seed0', '--host', '--wait', '--timeout', '--poll'], switches: [] },
1172
+ 'comfy plate': { valued: ['--mode', '--painting', '--mask-from', '--out', '--graph', '--model', '--checkpoint-sha256', '--seed', '--grow', '--steps', '--prompt', '--negative', '--host', '--wait', '--timeout', '--poll'], switches: [] },
1150
1173
  inputs: { valued: ['--source', '--config', '--out'], switches: [] },
1151
1174
  build: { valued: ['--config', '--source', '--full', '--head', '--out', '--seam', '--project', '--page-edges', '--pack-shape', '--requirements', '--idle-keys', '--lead-in', '--alt', '--set', '--environment', '--wind-band'], switches: ['--loop', '--seam-pairs', '--keep-stills', '--all-sets', '--no-extremes'] },
1152
1175
  compose: { valued: ['--scene', '--out', '--requirements', '--accept'], switches: [] },
@@ -1342,6 +1365,7 @@ function cmdRig(args: string[]): number {
1342
1365
  if (!isPageEdges(edges)) return usage(edges);
1343
1366
  const shape = packShapeOf(packShape ?? undefined);
1344
1367
  if (!isPackShape(shape)) return usage(shape);
1368
+ clearRunStamp(out);
1345
1369
  let bin: string;
1346
1370
  try {
1347
1371
  bin = findRigc(import.meta.dir, process.env.PATH ?? '');
@@ -1349,8 +1373,12 @@ function cmdRig(args: string[]): number {
1349
1373
  return printRefusal(err);
1350
1374
  }
1351
1375
  const scratch = mkdtempSync(join(tmpdir(), 'rig-parts-rig-'));
1376
+ const startedAt = new Date().toISOString();
1352
1377
  try {
1353
- rigStage({ config, parts: partsDir, out, idleKeys: keys, pageEdges: edges, packShape: shape }, rigcRunner(bin), scratch, console.log);
1378
+ const pkg = readPackageIdentity(join(import.meta.dir, 'package.json'));
1379
+ const rig = rigStage({ config, parts: partsDir, out, idleKeys: keys, pageEdges: edges, packShape: shape }, rigcRunner(bin), scratch, console.log);
1380
+ const finishedAt = new Date().toISOString();
1381
+ writeRunStamp({ pkg, command: 'rig', startedAt, finishedAt, outDir: out, configPath: config, outputPaths: rigOutputFiles(rig) });
1354
1382
  return EXIT_OK;
1355
1383
  } catch (err) {
1356
1384
  return printRefusal(err);
@@ -1870,11 +1898,16 @@ function cmdAssemble(args: string[]): number {
1870
1898
  return EXIT_OK;
1871
1899
  }
1872
1900
  const out = flags.get('--out') as string;
1873
- assembleStage(
1901
+ clearRunStamp(out);
1902
+ const pkg = readPackageIdentity(join(import.meta.dir, 'package.json'));
1903
+ const startedAt = new Date().toISOString();
1904
+ const result = assembleStage(
1874
1905
  { source, full, head, config, ...(flags.has('--requirements') ? { requirements: flags.get('--requirements') as string } : {}), ...(seam === undefined ? {} : { seam: seam as SeamRule }), ...(project === undefined ? {} : { project: project as ProjectRule }), ...(alts.length === 0 ? {} : { alts }) },
1875
1906
  { 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) },
1876
1907
  console.log,
1877
1908
  );
1909
+ const finishedAt = new Date().toISOString();
1910
+ writeRunStamp({ pkg, command: 'assemble', startedAt, finishedAt, outDir: out, configPath: config, outputPaths: assembleOutputFiles(out, result) });
1878
1911
  return EXIT_OK;
1879
1912
  } catch (err) {
1880
1913
  if (staged !== null) {
@@ -1887,7 +1920,7 @@ function cmdAssemble(args: string[]): number {
1887
1920
  }
1888
1921
 
1889
1922
  /** Parse `--flag value` pairs and bare `--switch`es, as the command's {@link TAKES} row names them; a string is a usage error. */
1890
- function comfyFlags(args: string[], command: 'comfy seethrough' | 'comfy paint'): { v: Map<string, string>; on: Set<string> } | string {
1923
+ function comfyFlags(args: string[], command: 'comfy seethrough' | 'comfy paint' | 'comfy plate'): { v: Map<string, string>; on: Set<string> } | string {
1891
1924
  const switches: readonly string[] = TAKES[command].switches;
1892
1925
  const v = new Map<string, string>();
1893
1926
  const on = new Set<string>();
@@ -1923,11 +1956,57 @@ function secondsFlag(v: Map<string, string>, flag: string, fallback: number): nu
1923
1956
  return Number.isFinite(n) && n > 0 ? n : `${flag} ${raw} is not a number of seconds above 0`;
1924
1957
  }
1925
1958
 
1959
+ /** Flags `comfy plate --mode foreground` does not take: it runs no box and no model. */
1960
+ const PLATE_BOX_FLAGS = ['--graph', '--model', '--checkpoint-sha256', '--seed', '--grow', '--steps', '--prompt', '--negative', '--host', '--wait', '--timeout', '--poll'];
1961
+
1962
+ async function cmdComfyPlate(v: Map<string, string>): Promise<number> {
1963
+ const mode = v.get('--mode');
1964
+ if (mode !== 'background' && mode !== 'foreground') return usage(`comfy plate needs --mode background or --mode foreground${mode === undefined ? '' : `; got "${mode}"`}`);
1965
+ const painting = v.get('--painting');
1966
+ if (painting === undefined) return usage('comfy plate needs --painting <png>');
1967
+ const out = v.get('--out');
1968
+ if (out === undefined) return usage('comfy plate needs --out <dir>');
1969
+ try {
1970
+ if (mode === 'foreground') {
1971
+ const extra = PLATE_BOX_FLAGS.filter((x) => v.has(x));
1972
+ if (extra.length > 0) return usage(`comfy plate --mode foreground runs no box and no model; ${extra.join(', ')} ${extra.length === 1 ? 'is' : 'are'} for --mode background`);
1973
+ console.log(`rig-parts comfy plate: foreground ${painting} -> ${out}`);
1974
+ const r = runForeground({ painting, maskFrom: v.get('--mask-from'), out });
1975
+ console.log(` mask from ${r.mask.source} ${r.mask.from}; no box, no model (graph ${r.graph})`);
1976
+ console.log(` wrote ${join(out, r.output.path)} (sha256 ${r.output.sha256}), ${r.mask.path} and receipt.json`);
1977
+ return EXIT_OK;
1978
+ }
1979
+ const graph = v.get('--graph') ?? 'lama';
1980
+ if (graph !== 'lama' && graph !== 'core') return usage(`--graph ${graph} is not lama or core`);
1981
+ const wait = secondsFlag(v, '--wait', 1800);
1982
+ const timeout = secondsFlag(v, '--timeout', 3600);
1983
+ const poll = secondsFlag(v, '--poll', 3);
1984
+ for (const x of [wait, timeout, poll]) if (typeof x === 'string') return usage(x);
1985
+ const seed = intFlag(v, '--seed', 0, 0);
1986
+ const grow = intFlag(v, '--grow', DEFAULT_GROW_PX, 0);
1987
+ const steps = intFlag(v, '--steps', 30, 1);
1988
+ for (const x of [seed, grow, steps]) if (typeof x === 'string') return usage(x);
1989
+ if (graph === 'lama') for (const x of ['--steps', '--prompt', '--negative']) if (v.has(x)) return usage(`${x} is for --graph core; the lama graph takes no prompt and no steps`);
1990
+ console.log(`rig-parts comfy plate: background (${graph}) ${painting} -> ${out}`);
1991
+ // Every local refusal (no source mask, the checksum, the grid) comes before the host is resolved.
1992
+ const r = await runBackground(
1993
+ () => new ComfyClient(resolveHost(v.get('--host'), process.env.COMFY_HOST), { poll: poll as number, request: 30 }),
1994
+ { painting, maskFrom: v.get('--mask-from'), out, graph, model: v.get('--model'), checkpointSha256: v.get('--checkpoint-sha256'), seed: seed as number, growPx: grow as number, steps: steps as number, prompt: v.get('--prompt'), negative: v.get('--negative'), wait: wait as number, timeout: timeout as number },
1995
+ (l) => console.log(l),
1996
+ );
1997
+ console.log(` wrote ${join(out, r.output.path)} (sha256 ${r.output.sha256}), ${r.mask.path} and receipt.json; model ${r.model?.name} (checkpoint sha256 declared), GPU ${r.gpu}`);
1998
+ return EXIT_OK;
1999
+ } catch (err) {
2000
+ return printRefusal(err);
2001
+ }
2002
+ }
2003
+
1926
2004
  async function cmdComfy(args: string[]): Promise<number> {
1927
2005
  const [sub, ...rest] = args;
1928
- if (sub !== 'seethrough' && sub !== 'paint') return usage(`comfy takes seethrough or paint; got ${sub === undefined ? 'nothing' : `"${sub}"`}`);
2006
+ if (sub !== 'seethrough' && sub !== 'paint' && sub !== 'plate') return usage(`comfy takes seethrough, paint or plate; got ${sub === undefined ? 'nothing' : `"${sub}"`}`);
1929
2007
  const f = comfyFlags(rest, `comfy ${sub}`);
1930
2008
  if (typeof f === 'string') return usage(f);
2009
+ if (sub === 'plate') return cmdComfyPlate(f.v);
1931
2010
  const { v, on } = f;
1932
2011
  if (on.has('--offload') && on.has('--no-offload')) return usage('--offload and --no-offload cannot be combined');
1933
2012
  const wait = secondsFlag(v, '--wait', 1800);
package/docs/AUTHORING.md CHANGED
@@ -179,7 +179,7 @@ read by no CPU stage).
179
179
  | `constraints` | rig (handed to rig-c as `rig.json`'s `constraints`); `compare` and the coverage lines (roles) | **authored**, optional; `propose` writes none, but with `--cloth` (issue #364), where it writes the recipe's physics and swing transforms (*Recipe: cloth and hair that answer the world*, below). A list of constraints in **rig-c's own rig-spec shape** (`RigConstraint`: `ik`, `transform`, `path`, `physics`, `slider` — rig-c's `src/rig.ts` documents every field), in the order rigc applies them. The loader checks only what this package owns: each entry is an object with a `type` rigc names (`CONFIG_CONSTRAINT_TYPE_KNOWN`) and a non-empty `name`, unique within its kind as rigc finds constraints (`CONFIG_CONSTRAINT_NAME_UNIQUE`; an ik and a transform may share one); every bone it names — `bones`, an ik's `target`, a transform's `source`, a physics or slider constraint's `bone` — is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`); the bone a constraint follows does not sit under a bone it drives (`CONFIG_CONSTRAINT_TARGET_DETACHED`). Every other field (`mix`, `softness`, `properties`, a path's `slot`, a slider's `animation`) and every value is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`) — an ik's `bones` as a shape too: from rig-c 2.15.0 rigc refuses an ik over more than two bones, or over a pair whose second bone is not the first's child (issue #103; this loader refused both itself until then). A note and an `x-` record may ride on an entry; the rig stage leaves them out of what it hands rigc. Under the default `--idle-keys ctl` a two-bone ik whose child link the idle keys is split by that link's control, and rigc refuses the pair: run `rig --idle-keys direct` or `build --idle-keys direct` (the rig stage adds that sentence, naming the flag on the command that ran, to rigc's line; `build` forwards it to its rig stage, issue #95). Each bone a constraint follows is declared to rigc as `invariants.detached` from every bone it drives, which rigc's gate rule `A25` checks |
180
180
  | `stops` | rig (handed to rig-c as `rig.json`'s `stops`, and moves slots, mesh weights and child bones on stopped links onto `<link>_d`); `propose --from-config` (`LINT stop on <chain> …`) | **authored**, optional (issues #404, #447): `[{chain, links?, against, at, inward, outward, lower?: {inward, outward}}]` — rig-c's leg stops (`RigStop`, rig-c 2.56.0, `@rig-c/core/stop`). `chain` is a chain `bones` declares (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `links`, optional, is a non-empty list of links of that chain (`CONFIG_NAME_RESOLVES`, `CONFIG_FIELD_TYPE`), or absent for every link of `chain` in chain order; `against` is a bone `bones` declares, a chain link as `<chain><i>` (`CONFIG_NAME_RESOLVES`, `RIG_NAME_RESOLVES`); `at` is `[x, y]` in `against`'s local space, as rig-c's stop takes it (`CONFIG_FIELD_TYPE`): since each chain link (`leg_r0`, `leg_r1`) is turned to point along its segment (`+x` from origin to next link or tip, `+y` 90° counter-clockwise in Spine world), `at: [d, n]` sits `d` px from `against`'s origin toward its end and `n` px perpendicular to it; `inward`, `outward` and `lower.inward`, `lower.outward` are finite numbers (`CONFIG_FIELD_TYPE`). Every other stop rule — non-negative bounds, each stopped link written by a constraint, `against` not under the stopped chain, the aim not degenerate, `\|rest\| + outward <= 180°` (`RIG_STOP_BOUNDS`) — is rigc's to accept or refuse at the rig stage's gate, in rigc's words (`RIG_RIGC_GREEN`). **Rising-limb / prone geometry (issue #447):** rig-c's `expandStops` aims `<chain>_rest` from `links[0]`'s setup origin at `<chain>_touch` (`at` in `against`'s local frame) and clamps `<link>_d` inside `[rest − inward, rest + outward]`; Spine wraps rotation at `±180°`, so `\|rest\| + outward <= 180°` is required (`RIG_STOP_BOUNDS`). Whenever `<chain>_touch` lies **above** `links[0]`'s root in rig pixels (`ty < y0`, i.e. higher Spine `y` — e.g. stopping a hanging cloth chain against a rising shin `leg_<s1>` in a prone or kneeling pose where the knee sits below `links[0]` and the ankle above it, so positive `at[0]` walks upward along the shin past `links[0]`'s root), `rest` lands in the upper half-plane (`\|rest\| > 90°`) and `\|rest\| + outward` exceeds `180°`. Stop against the descending thigh (`leg_<s0>`), set `links` to start at a link whose root sits above `<chain>_touch`, or omit the stop when the rising shin sits outside the hanging chain's sweep; `propose --from-config` prints `LINT stop on <chain> …` with the exact coordinates and angles when `<chain>_touch` lies above `links[0]`'s root or `\|rest\| + outward > 180°`. For every stopped link `<link>`, the rig stage moves any slot on `<link>`, any mesh weight on `<link>`, and any bone whose parent is `<link>` (a branched cloth tree's branches hanging from `<trunk_last>`, before `--idle-keys ctl` adds `<bone>_ctl` and before `turn` adds `turn_<part>_<bone>`) onto `<link>_d`, the drawn link bone rig-c's `expandStops` creates at `<link>`'s setup frame to carry the clamped rotation. Absent, `rig.json` carries no `stops` and no byte of any output moves |
181
181
  | `turn` | rig (adds the turn control or 2.5D head-turn producer) | **proposed** only with `propose --full`/`--head` (issue #251), then corrected, or **authored** for 2.5D depth-sampled head turns (issue #763): `{pivot?, depths?, deform?, band?, radius?, surface?: {radius?}, head?: {pivot?, radius?}, roles?, counter?, grid?, unitDepths?, body?}`. When `roles` is declared (`{<part>: "surface" \| "unit" \| "rear"}`, issue #763; `CONFIG_TURN_ROLE_UNKNOWN`, `CONFIG_TURN_SURFACE_REQUIRED`, `RIG_TURN_SURFACE_MESH_BINDINGS`, `CONFIG_TURN_UNIT_MESH_BONES`), the rig stage runs the 2.5D depth-sampled head-turn producer: it edge-extends each turn-bound part's depth sheet across its transparent border and semi-transparent fringe from the nearest fully opaque (`alpha === 255`) texel before `PAD = 4` clamping (`padTurnDepthSheet`, `DEPTH_SILHOUETTE_SIZE_MISMATCH`), keeps authored `"surface"` meshes and their skinning (#795), sampling each vertex at its weighted setup position on its own extended sheet and emitting one inverse-setup-bone offset per influence (`D = -(pivot + z - zRef) * sin(angle)`, on x for yaw and y for pitch, with no narrowing or 2D spin); shared frames moved by another turn role are refused (`RIG_TURN_SURFACE_MESH_BINDINGS`), as are alternate drawings without their own depth sampling frame (`RIG_TURN_SURFACE_MESH_ATTACHMENT`). It promotes `"surface"` regions to `generator: {kind: "grid", cols, rows, depth}` (`grid`: `[cols, rows]` or `{<part>: [cols, rows]}`, default `[13, 16]`, bounded at `<= 2,400` triangles per slot and `<= 4,000` total, `RIG_TURN_GRID_BUDGET`, `RIG_TURN_SURFACE_DEPTH_REQUIRED`, `RIG_TURN_SHARED_DEPTH_SCALE`), emits `faceshift` and `rear_shift` under `head` (`CONFIG_TURN_HEAD_BONE`, `RIG_TURN_HEAD_BONE`), `<part>_surface` and `<part>_unit` under `faceshift`, and `yaw_dial` and `pitch_dial` under `root` (`CONFIG_TURN_BONE_FREE`, `RIG_TURN_NAME_FREE`), re-parents `"unit"` region bones and `"rear"` bones and mesh weights to `faceshift` and `rear_shift` (while `"unit"` mesh parts receive their own `<part>_unit` carrier under `faceshift`, rebind direct `"head"` weights to `<part>_unit`, reparent bound chain roots to `<part>_unit` while keeping chain skinning weights intact, and key `<part>_unit` in `turn_units`, #790), samples each `"unit"` bone's depth from the `"surface"` depth sheet at its rest position (or reads `unitDepths.<part>`, `RIG_TURN_UNIT_DEPTH_REQUIRED`), enforces ear occlusion (`ear_r`/`ear_l` drawn before the `face` surface in `assemble.plan`, `CONFIG_TURN_EAR_DRAW_ORDER`, and behind the cheek surface, `RIG_TURN_EAR_DEPTH_BEHIND_CHEEK`), and writes `turn` and `tilt` `derive` tracks (`pivot` default `55` rig px, `counter` default `0.1` in `[0, 1]`, `CONFIG_TURN_COUNTER_RANGE`). `depths` holds, per part, the See-through layer's `depth_median` the part came from (larger = further back), read from the run the part was assembled from; a `painting:` patch has none and is not carried. A rider (issue #271) — a part from an `eyewhite`, `irides`, `eyelash`, `eyebrow`, `nose` or `mouth` layer — is drafted at the `face` part's depth, 0.001 nearer when parts.json draws it after the face and 0.001 further when before: See-through makes no depth of its own for the eye group (it cuts them from one depth map of the combined eyes) and clamps nose and mouth to the face's median − 0.001, and the two runs' own medians for these layers disagreed by up to 0.47 and swapped their order against the face. Every other layer — ears, headwear and earwear included — keeps its own median, unless it rides another part's bone. With no `face` part, or more than one, the riders keep their own and a note says so. A rider by bone (issue #535) — a part every *ownable* bone of which (a chain link, or a bone no other bone hangs from; `head`, `chest` and any bone with a child are shared and never count on their own) is *hosted* by another carried part, the host of a bone being the carried part that binds it (its region's bone; a mesh's `segments`, `contour` and `auto` regions' bones) with the most `opaque_px`, the earlier in parts.json on a tie, and which hosts no bone itself — is drafted at its host's depth, 0.001 nearer when drawn after the host and 0.001 further when before, and a note names the host, the bones and its own median: a pin, clip or ornament on the back hair's links travels with the back hair, not with its own layer's depth. `propose` reads the proposal's own `bones`, `meshes` and `regions`; the face riders are read by their tag first and never by their bones. A part bound to two hosts' bones rides neither and a note says so. In the rig stage, an authored depth on a rider by bone whose fraction differs from its host's by more than 0.1 of the dial (`TURN_RIDER_APART`, a share of `pivot − nearest`) is refused (`CONFIG_TURN_RIDER_DEPTH`); the host is read off `parts.json`'s `opaque_px`, so the config loader cannot see it. One note lists each part's depth and where it came from; a carrier the other run places more than 10 % of `pivot − nearest` away gets a note naming both values and the run read — the two runs are not reconciled. `pivot` is the depth that stays put; `propose` drafts the mean of the parts' depths weighted by `opaque_px`, the one depth at which the painted pixels' centroid does not slide under the dial. The rig stage adds a bone `turn` under `root` at its origin that nothing keys — its local x is the dial, in rig px — and carries each part by `(pivot − depth) / (pivot − nearest depth)` of it: the nearest part all of it, a part behind the pivot the other way, a part at the pivot not at all. Each part rides leaf twins (`turn_<part>_<bone>`, an identity child of every bone its slot and weights bind) moved by one `transform` constraint (`turn_<part>`, after the config's own); the idle's keys, the `<bone>_ctl` controls and a physics constraint stay on the bones, and the dial moves none of them. Optional `deform` (`Partial<FaceDeformFractions>`, issue #436) overrides the Set B ×2.5 face surface deformation table (`FACE_DEFORM_FRACTIONS`, checked against `FACE_DEFORM_RANGES` by `CONFIG_TURN_DEFORM_RANGE`); when `applyFaceSurfaceDeform` runs on a rig whose `motion` carries `tilt` or `turn` slider `derive` keys, it requires `config.turn` (`CONFIG_TURN_REQUIRED`, issue #478; `propose --full`/`--head` drafts it), promotes `face` on `head` (or `turn_face_head` when `turn` is declared) to the uneven 5×5 grid mesh, keys `face`, `hair_front` and `hair_back` deform timelines and ear/topknot tracks from `evalPitchFaceSurface` and `evalYawFaceSurface`, and samples the same deform field across each `features` member's rest span (`featRx = (24 / 106) · W`, `featRy = (12 / 128) · H`) with its depth fraction `z / zRef` as the field's angle input and chord foreshortening (`scalex` narrowing on the leading side and widening on the trailing side, `scaley` on pitch) so every feature's bounding box stays inside the deformed face plate across the rated band (issue #468). On yaw (`issue #479`), `evalYawFaceSurface` evaluates a **cylinder projection** (`cylinderYawDx`: `Δx(x, θ, R) = R · (sin(clamp(arcsin(clamp(x / R, −1, 1)) − θ, −π/2, π/2)) − clamp(x / R, −1, 1))`) of radius `R` (`turnSurfaceRadius`: `turn.surface.radius ?? turn.radius ?? turn.head.radius`, positive rig px checked by `CONFIG_FIELD_TYPE`, defaulting to half the face plate's opaque width `W / 2`) tapered by a cubic Hermite outline weight (`wOutline = 1` for `\|ux\| <= 0.7`, reaching `0` at `\|ux\| = 1.0`) so features slide across a fixed outline (`iris` shift within `±2%` of `cylinderYawDx`), the trailing cheek strip widens (`>= 1.54×` at `±15°`), and the leading jaw edge holds fixed (`0 px` shift) unless explicit horizontal `turn.deform` overrides (`turn_mid_x`, `turn_lead_compress_x`, `turn_trail_shift_x`) request the flat yaw table. On yaw (`issue #478`), `applyFaceSurfaceDeform` also derives a **head-only pivot** (`headTurnPivot`: `turn.head.pivot` when authored, otherwise the `opaque_px`-weighted mean of `depths[part]` across the head parts `DEFAULT_HEAD_TURN_PARTS` — `face`, `hair_front`, `hair_back`, `ear_r`, `ear_l`, `hairpin` — from `parts.json`, falling back to `turn.pivot`) so a forward torso or arm in `turn.depths` does not pull the head's rotation axis in front of `face`: `hair_back` (`depth_median > headPivot`, negative `headTurnFraction`) and `hairpin` behind `headPivot` translate opposite to the face's turn (`dx = s · turn_face_center_x · W · (headPivot − depth) / (headPivot − nearestHeadDepth)`), emerging on the trailing side to compensate for the leading-cheek foreshortening and keeping the combined head silhouette width near-constant across `±15°` without any same-sign `turn_hair_back_cheek_x` term. Optional `band` (`number` or `{yaw?, pitch?}`, positive degrees, issue #472) declares the rig's rated face turn band (default `FACE_RATED_BAND`: `yaw <= 15°`, `pitch <= 12°`); declaring a `turn.band` or a `motion.animations_from` `turn`/`tilt` `derive.degrees` above `±15°` yaw or `±12°` pitch without an `assemble.alternates` entry that replaces `face` is refused (`CONFIG_FACE_BAND_EXCEEDED`), and on a single-plate rig `applyFaceSurfaceDeform` adds self-targeting transform constraints `yaw_clamp` (`[-15, 15]`) and `pitch_clamp` (`[-12, 12]`) ahead of the slider constraints so driving `yaw` or `pitch` beyond the rated band clamps at the boundary. At rest: with `turn` declared, no pixel differs by more than 1 level at dial 0 (not byte-identical; the cause is float noise in the identity child bones, and the constraints add nothing); without `turn`, byte-identical. Neither `pivot` nor `depths` has a default (`CONFIG_FIELD_PRESENT`); `pivot` and `head.pivot` must lie behind the nearest part (`CONFIG_TURN_PIVOT_BEHIND_NEAREST`). Absent, no control is added and no byte of any output moves |
182
- | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
182
+ | `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite (and the same bytes beside `parts.json` when standalone `assemble` writes it to another directory, issue #1177), and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
183
183
  | `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
184
184
  | `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
185
185
  | `motion_seams` | propose, assemble, check | Optional `[{part, neighbour}]`, using output part names. Each unordered pair is declared once; self-pairs, unknown names, wrong shapes and unknown fields refuse (`CONFIG_MOTION_SEAM`, `PARTS_MOTION_SEAM`, `CHECK_MOTION_SEAM_DECLARATION`). Empty adds no pair. Assemble copies the declaration into `parts.json`; check merges it with existing pairs and never regenerates a removed declaration. It uses the existing non-root WARN floor and changes no bar or exit status. See *Explicit motion seam observations* below. |
@@ -4207,7 +4207,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4207
4207
  | `layers <dir \| layers.json \| file.psd>` | keep the existing columns (`opaque_px` still means alpha >8) and append source-alpha boxes `drawn(a>8)` / `opaque(a>=250)` with exclusive right/bottom; name absent boxes, report the existing body-group union height at **CORE_ALPHA (>=250)** in **input-canvas px**, and show its >8 union separately; no anatomical height, ownership/erosion or painting registration is inferred ([units and rig-scale guidance](AUTHORING.md#4-the-command-order)) |
4208
4208
  | `sheet --source <png> --layers <path>… --out <png>` | a labelled contact sheet of the painting and every layer or part |
4209
4209
  | `assemble --propose-plan … [--write-config <config>]` | propose `assemble.plan` and `extend_below_crop` from the two runs, leaving out an implausible layer with a note naming the rule, naming in a note any full-run body no planned part covers, and naming every layer no row takes with why (empty, taken from the other run only, a plausibility rule; `nose`, never planned, with the row that lets `propose` read the head's pitch). Front/back hair reaching more than 8 rig pixels beyond a side or top edge receives explicit `edges`; each explicit edge has the same strict reach bar. The legacy bottom entry is retained unchanged; qualifying side/top edges receive a separate entry without bottom. With no qualifying side/top edge, the proposal remains unchanged. |
4210
- | `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 |
4210
+ | `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 `run.json` (`spec` `rig-run/1`), and list the uncovered holes |
4211
4211
  | `head-crop-preflight --full <run> --canvas WxH --head-box '[left,top,right,bottom]'` | before the head run: JSON on stdout, one advice line per hit tag on stderr, exit 0 even when clipped. Counts original alpha > 8 full-run samples after centre registration through the square pad into painting coordinates: centres below left/top or at/above right/bottom are outside. Fractional boxes are accepted; corner samples count on both edges. No ghost cleanup, resampling, head run or assemble is needed. These counts cannot be compared with `ASSEMBLE_CROP_CLIPPED`, which counts rig pixels at alpha >= 128 after `cleanGhosts`. Preflight reads original samples before the head run exists, so soft fringes and ghost specks can be hits only here. Bottom is distinct because `extend_below_crop` handles it. Zero-hit tags remain in JSON. Existing pipeline outputs stay unchanged; help adds this command and guide reflects these documentation edits. |
4212
4212
  | `propose --head-box --full <run> --canvas WxH [--no-back-hair] [--write-config <config>]` | propose `seethrough.head_box` from the full run, held inside the painting; `--no-back-hair` leaves the back-hair layer out of that proposal |
4213
4213
  | `propose --parts --source --out [--compare <config>] [--write-config <config> [--only-missing]]` | 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 |
@@ -4216,7 +4216,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
4216
4216
  | `propose … --grid-rule figure\|part` | how each drafted lattice's spacing is chosen: `figure` (the default) one spacing for the figure, round(H / 37) rig px, a part already coarser keeping its own, with a note on its calibration and cost; `part` the reference's rule, a tenth of the part's short side (the oracle examples are proposed under it) |
4217
4217
  | `propose --parts --source --out --from-config <config> [--keypoints <file> [--person <id>]]` | draw and LINT the config's current bones (by the joints too, given `--keypoints`); proposes nothing, so takes only these flags (not `--full`, `--head`, `--cloth`, `--write-config`, `--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`) |
4218
4218
  | `compare --left <file> --right <file> [--map <bonemap.json>]` | compare two skeletons — a config, a proposal or a `rig.json` — bone by bone: origin, parent, tip, length and direction per pair, the bones neither side pairs, the required ones missing, and each side's roles read off the spec; no frame is guessed, and nothing pairs by resemblance (`propose --compare` reads origins only) |
4219
- | `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json`, written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
4219
+ | `rig --config --parts --out [--idle-keys ctl\|direct]` | author `rig.json` + `motion.json` (plus `mesh_report.json` and `run.json`, `spec` `rig-run/1`), written only after rig-c's gate is green; each mesh is in the mode its config entry names — `grid` (the lattice, what `propose` writes), `contour` (the traced outline with declared interior points) or `auto` (the contour mesh at alpha 1 and above, reduced and locally refined by rig-c's `reduceMesh` under the author's declared bounds, written only when its motion against the unreduced source on the idle passes the author's `motion` bounds through rig-c's `compareMeshesInMotion`; [AUTHORING §3](AUTHORING.md)); every chain link is turned along its chain and carries its `length`, so a physics constraint added later has a lever, with every offset under it in the turned frame so nothing moves; `--idle-keys` says whether the idle's keys on mesh-driving bones go through `<bone>_ctl` parents (default) or stay on the bones with `invariants.idleDrivesMeshes` declared; the config's `constraints` go to rigc as written, and a two-bone ik over keyed links needs `--idle-keys direct` (on `rig` or `build`) |
4220
4220
  | `check --rig --out [--parts] [--source] [--requirements]` | build packed, gated under `rig-play`, 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*) |
4221
4221
  | `loop --frames <dir> --out <file.gif \| file.png> [--palette]` | encode a rendered idle as a looping GIF, lossless APNG, or indexed APNG (`--palette`) |
4222
4222
  | `build --config --source --full --head --out [--seam] [--project] [--loop] [--lead-in <periods>] [--requirements] [--seam-pairs] [--keep-stills] [--idle-keys ctl\|direct]` | assemble, rig and check in one process, stopping at the first refusal; `--requirements`, `--seam-pairs` and `--keep-stills` are forwarded to check, `--idle-keys` to rig; `--lead-in` (with `--loop`) encodes the loop from the last of n + 1 idle periods played back to back, for a rig whose physics does not end where the render starts it |
@@ -5312,7 +5312,7 @@ says why each requirement exists and what breaks without it.
5312
5312
  | <a id="PAINTING_HANDS_APART"></a>`PAINTING_HANDS_APART` | under `--form standee`, the line between the two wrists crosses no background: hands clasped or touching (`SKIP` under `--form illustration`) | a painting with the hands apart and open (PAINTING.md, *Hands*) |
5313
5313
  | <a id="PAINTING_LEGS_APART"></a>`PAINTING_LEGS_APART` | under `--form standee`, the line between the knees, or between the ankles, crosses no background: the legs are one column there (a long skirt over the knees is refused here too; `SKIP` under `--form illustration`) | a painting with the legs apart and a visible gap at the knees and the ankles (PAINTING.md, *Legs*) |
5314
5314
 
5315
- ### The optional ComfyUI adapter (`comfy paint`, `comfy seethrough`)
5315
+ ### The optional ComfyUI adapter (`comfy paint`, `comfy seethrough`, `comfy plate`)
5316
5316
 
5317
5317
  `rig-parts comfy seethrough --image <png> --out <dir> --host <url> --config <config.json>`
5318
5318
  reads `seethrough.resolution`, `.steps`, `.seed` and `.offload` through the early
@@ -5336,6 +5336,52 @@ those settings. Changing a config seed alone cannot change a no-config run.
5336
5336
  | <a id="COMFY_PAINTING_SIZE"></a>`COMFY_PAINTING_SIZE` | the painting `comfy paint` got back is not twice the latent (a config with no `generation` block is `CONFIG_FIELD_PRESENT`, §6 *The config*) | `config.generation` |
5337
5337
  | <a id="CONFIG_POSE_CANVAS"></a><a id="CONFIG_POSE_KEYPOINTS"></a><a id="CONFIG_POSE_IN_CANVAS"></a>`CONFIG_POSE_CANVAS`, `CONFIG_POSE_KEYPOINTS`, `CONFIG_POSE_IN_CANVAS` | the pose file `generation.control.skeleton` names states another canvas than `generation.latent`, holds other than the 18 body-18 keypoints, or puts one off its canvas | the pose file (§3, the `generation.control.skeleton` row) |
5338
5338
 
5339
+
5340
+ #### Step-4 plates (`comfy plate`, issue #1183)
5341
+
5342
+ `rig-parts comfy plate --mode background|foreground --painting <png>
5343
+ --mask-from seethrough:<dir>|figure-mask:<dir> --out <dir>` makes the two plates
5344
+ a full-screen scene needs: the background with the figure removed, and a
5345
+ foreground matte with alpha. Only these two. It never makes a character part
5346
+ or a joint.
5347
+
5348
+ - **The mask comes from a source.** `seethrough:<dir>` is a See-through run in
5349
+ the wrapper form, and the figure is every drawn layer's alpha above 8 on the
5350
+ run's canvas. `figure-mask:<dir>` is an assemble output whose `parts.json`
5351
+ declares a `scene`, and the figure is its `figure_rig.png`. The mask is never
5352
+ fitted: a source grid that is not the painting's size is refused. With no
5353
+ source the command refuses by name, writes nothing and reaches no box.
5354
+ - **background** grows the mask by `--grow` px (a square, default 8) and
5355
+ inpaints it on a ComfyUI box. `--graph lama` (the default) uses the
5356
+ comfyui-inpaint-nodes pack and its LaMa model (`--model`, default
5357
+ `big-lama.pt`). `--graph core` uses ComfyUI's own nodes and the checkpoint
5358
+ `--model` names, with `--steps`, `--prompt` and `--negative`; it needs a
5359
+ painting whose sides are multiples of 8. Every node, input and model of the
5360
+ graph is checked against the box's `/object_info` before anything is
5361
+ uploaded, so a box without the pack refuses `lama` and still runs `core`. The
5362
+ job is appended behind any other job: never put in front, nothing reordered,
5363
+ nothing cancelled. A job still pending after `--wait` seconds is refused with
5364
+ its place in the queue and left there. The box's image is pasted into the
5365
+ painting inside the mask only, so every pixel outside it is the painting's,
5366
+ byte for byte. `--checkpoint-sha256` (64 hex characters) is required: the box
5367
+ does not report a hash, so the receipt records the value **as declared, not
5368
+ measured**.
5369
+ - **foreground** runs no box and no model. The plate is the painting's pixels
5370
+ inside the mask, transparent zero outside.
5371
+
5372
+ `<out>` holds `plate.png`, `mask.png` (the mask actually used: opaque white
5373
+ inside, opaque black outside) and `receipt.json`, spec
5374
+ `rig-parts-plate-receipt/1` ([STABILITY](STABILITY.md#plate-receipt)). A receipted
5375
+ plate pass from this command is a recorded source step, not a repair.
5376
+
5377
+ | rule | means | change |
5378
+ | --- | --- | --- |
5379
+ | <a id="PLATE_MASK_SOURCE"></a><a id="PLATE_MASK_GRID"></a><a id="PLATE_MASK_VALUES"></a><a id="PLATE_MASK_EMPTY"></a>`PLATE_MASK_SOURCE`, `PLATE_MASK_GRID`, `PLATE_MASK_VALUES`, `PLATE_MASK_EMPTY` | no `--mask-from`, or a source directory holding no See-through run or no scene figure mask; a source on another grid than the painting; a `figure_rig.png` holding other than opaque white and black; a mask with no figure pixel | run `comfy seethrough` on the painting, or `assemble` with `config.scene`, at the painting's own size |
5380
+ | <a id="PLATE_CHECKPOINT_SHA256"></a><a id="PLATE_MODEL_GIVEN"></a><a id="PLATE_CORE_GRID"></a>`PLATE_CHECKPOINT_SHA256`, `PLATE_MODEL_GIVEN`, `PLATE_CORE_GRID` | `--checkpoint-sha256` absent or not 64 hex characters; `--graph core` without `--model`; a painting off the multiple-of-8 grid under `--graph core` | the flag, or `--graph lama` |
5381
+ | <a id="PLATE_PAINTING_PRESENT"></a><a id="PLATE_OUT_EMPTY"></a>`PLATE_PAINTING_PRESENT`, `PLATE_OUT_EMPTY` | no `--painting` file, or an `--out` that already holds entries | `--painting`, `--out` |
5382
+ | <a id="COMFY_QUEUE_BEHIND"></a><a id="COMFY_GPU_NAMED"></a><a id="COMFY_PLATE_SIZE"></a>`COMFY_QUEUE_BEHIND`, `COMFY_GPU_NAMED`, `COMFY_PLATE_SIZE` | the job was still pending after `--wait` (its queue place is named; it is left on the box); `/system_stats` does not name exactly one device; the box's image is not the painting's size | `--wait`, or the box |
5383
+ | <a id="PLATE_RECEIPT_READ"></a><a id="PLATE_RECEIPT_SPEC"></a><a id="PLATE_RECEIPT_KEYS"></a><a id="PLATE_RECEIPT_FILE"></a><a id="PLATE_RECEIPT_HASH"></a>`PLATE_RECEIPT_READ`, `PLATE_RECEIPT_SPEC`, `PLATE_RECEIPT_KEYS`, `PLATE_RECEIPT_FILE`, `PLATE_RECEIPT_HASH` | the receipt read back before it is published is not JSON, not this spec, not in its key order, names a file that is gone, or records a sha256 that is not the file's | nothing to change by hand: the run is refused and `<out>` is not written |
5384
+
5339
5385
  ### assemble
5340
5386
 
5341
5387
  | rule | means | change |
@@ -6770,7 +6816,8 @@ What is composed:
6770
6816
  the px its own `build` measured.
6771
6817
  - **`scene.json`** (`spine-parts-scene-report/1`): the scene file's path as given,
6772
6818
  the canvas, the rig's name (the ids joined by `+`), the pack flags, the plate (its
6773
- image, provenance, note, bone, slot, size, `judged_by: "nothing"`), per character
6819
+ image, provenance, note, bone, slot, size, `sha256` of the PNG's bytes as compose read them — issue #1183, additive —
6820
+ and `judged_by: "nothing"`), per character
6774
6821
  its build, offset, `scale` (only when it is not 1), `rig_size`, `rig_scale`, placed bounds (the union of its part
6775
6822
  boxes, canvas px), shift and what it moved (`shifted`: the first-level bones, the
6776
6823
  regions on `root`, the count of weights bound to `root`), its counts and `accepted`
@@ -8099,6 +8146,7 @@ they do not certify a new toolchain, input or packaging build. No tuning to meet
8099
8146
  | <a id="CONFIG_WAIST_NAME_FREE"></a>`CONFIG_WAIST_NAME_FREE` | The generated bone name already exists; declare an unused name | declare an unused name |
8100
8147
  | <a id="RIG_WAIST_DECLARATION"></a>`RIG_WAIST_DECLARATION` | Actual provenance, pair bindings or drawing ownership do not match the bounded declaration; supply the declared base two-bone mesh/rigid-region pair | supply the declared base pair |
8101
8148
  | <a id="RIG_WAIST_MOTION"></a>`RIG_WAIST_MOTION` | Imported tracks drive the generated waist frame; retain their original authored targets | retain the original authored targets |
8149
+ | <a id="RUN_STAMP_PACKAGE"></a>`RUN_STAMP_PACKAGE` | `package.json` is missing, malformed or lacks a non-empty string `name` or `version` needed for `run.json` (`spec` `rig-run/1`) | restore valid `name` and `version` strings in `package.json` |
8102
8150
 
8103
8151
  ### Depth-driven rigging
8104
8152
 
package/docs/PAINTING.md CHANGED
@@ -407,6 +407,8 @@ To paint one without the character drifting, repaint only the limb:
407
407
  hand); the rest of that run is discarded. The base rig's other parts stay the
408
408
  base painting's.
409
409
 
410
- `comfy paint` does not run an inpainting graph; the demo's hand-detailer pass is
411
- the same idea at hand scale (a masked repaint on the same checkpoint, recorded
412
- beside its painting in rig-c/examples).
410
+ `comfy paint` does not run an inpainting graph, and neither does `comfy plate`
411
+ for this step: `comfy plate` inpaints only a step-4 background plate (the figure
412
+ removed) over a source mask, never a limb or a part. The demo's hand-detailer
413
+ pass is the same idea at hand scale (a masked repaint on the same checkpoint,
414
+ recorded beside its painting in rig-c/examples).
package/docs/STABILITY.md CHANGED
@@ -213,6 +213,7 @@ defaults are the help's too, and none is guessed from the art.
213
213
  | `sheet` | `--source`, `--layers` (repeatable), `--out`; optional `--cell`, `--cols` |
214
214
  | `inputs` | `--source`, `--config`, `--out` |
215
215
  | `comfy` | `paint`: `--config`, `--out`; optional `--seeds`, `--seed0`, `--host`, `--wait`, `--timeout`, `--poll` |
216
+ | `comfy` | `plate`: `--mode` (`background` or `foreground`), `--painting`, `--mask-from` (`seethrough:<dir>` or `figure-mask:<dir>`), `--out`; with `--mode background` also `--checkpoint-sha256` (required) and optional `--graph` (`lama` or `core`), `--model` (required with `core`), `--seed`, `--grow`, `--steps`, `--prompt`, `--negative` (the last three with `core` only), `--host`, `--wait`, `--timeout`, `--poll` (issue #1183, additive) |
216
217
  | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--no-offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll`, `--config` (See-through settings and optional depth block), `--depth-run` (`full` or `head`, required with the block) |
217
218
  | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`, `--write-config` (must name `--config` itself, issue #356); or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible), `--alt` (repeatable `<name>=<source>:<full>[:<head>]`, issue #454), `--requirements` (source-bound cut-material evidence only when the file declares `cut_material`, issue #888) |
218
219
  | `head-crop-preflight` | `--full`, `--canvas`, `--head-box` (JSON coordinate array); read-only advice before the head run, original alpha > 8 samples (issue #1082) |
@@ -295,8 +296,9 @@ rules that make the contract:
295
296
  - **`scene`** (issue #242) declares the painting a scene — the figure and what
296
297
  is round it — and takes no field: `{}`. With it `assemble` reads the
297
298
  recomposite inside the figure (the union of the full run's layers at alpha
298
- above 8), writes the figure as `figure_rig.png` beside the recomposite and a
299
- `scene` block in `parts.json`, and `check` leaves the painting's border rows
299
+ above 8), writes the figure as `figure_rig.png` beside the recomposite (and,
300
+ when standalone `assemble` puts `parts.json` in another directory, beside
301
+ `parts.json` too, issue #1177) and a `scene` block in `parts.json`, and `check` leaves the painting's border rows
300
302
  and columns out of the seam. Without the field no byte of any output moves.
301
303
 
302
304
  The fields, object by object (a bold path is where the object sits; `<part>` is a
@@ -431,6 +433,28 @@ Empty readings remain explicit.
431
433
  The report measures direct cover before projection and downstream processing.
432
434
  The field semantics are documented in AUTHORING's source projection cover entry.
433
435
 
436
+ ### Plate receipt
437
+
438
+ `comfy plate` (issue #1183) writes `receipt.json` beside `plate.png` and
439
+ `mask.png`, spec `rig-parts-plate-receipt/1`. Its keys, their order and their
440
+ meaning do not change within the spec; a key added, removed or redefined is a
441
+ new spec version. Every path in it is relative to the receipt's directory.
442
+
443
+ | key | meaning |
444
+ | --- | --- |
445
+ | `spec` | `"rig-parts-plate-receipt/1"` |
446
+ | `mode` | `"background"` or `"foreground"` |
447
+ | `painting` | `{ path, sha256 }` of the painting read |
448
+ | `mask` | `{ source, from, path, sha256 }`: `source` is `"seethrough"` or `"figure-mask"`, `from` the source directory, `path` the mask actually used (`mask.png`, opaque white inside) |
449
+ | `model` | `{ name, checkpoint_sha256, checkpoint_sha256_from }`, or null for `foreground`. `checkpoint_sha256` is the `--checkpoint-sha256` value, lower-cased; `checkpoint_sha256_from` is `"declared"`: the box reports no hash, so this field is **declared, not measured** |
450
+ | `params` | every parameter of the run, the seed included, in a fixed order per graph: `lama` — `seed`, `grow_px`, `mask_alpha_above`; `core` — `seed`, `grow_px`, `steps`, `cfg`, `sampler`, `scheduler`, `denoise`, `prompt`, `negative`, `mask_alpha_above`; `foreground` — `mask_alpha_above` |
451
+ | `graph` | `"rig-parts/plate-background-lama/1"`, `"rig-parts/plate-background-core/1"`, or the fixed local id `"rig-parts/plate-foreground/1"` |
452
+ | `gpu` | the device `/system_stats` names (the same seed gives other pixels on another GPU), or null for `foreground` |
453
+ | `output` | `{ path, sha256 }` of `plate.png` |
454
+
455
+ The receipt is read back against the bytes on disk before `<out>` is published;
456
+ a hash that is not its file's refuses the run.
457
+
434
458
  ### Head-crop preflight stdout
435
459
 
436
460
  `head-crop-preflight` writes one JSON object followed by a newline on success,
@@ -472,7 +496,7 @@ resolution before resizing; it can differ for non-opaque paintings.
472
496
  | file | written by | what is stable |
473
497
  | --- | --- | --- |
474
498
  | `stage-map.json` | `assemble`, `build`, under `assemble.stage_map: true` | `rig-parts-stage-map/1`, cropped last-writer and pre-seam RLE maps with writer dictionaries and excluded counts. See [Per-pixel stage map](AUTHORING.md#per-pixel-stage-map). |
475
- | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
499
+ | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), `excluded_px` after them only on a subset set's limb part whose cap the set exclusion took a pixel of (issue #603, additive: each pixel taken out of the count it was in, so the cap's counts are the written PNG's), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px` — on a subset set's limb part counted after the set exclusion, issue #603 — `seam_override_px`, and `fringe_pushed_back` when not empty); per-part `provenance` (`unchanged_layer_px`, `hand_px`, `automatic_px`, `edits`, `automatic`, additive, issue #823); optional top-level `motion_seams`, `alternates` and `cut_ownership` (one row per cut, independent of RGBA equality, issue #823); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242), and the same bytes beside `parts.json` when the two directories differ (issue #1177); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
476
500
  | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
477
501
  | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); or `mode` "explicit" with `image_sha256` and `region_sha256` (the verified guards; counts and coverage are measured from the supplied mesh, no legacy generator report is adopted); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
478
502
  | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493 retains existing pair warnings; issue #686 gates GAP on proven body-root pairs only (gap-only; mixed ghost remains INFO until rig-c/core#1555 supplies owners): `status` — `WARN`, `CLEAR`, `SKIP` or `FAIL` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, optional `root` (`limb`, `bone`, `parent`) on a proven body-root pair, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`, and only on new-root rows stock `gapOpen` plus UNDER-owned `ghostA`/`ghostB` cells selected by resolved per-frame draw order gate their summed count against the unchanged strict one-cell floor on the original raw kind boxes (their union when both kinds contribute), never narrowed partition boxes, while `gapCovered` and OVER-owned ghost cells are excluded (issue #711); `cells` retains partition counts, UNDER owner and counted total, `worst` retains frame/count/cell/box, and `roots` retains status, mode `gap-open+under-ghost`, ghost_owner `resolved-draw-order`, pairs, failed, reason and optional unmeasured bindings; eligible candidates whose valid setup bands are all zero retain a named unmeasured root and SKIP bar, including when no pair is selected; measured root FAIL wins over SKIP, while measured PASS plus an unmeasured root remains SKIP; every eligible body drawing with stock setup `banded > 0` is selected, including both when a parent is shared; issue #708 resolves a body slot on its exact generated turn child to the same named carrier only after unique identity-bone/control/per-part-transform proof, without changing pair identity, setup selection or the direct-carrier path; setup-only observation preserves the authored motion and default drawing, root-free inputs add no setup compile/render, and no animation remains SKIP rather than a measured zero; existing internal pair warnings and their exits are unchanged; issue #941 adds optional `required` only under the requirements file's `seam_over_motion.required: true` — `status` (`PASS` or `FAIL`), `mode` `gap-open`, `bar_px` 0, `pairs` (each `pair`, `class` — `body-root`, `internal-joint` or `explicit` — `frames`, `background_frames`, `max_px`) and `failed` — and with it the key is written even when no pair is declared; issue #591 adds optional `worlds` on physics rigs with readable declared pairs and animations: `default` and `still`, each `wind`, `gravity`, `status` (`REPORTED` or `SKIP`), `reason` on SKIP, `dir` only when rendered (relative to check.json: `seam_motion/default` or `seam_motion/still`, the complete retained render with frames.json and each animation's raw seam.json), and `rows` — pair, animation, status, drawn, banded, `gap` and `ghost`, each `max_px` and `worst` only; worst carries `index`, `px`, `cell`, `box`. Per-frame hits stay in the raw sidecars. These raw reference readings add no bar or warning and leave the custom environment reading unchanged), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `WIND_BAND` after it under `--wind-band` only (issue #590, additive: `status` `"REPORTED"`, `spec` `"rig-parts-wind-band/1"`, `path` as given, `sha256`, `steady_wind_only` `true`, `gravity` `[0, 1]`, `min`, `max`, `step`, `steps`, `fps`, `animations`, `max_gap`, `max_ghost`, `holds_from`, `holds_to`, `pairs_holding_all`, and `pairs` — each `pair`, `a`, `b`, `holds_all`, `holds_from`, `holds_to`, `first_break_below`, `first_break_above`, `worst_gap`, `worst_ghost`, `steps`), `skipped`, `config` under `build` only (issue #607, additive: `path` as `--config` was typed, `sha256` of the bytes the build read; `check` and `compose` read no config and write none), a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes. Missing stock partitions or resolved owner are named refusals, never zero. No whole-box exemption or consumer compositor remains; internal warnings and reference raw readings are unchanged. |
@@ -487,8 +511,9 @@ resolution before resizing; it can differ for non-opaque paintings.
487
511
  | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `remesh.json` | `remesh` | the input revision's files, `rig.json` and `mesh_report.json` with the part's attachment and row replaced (under `--delta` the row is the input's with its counts, `bones` and influences recomputed and `mode` "delta"), every other file byte for byte; `remesh.json` is spec `rig-parts-remesh/1`: `request` (`part`, `mesh`, `mesh_sha256`, `idle_keys`, `page_edges`, `pack_shape`; under `--delta`, issue #526: `part`, `delta` — the mesh edit as read — `delta_sha256`, `ops`, `applied` — `moved`, `added`, `removed`, `constrained` — `idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `baseline` (`reproduced`, `not_compared`; under `--delta` `reproduced` holds one sentence: no config is built, the input is the baseline), `target` (`before`, `after`: `vertices`, `triangles`, `hull`), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-remesh/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |
488
512
  | `rig.json`, `motion.json`, `mesh_report.json`, `images/`, `retune.json` | `retune` | the input revision's files, `rig.json` with `constraints` and `invariants.detached` replaced and `motion.json` with `animations.idle` replaced by the config's build, every other file byte for byte; `retune.json` is spec `rig-parts-retune/1`: `request` (`idle_keys`, `page_edges`, `pack_shape`), `versions` (`parts`, `rigc`), `input` (`rig` — `path`, `bytes`, `sha256` per file — `config_sha256`, `parts_json_sha256`), `held` (`compared`, `not_compared`), `changed` (`constraints` — each `name`, `type`, `fields` — `added`, `removed`, `idle`: `tracks_changed`, `duration` as before and after), `preserved` (`identical`, `spliced`), `revision` (per file as `input.rig`), `check` (`input`, `revision`: `pass`, `measured`, `not_met`, `skipped`, `physics`, then `line` and `status` — issue #541, additive, the spec stays `rig-parts-retune/1`: `line` is the last line `check` prints on that tree, byte for byte, and `status` every block's status as that tree's `check.json` records it, by name in the file's order — `gate`, `loop` and `seam` read from their figures, every other block its own `status`, a block the file does not write absent; `scope`) |
489
513
  | `input-check.json` | `remesh --record-input-check`, `retune --record-input-check` | spec `rig-parts-input-check/1` (issue #617, additive): `versions` (`parts`, `rigc` — `rigc --version`'s whole output), `options` (`page_edges`, `pack_shape`, `requirements` — null, or `path` as resolved and `sha256`), `rig` and `parts` (`dir` as resolved, `files` — `path`, `bytes`, `sha256` per file: every file under `--rig`; `parts.json` and every file under `parts/`), `check` (the input's check side as `remesh.json` carries it); `--input-check` reads it back, and either command's serves the other |
490
- | the scene report | `compose` | spec `spine-parts-scene-report/1` |
514
+ | the scene report | `compose` | spec `spine-parts-scene-report/1`; the plate block carries `sha256` of the plate PNG's bytes after `size` (issue #1183, additive under *What "stable" means here*: a new report key in a minor version, so the spec stays `/1`) |
491
515
  | `idle.png`, `idle-indexed.png`, `idle.gif` | `loop`, `build --loop` | APNG and GIF encodings of the rendered idle |
516
+ | `run.json` | `rig`, `assemble` | spec `rig-run/1` (issue #1165, additive): `spec`, `package` (`name`, `version`), `command` (`"rig"` or `"assemble"`), `started_at` and `finished_at` (UTC ISO-8601 millisecond timestamps ending in `Z`, read in the CLI layer), `config` (`path` relative to `--out`, `sha256` of the config file on disk), and `outputs` (`path` relative to `--out`, `sha256` of each written output file on disk, sorted by `path` in code-unit order and excluding `run.json` itself); written only after the command's gate is green |
492
517
 
493
518
  Issue #705 pins setup-seam acceptance to one source-relative scale1 union U of the authored stage and all actual drawn base/checked-set still vertices. U is snapped relative to the source origin, including odd-width half phase.
494
519
  The existing seam fields and pair pictures use that grid; source/blink and
@@ -552,6 +577,49 @@ Files authors write for this package, each with a spec id the reader holds:
552
577
  name on purpose: they name a file format, not the tool, and a file written before
553
578
  the rename still reads. They do not change at 1.0.
554
579
 
580
+ ### Run stamp (`run.json`, spec `rig-run/1`)
581
+
582
+ The CLI commands `rig` and `assemble` (when writing `--out`) write `<out>/run.json`
583
+ after all stage gates pass and all other output files are on disk:
584
+
585
+ ```json
586
+ {
587
+ "spec": "rig-run/1",
588
+ "package": { "name": "@rig-c/parts", "version": "<package.json version>" },
589
+ "command": "rig",
590
+ "started_at": "2026-11-07T00:00:00.000Z",
591
+ "finished_at": "2026-11-07T00:00:01.000Z",
592
+ "config": { "path": "../config.json", "sha256": "<hex>" },
593
+ "outputs": [
594
+ { "path": "images/cloth.png", "sha256": "<hex>" },
595
+ { "path": "mesh_report.json", "sha256": "<hex>" },
596
+ { "path": "motion.json", "sha256": "<hex>" },
597
+ { "path": "rig.json", "sha256": "<hex>" }
598
+ ]
599
+ }
600
+ ```
601
+
602
+ Key order is fixed as shown; `outputs` is sorted by `/`-separated `path` in UTF-16
603
+ code-unit order. Every `path` in `config` and `outputs` is relative to the `--out`
604
+ directory (`../`-prefixed when `--config` sits outside `--out`; never an absolute or
605
+ home path). Every `sha256` is computed from the bytes on disk after writing. A refused
606
+ run writes no `run.json`. Because `started_at` and `finished_at` record wall-clock
607
+ time read in `cli.ts` (`src/` remains pure), `run.json` is outside the byte-for-byte
608
+ determinism comparisons (`RG03`, `RG19`, `AS07`); for the same input at the same
609
+ relative `--config` layout, two `run.json` files differ only in `started_at` and
610
+ `finished_at`.
611
+
612
+ `outputs` lists exactly the files the stage wrote in this run, derived from what the
613
+ stage returns, not from a walk of `--out`: a stray or earlier file under `--out` is
614
+ neither hashed nor listed. Before the stage starts, the command removes an earlier
615
+ `<out>/run.json`, so a run the stage refuses, into a reused `--out`, leaves no stamp
616
+ (a usage error, exit 2, stops before that and touches nothing under `--out`). A
617
+ `package.json` without a non-empty `name` and `version` refuses `RUN_STAMP_PACKAGE`
618
+ and writes no stamp. `build` and the in-process stages write no `run.json`.
619
+
620
+ `rig-run/1` is stable: its keys, their order and their meaning do not change within
621
+ the spec. A key added, removed or redefined is a new spec version.
622
+
555
623
  ## Environment
556
624
 
557
625
  The installed package reads two environment variables and no other: `PATH`, where
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.26.0",
3
+ "version": "2.27.0",
4
4
  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/assemble.ts CHANGED
@@ -117,7 +117,7 @@ import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth,
117
117
  */
118
118
  import { sourceLimbTarget, nearestTargetPart } from './limbownership.ts';
119
119
  import { type ArmSplit, type BoneEntry, type CharacterConfig, type ConfigConstraint, type ControlSkeleton, controlSkeletonOf, type CropEdge, type Cut, type EarlyConfig, type Extend, type Limb, type MeshSpec, type Patch, type PlanEntry, type RegionSpec, type Run, type SeeThrough, turnMovingPartPair, type TurnSpec } from './config.ts';
120
- import { PartsError, type Problem, refuseIfAny } from './errors.ts';
120
+ import { foldName, PartsError, type Problem, refuseIfAny } from './errors.ts';
121
121
  import { CORE_ALPHA, figuresPhrase, implausibleRules, type Layer, type LayerFigures, layerFigures, type LayerSet, NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE, ruleSummary } from './layers.ts';
122
122
  import { padToSquare, squarePad } from './inputs.ts';
123
123
  import type { MotionSeamDeclaration } from './motionseams.ts';
@@ -6049,8 +6049,8 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6049
6049
  });
6050
6050
  refuseIfAny(empty);
6051
6051
  const placed: PlacedPart[] = order.map((d) => ('plan' in d ? planned[d.plan] : 'cut' in d ? cutPlaced[d.cut] : 'limb' in d ? limbPlaced[d.limb] : cut[d.patch]) as PlacedPart);
6052
- const artFiles = new Map<string, string>(); for (const p of placed) { const k = `${p.record.name}.png`.toLowerCase(), prev = artFiles.get(k); if (prev !== undefined) refuseIfAny([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: `${p.record.name}.png`, detail: `part "${prev}" ("${prev}.png") and part "${p.record.name}" ("${p.record.name}.png") collides with a part artwork filename; choose noncolliding part names before sheet emission` }]); artFiles.set(k, p.record.name); }
6053
- for (const p of placed) if (p.record.depth !== undefined && artFiles.has(p.record.depth.image.toLowerCase())) refuseIfAny([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: p.record.depth.image, detail: `part "${p.record.name}" sheet "${p.record.depth.image}" and part "${artFiles.get(p.record.depth.image.toLowerCase())}" ("${artFiles.get(p.record.depth.image.toLowerCase())}.png") collides with a part artwork filename; choose noncolliding part names before sheet emission` }]);
6052
+ const artFiles = new Map<string, string>(); for (const p of placed) { const k = foldName(`${p.record.name}.png`), prev = artFiles.get(k); if (prev !== undefined) refuseIfAny([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: `${p.record.name}.png`, detail: `part "${prev}" ("${prev}.png") and part "${p.record.name}" ("${p.record.name}.png") collides with a part artwork filename; choose noncolliding part names before sheet emission` }]); artFiles.set(k, p.record.name); }
6053
+ for (const p of placed) if (p.record.depth !== undefined && artFiles.has(foldName(p.record.depth.image))) refuseIfAny([{ code: 'DEPTH_SHEET_UNAMBIGUOUS', object: p.record.depth.image, detail: `part "${p.record.name}" sheet "${p.record.depth.image}" and part "${artFiles.get(foldName(p.record.depth.image))}" ("${artFiles.get(foldName(p.record.depth.image))}.png") collides with a part artwork filename; choose noncolliding part names before sheet emission` }]);
6054
6054
 
6055
6055
 
6056
6056
  const regionSupport = new Map<string, Mask>();
@@ -21,13 +21,13 @@ import { checkRow, checkSlotRow, checkSlotParts } from './checkrow.ts';
21
21
  * derived from the art: no declaration, no measurement (SKIP, never a pass).
22
22
  */
23
23
  import { existsSync, readFileSync } from 'node:fs';
24
- import { join } from 'node:path';
24
+ import { basename, join } from 'node:path';
25
25
  import { Plate } from '@rig-c/core/plate';
26
26
  import type { Frame, Piece } from '@rig-c/core/render-shared';
27
27
  import { seamSourceAttachment } from './check.ts';
28
28
  import { cropToSpineY } from './coords.ts';
29
29
  import type { Problem } from './errors.ts';
30
- import type { PartsFile } from './parts.ts';
30
+ import { partImageReference, type PartsFile } from './parts.ts';
31
31
  import { readPng } from './raster/png.ts';
32
32
 
33
33
  export const BOUNDARY_COLOUR_LINE = 'BOUNDARY_COLOUR_STEP';
@@ -140,7 +140,7 @@ export function measureBoundaryColour(api: Api, input: BoundaryColourInput, decl
140
140
  if (got === undefined) {
141
141
  const name = image.replace(/\.png$/, '');
142
142
  const rec = records.get(name);
143
- const partPng = join(input.partsDir, `${name}.png`), rigPng = join(input.imagesDir, image);
143
+ const partPng = rec === undefined ? '' : join(input.partsDir, basename(partImageReference(rec).path)), rigPng = join(input.imagesDir, image);
144
144
  if (rec === undefined) got = `parts.json holds no record "${name}" for the image "${image}"`;
145
145
  else if (!existsSync(partPng) || !existsSync(rigPng)) got = `${existsSync(partPng) ? `the rig image "${image}"` : `the parts image "${name}.png"`} is absent`;
146
146
  else {