spine-parts 2.20.2 → 2.22.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/docs/AUTHORING.md CHANGED
@@ -160,6 +160,7 @@ read by no CPU stage).
160
160
  | `assemble.head_face_underfill` | assemble, `assemble --propose-plan` | **authored**, optional (issue #492): `boolean` (`CONFIG_FIELD_TYPE` on any other). During head-face preparation, when both runs exist and `full:face` has at least `150` opaque run px (`PROPOSE_MIN_PX`), the stage maps `full:face` into the head canvas via `fullLayerToHead` and measures how much of its hole-filled silhouette (`alpha > 8`) is covered by `head:face` (`alpha > 8`). An explicit plan selecting `head:face` is refused when that layer covers less than `75 %` (`HEAD_FACE_COVERAGE_FLOOR`, measured `0.0 %..48.6 %` on hollow/omitted head runs vs `84.8 %..99.6 %` on clean head runs across the 4 public examples and 9-standee corpus), with `SEETHROUGH_HEAD_RUN_HOLLOW`, unless `head_face_underfill: true` is declared. When `head_face_underfill: true` is declared and `head:face` exists (`opaqueRunPx >= 150`), `fullLayerToHead(full:face)` is composited under `head:face` on the head canvas (`alpha = max(headAlpha, fullAlpha)`, RGB blended by `headAlpha / 255`) before `head:face` is placed in rig space (`underfill=<N>px(full:face)` on the `face` part log line and a `face: head_face_underfill composited …` note in `assemble --propose-plan`). The fill restores transparent pixels only and leaves the cut's own edge where it is — a hollow whose edge is not under hair stays visible; follow [Source before scissors](#source-before-scissors) for its source remedy. When `head:face` has fewer than `150` opaque pixels, `SEETHROUGH_HEAD_RUN_HOLLOW` still fires even under `head_face_underfill: true` because the head run omitted the face layer and cannot supply a jawline. The proposer instead selects `full:face` after this refusal when that full-run candidate passes the pixel floor and plausibility guards (issue #863); if it does not, the refusal remains. An assemble plan selecting `full:face` without `head:face` does not prepare the unused head face |
161
161
  | `assemble.yield_refused` | assemble | **authored**, optional boolean, default `false` (issue #819; other types: `CONFIG_FIELD_TYPE`). With `true`, an original front projection-core pixel refused at max-channel drift > `DRIFT_LIMIT` (90) can yield when its original source pixel is still opaque. Non-core rim pixels (0 < alpha < `CORE_ALPHA`, 250) on the same 8-connected part body can then yield too (issue #832). Connectivity reads the part support before clearing: the opaque border outside the eroded projection core connects the body to its rim but is not itself newly cleared. A separate rim island without a yielded core seed is unchanged. At every cleared pixel, the actual top-most opaque holder below it (alpha >= 250), after earlier yields, must have colour within 90 of the painting. A deeper matching part cannot bypass an intervening opaque mismatch. This setting also applies to alternate sets. A yielded pixel's alpha becomes 0 and its RGB is not repainted. Accepted own-core pixels in the same connected support within the original yielded core's Gaussian footprint (radius 4 rig pixels), with a matching opaque behind holder, finish to painting RGB while retaining alpha and ownership (issue #841); original refusals, protected samples and replacements are excluded. Away from that footprint projection is unchanged. Merge/ring replacements, samples explicitly kept by `keep_under_occluders`, and pixels outside a derived piece cannot connect a rim or be newly yielded. Front is relative to the matching part behind, so original refusals in another run are eligible even when a different part is the global top holder. The reading proceeds back to front against the current behind pixels; alpha changes do not repaint or create a new matching colour. `yieldReadings` optionally records `finishedProjection` (accepted samples whose RGB changed), and records `yieldedRim` as the rim subset of total `yielded`, skipped core merge/ring/nonopaque/no-match counts and original/final global holders; a yielded pixel also taken by projection closing is omitted from the written `source_px_taken` count. Existing cuts/patches and thresholds are unchanged. The `drift:` line reports `yielded N px` per affected part, even below the drift-body size bar; with the setting off it names `assemble.yield_refused: true` as the conditional remedy. Rebuild and inspect the newly exposed layer in motion before considering any cut; a mismatching or absent behind holder cannot be repaired by this setting. |
162
162
  | `assemble.keep_under_occluders` | assemble | **authored**, optional array of unique source part names from `assemble.plan`, default `[]` (issue #825). For each named part, keep its own See-through RGBA where the front-most covering part in the final draw stack has alpha greater than 0 and below `CORE_ALPHA` (250), including a cover in the other run. Covers at raw alpha <= 8 are ghosts and are not kept under; a ghost-cleaned sample with final alpha 0 is absent cover and does not trigger restoration. Only original opaque own-layer samples are restored after source projection/closing and protected from later seam re-take; merged/rim, cap, under-fill and authored replacement pixels are excluded. This keeps their existing provenance and makes no holes; fully opaque cover and absent cover keep the old path. Cuts and limb pieces inherit the source part's protection. Unknown names: `CONFIG_NAME_RESOLVES`; duplicates: `CONFIG_PART_UNIQUE`; invalid shape: `CONFIG_FIELD_TYPE`. Inspect the part's own amodal layer first: this handle preserves its existing content and cannot complete a missing pixel — in particular, it does not close a motion opening inside the figure (`figure_openings` / [Openings inside the figure on undeclared layer pairs](#openings-inside-the-figure-on-undeclared-layer-pairs-issue-933)) where the lower layer has no opaque core under an opaque upper layer (measured with every `assemble.plan` part named in `keep_under_occluders`: `0` of `1` pair-animation warnings across `demo`'s eight animations closed, with `hair_back\|handwear_r` on `hop` frame `5` staying at `40` cells over `28` allowed in `38x70` world units at `2.517` world units/cell, while `scarf` reads `CLEAR` (`0` warnings) both with and without `keep_under_occluders`; use `assemble.extend_painting` when the lower part lacks opaque source material under an opaque upper cover). Example: `"keep_under_occluders": ["shin_r"]`. |
163
+ | `assemble.require_hidden_extent` | assemble, build | **authored**, optional array of unique `{part, occluder}` source-name pairs from `assemble.plan` (issue #1047). The distinct occluder must draw after the part. Before cleanup, projection, underfill, cuts or limb splitting, the original selected source is normalized to the rig grid. Own support is alpha >8. Its enclosed holes are `fillHoles(support) \ support`, using four-connected exterior background. Any hole cell under the resolved front-most named occluder (alpha >8) refuses `ASSEMBLE_HIDDEN_EXTENT_ABSENT`. Zero holes with measurable filled-support overlap passes. No overlap or unavailable original ancestry refuses `ASSEMBLE_HIDDEN_EXTENT_UNMEASURED`. A region take's output (`assemble.take`) counts as the selected source. Cover resolves over `assemble.plan` source families only; cut slots are not resolved as cover, which is a stated limit. Omitted or `[]` adds no reading or output. This is a source-support bar reached by build at assemble. See [Original hidden extent required](#original-hidden-extent-required). |
163
164
  | `assemble.editor_receipts` | assemble, build | **authored**, optional (issue #946): `{receipts: [{file, sha256, from_sha256, editor}], required?, trace_parts?}`. Each receipt records an image edited in an image editor; `file` (relative to the config's directory) must exist and hash to `sha256`, verified at assemble; `from_sha256` and `editor` are the author's declaration, held only to form. With `required: true`, every author-made layer, hidden-art layer, cut `under` and limb `cap` the build reads, alternate sets' runs included, needs a receipt whose `sha256` is its file's. With `trace_parts: true` (issue #947), every part's pixels must trace to a layer of the split or to a receipted image: the receipts are demanded as under `required`, and every shape the config draws through a part — a cut's `polygon`, `seethrough.arm_split`, a limb's `split.line`, a patch's `box`, a painting extension's `band` — is refused (`ASSEMBLE_PART_SOURCE`). Absent, no file is read and no byte moves. See [Editor receipts](#editor-receipts-assembleeditor_receipts-issue-946) and [Part sources](#part-sources-assembleeditor_receiptstrace_parts-issue-947). |
164
165
  | `limbs` | assemble (the cut and the caps), rig (through `regions`), check (`LIMB_ONE_BONE`) | **proposed** by `propose --keypoints` (issue #349), then checked: `{<limb>: {segments: [{part, from, bone}, {part, from, bone, joint, range?, cap?, edge?, cap_shape?, cut_band?, hybrid?}, …], split?, layout?, front?}}`, the upper segment first. The rule is *Limbs: cut at their joints* below the table. `part` is a new part (`CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` against the plan, patches, cuts and every other limb part); `from` a plan part or a cut's piece (`CONFIG_NAME_RESOLVES`) — the layer the segment's pixels come from, which is cut into the limb parts and is not itself made: a `meshes` or `regions` entry for it is `CONFIG_NAME_RESOLVES`, and the segments of one limb that take one part are consecutive (`CONFIG_LIMB_FROM_RUN`); `bone` a declared bone, each segment's the child of the one before (`CONFIG_LIMB_BONES_CHAIN`); the upper segment names no `joint`, `range`, `cap`, `edge`, `cap_shape` or `cut_band` (`CONFIG_KEY_KNOWN`), every other names its `joint` (`CONFIG_FIELD_PRESENT`) — the joint is its bone's origin; `range` is `[min, max]` degrees from rest with `min <= 0 <= max` (`CONFIG_LIMB_RANGE`), which `assemble` writes into the lower part's `parts.json` record and `check` poses the joint at — its two ends and its middle — reading the seam there (`SEAM_OVER_RANGE`, issue #360; rig-c needs no rotation limit); `cap` a PNG path relative to the config's directory (`CONFIG_FIELD_TYPE`); `edge` `"feather"` (issue #360), the one value it takes, and `cap_shape` `"disc"` (issue #360) or `"ball"` (issue #579) (`CONFIG_FIELD_TYPE` on any other) — the cut's geometry at that joint, *Limbs: cut at their joints* below; absent, the cut is hard and the cap the layer's half-disc of half the limb's width; `cut_band` a whole number of px, 1 or more (`CONFIG_FIELD_TYPE`), on a segment that takes the segment above's part — between two layers nothing is cut, so a band there is `CONFIG_KEY_KNOWN` — places the cut within that many px of the joint line (issue #360, *Limbs: cut at their joints*); absent, the cut is the joint line. Each limb part is attached like any part — `regions.<part>`, which must be the segment's `bone` (`CONFIG_LIMB_BONE`), or a mesh, which `check` holds to that bone alone (`LIMB_ONE_BONE`). With `limbs`, `assemble` reads `bones` too (`CONFIG_FIELD_PRESENT` without it). Absent, nothing is cut at a joint and no byte of any output moves. Optional `front` (issue #664), `{parts: [<own segment part>, …], after: "<produced part>"}`, gives each named segment a second slot `<part>_front`, empty at setup, placed after `after`'s slot family, for a gesture set to draw on (`CONFIG_FRONT_SCOPE`, `CONFIG_FRONT_NAME`, `CONFIG_FRONT_LAYOUT`; *Front slots (issue #664)* below) |
165
166
  | `bones` | rig; `propose --from-config` | **proposed** by `propose`, then corrected. A single bone `{name, parent, at, tip?}` or a chain `{chain, parent, points, tip, link_inherit?}` whose links are named `<chain>0 … <chain>n`. Parents come before children. In `rig.json` each link is **turned along its chain** — `rotation` is the direction from its origin to the next link's (the last link's to `tip`) and `length` that distance (issue #73), so a physics constraint added downstream finds a lever; under `--idle-keys ctl` the link's `<link>_ctl` carries the turn and the length and the link sits at local rotation 0 beneath it. A single bone with a `tip` is turned the same way, towards its tip, with that distance as its length (issue #239); a tip on the bone's own origin is refused (`RIG_TIP_DISTINCT`). The five face bones `eye_r`, `eye_l`, `brow_r`, `brow_l` and `mouth` (by name, when one has no tip of its own) are turned to the eye line — the line through the origins of `eye_r` and `eye_l` as `bones` writes them, read image-left to image-right, drawn when parts.json holds both an `eyewhite-r` and an `eyewhite-l` part — so the blink's `scaley` squashes across the eye line on a tilted head; move an eye bone and the line moves with it. With one eyewhite or none, or an eye bone missing, the rig stage's `face axis:` line says so and they keep the page's axes. A bone under a face bone keeps the face's axis. With the line, `rig.json` also declares `invariants.axes` — one entry, `"face"`, through `eye_r` and `eye_l`, holding the turned face bones (and their controls) — so rig-c's gate holds the build to the line; the line is the one rigc draws through the same two bones, so the tolerance is only the float floor — the largest gap the emitted (float32) bones have to it, rounded up to 6 places plus one 6-place unit — and the `face axis:` line prints it. With the line the rig stage also adds `head_up` (issue #250): a slotless bone under `head`, at head's origin, turned to the eye line + 90 degrees and as long as the eye midpoint lies from head's origin along that axis — the head's frame, which a rule that needs it reads; `head` keeps its own frame, so no key on it or under it changes meaning, and a config bone of that name is refused (`RIG_HEAD_UP_NAME_FREE`). A face bone with its own `tip` is held too (issue #258), in a second entry, `"face_tips"`, when its tip lies along the line within whole-pixel rounding — a tip written in whole pixels sits at most sqrt(2)/2 px off the point of the line it stands for, so its direction may sit up to asin((sqrt(2)/2) / length) degrees off — with its tolerance measured the same way; a tip further off is the bone's own axis, and the `face axis:` line names it with its gap and that bound. A failure is rig-c's `A51_BONES_LIE_ALONG_THEIR_DECLARED_AXIS` line, which names the bone and the fix (rig-c's `docs/AUTHORING.md` §3.7 and §5.2); with no line no entry is written and A51 reports SKIP. Every region on a turned bone is turned back, so the setup pose does not move. Any other single bone keeps world rotation 0; one whose parent is a link is turned back upright. A single bone may declare `inherit` (issue #348): what it takes from its parent's transform, one of rig-c's own mode names exactly as rig-c's table spells them — `normal`, `onlyTranslation`, `noRotationOrReflection`, `noScale`, `noScaleOrReflection` (rig-c's `RigBone.inherit`) — written to that bone in `rig.json` as declared; any other spelling, `"NoScale"` included (the runtime would fold its first letter; nothing here folds or maps), is refused (`CONFIG_BONE_INHERIT`), and a chain takes no `inherit` (`CONFIG_KEY_KNOWN`). A chain may instead declare `link_inherit` (issue #369), an object mapping its own expanded link names to those same modes, for example `"link_inherit": {"leg_r1": "noScale"}`. Only the named link changes; omitted links inherit normally. A key outside this chain is `CONFIG_NAME_RESOLVES`, with this chain's valid link names in the detail; a non-object or non-string mode is `CONFIG_FIELD_TYPE`, and another mode spelling is `CONFIG_BONE_INHERIT`. The mode is forwarded to the expanded link, or to its control under `--idle-keys ctl`, by the same rule as a single bone. This is an authored opt-in: `propose` does not add it. Its setup rotation is the turn from where rig-c's own poser puts the bone with no rotation of its own under that mode, so it still stands upright (or along its tip) at the setup pose. Where the idle gives the bone a `<bone>_ctl`, the mode goes on the control: the control is the bone the parent's rotation reaches, and the bone under it inherits normally, so the idle's keys moved onto the control still turn it. A foot that does not take its shin's rotation (`noRotationOrReflection` or `onlyTranslation`) keeps its shoe level while the leg is posed (`FEET_STAY_LEVEL`, §7); which mode is the author's. `noScale` keeps a shin or shoe's shape under a scaled parent but still takes the parent's rotation: a shoe that must also stay level needs a separate rotation constraint, for example a transform constraint from an unrotated bone. This does not change the proposed feet's existing inheritance or `FEET_STAY_LEVEL` default. An automatic mesh weighted through a bone with a mode other than `normal` gets no derived amplitude (its row names the bone) and no residual envelope (rig-c's `SKINNING_RANGE_UNSUPPORTED`). Absent, `rig.json` carries no `inherit` and no byte moves |
@@ -4595,6 +4596,46 @@ path. Declarations apply to the **base painting only** and are not inherited
4595
4596
  into alternate paintings. Native setup and animation boundary checks remain
4596
4597
  consumer acceptance work; assembly provenance does not establish motion quality.
4597
4598
 
4599
+ ### Per-pixel stage map
4600
+
4601
+ Declare `assemble.stage_map: true` to emit `stage-map.json` beside `parts.json`
4602
+ (`assemble --out work` writes `work/rig/stage-map.json`). Omitted or `false`
4603
+ disables it. Reusing an output directory with the option off removes its old map.
4604
+ The observer shares the aggregate classifier and leaves the other output bytes
4605
+ unchanged.
4606
+
4607
+ The JSON schema is `rig-parts-stage-map/1`. `rig_size` gives the rig width and
4608
+ height. `automatic` maps stage names to negative writer IDs. Positive ID `n`
4609
+ resolves to `edits[n - 1]`. Zero means final RGBA equals the part's original
4610
+ normalized source at the same rig-grid coordinate. `-2147483648` means excluded,
4611
+ final alpha at most 8. Other negative IDs name the last value-changing writer,
4612
+ including the explicit `unattributed` stage when lineage is unavailable.
4613
+
4614
+ `parts` follows the output draw order. Each row has `name`, `x`, `y`, `w`, `h`,
4615
+ `excluded_px` and `runs`. Each run is `[writer ID, length]`, with positive integer
4616
+ length. Expand runs consecutively in row-major order across row boundaries into
4617
+ exactly `w * h` cells. Cell index `k` is at rig coordinate
4618
+ `(x + k % w, y + floor(k / w))`, top-left origin, y down. Excluded cells have
4619
+ an independent count. The remaining histogram equals `unchanged_layer_px`,
4620
+ `hand_px`, `automatic_px` and every edit/stage subtotal in the part's provenance.
4621
+ `alternates`, when present, contains `{name, map}` rows with the same schema and
4622
+ only the records emitted for that set. Their part names match the alternate's
4623
+ `records`, and its `slots` resolve the emitted PNG names.
4624
+
4625
+ `pre_seam_writer_runs` uses the same RLE layout. Where the last-writer channel
4626
+ is `seamOverride`, it records the buffer's writer immediately before that seam
4627
+ change. Elsewhere `-2147483647` means no surviving override, and excluded cells
4628
+ use `-2147483648`. In this companion channel, zero means the prior buffer had
4629
+ no recorded writer. The writer before the seam override is a sparse boundary
4630
+ observation of that boundary alone. Only `runs`
4631
+ reconciles with aggregate provenance. A seam change that restores the raw
4632
+ source is classified unchanged and has no surviving override in this report.
4633
+
4634
+ Only final alpha above 8 is attributed. Cleared pixels and transient writes are
4635
+ outside this report. A final value restored to its original source is unchanged.
4636
+ A pixel changed by `seamOverride` after `paintingEdge` is attributed to
4637
+ `seamOverride`. The map records attribution and cannot determine intent.
4638
+
4598
4639
  ### Source before scissors
4599
4640
 
4600
4641
  <a id="source-before-scissors-issue-819"></a>
@@ -5245,6 +5286,9 @@ those settings. Changing a config seed alone cannot change a no-config run.
5245
5286
  | <a id="ASSEMBLE_PAINTING_EXTENSION_CONFLICT"></a>`ASSEMBLE_PAINTING_EXTENSION_CONFLICT` | two declared final parts can reach the same eligible painting pixel without explicit precedence | make their reachable claims disjoint, or declare a unique nonnegative integer `order` on every entry; lower orders claim first, never array order |
5246
5287
  | <a id="ASSEMBLE_PAINTING_CANVAS"></a>`ASSEMBLE_PAINTING_CANVAS` | a callable extension stage receives a part outside the rig canvas | pass the final in-canvas assembled stack with its crop offsets |
5247
5288
  | <a id="ASSEMBLE_PART_OPAQUE"></a>`ASSEMBLE_PART_OPAQUE` | a part ended with no opaque pixel | drop the entry, or take the tag from the other run |
5289
+ | <a id="ASSEMBLE_HIDDEN_EXTENT_ABSENT"></a>`ASSEMBLE_HIDDEN_EXTENT_ABSENT` | a declared `assemble.require_hidden_extent` pair has an enclosed own-source hole beneath its resolved front-most occluder, before cleanup or any writer. The refusal names both source parts, original run:tag, absent/overlap rig-cell counts, soft/opaque cover counts and the first cell | supply a source that already carries the extent, such as a second decomposition run. That source-production route is separate from this change. [Original hidden extent required](#original-hidden-extent-required) states the domain and open-cuff boundary |
5290
+ | <a id="ASSEMBLE_HIDDEN_EXTENT_UNMEASURED"></a>`ASSEMBLE_HIDDEN_EXTENT_UNMEASURED` | a declared pair has no filled own-support overlap under the resolved occluder, empty own support, unavailable original selected-layer ancestry or a partial alternate replacing only one declared source family | resolve the original sources and their declared overlap. An empty hole set with measurable overlap is a valid zero reading. See [Original hidden extent required](#original-hidden-extent-required) |
5291
+ | <a id="CONFIG_HIDDEN_EXTENT_ORDER"></a>`CONFIG_HIDDEN_EXTENT_ORDER` | `assemble.require_hidden_extent` names the same source as part and occluder, or names an occluder drawn before the part | declare distinct source parts with the occluder after the part in `assemble.plan` |
5248
5292
  | <a id="DIFF_COMPONENTS_INPUT"></a>`DIFF_COMPONENTS_INPUT` | `diff-components` needs readable PNG stack/painting/part images, a writable `--out` target when writing, explicit parts, positive integer floor, a finite threshold in [0,255], matching native dimensions and valid coverage/domain inputs; flags must be unique and known, with nonempty values | Supply the named missing or invalid input; no resampling or inferred figure is performed |
5249
5293
  | <a id="DIFF_COMPONENTS_BINDING"></a>`DIFF_COMPONENTS_BINDING` | The shipped report reader found a stack or painting SHA-256 different from the supplied bytes; found and required digests are printed | Regenerate against the bytes being reviewed |
5250
5294
  | <a id="DIFF_COMPONENTS_REPORT"></a>`DIFF_COMPONENTS_REPORT` | Invalid report JSON/spec, or its exhaustive inventory, definition, paths, domain or coverage differs from remeasurement; capped inventories are refused | Regenerate the complete versioned report against the same input paths, bytes, parts and figure domain |
@@ -5624,7 +5668,7 @@ documents do not ship). Each is an input this package built; none is an author's
5624
5668
  | <a id="SEAM_OVER_MOTION"></a>`SEAM_OVER_MOTION` | **Existing internal-joint and explicit-seam pairs remain warnings** (issue #493; a seam that opens in motion may be intended). **Proven body-root pairs are a bar** (issue #686): an above-floor opening adds `CHECK_SEAM_OVER_MOTION`, sets `PASS` false and exits 1. **Under the requirements file's `seam_over_motion.required: true`** (issue #941) every declared pair, of all three classes, is also held to 0 background cells on every frame — [`CHECK_SEAM_OVER_MOTION_REQUIRED`](#CHECK_SEAM_OVER_MOTION_REQUIRED); undeclared, nothing in this row moves. Every declared neighbour pair — each limb's two segments at a joint, the upper and the one below (`parts.json`'s limb records, `config.limbs`), and under `--requirements` each `seam`'s `part` and `neighbour`, one pair however many declare it — read in every animation `motion.json` holds, the idle included, by rig-c's seam reading: one `rigc render --seam <a>:<b>,… --fps 12` over the packed build as played (physics on), whose `seam.json` (`rigc-seam/1`, rig-c's AUTHORING §8.8) names per pair and frame a **gap** (background inside the joint) or a **ghost** (one piece's overlap band swung clear of its partner), each frame's cells (`px`, one texel of the coarser drawing — a rig px on a build at scale 1), its cell size and its world box. Printed for existing warning pairs and animations with a frame over the floor: `WARN seam "<a>\|<b>" opens on N frame(s) [<frames>] max <px> px in "<animation>" — over the one-cell floor`, then how many more frames rigc named that were under it. **The floor**: a frame's gap or ghost is reported when it holds more cells than its box is long (its longer side, in cells) — thicker than one cell. A cell is drawn when the renderer paints its centre at half opacity, so an outline that moves by less than a cell flips the cells along it: a line one cell deep, joined or scattered, holds at most as many cells as its box is long, and a hole of any area more. The rule types no number; measured on `examples/wind`'s idle, rigc names 43 openings over its six limb pairs (the two elbows, 1 to 5 cells, boxes up to 17 cells long), every one one cell thick, and on rig-c's `gallery/walk` 13 joint cracks of 1 to 3 cells, all one cell thick. `check.json`'s `SEAM_OVER_MOTION` holds `status` (`WARN`, `CLEAR`, `SKIP`, or `FAIL` for a new root tear), `fps`, `floor`, `pairs`, `animations`, `warnings` and one row per pair and animation (`opens` and `px` over the floor, `max_px`, `under_floor`, rigc's `status`, `drawn` and `banded`); for existing warning pairs it moves no exit status, no `check: PASS` and no bar count — the summary ends `; N warning(s) (SEAM_OVER_MOTION, not a bar)`. **SKIP**, named: no pair declared (no limb segment, no `seam`; then `check.json` has no key), no `parts.json`, no animation, every pair naming a slot `rig.json` lacks (each printed `not read`), or rigc reading no band on any frame of any pair (rigc's own `skip`: the two drawings share no cell at rest) — nothing measured, never a pass | [Source before scissors](#source-before-scissors) first; if the opening is not intended: a cap that covers the turn (`config.limbs`, *Limbs: cut at their joints*; `limb cap:` names the pixels the layer lacks), or a motion that bends that joint less; if it is intended, nothing |
5625
5669
  | <a id="CHECK_MOTION_SEAM_ROOT"></a>`CHECK_MOTION_SEAM_ROOT` | a body-root declaration has missing or ambiguous segment0, bone, parent, slot or default-skin attachment; the refusal names the part and candidates | supply the declared one-to-one hierarchy/slot/provenance binding; no nearest or mesh-influence fallback |
5626
5670
  | <a id="CHECK_SEAM_OVER_MOTION"></a>`CHECK_SEAM_OVER_MOTION` | a proven body-root pair has an active animation gapOpen plus UNDER-owned ghost above the unchanged one-cell floor; the refusal names pair, animation, frame, cells, cell size and world box | [Source before scissors](#source-before-scissors) first; repair the declared rest overlap or authored motion; the existing internal-joint warning policy and physics reference worlds are unchanged |
5627
- | <a id="CHECK_SEAM_OVER_MOTION_REQUIRED"></a>`CHECK_SEAM_OVER_MOTION_REQUIRED` | the requirements file declares `seam_over_motion.required: true` (issue #941; [Background over every frame](#background-over-every-frame-issue-941)) and a declared seam pair — body-root, internal-joint or explicit — shows background on a frame: rigc's `gapOpen` (a gap cell inside the carried setup-overlap band where the whole skeleton composite has alpha 0) above 0 on any frame of any animation `motion.json` holds, every frame at 12 fps, no floor. The refusal names the class, the pair, the animation, the worst frame and its time, the frames that open, the cells found, the cell size and the world box, against 0 required. Also refused under the declaration, since a SKIP is never a pass: `SEAM_OVER_MOTION` itself a SKIP (no pair or no animation to read), a pair naming a slot `rig.json` lacks, or a pair and animation rigc read no band in | the art or the motion, by the file the refusal points at: [Source before scissors](#source-before-scissors) first — the layer that holds the pixels under the joint (`config.assemble`, `extend_painting`); then the joint's cap (`config.limbs`, *Limbs: cut at their joints*), or the keys that pull the pieces apart (`motion.json` through `config.motion` or the animations file `animations_from` names). For a SKIP, declare the pairs (`config.limbs`, `config.motion_seams`, a `--requirements` `seam`) or drop the declaration from the requirements file |
5671
+ | <a id="CHECK_SEAM_OVER_MOTION_REQUIRED"></a>`CHECK_SEAM_OVER_MOTION_REQUIRED` | the requirements file declares `seam_over_motion.required: true` (issue #941; [Background over every frame](#background-over-every-frame-issue-941)) and a declared seam pair — body-root, internal-joint or explicit — shows background on a frame: rigc's `gapOpen` (a gap cell inside the carried setup-overlap band where the whole skeleton composite has alpha 0) above 0 on any frame of any animation `motion.json` holds, every frame at 12 fps, no floor. The refusal names the class, the pair, the animation, the worst frame and its time, the frames that open, the cells found, the cell size and the world box, against 0 required. Also refused under the declaration, since a SKIP is never a pass: `SEAM_OVER_MOTION` itself a SKIP (no pair or no animation to read), a pair naming a slot `rig.json` lacks, or a pair and animation rigc read no band in | the art or the motion, by the file the refusal points at: [Source before scissors](#source-before-scissors) first — the layer that holds the pixels under the joint (`config.assemble`, `extend_painting`); then the joint's cap (`config.limbs`, *Limbs: cut at their joints*), or the keys that pull the pieces apart (`motion.json` through `config.motion` or the animations file `animations_from` names). For a SKIP, declare the pairs (`config.limbs`, `config.motion_seams`, a `--requirements` `seam`) or drop the declaration from the requirements file. For a `figure` gapOpen classification, declare `assemble.require_hidden_extent: [{part, occluder}]` to learn whether the original layer carries the enclosed hidden extent. See [Original hidden extent required](#original-hidden-extent-required). |
5628
5672
  | <a id="CLOTH_SETTLES"></a>`CLOTH_SETTLES` | **a warning, never a refusal** (issue #501; the owner's ruling: cloth at rest while the character stands may be intended). Every physics chain, read by its tip on the idle `check` renders — `rigc render --animation idle --fps 12 --geometry`, physics on, rigc's default environment. A chain is a **physics leaf** — a bone a physics constraint names (`rig.json`'s `constraints` or `motion.json`'s `physics`) with no such bone under it — and the run of physics bones above it; its tip is the leaf's end (origin plus `length` along its world x axis), or its origin when the leaf has no length; its speed between frames is the tip's distance over their time, from the idle's `geometry.json`. A chain **settles** at the first frame from which every speed to the idle's last frame is under the floor, and each one that does — before the loop's length is out — prints `WARN chain "<root>" .. "<tip>" (N physics link(s)) settles at <t> s of the <d> s idle — its tip's end under 0.01694 rig px/s from there to the last frame (fastest on the idle <v> rig px/s)`. **The floor**, 0.01694 rig px/s, is derived, not chosen: half the slowest tip an idle key drives on the public examples (the repository's floor rule, half the weaker figure) — measured with this port's build of each (rig-c 2.60.0), over the 31 chains a keyed bone at or above the leaf drives (`demo` 12, `reference-sample` 1, `scarf` 11, `wind` 7) the slowest frame-to-frame tip speed is `scarf`'s `skirt_l2`, 0.03388 rig px/s; the ten no key drives — `wind`'s skirt, eight trees and the swing, hung from a `hip` its idle never keys, and `reference-sample`'s `hip_jiggle` — fall under it from 1.5 to 2.75 s on a 3.333 s idle (`hip_jiggle` at 0 s: it never moves) and end at 0.0025 rig px/s or less. `check.json`'s `CLOTH_SETTLES` holds `status` (`WARN`, `CLEAR`), `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings` and one row per chain (`tip`, `root`, `links`, `point` — `end` or `origin` — `settles_at`, null when it does not, `max_rig_px_per_s`, `min_rig_px_per_s`); it moves no exit status, no `check: PASS` and no bar count — the summary's warning clause names it, `; N warning(s) (CLOTH_SETTLES, not a bar)` (with `SEAM_OVER_MOTION` before it, and N their sum, where that read a pair). It reads the idle alone, one loop from rigc's physics reset at frame 0: a chain that settles later than the idle is long is not seen. **SKIP**, named: no physics constraint (then `check.json` has no key), or no idle — nothing measured, never a pass | if the chain should move while the character stands, one of the consumer's two levers: an environment at render (`rigc render --environment`, wind and gravity in time — rig-c's AUTHORING §8.4), or a consumer's animation that moves the bone the chain hangs from. The drafted idle keys no hip, by measurement: a hip turn at the idle's period fails a bar on all five public examples (issue #502, §3 *What moves them*). A `cloth` recipe's skirt hangs from `hip`, which the drafted idle never keys (§3, *Recipe: cloth and hair that answer the world*, *What moves them*, which has a worked schedule for `wind`). If it is intended, nothing |
5629
5673
  | <a id="figure_openings"></a>`figure_openings` | **a warning, never a refusal** (issue #933; see [Openings inside the figure on undeclared layer pairs](#openings-inside-the-figure-on-undeclared-layer-pairs-issue-933)). Reads transparent openings inside the pair's own posed hole-filled union (`alpha == 0` inside `fillHoles(a ∪ b)`, excluding cells already transparent at setup) across every undeclared setup-overlapping (`alpha >= 128`) layer pair in `rig.json` draw order in every animation `motion.json` holds at 12 fps (`scale = 1 / cell`). Prints `figure_openings: CLEAR — N undeclared setup-overlapping pair(s) in M animation(s) (<names>) at 12 fps (cell <cell> world units): 0 warning(s), never a bar` when clean, `figure_openings: WARN — …` followed by one `WARN opening "<a>\|<b>" above "<above>" (under "<under>") on K frame(s) [<frames>], worst frame <f> (t = <t>s) in "<animation>": found <found_cells> cell(s), <= <allowed_cells> cell(s) allowed in <w>x<h> world units at <cell> world units/cell — transparent opening inside the figure over motion on an undeclared layer pair (not a bar)` line per opening above the one-cell floor (`found_cells > allowed_cells`), or `figure_openings: SKIP — <reason>` when there is no `parts.json`, no animation, or no undeclared setup-overlapping pair. `check.json`'s `figure_openings` is written whenever the reader ran (`status` `"CLEAR"` or `"WARN"`), holding `status`, `fps`, `cell`, `pairs`, `animations`, `warnings` and `openings` (`pair`, `under`, `above`, `animation`, `frame`, `time`, `opens`, `cell`, `found_cells`, `allowed_cells`, `box`); it moves no exit status, no `check: PASS` and no bar count | if the opening is an unintended tear where a lower layer lacks opaque art under an opaque upper layer, use `assemble.extend_painting` (not `assemble.keep_under_occluders`, which only preserves existing `alpha >= 250` lower pixels under a translucent cover), or adjust mesh weights / motion keys; if it is a deliberate silhouette loop shifting in world space, nothing |
5630
5674
  | <a id="CHECK_FOLDS_READ"></a>`CHECK_FOLDS_READ` | the fold render's `frames.json` names no set for an animation, a `folds.json` is missing, not `rigc-folds/1`, another animation's or another rate's, or a folding mesh has no line rigc printed for it | a rigc problem; report it, with `rigc --version` |
@@ -5754,6 +5798,16 @@ The body-root bar counts stock partitions `gapOpen` plus `ghostA` or `ghostB` ow
5754
5798
 
5755
5799
  **Why `fillHoles(a ∪ b)` and why warning (`WARN`), not a bar:** counting only cells inside the holes of the pair's own posed union (`fillHoles(a ∪ b)`) rather than of the whole figure (`fillHoles(frameUnion)`) eliminates all `36` third-part pocket warnings on `demo` (where a cheek-to-ponytail or arm-to-waist pocket is closed only by a third part such as the collar, shoulder or torso), so all five public examples read `CLEAR` (`0` warnings) on `idle`, and `reference-demo`, `reference-sample`, `scarf` and `wind` read `CLEAR` (`0` warnings) across every animation. The single remaining warning across all five public examples (`demo` `hair_back|handwear_r` on `hop` frames `[5-6]`, worst frame `5` at `t = 0.417s`: `found 40 cell(s), <= 28 cell(s) allowed in 38x70 world units at 2.517 world units/cell`) was visually inspected and is a false positive from a silhouette loop between `hair_back` and `handwear_r` themselves: on `demo`, `hair_back`'s right twin-tail curls inward behind the right arm and touches `handwear_r` both above (at the puff sleeve) and below (at the curled hair tip near the wrist), so `hair_back ∪ handwear_r` alone encloses a small background window between the forearm and the curling hair lock; when the character jumps in `hop`, that window shifts into the world cells that `hair_back` and `handwear_r` covered at `t = 0`. Because two layers with curved silhouettes can enclose a deliberate background loop between themselves during a jump, `figure_openings` is a **warning (`WARN`, never a bar)**.
5756
5800
 
5801
+ <a id="original-hidden-extent-required"></a>
5802
+
5803
+ **Original hidden extent required** (issue #1047). A moving cover can reveal an enclosed hole the lower source never carried. Declare `assemble.require_hidden_extent: [{"part":"behind","occluder":"front"}]` to require that material at assemble. Names are original `assemble.plan` source names, before cuts and limb descendants. The declaration applies a source obligation for that moving cover without an animation filter. An alternate selecting both source families checks its own original sources. An alternate selecting only one refuses as unmeasured because the pair's original selected material is unavailable there. An alternate selecting neither retains the checked base material.
5804
+
5805
+ On the normalized original selected-run RGBA, let `S = alpha >8`, `F = fillHoles(S)` and `H = F \ S`. Exterior background reachability is four-connected. Let `C` select cells where the named occluder is the front-most other original source family at alpha >8, in production source-family draw order. The absent domain is `H ∩ C`, and the measurable overlap is `F ∩ C`. Any absent-domain cell refuses before output. Zero absent cells with measurable overlap passes. All declared pairs are read before refusal. Cuts, underfill, painting extension and later writers cannot provide the original baseline.
5806
+
5807
+ **Open-cuff boundary.** A cover at an open edge, such as a hand at a sleeve cuff, is outside the enclosed-hole domain when the missing region reaches exterior background through a four-connected path. This rule does not detect that missing open-edge extent. A deliberately open source shape does not become an inferred silhouette.
5808
+
5809
+ The `seam_over_motion.required` figure/background classification points here as a source diagnosis. Its existing zero-gapOpen bar and `figure_openings` warning retain their current definitions. This source-support bar runs during assemble and build's assemble stage. A source carrying the absent extent is required, and producing one through a second decomposition run is a separate route.
5810
+
5757
5811
  **How `assemble.keep_under_occluders` relates:** `assemble.keep_under_occluders` only preserves a named lower part's original See-through RGB where the lower layer **already has** `alpha >= 250` (`CORE_ALPHA`) beneath a translucent front cover (`0 < alpha < 250` in the final stack). Where an upper layer was opaque at setup (`alpha >= 250`) or the lower layer had no opaque core under the upper layer (or where a silhouette loop shifts in world space), `keep_under_occluders` changes nothing: measured with every `assemble.plan` part named in `keep_under_occluders`, **0 of 1** pair-animation warnings on `demo` closed (`hair_back|handwear_r` on `hop` frame `5` stayed at `40` cells over `28` allowed in `38x70` world units at `2.517` world units/cell), and `scarf` read `CLEAR` (`0` warnings) both with and without `keep_under_occluders`. To close a genuine tear where the lower layer lacks opaque art under an opaque upper layer, use `assemble.extend_painting` (or adjust mesh weights / motion keys so the upper part does not slide off the lower part's boundary). **Diagnostic preview background:** `rigc render` composites diagnostic frame PNGs over `BACKGROUND = [232, 232, 232, 255]` (`#e8e8e8` light grey), which visually masks an `alpha == 0` sliver next to light cloth, pale hair or skin; reading `alpha == 0` on the posed skeleton's transparent composite catches the opening regardless of preview background colour.
5758
5812
 
5759
5813
  ### compose
package/docs/STABILITY.md CHANGED
@@ -153,7 +153,8 @@ part name, `[i]` an entry of a list):
153
153
  - **generation.control.skeleton**, the pose file it names when it is no built-in — required: `width`, `height`, `points`
154
154
  - **seethrough** — required: `resolution`, `steps`, `seed`, `offload`; optional: `head_box`, `arm_split`
155
155
  - **seethrough.arm_split** — required: `order`, and one of `x` or `line` (issue #439)
156
- - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `keep_under_occluders`, `extend_painting`, `take`, `editor_receipts`
156
+ - **assemble** — required: `rig_scale`, `plan` (from plain `assemble` on); optional: `seam`, `project`, `ground`, `extend_below_crop`, `patches`, `cuts`, `alternates`, `head_face_underfill`, `yield_refused`, `stage_map`, `keep_under_occluders`, `require_hidden_extent`, `extend_painting`, `take`, `editor_receipts`
157
+ - **assemble.require_hidden_extent[i]** — required: `part`, `occluder`
157
158
  - **assemble.alternates[i]** — required: `name`; optional: `source`, `full`, `head`, `parts`, `hides`, `head_box`, `cuts`, `skeleton`, `anchor`, `base_anchor`, `drawn`, `tips`, `front`, `layers`, `focus` (issues #454, #465, #543, #652, #664, #666, #719, #780). `focus` is an authored finite `[x, y]` in painting pixels, within its canvas (edges included), refused as CONFIG_SET_FOCUS before assemble output when invalid; only when present, `parts.json` records it with focus_source_size and `sets.json` emits it in setup-world coordinates through the actual rig resize and `src/coords.ts`. Absent focus emits no field or inferred value; changing/removing it requires reassembly
158
159
  - **assemble.extend_below_crop[i]** — required: `part`, `run`, `tag`; optional: `edges` (left, right, top, bottom; explicit edges require a head-run part and the full-run layer of the same tag)
159
160
  - **assemble.extend_painting[i]** — required: `part`, `band`, `max_distance`; optional: `min_held_alpha`, `order` (issues #848, #854, #855; explicit final layer-derived part, half-open rig band and positive four-neighbour path bound; base painting only). The optional integer floor 1–255 admits exact original alpha-over coverage strictly below it; absent or 1 blocks every nonzero holder. Only selected target samples below the floor may take painting RGBA; target samples at/above the floor and every non-target holder remain exact. By default overlapping reachable claims refuse. With `order` on every entry (unique nonnegative safe integers), lower values claim first and their gains block later candidates and paths; array order never breaks ties or supplies missing precedence
@@ -298,6 +299,7 @@ resolution before resizing; it can differ for non-opaque paintings.
298
299
 
299
300
  | file | written by | what is stable |
300
301
  | --- | --- | --- |
302
+ | `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). |
301
303
  | `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) |
302
304
  | `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) |
303
305
  | `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) |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "spine-parts",
3
- "version": "2.20.2",
3
+ "version": "2.22.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
@@ -1,3 +1,4 @@
1
+ import { hiddenExtentProblems, type HiddenExtentDeclaration, type HiddenExtentSource } from './hiddenextent.ts';
1
2
  import { headBoxInside } from './headbox.ts';
2
3
  import { edgePairResiduals, type EdgeResidualReport } from './edgeresidual.ts';
3
4
  import type { SupportDomain } from './coincide.ts';
@@ -9,7 +10,7 @@ import { materialSource, type MaterialSource, materialRows, polygonMaterialEdges
9
10
  import { unionTakenSources } from './takesource.ts';
10
11
  import { authoredUnitDepths, type AuthoredUnitDepth } from './authoredunit.ts';
11
12
  import { paintingExtensionMasks, paintingExtensionProblems, type PaintingExtension } from './paintingextension.ts';
12
- import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline } from './provenance.ts';
13
+ import { AUTOMATIC_WRITERS as AW, compactValueBaseline, pixelProvenance, rgbaEqual, type ValueBaseline, type StageMap } from './provenance.ts';
13
14
  import { bindDepthRun, copyDepthMaterial, registerDepthRun, transportPartDepth, type DepthConfig, type RegisteredDepth } from './depthsheets.ts';
14
15
  /**
15
16
  * The assemble stage: two See-through runs over one painting — a FULL-body run
@@ -363,8 +364,12 @@ export interface AssembleInput {
363
364
  headFaceUnderfill?: boolean;
364
365
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
365
366
  yieldRefused?: boolean;
367
+ /** Report-only last-writer sidecar, default off. */
368
+ stageMap?: boolean;
366
369
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
367
370
  keepUnderOccluders?: readonly string[];
371
+ /** Original selected material must cover its enclosed holes beneath this source pair. */
372
+ requireHiddenExtent?: readonly HiddenExtentDeclaration[];
368
373
  /** Base painting only; named final parts, explicit band and path bound (#848). */
369
374
  paintingExtension?: readonly PaintingExtension[];
370
375
  /**
@@ -4717,6 +4722,8 @@ export function softOcclusionLine(r: SoftOcclusionReading): string {
4717
4722
  }
4718
4723
 
4719
4724
  export interface AssembleResult {
4725
+ /** Compressed per-pixel classification, present only when requested. */
4726
+ stageMap?: StageMap;
4720
4727
  /** The already-resampled opaque painting used by this assembly. */
4721
4728
  paintingInRig: Raster;
4722
4729
  /** Report-only residual candidates, present after the visible edge pass. */
@@ -4965,7 +4972,7 @@ export function assemble(input: AssembleInput): AssembleResult {
4965
4972
  if (input.regionTake === undefined) return assembleParts(input);
4966
4973
  const targets = regionTakeTargets(input.regionTake.targets, input.cuts, input.limbs);
4967
4974
  const counterfactual = input.projectRule === 'core' ? { cleanup: new Map<string, RunLayer[]>(), seam: new Map<string, Uint8Array>() } : undefined;
4968
- const before = assembleParts({ ...input, full: input.regionTake.full, head: input.regionTake.head, regionTake: undefined }, targets, null, counterfactual);
4975
+ const before = assembleParts({ ...input, full: input.regionTake.full, head: input.regionTake.head, regionTake: undefined, requireHiddenExtent: undefined }, targets, null, counterfactual);
4969
4976
  return assembleParts(input, targets, before, counterfactual);
4970
4977
  }
4971
4978
 
@@ -4992,6 +4999,26 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
4992
4999
  refuseIfAny(depthInputProblems);
4993
5000
  // Issue #366: one run's file, padded to the resolution square; read as both runs, as before.
4994
5001
  const fullPadded = single ? padSingleRun(depthFullInput, frame, input.resolution) : depthFullInput;
5002
+ if ((input.requireHiddenExtent?.length ?? 0) > 0) {
5003
+ // Read the selected original layers, before split/underfill/cleanup can replace their material.
5004
+ const originals = input.plan.map(([name, run, tag]): HiddenExtentSource => {
5005
+ const set = run === 'full' ? fullPadded : depthHeadInput;
5006
+ const layer = set.layers.find(candidate => candidate.name === tag);
5007
+ return { name, from: `${run}:${tag}`, image: layer === undefined ? null : layerToRig(placeLayer(layer, input.resolution), frame, run) };
5008
+ });
5009
+ const painting = patches.length === 0 ? null : sourceInRig(source, frame.W, frame.H);
5010
+ const silhouette = painting === null ? null : figureSilhouette(painting);
5011
+ const sources: HiddenExtentSource[] = [];
5012
+ for (const slot of drawOrder(input.plan.map(([name]) => name), patches)) {
5013
+ if ('plan' in slot) sources.push(originals[slot.plan]);
5014
+ if ('patch' in slot) {
5015
+ const patch = patches[slot.patch];
5016
+ const placed = cutPatch(patch, painting as Raster, silhouette);
5017
+ sources.push({ name: patch.name, from: 'painting:patch', image: placed?.image ?? newRaster(1, 1), x: placed?.record.x ?? 0, y: placed?.record.y ?? 0 });
5018
+ }
5019
+ }
5020
+ refuseIfAny(hiddenExtentProblems(input.requireHiddenExtent!, sources, frame.W, frame.H));
5021
+ }
4995
5022
  // Issue #439: when seethrough.arm_split is declared, split the full run's overlapping handwear into handwear-r and handwear-l.
4996
5023
  const fullArmSplit = input.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, input.resolution, input.armSplit);
4997
5024
  // Issue #490: when generation.control.skeleton is present, split merged arm layers (or refuse when sleeve and drape share one colour).
@@ -6000,16 +6027,48 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6000
6027
  const map = runMap(frame, run), dx = single ? frame.fullPad : 0, dy = single ? frame.fullPadTop : 0;
6001
6028
  for (const layer of set.layers) if (layer.regionSelection !== undefined) regionSupport.set(`${run}:${layer.name}`, warpSupport(layer.regionSelection, { sx: map.sx, sy: map.sx, tx: map.tx + dx * map.sx, ty: map.ty + dy * map.sx }, W, H, map.k < 1 ? 'bilinear' : 'bicubic'));
6002
6029
  }
6003
- seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder, input.turnMovingPair ?? null, (i, p) => { writersInOrder[i][p] = AW.seamOverride; }, counterfactual === undefined ? undefined : beforeTake === null ? { record: counterfactual.seam } : { baseline: counterfactual.seam, support: regionSupport });
6030
+ const preSeamWriters = input.stageMap === true ? new Map<number, Map<number, number>>() : undefined;
6031
+ seamOverride(placed, srcr, seamRule, seamRule === 'silhouette' ? silhouette : null, keepInOrder, input.turnMovingPair ?? null, (i, p) => {
6032
+ if (preSeamWriters !== undefined) {
6033
+ const changed = preSeamWriters.get(i) ?? new Map<number, number>();
6034
+ changed.set(p, writersInOrder[i][p]);
6035
+ preSeamWriters.set(i, changed);
6036
+ }
6037
+ writersInOrder[i][p] = AW.seamOverride;
6038
+ }, counterfactual === undefined ? undefined : beforeTake === null ? { record: counterfactual.seam } : { baseline: counterfactual.seam, support: regionSupport });
6039
+ const stageMap: StageMap | undefined = input.stageMap !== true ? undefined : {
6040
+ schema: 'rig-parts-stage-map/1', rig_size: [W, H], automatic: AW, edits: [...editNames], parts: [],
6041
+ };
6004
6042
  placed.forEach((p, i) => {
6005
- p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null);
6043
+ const map = stageMap === undefined ? undefined : {
6044
+ name: p.record.name, x: p.record.x, y: p.record.y, w: p.record.w, h: p.record.h,
6045
+ excluded_px: 0, runs: [] as Array<[number, number]>, pre_seam_writer_runs: [] as Array<[number, number]>,
6046
+ };
6047
+ p.record.provenance = pixelProvenance(p.image, p.record.x, p.record.y, W, writersInOrder[i], editNames, 0, valueBaselines.get(p.record.from) ?? null, map, preSeamWriters?.get(i));
6048
+ if (map !== undefined) stageMap!.parts.push(map);
6006
6049
  const depth = authoredDepths.get(p.record.name);
6007
6050
  if (depth !== undefined) p.record.provenance.depth = depth;
6008
6051
  });
6009
- if (beforeTake !== null) retainRegionNeighbours(placed, beforeTake.images, targets!);
6052
+ if (beforeTake !== null) {
6053
+ retainRegionNeighbours(placed, beforeTake.images, targets!);
6054
+ if (stageMap !== undefined) stageMap.parts = stageMap.parts.map(p => {
6055
+ if (targets!.has(p.name)) return p;
6056
+ const previous = beforeTake.stageMap!;
6057
+ const original = previous.parts.find(q => q.name === p.name)!;
6058
+ const remap = ([id, length]: [number, number]): [number, number] => {
6059
+ if (id <= 0) return [id, length];
6060
+ const edit = previous.edits[id - 1];
6061
+ let index = stageMap.edits.indexOf(edit);
6062
+ if (index < 0) { index = stageMap.edits.length; stageMap.edits.push(edit); }
6063
+ return [index + 1, length];
6064
+ };
6065
+ return { ...original, runs: original.runs.map(remap), pre_seam_writer_runs: original.pre_seam_writer_runs.map(remap) };
6066
+ });
6067
+ }
6010
6068
  // Provenance is now numbers/labels only. No later raster/figure operation
6011
6069
  // reads report buffers; release all aliases before recomposite/error work.
6012
6070
  valueBaselines.clear();
6071
+ preSeamWriters?.clear();
6013
6072
  writersInOrder.length = 0;
6014
6073
  patchWriters.length = 0;
6015
6074
  for (const group of [built, pieces, cutSources, limbPieces]) for (const b of group) if (b !== null) b.writers = undefined;
@@ -6047,6 +6106,7 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
6047
6106
  ...(softOcclusion.length === 0 ? {} : { softOcclusion }),
6048
6107
  ...(!single ? { cropClipped: cropClippedLines(plan, extend, (run, tag) => rig.get(`${run}:${tag}`) ?? null, frame) } : {}),
6049
6108
  paintingInRig: srcr,
6109
+ ...(stageMap === undefined ? {} : { stageMap }),
6050
6110
  parts: {
6051
6111
  rig_size: [W, H],
6052
6112
  scale_rig_per_source: frame.S,
@@ -6985,8 +7045,12 @@ export function stageFields(
6985
7045
  headFaceUnderfill?: boolean;
6986
7046
  /** `assemble.yield_refused`, default false; transfer of refused cores/rims, finishing nearby accepted projection RGB. */
6987
7047
  yieldRefused?: boolean;
7048
+ /** Report-only last-writer sidecar, default off. */
7049
+ stageMap?: boolean;
6988
7050
  /** Plan parts whose own samples survive source re-take beneath soft front cover. */
6989
7051
  keepUnderOccluders?: readonly string[];
7052
+ /** Original selected material must cover its enclosed holes beneath this source pair. */
7053
+ requireHiddenExtent?: readonly HiddenExtentDeclaration[];
6990
7054
  /** Base painting only; named final parts, explicit band and path bound (#848). */
6991
7055
  paintingExtension?: readonly PaintingExtension[];
6992
7056
  turnMovingPair?: (a: string, b: string) => boolean;
@@ -7016,7 +7080,9 @@ export function stageFields(
7016
7080
  ...(keySkeleton === undefined ? {} : { keySkeleton }),
7017
7081
  ...(cfg.assemble.head_face_underfill === undefined ? {} : { headFaceUnderfill: cfg.assemble.head_face_underfill }),
7018
7082
  ...(cfg.assemble.yield_refused === undefined ? {} : { yieldRefused: cfg.assemble.yield_refused }),
7083
+ ...(cfg.assemble.stage_map === undefined ? {} : { stageMap: cfg.assemble.stage_map }),
7019
7084
  ...(cfg.assemble.keep_under_occluders === undefined ? {} : { keepUnderOccluders: cfg.assemble.keep_under_occluders }),
7085
+ ...(cfg.assemble.require_hidden_extent === undefined ? {} : { requireHiddenExtent: cfg.assemble.require_hidden_extent }),
7020
7086
  ...(cfg.assemble.ground === undefined ? {} : { ground: cfg.assemble.ground }),
7021
7087
  ...(cfg.assemble.extend_painting === undefined ? {} : { paintingExtension: cfg.assemble.extend_painting }),
7022
7088
  ...(turnMovingPair === null ? {} : { turnMovingPair }),
package/src/build.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { STAGE_MAP_FILE } from './provenance.ts';
1
2
  import { withoutCheckRows } from './checkrow.ts';
2
3
  import { readSetupFigureMask } from './setupfiguremask.ts';
3
4
  import { EDGE_RESIDUAL_FILE, edgeResidualLines } from './edgeresidual.ts';
@@ -690,6 +691,16 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
690
691
  };
691
692
  log(`${notice.code}: ${notice.object} ${notice.detail}`);
692
693
  }
694
+ const hiddenExtent = fields.requireHiddenExtent?.filter(({ part, occluder }) => altPlanNames.has(part) || altPlanNames.has(occluder));
695
+ const incompleteExtent = hiddenExtent?.filter(({ part, occluder }) => !altPlanNames.has(part) || !altPlanNames.has(occluder)) ?? [];
696
+ if (incompleteExtent.length > 0) {
697
+ for (const { part, occluder } of incompleteExtent) altProblems.push({
698
+ code: 'ASSEMBLE_HIDDEN_EXTENT_UNMEASURED',
699
+ object: `alternate set "${alt.name}", part "${part}" under "${occluder}"`,
700
+ detail: 'replaces only one declared source family; original selected material for both families is required to measure their enclosed overlap',
701
+ });
702
+ continue;
703
+ }
693
704
  let altRes: ReturnType<typeof assemble>;
694
705
  try {
695
706
  altRes = assemble({
@@ -700,6 +711,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
700
711
  capOwnership: input.setCapOwnership ?? 'target',
701
712
  full: altRuns.full,
702
713
  head: altRuns.head,
714
+ ...(hiddenExtent === undefined ? {} : { requireHiddenExtent: hiddenExtent }),
703
715
  ...(fields.keepUnderOccluders === undefined ? {} : { keepUnderOccluders: fields.keepUnderOccluders.filter(name => altPlanNames.has(name)) }),
704
716
  resolution: fields.resolution,
705
717
  headBox: altHeadBox,
@@ -716,6 +728,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
716
728
  ...(fields.armSplit !== undefined && altPlan.some((e) => e[1] === 'full' && (e[2] === 'handwear-r' || e[2] === 'handwear-l')) ? { armSplit: fields.armSplit } : {}),
717
729
  ...(fields.headFaceUnderfill === undefined ? {} : { headFaceUnderfill: fields.headFaceUnderfill }),
718
730
  ...(fields.yieldRefused === undefined ? {} : { yieldRefused: fields.yieldRefused }),
731
+ ...(fields.stageMap === undefined ? {} : { stageMap: fields.stageMap }),
719
732
  ...(fields.ground === undefined ? {} : { ground: fields.ground }),
720
733
  ...(alternateFigure === undefined ? {} : { declaredFigure: alternateFigure }),
721
734
  ...(fields.turnMovingPair === undefined ? {} : { turnMovingPair: fields.turnMovingPair }),
@@ -742,6 +755,10 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
742
755
  .filter(({ record }) => coveredSet.has(record.name))
743
756
  .flatMap(({ record, image, depthImage }) => [{ name: `${alt.name}_${record.name}`, image }, ...(depthImage === undefined || record.depth === undefined ? [] : [{ name: `${alt.name}_${record.depth.image.slice(0, -4)}`, image: depthImage }])]);
744
757
  const keptRecords = altRes.parts.parts.filter((p) => coveredSet.has(p.name)).map(p => p.depth === undefined ? p : { ...p, depth: { ...p.depth, image: `${alt.name}_${p.depth.image}` } });
758
+ if (result.stageMap !== undefined && altRes.stageMap !== undefined) {
759
+ altRes.stageMap.parts = altRes.stageMap.parts.filter(p => coveredSet.has(p.name));
760
+ (result.stageMap.alternates ??= []).push({ name: alt.name, map: altRes.stageMap });
761
+ }
745
762
  const slots: Record<string, string> = {};
746
763
  for (const r of keptRecords) slots[altFront.has(r.name) ? `${r.name}${FRONT_SUFFIX}` : r.name] = `${alt.name}_${r.name}`;
747
764
  let altRecomposite = altRes.parts.recomposite as RecompositeRecord;
@@ -823,6 +840,9 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
823
840
  sha256: createHash('sha256').update(paintingBytes).digest('hex'), resample: 'lanczos3-rgb-opaque' };
824
841
  writeFileSync(join(dirname(outs.partsJson), PAINTING_IN_RIG_FILE), paintingBytes);
825
842
  writeParts(outs.partsJson, result.parts);
843
+ const stageMapPath = join(dirname(outs.partsJson), STAGE_MAP_FILE);
844
+ if (result.stageMap === undefined) rmSync(stageMapPath, { force: true });
845
+ else writeFileSync(stageMapPath, JSON.stringify(result.stageMap) + '\n');
826
846
  const residualPath = join(dirname(outs.partsJson), EDGE_RESIDUAL_FILE);
827
847
  if (result.edgeResiduals === undefined) rmSync(residualPath, { force: true });
828
848
  else writeFileSync(residualPath, JSON.stringify(result.edgeResiduals, null, 2) + '\n');
package/src/config.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { hiddenExtentNameProblems, type HiddenExtentDeclaration } from './hiddenextent.ts';
1
2
  import { SEAM_RULES, type SeamRule } from './seamrule.ts';
2
3
  import { DEFAULT_PROJECT_RULE, GROUNDS, type Ground, PROJECT_RULES, type ProjectRule } from './projectrule.ts';
3
4
  import type { TakeDeclaration } from './takeregion.ts';
@@ -331,8 +332,12 @@ export interface Assemble {
331
332
  head_face_underfill?: boolean;
332
333
  /** Opt-in: yield original drift-refused front cores and connected non-core rims to an opaque behind holder matching the painting. */
333
334
  yield_refused?: boolean;
335
+ /** Emit the report-only last-writer sidecar; absent or false is off. */
336
+ stage_map?: boolean;
334
337
  /** Named plan parts retain their own pixels beneath a drawn-in-front soft occluder. */
335
338
  keep_under_occluders?: string[];
339
+ /** Require original material in enclosed source holes beneath a named moving cover. */
340
+ require_hidden_extent?: HiddenExtentDeclaration[];
336
341
  }
337
342
 
338
343
  export interface SingleBone {
@@ -1671,7 +1676,7 @@ export interface EarlyConfig {
1671
1676
  depth?: DepthConfig;
1672
1677
  key: string;
1673
1678
  seethrough: SeeThrough;
1674
- assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeDeclaration[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; keep_under_occluders?: string[]; extend_painting?: PaintingExtension[] };
1679
+ assemble: { rig_scale: number; seam?: SeamRule; project?: ProjectRule; ground?: Ground; take?: TakeDeclaration[]; editor_receipts?: EditorReceipts; head_face_underfill?: boolean; yield_refused?: boolean; stage_map?: boolean; keep_under_occluders?: string[]; require_hidden_extent?: HiddenExtentDeclaration[]; extend_painting?: PaintingExtension[] };
1675
1680
  }
1676
1681
 
1677
1682
  /** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
@@ -1749,14 +1754,18 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null, p
1749
1754
  if (door === 'layers') {
1750
1755
  if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
1751
1756
  if ('assemble' in t) {
1752
- const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
1757
+ const a = c.object('config.assemble', t.assemble, sectionRequired(door, 'assemble'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'stage_map', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
1753
1758
  if (a !== null) {
1754
1759
  checkAssembleRules(c, a);
1755
1760
  if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
1756
1761
  if ('head_face_underfill' in a && typeof a.head_face_underfill !== 'boolean') {
1757
1762
  c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
1758
1763
  }
1764
+ if ('stage_map' in a && typeof a.stage_map !== 'boolean') {
1765
+ c.fail('CONFIG_FIELD_TYPE', 'config.assemble.stage_map', `is ${show(a.stage_map)}; true or false is required`);
1766
+ }
1759
1767
  checkKeepUnderOccluders(c, a, null);
1768
+ checkRequiredHiddenExtent(c, a, null);
1760
1769
  if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
1761
1770
  if ('take' in a) checkTakeLayers(c, a.take);
1762
1771
  if ('editor_receipts' in a) checkEditorReceipts(c, a.editor_receipts);
@@ -2489,6 +2498,21 @@ function checkPaintingExtensions(c: Check, value: Json, names: ReadonlySet<strin
2489
2498
  }
2490
2499
  }
2491
2500
 
2501
+ function checkRequiredHiddenExtent(c: Check, a: Record<string, Json>, names: readonly string[] | null): void {
2502
+ if (!('require_hidden_extent' in a)) return;
2503
+ const at = 'config.assemble.require_hidden_extent';
2504
+ if (!c.array(at, a.require_hidden_extent, false)) return;
2505
+ const declarations: HiddenExtentDeclaration[] = [];
2506
+ (a.require_hidden_extent as Json[]).forEach((value, i) => {
2507
+ const row = c.object(`${at}[${i}]`, value, ['part', 'occluder'], []);
2508
+ if (row === null) return;
2509
+ const partOk = c.string(`${at}[${i}].part`, row.part);
2510
+ const coverOk = c.string(`${at}[${i}].occluder`, row.occluder);
2511
+ if (partOk && coverOk) declarations.push({ part: row.part as string, occluder: row.occluder as string });
2512
+ });
2513
+ c.problems.push(...hiddenExtentNameProblems(declarations, names));
2514
+ }
2515
+
2492
2516
  function checkKeepUnderOccluders(c: Check, a: Record<string, Json>, plan: readonly string[] | null): void {
2493
2517
  if (!('keep_under_occluders' in a)) return;
2494
2518
  const at = 'config.assemble.keep_under_occluders';
@@ -2608,7 +2632,7 @@ function checkAssembleRules(c: Check, a: Record<string, Json>): void {
2608
2632
 
2609
2633
  function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
2610
2634
  const required = sectionRequired(door, 'assemble');
2611
- const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'keep_under_occluders', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
2635
+ const a = c.object('config.assemble', v, required.filter((k) => k !== 'plan'), ['plan', 'extend_below_crop', 'patches', 'cuts', 'alternates', 'head_face_underfill', 'yield_refused', 'stage_map', 'keep_under_occluders', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
2612
2636
  if (a === null) return { parts: [], patches: [], cuts: [] };
2613
2637
  checkAssembleRules(c, a);
2614
2638
  if (required.includes('plan') && !('plan' in a)) {
@@ -2622,6 +2646,9 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
2622
2646
  if ('yield_refused' in a && typeof a.yield_refused !== 'boolean') {
2623
2647
  c.fail('CONFIG_FIELD_TYPE', `${p}.yield_refused`, `is ${show(a.yield_refused)}; true or false is required`);
2624
2648
  }
2649
+ if ('stage_map' in a && typeof a.stage_map !== 'boolean') {
2650
+ c.fail('CONFIG_FIELD_TYPE', `${p}.stage_map`, `is ${show(a.stage_map)}; true or false is required`);
2651
+ }
2625
2652
  const parts: string[] = [];
2626
2653
  if ('plan' in a && c.array(`${p}.plan`, a.plan, true)) {
2627
2654
  const seenPart = new Map<string, number>();
@@ -2644,6 +2671,7 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
2644
2671
  });
2645
2672
  }
2646
2673
  checkKeepUnderOccluders(c, a, parts);
2674
+ checkRequiredHiddenExtent(c, a, parts);
2647
2675
  if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
2648
2676
  if ('take' in a) checkTakeLayers(c, a.take, parts);
2649
2677
  if ('editor_receipts' in a) checkEditorReceipts(c, a.editor_receipts);
@@ -0,0 +1,88 @@
1
+ import type { Problem } from './errors.ts';
2
+ import { CORE_ALPHA, OPAQUE_ALPHA_ABOVE } from './layers.ts';
3
+ import { fillHoles } from './raster/morph.ts';
4
+ import { newMask, type Raster } from './raster/types.ts';
5
+
6
+ /** A source part whose enclosed missing material must not sit under this moving cover. */
7
+ export interface HiddenExtentDeclaration {
8
+ part: string;
9
+ occluder: string;
10
+ }
11
+
12
+ /** Original selected material, in source-family draw order, before cleanup or preparation. */
13
+ export interface HiddenExtentSource {
14
+ name: string;
15
+ from: string;
16
+ image: Raster | null;
17
+ x?: number;
18
+ y?: number;
19
+ }
20
+
21
+ export function hiddenExtentNameProblems(declarations: readonly HiddenExtentDeclaration[], names: readonly string[] | null): Problem[] {
22
+ const problems: Problem[] = [];
23
+ const seen = new Set<string>();
24
+ declarations.forEach(({ part, occluder }, i) => {
25
+ const object = `config.assemble.require_hidden_extent[${i}]`;
26
+ const pair = JSON.stringify([part, occluder]);
27
+ if (seen.has(pair)) problems.push({ code: 'CONFIG_PART_UNIQUE', object, detail: `repeats "${part}" under "${occluder}"; each directed source pair is declared once` });
28
+ seen.add(pair);
29
+ if (names !== null) for (const [key, name] of [['part', part], ['occluder', occluder]]) {
30
+ if (!names.includes(name)) problems.push({ code: 'CONFIG_NAME_RESOLVES', object: `${object}.${key}`, detail: `names "${name}"; a source part in assemble.plan is required, before cuts or limb splitting` });
31
+ }
32
+ if (part === occluder || (names !== null && names.includes(part) && names.includes(occluder) && names.indexOf(occluder) < names.indexOf(part))) {
33
+ problems.push({ code: 'CONFIG_HIDDEN_EXTENT_ORDER', object, detail: `names "${part}" under "${occluder}"; a distinct occluder drawn after the source part is required` });
34
+ }
35
+ });
36
+ return problems;
37
+ }
38
+
39
+ /** Enclosed source holes only. Exterior-connected missing material is outside this contract. */
40
+ export function hiddenExtentProblems(declarations: readonly HiddenExtentDeclaration[], sources: readonly HiddenExtentSource[], width: number, height: number): Problem[] {
41
+ const names = sources.map(source => source.name);
42
+ const sourceNames = sources.filter(source => !source.from.startsWith('painting:')).map(source => source.name);
43
+ const problems = hiddenExtentNameProblems(declarations, sourceNames);
44
+ const alpha = (source: HiddenExtentSource, x: number, y: number): number => {
45
+ const image = source.image;
46
+ const sx = x - (source.x ?? 0), sy = y - (source.y ?? 0);
47
+ return image === null || sx < 0 || sy < 0 || sx >= image.width || sy >= image.height ? 0 : image.data[(sy * image.width + sx) * 4 + 3];
48
+ };
49
+ for (const { part, occluder } of declarations) {
50
+ const at = names.indexOf(part), coverAt = names.indexOf(occluder);
51
+ if (at < 0 || coverAt <= at || !sourceNames.includes(part) || !sourceNames.includes(occluder)) continue;
52
+ const own = sources[at];
53
+ const object = `part "${part}" (${own.from}) under "${occluder}"`;
54
+ const unavailable = sources.slice(at).find(source => source.image === null);
55
+ if (unavailable !== undefined) {
56
+ problems.push({ code: 'ASSEMBLE_HIDDEN_EXTENT_UNMEASURED', object, detail: `original selected material for "${unavailable.name}" (${unavailable.from}) is unavailable; source ancestry is required before cleanup or any writer` });
57
+ continue;
58
+ }
59
+ const support = newMask(width, height);
60
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) support.data[y * width + x] = alpha(own, x, y) > OPAQUE_ALPHA_ABOVE ? 1 : 0;
61
+ const filled = fillHoles(support);
62
+ let overlap = 0, soft = 0, opaque = 0, first = -1;
63
+ for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
64
+ const p = y * width + x;
65
+ if (filled.data[p] === 0) continue;
66
+ let front = -1, frontAlpha = 0;
67
+ for (let j = sources.length - 1; j > at; j--) {
68
+ const a = alpha(sources[j], x, y);
69
+ if (a <= OPAQUE_ALPHA_ABOVE) continue;
70
+ front = j;
71
+ frontAlpha = a;
72
+ break;
73
+ }
74
+ if (front !== coverAt) continue;
75
+ overlap++;
76
+ if (support.data[p] === 1) continue;
77
+ if (first < 0) first = p;
78
+ if (frontAlpha < CORE_ALPHA) soft++;
79
+ else opaque++;
80
+ }
81
+ if (soft + opaque > 0) {
82
+ problems.push({ code: 'ASSEMBLE_HIDDEN_EXTENT_ABSENT', object, detail: `${soft + opaque} enclosed-hole rig cells of ${overlap} covered cells have own alpha <= ${OPAQUE_ALPHA_ABOVE}, > ${OPAQUE_ALPHA_ABOVE} required (soft cover ${soft}, opaque cover ${opaque}); first at ${first % width},${Math.floor(first / width)}; a source carrying this extent is required` });
83
+ } else if (overlap === 0) {
84
+ problems.push({ code: 'ASSEMBLE_HIDDEN_EXTENT_UNMEASURED', object, detail: `has no filled own-support overlap beneath the resolved occluder at alpha > ${OPAQUE_ALPHA_ABOVE}; a measurable source overlap is required` });
85
+ }
86
+ }
87
+ return problems;
88
+ }
package/src/provenance.ts CHANGED
@@ -11,6 +11,32 @@ export const AUTOMATIC_WRITERS = {
11
11
  seamOverride: -9, armSplit: -10, headFaceUnderfill: -11, ghostCleanup: -12, unattributed: -13, paintingExtension: -14, paintingEdge: -15,
12
12
  } as const;
13
13
  export type AutomaticWriter = keyof typeof AUTOMATIC_WRITERS;
14
+ /** Sidecar codes share provenance's writer IDs. Excluded has a separate code. */
15
+ export const EXCLUDED_PIXEL = -2147483648;
16
+ export const NOT_OVERRIDDEN_PIXEL = -2147483647;
17
+ export const STAGE_MAP_FILE = 'stage-map.json';
18
+ export interface PartStageMap {
19
+ name: string;
20
+ x: number;
21
+ y: number;
22
+ w: number;
23
+ h: number;
24
+ excluded_px: number;
25
+ /** [writer ID, run length], row-major in the cropped part, across row boundaries. */
26
+ runs: Array<[number, number]>;
27
+ /** Prior buffer writer only where a final seamOverride classification survives. */
28
+ pre_seam_writer_runs: Array<[number, number]>;
29
+ }
30
+ export interface StageMap {
31
+ schema: 'rig-parts-stage-map/1';
32
+ rig_size: [number, number];
33
+ automatic: typeof AUTOMATIC_WRITERS;
34
+ /** Positive ID n resolves to edits[n - 1]. */
35
+ edits: string[];
36
+ parts: PartStageMap[];
37
+ alternates?: Array<{ name: string; map: StageMap }>;
38
+ }
39
+
14
40
  export interface PixelProvenance {
15
41
  /** Scalar transport omitted only for fully explicit unit consumers (#877). */
16
42
  depth?: AuthoredUnitDepth;
@@ -43,14 +69,21 @@ export function compactValueBaseline(raw: Raster): ValueBaseline {
43
69
  /** Value equality with the raw normalized See-through baseline wins first.
44
70
  * Otherwise the last stage that CHANGED RGBA wins; buffer copies inherit IDs.
45
71
  * A null baseline is explicit for authored layers/painting patches. */
46
- export function pixelProvenance(image: Raster, x: number, y: number, width: number, writers: Int32Array | null, edits: readonly string[], patchId = 0, baseline: Raster | ValueBaseline | null = null): PixelProvenance {
72
+ export function pixelProvenance(image: Raster, x: number, y: number, width: number, writers: Int32Array | null, edits: readonly string[], patchId = 0, baseline: Raster | ValueBaseline | null = null, map?: PartStageMap, beforeSeam?: ReadonlyMap<number, number>): PixelProvenance {
47
73
  const out: PixelProvenance = { unchanged_layer_px: 0, hand_px: 0, automatic_px: 0, edits: [], automatic: [] };
48
74
  const counts = new Map<number, number>();
49
75
  const reference = baseline === null ? null : 'image' in baseline ? baseline.image : baseline;
50
76
  const bx = baseline !== null && 'image' in baseline ? baseline.x : 0;
51
77
  const by = baseline !== null && 'image' in baseline ? baseline.y : 0;
52
78
  for (let j = 0; j < image.height; j++) for (let i = 0; i < image.width; i++) {
53
- if (image.data[(j * image.width + i) * 4 + 3] <= OPAQUE_ALPHA_ABOVE) continue;
79
+ if (image.data[(j * image.width + i) * 4 + 3] <= OPAQUE_ALPHA_ABOVE) {
80
+ if (map !== undefined) {
81
+ appendStageRun(map.runs, EXCLUDED_PIXEL);
82
+ appendStageRun(map.pre_seam_writer_runs, EXCLUDED_PIXEL);
83
+ map.excluded_px++;
84
+ }
85
+ continue;
86
+ }
54
87
  const q = (y + j) * width + x + i;
55
88
  const u = x + i - bx, v = y + j - by;
56
89
  const same = reference !== null && u >= 0 && v >= 0 && u < reference.width && v < reference.height &&
@@ -58,6 +91,11 @@ export function pixelProvenance(image: Raster, x: number, y: number, width: numb
58
91
  const previous = writers?.[q] ?? patchId;
59
92
  // Unknown lineage is reported explicitly, never invented as unchanged.
60
93
  const id = same ? 0 : previous === 0 ? AUTOMATIC_WRITERS.unattributed : previous;
94
+ if (map !== undefined) {
95
+ appendStageRun(map.runs, id);
96
+ appendStageRun(map.pre_seam_writer_runs, id === AUTOMATIC_WRITERS.seamOverride
97
+ ? beforeSeam?.get(q) ?? NOT_OVERRIDDEN_PIXEL : NOT_OVERRIDDEN_PIXEL);
98
+ }
61
99
  if (id > 0) out.hand_px++;
62
100
  else if (id < 0) out.automatic_px++;
63
101
  else out.unchanged_layer_px++;
@@ -68,6 +106,13 @@ export function pixelProvenance(image: Raster, x: number, y: number, width: numb
68
106
  return out;
69
107
  }
70
108
 
109
+ /** Append directly to compressed output without a second rig-grid buffer. */
110
+ function appendStageRun(runs: Array<[number, number]>, id: number): void {
111
+ const last = runs[runs.length - 1];
112
+ if (last !== undefined && last[0] === id) last[1]++;
113
+ else runs.push([id, 1]);
114
+ }
115
+
71
116
  /** The reader and selftests share this arithmetic check; no hand-edit gate. */
72
117
  export function provenanceAddsUp(p: PixelProvenance, opaque: number): boolean {
73
118
  return p.unchanged_layer_px + p.hand_px + p.automatic_px === opaque &&