spine-parts 2.25.1 → 2.26.1
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 +27 -1
- package/docs/AUTHORING.md +26 -1
- package/docs/STABILITY.md +104 -3
- package/package.json +1 -1
- package/src/build.ts +8 -2
- package/src/partscheck.ts +421 -0
package/cli.ts
CHANGED
|
@@ -16,7 +16,7 @@ import { applyDepth, prepareDepth } from './src/depthworkflow.ts';
|
|
|
16
16
|
*/
|
|
17
17
|
import { spawnSync } from 'node:child_process';
|
|
18
18
|
import { runBuildProcess, processRigcRunner as rigcRunner } from './tools/build-process.ts';
|
|
19
|
-
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
|
|
19
|
+
import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs';
|
|
20
20
|
import { tmpdir } from 'node:os';
|
|
21
21
|
import { basename, dirname, extname, join, resolve } from 'node:path';
|
|
22
22
|
import { DEFAULT_PROJECT_RULE, DEFAULT_SEAM_RULE, headGarmentOverlaps, headGarmentWarning, HOLES_LISTED, PROJECT_RULES, type ProjectRule, proposeFields, proposePlan, proposeSinglePlan, SEAM_RULES, type SeamRule } from './src/assemble.ts';
|
|
@@ -35,6 +35,7 @@ import { makeInputs } from './src/inputs.ts';
|
|
|
35
35
|
import { idleKeysOf, isIdleKeys } from './src/rig.ts';
|
|
36
36
|
import { bodyCoreBox, bodyOpaqueBox, CORE_ALPHA, depthSkipLine, exportLayers, figuresPhrase, hiddenLayerLine, implausibleRules, layerCoreBox, layerFigures, layerOpaqueBox, type LayerSet, layerSetDiff, type OpaqueBox, OPAQUE_ALPHA_ABOVE, pct, readLayers, readWrapperLayers, ruleSummary, templateLayerNames, templatePsdBytes, times } from './src/layers.ts';
|
|
37
37
|
import { checkImageSize, choosePerson, KEYPOINTS_SPEC, loadKeypoints, type RigJoints, toRigJoints } from './src/keypoints.ts';
|
|
38
|
+
import { checkPartsStage } from './src/partscheck.ts';
|
|
38
39
|
import { basisLines, branchSqueezeLine, checkProposal, compare, compareLines, DEFAULT_GRID_RULE, draftTurn, drawLandmarks, FIGURE_GRID_DIVISOR, FRINGE_STEP_PX, GRID_RULES, type GridRule, type BustDraft, HIP_MIN_FRACTION, type DraftLintFinding, lint, lintLine, type PartSet, PROPOSAL_CONFIG_SECTIONS, proposalAsConfig, proposeWithBasis, readBustLandmarks, readPartSet, serializeProposal, withTurn, WRIST_ON_PART_PX } from './src/propose.ts';
|
|
39
40
|
import { BASIS_FILE, BASIS_SPEC, basisFile, basisLine, coverageLines, legChainChoice, serializeBasis } from './src/diagnostics.ts';
|
|
40
41
|
import { BEND_DEGREES, BEND_WORST_SHARE, DUST_MAX_PX, DUST_MAX_SHARE, IDLE_BOUND_PX, MESH_DRAFT_REPORT, MESH_DRAFT_SPEC, meshDraftStage, MORE_TRIANGLES_FLAG, relativeConfigPaths, TOLERANCE_FIGURE_DIVISOR } from './src/meshdraft.ts';
|
|
@@ -565,6 +566,12 @@ usage:
|
|
|
565
566
|
same input), refused as RETUNE_INPUT_CHECK_BOUND,
|
|
566
567
|
RETUNE_INPUT_CHECK_FILE and RETUNE_INPUT_CHECK_MOVED.
|
|
567
568
|
|
|
569
|
+
rig-parts check-parts --parts <dir> --out <dir> [--json]
|
|
570
|
+
Read assemble outputs, bind their bytes and write parts-check.json.
|
|
571
|
+
--out is disjoint from --parts. No rig or renderer is required.
|
|
572
|
+
Exit 0 records input integrity; all six unmeasured quality classes print HOLE.
|
|
573
|
+
--json prints the completed report only, with the recorded exit code.
|
|
574
|
+
|
|
568
575
|
rig-parts check --rig <dir> --out <dir> [--parts <dir>] [--source <painting.png>] [--no-extremes]
|
|
569
576
|
[--page-edges pot|free] [--pack-shape rect|polygon]
|
|
570
577
|
[--requirements <file.json>] [--seam-pairs] [--keep-stills]
|
|
@@ -1126,6 +1133,7 @@ function printLayerTable(set: LayerSet): void {
|
|
|
1126
1133
|
* no row; `layers` takes one positional path beside its flags (issue #359).
|
|
1127
1134
|
*/
|
|
1128
1135
|
const TAKES = {
|
|
1136
|
+
'check-parts': { valued: ['--parts', '--out'], switches: ['--json'] },
|
|
1129
1137
|
'diff-components': { valued: ['--stack', '--painting', '--parts', '--figure', '--floor', '--threshold', '--out', '--verify'], switches: [] },
|
|
1130
1138
|
'depth-prepare': { valued: ['--parts', '--config', '--out'], switches: [] },
|
|
1131
1139
|
'depth-apply': { valued: ['--parts', '--manifest', '--config', '--rig-config', '--out'], switches: [] },
|
|
@@ -1376,6 +1384,23 @@ function flags(args: string[], command: Command, required: readonly string[]): M
|
|
|
1376
1384
|
return got;
|
|
1377
1385
|
}
|
|
1378
1386
|
|
|
1387
|
+
function cmdCheckParts(args: string[]): number {
|
|
1388
|
+
const json = args.filter(arg => arg === '--json').length;
|
|
1389
|
+
if (json > 1) return usage('--json is given twice');
|
|
1390
|
+
const values = flags(args.filter(arg => arg !== '--json'), 'check-parts', ['--parts', '--out']);
|
|
1391
|
+
if (typeof values === 'string') return usage(values);
|
|
1392
|
+
try {
|
|
1393
|
+
const input = values.get('--parts') as string;
|
|
1394
|
+
const parts = existsSync(input) ? realpathSync(input) : input;
|
|
1395
|
+
const report = checkPartsStage(parts, values.get('--out') as string, json === 1 ? () => {} : console.log);
|
|
1396
|
+
if (json === 1) process.stdout.write(JSON.stringify(report, null, 2) + '\n');
|
|
1397
|
+
return report.exit_code;
|
|
1398
|
+
} catch (error) {
|
|
1399
|
+
if (error instanceof PartsError) return printRefusal(error);
|
|
1400
|
+
return printRefusal(new PartsError([{ code: 'PARTS_CHECK_INTERNAL', object: 'check-parts', detail: 'unexpected internal exception; no report was published' }]));
|
|
1401
|
+
}
|
|
1402
|
+
}
|
|
1403
|
+
|
|
1379
1404
|
function cmdCheck(args: string[]): number {
|
|
1380
1405
|
// The switches check takes (issues #202, #209, #454): they carry no value, so they are taken out before the valued flags are read.
|
|
1381
1406
|
const json = args.filter((a) => a === '--json').length;
|
|
@@ -2333,6 +2358,7 @@ function main(argv: string[]): number | Promise<number> {
|
|
|
2333
2358
|
if (command === 'head-crop-preflight') return cmdHeadCropPreflight(rest);
|
|
2334
2359
|
if (command === 'compare') return cmdCompare(rest);
|
|
2335
2360
|
if (command === 'check') return cmdCheck(rest);
|
|
2361
|
+
if (command === 'check-parts') return cmdCheckParts(rest);
|
|
2336
2362
|
if (command === 'loop') return cmdLoop(rest);
|
|
2337
2363
|
if (command === 'assemble') return cmdAssemble(rest);
|
|
2338
2364
|
if (command === 'inputs') return cmdInputs(rest);
|
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. |
|
|
@@ -5735,6 +5735,31 @@ documents do not ship). Each is an input this package built; none is an author's
|
|
|
5735
5735
|
| <a id="COMPARE_WARMUP_UNSUPPORTED"></a>`COMPARE_WARMUP_UNSUPPORTED` | a physics warm-up other than 0 was asked of the comparison; physics resets at time 0 and steps from there | an input this package built, not an author's: report it with the line |
|
|
5736
5736
|
| <a id="SKINNING_RANGE_UNSUPPORTED"></a>`SKINNING_RANGE_UNSUPPORTED` | `skinningEnvelopeBone` was handed a bone range not declared by the bone's own keys (a physics swing, a range read off a posed schedule), or a bone whose setup scale is not uniform; the bound is not proven, so it is refused | nothing to change for the build: inside the residual clause it means the residual veto was not applied to that bone, and the motion comparison decides |
|
|
5737
5737
|
|
|
5738
|
+
### check-parts
|
|
5739
|
+
|
|
5740
|
+
Run `rig-parts check-parts --parts <assembled-dir> --out <disjoint-report-dir>`
|
|
5741
|
+
before parts review. Add `--json` for the completed report alone. The command
|
|
5742
|
+
writes `parts-check.json` and reads no rig, motion or plate. Exit 0 records input
|
|
5743
|
+
integrity while the six #945/#884 quality classes remain named HOLEs.
|
|
5744
|
+
[STABILITY](STABILITY.md#parts-stage-integrity-report) defines the binding and
|
|
5745
|
+
closed diagnostic vocabulary. Base and alternate `scene.figure_mask` remain
|
|
5746
|
+
outside the consumed inputs pending [#1177](https://github.com/rig-c/parts/issues/1177).
|
|
5747
|
+
|
|
5748
|
+
| rule | means | change |
|
|
5749
|
+
| --- | --- | --- |
|
|
5750
|
+
| <a id="PARTS_CHECK_INPUT_READ"></a>`PARTS_CHECK_INPUT_READ` | an input cannot be inventoried, is a link/special file, or references an asset outside the input root | supply a readable regular-file assemble output |
|
|
5751
|
+
| <a id="PARTS_CHECK_PNG_READ"></a>`PARTS_CHECK_PNG_READ` | the named part or auxiliary depth PNG is missing or undecodable | restore the declared PNG or re-run assemble |
|
|
5752
|
+
| <a id="PARTS_CHECK_REPORT"></a>`PARTS_CHECK_REPORT` | a present source-cover/allocation report has invalid JSON, spec, grid, membership or counted spans | regenerate the named producer report with the assemble output |
|
|
5753
|
+
| <a id="PARTS_CHECK_OUTPUT"></a>`PARTS_CHECK_OUTPUT` | output and input roots overlap | choose a disjoint report directory |
|
|
5754
|
+
| <a id="PARTS_CHECK_INPUT_CHANGED"></a>`PARTS_CHECK_INPUT_CHANGED` | bytes or inventory membership changed while reading | freeze the input and run again |
|
|
5755
|
+
| <a id="PARTS_CHECK_PUBLISH"></a>`PARTS_CHECK_PUBLISH` | the report could not be atomically published | supply a writable output root and resolve any existing temporary file |
|
|
5756
|
+
| <a id="PARTS_CHECK_INTERNAL"></a>`PARTS_CHECK_INTERNAL` | an unexpected exception or undeclared diagnostic occurred | report the tool failure |
|
|
5757
|
+
| <a id="PARTS_UNPLANNED_SOURCE_COVER"></a>`PARTS_UNPLANNED_SOURCE_COVER` | REPORTED direct input support under an unplanned front owner, with part/source/count/spans | review its provenance; no quality threshold is applied |
|
|
5758
|
+
| <a id="PARTS_SOURCE_COVER"></a>`PARTS_SOURCE_COVER` | HOLE when source_cover.json is absent | re-run assemble when a cover inventory is required |
|
|
5759
|
+
| <a id="PARTS_PAINTING_ALLOCATION"></a>`PARTS_PAINTING_ALLOCATION` | HOLE when painting_allocation.json is absent | retain the missing transfer observation in review |
|
|
5760
|
+
| <a id="PARTS_PLATE_GHOST"></a><a id="PARTS_PLATE_STRUCTURE"></a><a id="PARTS_PLATE_SMEAR"></a><a id="PARTS_PLATE_STEPS"></a>`PARTS_PLATE_GHOST`, `PARTS_PLATE_STRUCTURE`, `PARTS_PLATE_SMEAR`, `PARTS_PLATE_STEPS` | HOLE; no adopted plate discriminator is available | carry these unmeasured classes to parts review |
|
|
5761
|
+
| <a id="PARTS_INVENTED_MATERIAL"></a><a id="PARTS_INVENTED_EXPOSURE"></a>`PARTS_INVENTED_MATERIAL`, `PARTS_INVENTED_EXPOSURE` | HOLE; validated producer material truth and posed exposure are unavailable | retain the producer-provenance and frame-measurement gaps in review |
|
|
5762
|
+
|
|
5738
5763
|
### check and build
|
|
5739
5764
|
|
|
5740
5765
|
| rule | means | change |
|
package/docs/STABILITY.md
CHANGED
|
@@ -29,6 +29,105 @@ below). A build's bytes are not promised across versions. A later version may mo
|
|
|
29
29
|
them, and when it does, the change that moves them declares which bytes and why (the
|
|
30
30
|
winding change of #133 is the example: [MIGRATION.md](MIGRATION.md)).
|
|
31
31
|
|
|
32
|
+
## Parts-stage integrity report
|
|
33
|
+
|
|
34
|
+
`rig-parts check-parts --parts <assembled-dir> --out <disjoint-report-dir>
|
|
35
|
+
[--json]` writes `parts-check.json`, spec `rig-parts-parts-check/1`.
|
|
36
|
+
Exit 0 is not a quality pass. No #945/#884 defect class is measured yet.
|
|
37
|
+
The six quality HOLEs are always present. They name plate ghost, plate structure,
|
|
38
|
+
plate smear, stepped fill, invented material and invented-material exposure.
|
|
39
|
+
|
|
40
|
+
The top-level key order is `spec`, `stage`, `inputs`, `parts`, `refusals`,
|
|
41
|
+
`reported`, `holes`, `exit_code`. `stage` is `parts`. `inputs` is sorted by
|
|
42
|
+
relative POSIX path. Each row has `path`, `status`, `sha256`, in that order.
|
|
43
|
+
Status is `read`, `missing`, `unreadable` or optional `absent`; SHA-256 is null
|
|
44
|
+
unless the file was read. The inventory binds regular files under `--parts`,
|
|
45
|
+
including primary and alternate PNGs, declared depth images, `parts.json`,
|
|
46
|
+
`painting_in_rig.png` and present source-cover/allocation reports. Missing
|
|
47
|
+
required references are explicit inventory rows. Symlinks and special files
|
|
48
|
+
are refused. Inputs are hashed again before atomic publication.
|
|
49
|
+
|
|
50
|
+
Base and alternate `scene.figure_mask` are declared but not consumed, read,
|
|
51
|
+
hashed or bound by this command. Their standalone-assemble location is tracked
|
|
52
|
+
in [#1177](https://github.com/rig-c/parts/issues/1177). The plate is outside this
|
|
53
|
+
command's inputs. `painting_in_rig` is written beside `parts.json` in both
|
|
54
|
+
standalone assemble and build layouts and is consumed and hash-checked.
|
|
55
|
+
|
|
56
|
+
`parts` preserves primary names, alternate records, the source-cover inventory
|
|
57
|
+
and allocation reports. Embedded object keys are sorted, and producer array
|
|
58
|
+
order is retained. `refusals` rows have `code`, `object`, `found`, `required`,
|
|
59
|
+
`detail`; reused metadata-reader diagnostics retain their code and detail with
|
|
60
|
+
null structured values when the reader supplies none. A refused input produces
|
|
61
|
+
a report and exit 1. `reported` rows have `code`, `set`, `part`, `source`, `count`,
|
|
62
|
+
`spans`; unplanned direct cover is reported without a refusal. `holes` rows have
|
|
63
|
+
`code`, `object`, `reason`, `line`. Absent source cover or allocation adds its
|
|
64
|
+
own HOLE; malformed present reports are refused. A HOLE carries no measured zero.
|
|
65
|
+
|
|
66
|
+
Bad arguments (exit 2), overlapping output, changing inputs, internal exceptions
|
|
67
|
+
and publication failures (exit 1) produce no new report. After parsing `--out`
|
|
68
|
+
and checking overlap, the command removes exactly `parts-check.json` and
|
|
69
|
+
`parts-check.json.tmp` there before reading inputs. Failed input reads cannot
|
|
70
|
+
leave an earlier success report. Bad arguments that prevent resolving `--out`
|
|
71
|
+
cannot remove a prior report. The CLI resolves an existing `--parts` root to its
|
|
72
|
+
real path before reading, including a symlinked root. Consumers bind the report
|
|
73
|
+
and current input hashes and read its `exit_code`. A sibling temporary file is
|
|
74
|
+
exclusively created, cleaned up after a failed write, then renamed into place.
|
|
75
|
+
Identical inputs produce identical report bytes on repeat
|
|
76
|
+
runs and under output roots with different parents.
|
|
77
|
+
|
|
78
|
+
The diagnostic code vocabulary below is closed for `rig-parts-parts-check/1`,
|
|
79
|
+
including reused reader and invocation codes. Adding a code requires a new spec
|
|
80
|
+
version. The generated controls derive literals from `src/parts.ts`,
|
|
81
|
+
`src/takesource.ts`, `src/depthsheets.ts`, `src/setfocus.ts` and `src/partscheck.ts`,
|
|
82
|
+
compare this list with the command's allowlist, and plant an undeclared code.
|
|
83
|
+
|
|
84
|
+
<!-- parts-check:codes -->
|
|
85
|
+
- `CONFIG_SET_FOCUS`
|
|
86
|
+
- `PARTS_ALT_BASE_ANCHOR`
|
|
87
|
+
- `PARTS_ALT_TIPS`
|
|
88
|
+
- `PARTS_ALT_TIPS_SOURCE`
|
|
89
|
+
- `PARTS_BOX_INSIDE_RIG`
|
|
90
|
+
- `PARTS_CHECK_INPUT_CHANGED`
|
|
91
|
+
- `PARTS_CHECK_INPUT_READ`
|
|
92
|
+
- `PARTS_CHECK_INTERNAL`
|
|
93
|
+
- `PARTS_CHECK_OUTPUT`
|
|
94
|
+
- `PARTS_CHECK_PNG_READ`
|
|
95
|
+
- `PARTS_CHECK_PUBLISH`
|
|
96
|
+
- `PARTS_CHECK_REPORT`
|
|
97
|
+
- `PARTS_COUNTS_ADD_UP`
|
|
98
|
+
- `PARTS_CUT_FROM_KNOWN`
|
|
99
|
+
- `PARTS_DEPTH_REFERENCE`
|
|
100
|
+
- `PARTS_FIELD_PRESENT`
|
|
101
|
+
- `PARTS_FIELD_TYPE`
|
|
102
|
+
- `PARTS_FILE_PRESENT`
|
|
103
|
+
- `PARTS_FROM_KNOWN`
|
|
104
|
+
- `PARTS_HOLES_LARGEST_FIRST`
|
|
105
|
+
- `PARTS_HOLE_PART_KNOWN`
|
|
106
|
+
- `PARTS_HYBRID_PAIR`
|
|
107
|
+
- `PARTS_INVENTED_EXPOSURE`
|
|
108
|
+
- `PARTS_INVENTED_MATERIAL`
|
|
109
|
+
- `PARTS_IS_JSON`
|
|
110
|
+
- `PARTS_KEY_KNOWN`
|
|
111
|
+
- `PARTS_MOTION_SEAM`
|
|
112
|
+
- `PARTS_NAME_UNIQUE`
|
|
113
|
+
- `PARTS_PAINTING_ALLOCATION`
|
|
114
|
+
- `PARTS_PAINTING_OPAQUE`
|
|
115
|
+
- `PARTS_PAINTING_PNG`
|
|
116
|
+
- `PARTS_PAINTING_PRESENT`
|
|
117
|
+
- `PARTS_PAINTING_SHA256`
|
|
118
|
+
- `PARTS_PAINTING_SIZE`
|
|
119
|
+
- `PARTS_PLATE_GHOST`
|
|
120
|
+
- `PARTS_PLATE_SMEAR`
|
|
121
|
+
- `PARTS_PLATE_STEPS`
|
|
122
|
+
- `PARTS_PLATE_STRUCTURE`
|
|
123
|
+
- `PARTS_SINGLE_RUN_PAD`
|
|
124
|
+
- `PARTS_SOURCE_COVER`
|
|
125
|
+
- `PARTS_TAKEN_LAYERS`
|
|
126
|
+
- `PARTS_UNPLANNED_SOURCE_COVER`
|
|
127
|
+
- `PROPOSE_PNG_MATCHES_BOX`
|
|
128
|
+
- `USAGE`
|
|
129
|
+
<!-- /parts-check:codes -->
|
|
130
|
+
|
|
32
131
|
## Programmatic config file references
|
|
33
132
|
|
|
34
133
|
`@rig-c/parts/src/config.ts` exports `configFileReferences(raw: unknown):
|
|
@@ -122,6 +221,7 @@ defaults are the help's too, and none is guessed from the art.
|
|
|
122
221
|
| `propose` | `--parts`, `--source`, `--out`, `--full`, `--head`, `--write-config` together: the [neck draft](AUTHORING.md#a-neck-that-moves-on-its-own) for an existing config with `turn.body` and one neck plan row; reassembles under `<out>/rig`, preserves the sampled turn and drafts a rigid neck unit (issue #826) |
|
|
123
222
|
| `compare` | `--left`, `--right`; optional `--map` |
|
|
124
223
|
| `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
|
|
224
|
+
| `check-parts` | `--parts`, `--out`; optional `--json` |
|
|
125
225
|
| `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills`, `--no-extremes` (issue #829), `--set` or `--all-sets` (issue #454), `--environment` (issue #538, additive), `--wind-band` (issue #590, additive), `--json` (issue #904) |
|
|
126
226
|
| `loop` | `--frames`, `--out`; optional `--palette` |
|
|
127
227
|
| `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--no-extremes` (issue #829), `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454), `--environment` (as for `check`, issue #538, additive), `--wind-band` (as for `check`, issue #590, additive) |
|
|
@@ -195,8 +295,9 @@ rules that make the contract:
|
|
|
195
295
|
- **`scene`** (issue #242) declares the painting a scene — the figure and what
|
|
196
296
|
is round it — and takes no field: `{}`. With it `assemble` reads the
|
|
197
297
|
recomposite inside the figure (the union of the full run's layers at alpha
|
|
198
|
-
above 8), writes the figure as `figure_rig.png` beside the recomposite and
|
|
199
|
-
`
|
|
298
|
+
above 8), writes the figure as `figure_rig.png` beside the recomposite (and,
|
|
299
|
+
when standalone `assemble` puts `parts.json` in another directory, beside
|
|
300
|
+
`parts.json` too, issue #1177) and a `scene` block in `parts.json`, and `check` leaves the painting's border rows
|
|
200
301
|
and columns out of the seam. Without the field no byte of any output moves.
|
|
201
302
|
|
|
202
303
|
The fields, object by object (a bold path is where the object sits; `<part>` is a
|
|
@@ -372,7 +473,7 @@ resolution before resizing; it can differ for non-opaque paintings.
|
|
|
372
473
|
| file | written by | what is stable |
|
|
373
474
|
| --- | --- | --- |
|
|
374
475
|
| `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). |
|
|
375
|
-
| `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) |
|
|
476
|
+
| `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) |
|
|
376
477
|
| `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) |
|
|
377
478
|
| `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) |
|
|
378
479
|
| `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. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spine-parts",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.26.1",
|
|
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/build.ts
CHANGED
|
@@ -970,9 +970,15 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
|
|
|
970
970
|
writeSupportDomains(outs.partsJson, outs.partsDir, result.parts, result.supportDomains, supportDeclarations);
|
|
971
971
|
writePng(outs.recomposite, result.recomposite);
|
|
972
972
|
writePng(outs.errorMap, result.errorMap);
|
|
973
|
-
// Issue #242: under config.scene, the figure the recomposite was read inside, beside the recomposite.
|
|
973
|
+
// Issue #242: under config.scene, the figure the recomposite was read inside, beside the recomposite (and beside parts.json when separate, #1177).
|
|
974
974
|
const figurePath = result.figure === null ? null : join(dirname(outs.recomposite), FIGURE_MASK_FILE);
|
|
975
|
-
if (figurePath !== null)
|
|
975
|
+
if (figurePath !== null) {
|
|
976
|
+
const figureBytes = encodePngBytes(result.figure as Raster);
|
|
977
|
+
writeFileSync(figurePath, figureBytes);
|
|
978
|
+
if (resolve(dirname(outs.partsJson)) !== resolve(dirname(outs.recomposite))) writeFileSync(join(dirname(outs.partsJson), FIGURE_MASK_FILE), figureBytes);
|
|
979
|
+
} else if (resolve(dirname(outs.partsJson)) !== resolve(dirname(outs.recomposite))) {
|
|
980
|
+
rmSync(join(dirname(outs.partsJson), FIGURE_MASK_FILE), { force: true });
|
|
981
|
+
}
|
|
976
982
|
const [W, H] = result.parts.rig_size;
|
|
977
983
|
log(`rig-parts assemble: ${result.images.length} part(s) on a ${W}x${H} rig (${result.parts.scale_rig_per_source} rig px per source px), seam rule ${result.seamRule}, projection rule ${result.projectRule}`);
|
|
978
984
|
// Issue #996: a ground declared or defaulted plain whose border ring is not one colour, under project: visible only.
|
|
@@ -0,0 +1,421 @@
|
|
|
1
|
+
/** Assemble-output integrity and explicit unmeasured quality classes. No rig or renderer. */
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
|
|
5
|
+
import { failLine, PartsError, type Problem } from './errors.ts';
|
|
6
|
+
import { FIGURE_MASK_FILE, partImageReference, partsFileReferences, readParts, type PartsFile } from './parts.ts';
|
|
7
|
+
import { readPng } from './raster/png.ts';
|
|
8
|
+
import { RasterError } from './raster/types.ts';
|
|
9
|
+
import { NotAPngError } from '@rig-c/core/png';
|
|
10
|
+
import { SOURCE_COVER_SPEC, sourceCoverReport } from './sourcecover.ts';
|
|
11
|
+
|
|
12
|
+
export const PARTS_CHECK_SPEC = 'rig-parts-parts-check/1';
|
|
13
|
+
export const PARTS_CHECK_FILE = 'parts-check.json';
|
|
14
|
+
|
|
15
|
+
/** Closed diagnostic vocabulary for this spec, including reused metadata readers. */
|
|
16
|
+
export const PARTS_CHECK_CODES: readonly string[] = [
|
|
17
|
+
'CONFIG_SET_FOCUS',
|
|
18
|
+
'PARTS_ALT_BASE_ANCHOR',
|
|
19
|
+
'PARTS_ALT_TIPS',
|
|
20
|
+
'PARTS_ALT_TIPS_SOURCE',
|
|
21
|
+
'PARTS_BOX_INSIDE_RIG',
|
|
22
|
+
'PARTS_CHECK_INPUT_CHANGED',
|
|
23
|
+
'PARTS_CHECK_INPUT_READ',
|
|
24
|
+
'PARTS_CHECK_INTERNAL',
|
|
25
|
+
'PARTS_CHECK_OUTPUT',
|
|
26
|
+
'PARTS_CHECK_PNG_READ',
|
|
27
|
+
'PARTS_CHECK_PUBLISH',
|
|
28
|
+
'PARTS_CHECK_REPORT',
|
|
29
|
+
'PARTS_COUNTS_ADD_UP',
|
|
30
|
+
'PARTS_CUT_FROM_KNOWN',
|
|
31
|
+
'PARTS_DEPTH_REFERENCE',
|
|
32
|
+
'PARTS_FIELD_PRESENT',
|
|
33
|
+
'PARTS_FIELD_TYPE',
|
|
34
|
+
'PARTS_FILE_PRESENT',
|
|
35
|
+
'PARTS_FROM_KNOWN',
|
|
36
|
+
'PARTS_HOLES_LARGEST_FIRST',
|
|
37
|
+
'PARTS_HOLE_PART_KNOWN',
|
|
38
|
+
'PARTS_HYBRID_PAIR',
|
|
39
|
+
'PARTS_INVENTED_EXPOSURE',
|
|
40
|
+
'PARTS_INVENTED_MATERIAL',
|
|
41
|
+
'PARTS_IS_JSON',
|
|
42
|
+
'PARTS_KEY_KNOWN',
|
|
43
|
+
'PARTS_MOTION_SEAM',
|
|
44
|
+
'PARTS_NAME_UNIQUE',
|
|
45
|
+
'PARTS_PAINTING_ALLOCATION',
|
|
46
|
+
'PARTS_PAINTING_OPAQUE',
|
|
47
|
+
'PARTS_PAINTING_PNG',
|
|
48
|
+
'PARTS_PAINTING_PRESENT',
|
|
49
|
+
'PARTS_PAINTING_SHA256',
|
|
50
|
+
'PARTS_PAINTING_SIZE',
|
|
51
|
+
'PARTS_PLATE_GHOST',
|
|
52
|
+
'PARTS_PLATE_SMEAR',
|
|
53
|
+
'PARTS_PLATE_STEPS',
|
|
54
|
+
'PARTS_PLATE_STRUCTURE',
|
|
55
|
+
'PARTS_SINGLE_RUN_PAD',
|
|
56
|
+
'PARTS_SOURCE_COVER',
|
|
57
|
+
'PARTS_TAKEN_LAYERS',
|
|
58
|
+
'PARTS_UNPLANNED_SOURCE_COVER',
|
|
59
|
+
'PROPOSE_PNG_MATCHES_BOX',
|
|
60
|
+
'USAGE',
|
|
61
|
+
];
|
|
62
|
+
|
|
63
|
+
export const PARTS_QUALITY_HOLES = [
|
|
64
|
+
['PARTS_PLATE_GHOST', 'no adopted plate-ghost discriminator; assemble outputs do not bind a background plate or composed figure outline'],
|
|
65
|
+
['PARTS_PLATE_STRUCTURE', 'no adopted background-structure continuation measure or reference'],
|
|
66
|
+
['PARTS_PLATE_SMEAR', 'no adopted plate-smear discriminator'],
|
|
67
|
+
['PARTS_PLATE_STEPS', 'no adopted plate-fill continuity measure'],
|
|
68
|
+
['PARTS_INVENTED_MATERIAL', 'no validated producer-bound per-pixel painted-versus-invented record'],
|
|
69
|
+
['PARTS_INVENTED_EXPOSURE', 'invented-material identity and posed-frame observations are unavailable at the parts stage'],
|
|
70
|
+
] as const;
|
|
71
|
+
|
|
72
|
+
export interface PartsCheckInput {
|
|
73
|
+
path: string;
|
|
74
|
+
status: 'read' | 'missing' | 'unreadable' | 'absent';
|
|
75
|
+
sha256: string | null;
|
|
76
|
+
}
|
|
77
|
+
interface Refusal extends Problem { found: unknown; required: unknown }
|
|
78
|
+
interface Hole { code: string; object: string; reason: string; line: string }
|
|
79
|
+
interface CoverRow { code: string; set: string | null; part: string; source: string; count: number; spans: unknown[] }
|
|
80
|
+
export interface PartsCheckReport {
|
|
81
|
+
spec: typeof PARTS_CHECK_SPEC;
|
|
82
|
+
stage: 'parts';
|
|
83
|
+
inputs: PartsCheckInput[];
|
|
84
|
+
parts: { primary: string[]; alternates: unknown[]; source_cover: unknown; painting_allocation: unknown[] };
|
|
85
|
+
refusals: Refusal[];
|
|
86
|
+
reported: CoverRow[];
|
|
87
|
+
holes: Hole[];
|
|
88
|
+
exit_code: number;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function object(value: unknown): value is Record<string, unknown> {
|
|
92
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
93
|
+
}
|
|
94
|
+
function count(value: unknown): value is number { return Number.isSafeInteger(value) && Number(value) >= 0; }
|
|
95
|
+
function strings(value: unknown): value is string[] { return Array.isArray(value) && value.every(v => typeof v === 'string'); }
|
|
96
|
+
function hash(value: unknown): boolean { return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value); }
|
|
97
|
+
function unique(value: unknown[]): boolean { return new Set(value).size === value.length; }
|
|
98
|
+
function grid(value: unknown): value is [number, number] {
|
|
99
|
+
return Array.isArray(value) && value.length === 2 && value.every(v => count(v) && v > 0);
|
|
100
|
+
}
|
|
101
|
+
function pixels(value: unknown, size: [number, number]): boolean {
|
|
102
|
+
if (!object(value) || !count(value.count) || !Array.isArray(value.spans)) return false;
|
|
103
|
+
let total = 0;
|
|
104
|
+
let previousY = -1;
|
|
105
|
+
let previousRight = -1;
|
|
106
|
+
for (const span of value.spans) {
|
|
107
|
+
if (!Array.isArray(span) || span.length !== 3 || !span.every(count)) return false;
|
|
108
|
+
const [y, left, right] = span as number[];
|
|
109
|
+
if (y >= size[1] || right > size[0] || left >= right || y < previousY || (y === previousY && left < previousRight)) return false;
|
|
110
|
+
previousY = y;
|
|
111
|
+
previousRight = right;
|
|
112
|
+
total += right - left;
|
|
113
|
+
}
|
|
114
|
+
return total === value.count;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Preserve array order, but make embedded producer objects independent of JSON key order. */
|
|
118
|
+
function canonical(value: unknown): unknown {
|
|
119
|
+
if (Array.isArray(value)) return value.map(canonical);
|
|
120
|
+
if (object(value)) return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
|
|
121
|
+
return value;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
function physical(path: string): string {
|
|
125
|
+
const absolute = resolve(path);
|
|
126
|
+
if (existsSync(absolute)) return realpathSync(absolute);
|
|
127
|
+
const parent = dirname(absolute);
|
|
128
|
+
return parent === absolute ? absolute : join(physical(parent), relative(parent, absolute));
|
|
129
|
+
}
|
|
130
|
+
function within(parent: string, path: string): boolean {
|
|
131
|
+
const rel = relative(parent, path);
|
|
132
|
+
return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
|
|
133
|
+
}
|
|
134
|
+
function fatal(code: string, object: string, detail: string): never {
|
|
135
|
+
throw new PartsError([{ code, object, detail }]);
|
|
136
|
+
}
|
|
137
|
+
function ioError(error: unknown): error is Error & { code: string } {
|
|
138
|
+
return error instanceof Error && 'code' in error && typeof error.code === 'string' && /^E[A-Z]+$/.test(error.code);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** No source writes. A disjoint output root is required even for a refused input. */
|
|
142
|
+
export function checkPartsStage(input: string, output: string, log: (line: string) => void = console.log): PartsCheckReport {
|
|
143
|
+
const home = resolve(input);
|
|
144
|
+
const out = resolve(output);
|
|
145
|
+
const realHome = physical(home);
|
|
146
|
+
const realOut = physical(out);
|
|
147
|
+
if (within(realHome, realOut) || within(realOut, realHome)) {
|
|
148
|
+
fatal('PARTS_CHECK_OUTPUT', '--out', 'overlaps --parts; a disjoint report directory is required');
|
|
149
|
+
}
|
|
150
|
+
const destination = join(out, PARTS_CHECK_FILE);
|
|
151
|
+
const temporary = `${destination}.tmp`;
|
|
152
|
+
try {
|
|
153
|
+
rmSync(destination, { force: true });
|
|
154
|
+
rmSync(temporary, { force: true });
|
|
155
|
+
} catch {
|
|
156
|
+
fatal('PARTS_CHECK_PUBLISH', '--out', 'could not remove the previous report or its temporary file before reading inputs');
|
|
157
|
+
}
|
|
158
|
+
const clean = (value: string): string => value.replaceAll(home, '.').replaceAll(realHome, '.');
|
|
159
|
+
const refusals: Refusal[] = [];
|
|
160
|
+
const refuse = (code: string, at: string, found: unknown, required: unknown, detail: string): void => {
|
|
161
|
+
if (!PARTS_CHECK_CODES.includes(code)) fatal('PARTS_CHECK_INTERNAL', 'check-parts', 'reader emitted a code outside the signed spec');
|
|
162
|
+
refusals.push({ code, object: clean(at), found, required, detail: clean(detail) });
|
|
163
|
+
};
|
|
164
|
+
const readerError = (error: unknown): void => {
|
|
165
|
+
if (!(error instanceof PartsError)) throw error;
|
|
166
|
+
for (const problem of error.problems) refuse(problem.code, problem.object, null, null, problem.detail);
|
|
167
|
+
};
|
|
168
|
+
const requiredPaths = new Set(['parts.json']);
|
|
169
|
+
const optionalPaths = new Set(['source_cover.json', 'painting_allocation.json']);
|
|
170
|
+
const ignoredPaths = new Set<string>();
|
|
171
|
+
let initialManifestHash: string | undefined;
|
|
172
|
+
// Only metadata is read here. Figure masks have a layout-dependent location (#1177).
|
|
173
|
+
try {
|
|
174
|
+
const manifestPath = join(home, 'parts.json');
|
|
175
|
+
if (lstatSync(manifestPath).isFile()) {
|
|
176
|
+
const bytes = readFileSync(manifestPath);
|
|
177
|
+
initialManifestHash = createHash('sha256').update(bytes).digest('hex');
|
|
178
|
+
const raw: unknown = JSON.parse(bytes.toString('utf8'));
|
|
179
|
+
if (object(raw)) {
|
|
180
|
+
const scenes = [raw.scene, ...(Array.isArray(raw.alternates) ? raw.alternates.filter(object).map(set => set.scene) : [])];
|
|
181
|
+
for (const scene of scenes) if (object(scene) && scene.figure_mask === FIGURE_MASK_FILE) {
|
|
182
|
+
ignoredPaths.add(FIGURE_MASK_FILE);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
} catch (error) {
|
|
187
|
+
if (!(error instanceof SyntaxError) && !ioError(error)) throw error;
|
|
188
|
+
// The regular metadata reader below owns the named refusal.
|
|
189
|
+
}
|
|
190
|
+
const inventory = (reportErrors: boolean): PartsCheckInput[] => {
|
|
191
|
+
const rows = new Map<string, PartsCheckInput>();
|
|
192
|
+
const visit = (name: string): void => {
|
|
193
|
+
if (ignoredPaths.has(name)) return;
|
|
194
|
+
const path = join(home, name);
|
|
195
|
+
try {
|
|
196
|
+
const stat = lstatSync(path);
|
|
197
|
+
if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
|
|
198
|
+
rows.set(name, { path: name, status: 'unreadable', sha256: null });
|
|
199
|
+
if (reportErrors) refuse('PARTS_CHECK_INPUT_READ', name, 'non-regular input', 'regular file or directory', 'input links and special files require a regular-file scratch copy');
|
|
200
|
+
} else if (stat.isDirectory()) {
|
|
201
|
+
for (const entry of readdirSync(path).sort()) visit(name === '.' ? entry : `${name}/${entry}`);
|
|
202
|
+
} else {
|
|
203
|
+
rows.set(name, { path: name, status: 'read', sha256: createHash('sha256').update(readFileSync(path)).digest('hex') });
|
|
204
|
+
}
|
|
205
|
+
} catch (error) {
|
|
206
|
+
if (!ioError(error)) throw error;
|
|
207
|
+
const missing = 'code' in error && error.code === 'ENOENT';
|
|
208
|
+
rows.set(name, { path: name, status: missing ? 'missing' : 'unreadable', sha256: null });
|
|
209
|
+
if (reportErrors) refuse('PARTS_CHECK_INPUT_READ', name, clean(error.message), 'readable regular input', 'input inventory could not read this object');
|
|
210
|
+
}
|
|
211
|
+
};
|
|
212
|
+
visit('.');
|
|
213
|
+
for (const name of [...requiredPaths, ...optionalPaths]) if (!rows.has(name)) {
|
|
214
|
+
rows.set(name, { path: name, status: optionalPaths.has(name) ? 'absent' : 'missing', sha256: null });
|
|
215
|
+
}
|
|
216
|
+
return [...rows.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
|
|
217
|
+
};
|
|
218
|
+
// Inventory first, then discover references through the existing metadata reader.
|
|
219
|
+
const before = inventory(true);
|
|
220
|
+
if (initialManifestHash !== undefined && before.find(row => row.path === 'parts.json')?.sha256 !== initialManifestHash) {
|
|
221
|
+
fatal('PARTS_CHECK_INPUT_CHANGED', 'parts.json', 'manifest changed while reading references; no report was published');
|
|
222
|
+
}
|
|
223
|
+
let file: PartsFile | undefined;
|
|
224
|
+
let references: ReturnType<typeof partsFileReferences> = [];
|
|
225
|
+
try {
|
|
226
|
+
references = partsFileReferences(home).filter(reference => reference.role !== 'figure_mask');
|
|
227
|
+
for (const reference of references) requiredPaths.add(reference.path);
|
|
228
|
+
const unsafe = references.filter(reference => !within(realHome, physical(join(home, reference.path))));
|
|
229
|
+
for (const reference of unsafe) refuse('PARTS_CHECK_INPUT_READ', reference.path, 'reference outside --parts', 'input inside --parts', 'copy declared assets into the assemble directory');
|
|
230
|
+
if (unsafe.length === 0 && !before.some(row => row.status === 'unreadable')) file = readParts(join(home, 'parts.json'));
|
|
231
|
+
} catch (error) {
|
|
232
|
+
if (ioError(error)) refuse('PARTS_CHECK_INPUT_READ', 'parts.json', clean(error.message), 'readable input', 'the manifest or its declared painting could not be read');
|
|
233
|
+
else readerError(error);
|
|
234
|
+
}
|
|
235
|
+
// Add missing declared references to the initial inventory, without re-reading bytes.
|
|
236
|
+
for (const name of requiredPaths) if (!before.some(row => row.path === name)) before.push({ path: name, status: 'missing', sha256: null });
|
|
237
|
+
before.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
|
|
238
|
+
const holes: Hole[] = [];
|
|
239
|
+
const hole = (code: string, at: string, reason: string): void => { holes.push({ code, object: at, reason, line: `${code}: HOLE — ${reason}` }); };
|
|
240
|
+
for (const [code, reason] of PARTS_QUALITY_HOLES) hole(code, 'parts', reason);
|
|
241
|
+
if (file !== undefined) {
|
|
242
|
+
const partRows = [
|
|
243
|
+
...file.parts.map(part => ({ part, path: partImageReference(part).path })),
|
|
244
|
+
...(file.alternates ?? []).flatMap(set => set.records.map(part => ({ part, path: partImageReference(part, set.name).path }))),
|
|
245
|
+
];
|
|
246
|
+
for (const { part, path } of partRows) {
|
|
247
|
+
try {
|
|
248
|
+
const image = readPng(join(home, path));
|
|
249
|
+
if (image.width !== part.w || image.height !== part.h) {
|
|
250
|
+
refuse('PROPOSE_PNG_MATCHES_BOX', `part "${part.name}"`, [image.width, image.height], [part.w, part.h], `${path} is ${image.width}x${image.height}; parts.json requires ${part.w}x${part.h}`);
|
|
251
|
+
}
|
|
252
|
+
} catch (error) {
|
|
253
|
+
if (!ioError(error) && !(error instanceof RasterError) && !(error instanceof NotAPngError)) throw error;
|
|
254
|
+
refuse('PARTS_CHECK_PNG_READ', `part "${part.name}"`, clean(error.message), 'decodable PNG', `${path} is not a readable PNG`);
|
|
255
|
+
}
|
|
256
|
+
}
|
|
257
|
+
for (const reference of references.filter(row => row.role !== 'part' && row.role !== 'alternate' && row.role !== 'painting')) {
|
|
258
|
+
try { readPng(join(home, reference.path)); }
|
|
259
|
+
catch (error) {
|
|
260
|
+
if (!ioError(error) && !(error instanceof RasterError) && !(error instanceof NotAPngError)) throw error;
|
|
261
|
+
refuse('PARTS_CHECK_PNG_READ', reference.path, clean(error.message), 'decodable PNG', 'declared auxiliary PNG is not readable');
|
|
262
|
+
}
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
const readReport = (name: string, spec: string): Record<string, unknown> | null => {
|
|
266
|
+
const row = before.find(entry => entry.path === name);
|
|
267
|
+
if (row?.status === 'absent') return null;
|
|
268
|
+
if (row?.status === 'unreadable') {
|
|
269
|
+
refuse('PARTS_CHECK_REPORT', name, 'unreadable input', spec, 'present report must be a readable regular file');
|
|
270
|
+
return null;
|
|
271
|
+
}
|
|
272
|
+
try {
|
|
273
|
+
const value: unknown = JSON.parse(readFileSync(join(home, name), 'utf8'));
|
|
274
|
+
if (!object(value) || value.spec !== spec) {
|
|
275
|
+
refuse('PARTS_CHECK_REPORT', name, object(value) ? value.spec ?? null : value, spec, 'report requires its declared producer spec');
|
|
276
|
+
return null;
|
|
277
|
+
}
|
|
278
|
+
return value;
|
|
279
|
+
} catch (error) {
|
|
280
|
+
if (!(error instanceof SyntaxError) && !ioError(error)) throw error;
|
|
281
|
+
refuse('PARTS_CHECK_REPORT', name, clean(error.message), spec, 'present report must be readable JSON');
|
|
282
|
+
return null;
|
|
283
|
+
}
|
|
284
|
+
};
|
|
285
|
+
const cover = readReport('source_cover.json', SOURCE_COVER_SPEC);
|
|
286
|
+
const reported: CoverRow[] = [];
|
|
287
|
+
if (before.find(row => row.path === 'source_cover.json')?.status === 'absent') {
|
|
288
|
+
hole('PARTS_SOURCE_COVER', 'source_cover.json', 'source_cover.json is absent; direct unplanned source cover is unavailable');
|
|
289
|
+
}
|
|
290
|
+
if (cover !== null) {
|
|
291
|
+
const valid = cover.stage === 'source-projection-input' &&
|
|
292
|
+
JSON.stringify(canonical(cover.predicate)) === JSON.stringify(canonical(sourceCoverReport([]).predicate)) &&
|
|
293
|
+
Array.isArray(cover.sets) && cover.sets.length > 0;
|
|
294
|
+
if (!valid) refuse('PARTS_CHECK_REPORT', 'source_cover.json', canonical(cover), 'source-projection-input predicate and nonempty sets', 'source cover header is malformed');
|
|
295
|
+
else for (const set of cover.sets as unknown[]) {
|
|
296
|
+
if (!object(set) || !(set.set === null || typeof set.set === 'string') || !grid(set.grid) ||
|
|
297
|
+
!Array.isArray(set.sources) || !Array.isArray(set.parts) || !Array.isArray(set.inputs) ||
|
|
298
|
+
!strings(set.hidden_parts) || !Array.isArray(set.inherited_parts) || !Array.isArray(set.output_assets)) {
|
|
299
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json set', canonical(set), 'complete source-cover set', 'set membership or grid is malformed');
|
|
300
|
+
continue;
|
|
301
|
+
}
|
|
302
|
+
const validSources = set.sources.every(source => object(source) && typeof source.source === 'string' &&
|
|
303
|
+
(source.run === 'full' || source.run === 'head') && typeof source.layer === 'string' &&
|
|
304
|
+
source.source === `${source.run}:${source.layer}` && (source.depth_median === null || typeof source.depth_median === 'number') &&
|
|
305
|
+
count(source.draw_order) && Number.isSafeInteger(source.plan_rank) && Number(source.plan_rank) >= -1 &&
|
|
306
|
+
strings(source.planned_parts) && strings(source.extend_parts) && (source.input_layer === null || typeof source.input_layer === 'string') &&
|
|
307
|
+
typeof source.prepared === 'boolean' && Array.isArray(source.taken_layers));
|
|
308
|
+
const validInputs = hash(set.painting_sha256) && set.inputs.every(row => object(row) &&
|
|
309
|
+
(row.run === 'full' || row.run === 'head') && typeof row.file === 'string' && hash(row.sha256) &&
|
|
310
|
+
Array.isArray(row.layers) && row.layers.every(layer => object(layer) && typeof layer.layer === 'string' &&
|
|
311
|
+
(layer.image === null || typeof layer.image === 'string')));
|
|
312
|
+
const validAssets = set.output_assets.every(row => object(row) && typeof row.part === 'string' &&
|
|
313
|
+
(row.image === null || typeof row.image === 'string')) && set.inherited_parts.every(row => object(row) && typeof row.part === 'string' && row.set === null);
|
|
314
|
+
const sources = new Set(set.sources.filter(object).map(source => source.source));
|
|
315
|
+
const expectedSets = [null, ...(file?.alternates ?? []).map(alternate => alternate.name)];
|
|
316
|
+
if (!validSources || sources.size !== set.sources.length || !validInputs || !validAssets ||
|
|
317
|
+
(file !== undefined && (!expectedSets.includes(set.set as string | null) || JSON.stringify(set.grid) !== JSON.stringify(file.rig_size)))) {
|
|
318
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json set', canonical(set), 'unique complete source identities, inputs, assets and matching rig grid', 'source-cover bindings are malformed');
|
|
319
|
+
continue;
|
|
320
|
+
}
|
|
321
|
+
if (!unique(set.parts.filter(object).map(part => part.part))) {
|
|
322
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json set', set.parts.filter(object).map(part => part.part), 'unique part membership', 'source-cover part names repeat');
|
|
323
|
+
}
|
|
324
|
+
if (file !== undefined && set.set === null && JSON.stringify(canonical(set.output_assets)) !==
|
|
325
|
+
JSON.stringify(canonical(file.parts.map(part => ({ part: part.name, image: `${part.name}.png` }))))) {
|
|
326
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json output_assets', canonical(set.output_assets), file.parts.map(part => part.name), 'primary asset membership disagrees with parts.json');
|
|
327
|
+
}
|
|
328
|
+
for (const part of set.parts) {
|
|
329
|
+
if (!object(part) || typeof part.part !== 'string' || !sources.has(part.source) || !count(part.support_px) ||
|
|
330
|
+
!count(part.held_under_cover_px) || part.held_under_cover_px > part.support_px || !Array.isArray(part.covered_by)) {
|
|
331
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json part', canonical(part), 'named part with source and support counts', 'part membership is malformed');
|
|
332
|
+
continue;
|
|
333
|
+
}
|
|
334
|
+
let covered = 0;
|
|
335
|
+
for (const owner of part.covered_by) {
|
|
336
|
+
const identity = object(owner) ? set.sources.filter(object).find(source => source.source === owner.source) : undefined;
|
|
337
|
+
if (!object(owner) || typeof owner.source !== 'string' || !sources.has(owner.source) || typeof owner.planned !== 'boolean' ||
|
|
338
|
+
owner.planned !== (Number(identity?.plan_rank) >= 0) || !pixels(owner.pixels, set.grid)) {
|
|
339
|
+
refuse('PARTS_CHECK_REPORT', `part "${part.part}"`, canonical(owner), 'known owner, boolean planned, counted in-grid spans', 'source-cover owner is malformed');
|
|
340
|
+
} else if (!owner.planned && object(owner.pixels)) {
|
|
341
|
+
covered += owner.pixels.count as number;
|
|
342
|
+
reported.push({ code: 'PARTS_UNPLANNED_SOURCE_COVER', set: set.set as string | null, part: part.part,
|
|
343
|
+
source: owner.source, count: owner.pixels.count as number, spans: owner.pixels.spans as unknown[] });
|
|
344
|
+
} else if (object(owner.pixels)) {
|
|
345
|
+
covered += owner.pixels.count as number;
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
if (covered + part.held_under_cover_px > part.support_px) {
|
|
349
|
+
refuse('PARTS_CHECK_REPORT', `part "${part.part}"`, covered + part.held_under_cover_px, part.support_px, 'covered and held support exceeds own support');
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
}
|
|
353
|
+
if (Array.isArray(cover.sets) && file !== undefined) {
|
|
354
|
+
const sets = cover.sets.filter(object).map(set => set.set);
|
|
355
|
+
const expected = [null, ...(file.alternates ?? []).map(set => set.name)];
|
|
356
|
+
if (!unique(sets) || JSON.stringify(sets) !== JSON.stringify(expected)) {
|
|
357
|
+
refuse('PARTS_CHECK_REPORT', 'source_cover.json', sets, expected, 'source-cover sets must match assembled set order and membership');
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
}
|
|
361
|
+
const allocation = readReport('painting_allocation.json', 'rig-parts-painting-allocation/1');
|
|
362
|
+
const allocations: unknown[] = [];
|
|
363
|
+
if (before.find(row => row.path === 'painting_allocation.json')?.status === 'absent') {
|
|
364
|
+
hole('PARTS_PAINTING_ALLOCATION', 'painting_allocation.json', 'painting_allocation.json is absent; painting-edge transfer membership is unavailable');
|
|
365
|
+
}
|
|
366
|
+
const validateAllocation = (name: string, value: Record<string, unknown>): void => {
|
|
367
|
+
if (value.code !== 'PAINTING_EDGE_COVERAGE_TRANSFER' || value.stage !== 'paintingEdges after piece guarding and restoration' ||
|
|
368
|
+
typeof value.supplier !== 'string' || !object(value.refused) || !Object.values(value.refused).every(count) ||
|
|
369
|
+
!Array.isArray(value.lineage) || !count(value.fallbackHeld) || !grid(value.grid) ||
|
|
370
|
+
(file !== undefined && JSON.stringify(value.grid) !== JSON.stringify(file.rig_size)) ||
|
|
371
|
+
!Array.isArray(value.coverageTransfers) || value.coverageTransfers.some(row =>
|
|
372
|
+
!object(row) || typeof row.front !== 'string' || typeof row.receiver !== 'string' || typeof row.owner !== 'string' || !pixels(row.pixels, value.grid as [number, number]))) {
|
|
373
|
+
refuse('PARTS_CHECK_REPORT', name, canonical(value), 'grid and named coverageTransfers with counted spans', 'allocation membership is malformed');
|
|
374
|
+
} else allocations.push({ path: name, report: canonical(value) });
|
|
375
|
+
};
|
|
376
|
+
if (allocation !== null) {
|
|
377
|
+
validateAllocation('painting_allocation.json', allocation);
|
|
378
|
+
if (!strings(allocation.written_reports) || !unique(allocation.written_reports) || allocation.written_reports.some(name =>
|
|
379
|
+
!/^painting_allocation\.[^/\\]+\.json$/.test(name) || (file !== undefined && !(file.alternates ?? []).some(set => name === `painting_allocation.${encodeURIComponent(set.name)}.json`)))) {
|
|
380
|
+
refuse('PARTS_CHECK_REPORT', 'painting_allocation.json', allocation.written_reports ?? null, 'written_reports containing sibling allocation filenames', 'alternate report inventory is malformed');
|
|
381
|
+
} else for (const name of allocation.written_reports) {
|
|
382
|
+
requiredPaths.add(name);
|
|
383
|
+
if (!before.some(row => row.path === name)) before.push({ path: name, status: 'missing', sha256: null });
|
|
384
|
+
const value = readReport(name, 'rig-parts-painting-allocation/1');
|
|
385
|
+
if (value !== null) {
|
|
386
|
+
if (typeof value.set !== 'string' || name !== `painting_allocation.${encodeURIComponent(value.set)}.json`) {
|
|
387
|
+
refuse('PARTS_CHECK_REPORT', name, value.set ?? null, 'matching alternate-set identity', 'alternate report set disagrees with its inventory filename');
|
|
388
|
+
}
|
|
389
|
+
validateAllocation(name, value);
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
}
|
|
393
|
+
before.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
|
|
394
|
+
const report: PartsCheckReport = {
|
|
395
|
+
spec: PARTS_CHECK_SPEC, stage: 'parts', inputs: before,
|
|
396
|
+
parts: { primary: file?.parts.map(part => part.name) ?? [], alternates: canonical(file?.alternates ?? []) as unknown[],
|
|
397
|
+
source_cover: canonical(cover), painting_allocation: allocations },
|
|
398
|
+
refusals, reported, holes, exit_code: refusals.length === 0 ? 0 : 1,
|
|
399
|
+
};
|
|
400
|
+
if (JSON.stringify(before) !== JSON.stringify(inventory(false))) {
|
|
401
|
+
fatal('PARTS_CHECK_INPUT_CHANGED', '--parts', 'input inventory changed during the read; no report was published');
|
|
402
|
+
}
|
|
403
|
+
let created = false;
|
|
404
|
+
try {
|
|
405
|
+
mkdirSync(out, { recursive: true });
|
|
406
|
+
created = true;
|
|
407
|
+
writeFileSync(temporary, JSON.stringify(report, null, 2) + '\n', { flag: 'wx' });
|
|
408
|
+
if (JSON.stringify(before) !== JSON.stringify(inventory(false))) {
|
|
409
|
+
fatal('PARTS_CHECK_INPUT_CHANGED', '--parts', 'input inventory changed before publication; no report was published');
|
|
410
|
+
}
|
|
411
|
+
renameSync(temporary, destination);
|
|
412
|
+
} catch (error) {
|
|
413
|
+
if (created && existsSync(temporary)) rmSync(temporary);
|
|
414
|
+
if (error instanceof PartsError) throw error;
|
|
415
|
+
fatal('PARTS_CHECK_PUBLISH', '--out', `could not publish ${PARTS_CHECK_FILE}; ${error instanceof Error ? error.message.replaceAll(out, '--out') : String(error)}`);
|
|
416
|
+
}
|
|
417
|
+
for (const refusal of refusals) log(failLine(refusal));
|
|
418
|
+
for (const row of reported) log(`${row.code}: REPORTED part "${row.part}" — ${row.source}, ${row.count} px`);
|
|
419
|
+
for (const row of holes) log(row.line);
|
|
420
|
+
return report;
|
|
421
|
+
}
|