spine-parts 2.20.2 → 2.21.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 +15 -1
- package/docs/STABILITY.md +2 -1
- package/package.json +1 -1
- package/src/assemble.ts +27 -1
- package/src/build.ts +11 -0
- package/src/config.ts +23 -3
- package/src/hiddenextent.ts +88 -0
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 |
|
|
@@ -5245,6 +5246,9 @@ those settings. Changing a config seed alone cannot change a no-config run.
|
|
|
5245
5246
|
| <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
5247
|
| <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
5248
|
| <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 |
|
|
5249
|
+
| <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 |
|
|
5250
|
+
| <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) |
|
|
5251
|
+
| <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
5252
|
| <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
5253
|
| <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
5254
|
| <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 +5628,7 @@ documents do not ship). Each is an input this package built; none is an author's
|
|
|
5624
5628
|
| <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
5629
|
| <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
5630
|
| <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 |
|
|
5631
|
+
| <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
5632
|
| <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
5633
|
| <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
5634
|
| <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 +5758,16 @@ The body-root bar counts stock partitions `gapOpen` plus `ghostA` or `ghostB` ow
|
|
|
5754
5758
|
|
|
5755
5759
|
**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
5760
|
|
|
5761
|
+
<a id="original-hidden-extent-required"></a>
|
|
5762
|
+
|
|
5763
|
+
**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.
|
|
5764
|
+
|
|
5765
|
+
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.
|
|
5766
|
+
|
|
5767
|
+
**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.
|
|
5768
|
+
|
|
5769
|
+
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.
|
|
5770
|
+
|
|
5757
5771
|
**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
5772
|
|
|
5759
5773
|
### 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`, `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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "spine-parts",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.21.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';
|
|
@@ -365,6 +366,8 @@ export interface AssembleInput {
|
|
|
365
366
|
yieldRefused?: boolean;
|
|
366
367
|
/** Plan parts whose own samples survive source re-take beneath soft front cover. */
|
|
367
368
|
keepUnderOccluders?: readonly string[];
|
|
369
|
+
/** Original selected material must cover its enclosed holes beneath this source pair. */
|
|
370
|
+
requireHiddenExtent?: readonly HiddenExtentDeclaration[];
|
|
368
371
|
/** Base painting only; named final parts, explicit band and path bound (#848). */
|
|
369
372
|
paintingExtension?: readonly PaintingExtension[];
|
|
370
373
|
/**
|
|
@@ -4965,7 +4968,7 @@ export function assemble(input: AssembleInput): AssembleResult {
|
|
|
4965
4968
|
if (input.regionTake === undefined) return assembleParts(input);
|
|
4966
4969
|
const targets = regionTakeTargets(input.regionTake.targets, input.cuts, input.limbs);
|
|
4967
4970
|
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);
|
|
4971
|
+
const before = assembleParts({ ...input, full: input.regionTake.full, head: input.regionTake.head, regionTake: undefined, requireHiddenExtent: undefined }, targets, null, counterfactual);
|
|
4969
4972
|
return assembleParts(input, targets, before, counterfactual);
|
|
4970
4973
|
}
|
|
4971
4974
|
|
|
@@ -4992,6 +4995,26 @@ function assembleParts(input: AssembleInput, targets?: ReadonlySet<string>, befo
|
|
|
4992
4995
|
refuseIfAny(depthInputProblems);
|
|
4993
4996
|
// Issue #366: one run's file, padded to the resolution square; read as both runs, as before.
|
|
4994
4997
|
const fullPadded = single ? padSingleRun(depthFullInput, frame, input.resolution) : depthFullInput;
|
|
4998
|
+
if ((input.requireHiddenExtent?.length ?? 0) > 0) {
|
|
4999
|
+
// Read the selected original layers, before split/underfill/cleanup can replace their material.
|
|
5000
|
+
const originals = input.plan.map(([name, run, tag]): HiddenExtentSource => {
|
|
5001
|
+
const set = run === 'full' ? fullPadded : depthHeadInput;
|
|
5002
|
+
const layer = set.layers.find(candidate => candidate.name === tag);
|
|
5003
|
+
return { name, from: `${run}:${tag}`, image: layer === undefined ? null : layerToRig(placeLayer(layer, input.resolution), frame, run) };
|
|
5004
|
+
});
|
|
5005
|
+
const painting = patches.length === 0 ? null : sourceInRig(source, frame.W, frame.H);
|
|
5006
|
+
const silhouette = painting === null ? null : figureSilhouette(painting);
|
|
5007
|
+
const sources: HiddenExtentSource[] = [];
|
|
5008
|
+
for (const slot of drawOrder(input.plan.map(([name]) => name), patches)) {
|
|
5009
|
+
if ('plan' in slot) sources.push(originals[slot.plan]);
|
|
5010
|
+
if ('patch' in slot) {
|
|
5011
|
+
const patch = patches[slot.patch];
|
|
5012
|
+
const placed = cutPatch(patch, painting as Raster, silhouette);
|
|
5013
|
+
sources.push({ name: patch.name, from: 'painting:patch', image: placed?.image ?? newRaster(1, 1), x: placed?.record.x ?? 0, y: placed?.record.y ?? 0 });
|
|
5014
|
+
}
|
|
5015
|
+
}
|
|
5016
|
+
refuseIfAny(hiddenExtentProblems(input.requireHiddenExtent!, sources, frame.W, frame.H));
|
|
5017
|
+
}
|
|
4995
5018
|
// Issue #439: when seethrough.arm_split is declared, split the full run's overlapping handwear into handwear-r and handwear-l.
|
|
4996
5019
|
const fullArmSplit = input.armSplit === undefined ? fullPadded : applyArmSplit(fullPadded, input.resolution, input.armSplit);
|
|
4997
5020
|
// Issue #490: when generation.control.skeleton is present, split merged arm layers (or refuse when sleeve and drape share one colour).
|
|
@@ -6987,6 +7010,8 @@ export function stageFields(
|
|
|
6987
7010
|
yieldRefused?: boolean;
|
|
6988
7011
|
/** Plan parts whose own samples survive source re-take beneath soft front cover. */
|
|
6989
7012
|
keepUnderOccluders?: readonly string[];
|
|
7013
|
+
/** Original selected material must cover its enclosed holes beneath this source pair. */
|
|
7014
|
+
requireHiddenExtent?: readonly HiddenExtentDeclaration[];
|
|
6990
7015
|
/** Base painting only; named final parts, explicit band and path bound (#848). */
|
|
6991
7016
|
paintingExtension?: readonly PaintingExtension[];
|
|
6992
7017
|
turnMovingPair?: (a: string, b: string) => boolean;
|
|
@@ -7017,6 +7042,7 @@ export function stageFields(
|
|
|
7017
7042
|
...(cfg.assemble.head_face_underfill === undefined ? {} : { headFaceUnderfill: cfg.assemble.head_face_underfill }),
|
|
7018
7043
|
...(cfg.assemble.yield_refused === undefined ? {} : { yieldRefused: cfg.assemble.yield_refused }),
|
|
7019
7044
|
...(cfg.assemble.keep_under_occluders === undefined ? {} : { keepUnderOccluders: cfg.assemble.keep_under_occluders }),
|
|
7045
|
+
...(cfg.assemble.require_hidden_extent === undefined ? {} : { requireHiddenExtent: cfg.assemble.require_hidden_extent }),
|
|
7020
7046
|
...(cfg.assemble.ground === undefined ? {} : { ground: cfg.assemble.ground }),
|
|
7021
7047
|
...(cfg.assemble.extend_painting === undefined ? {} : { paintingExtension: cfg.assemble.extend_painting }),
|
|
7022
7048
|
...(turnMovingPair === null ? {} : { turnMovingPair }),
|
package/src/build.ts
CHANGED
|
@@ -690,6 +690,16 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
|
|
|
690
690
|
};
|
|
691
691
|
log(`${notice.code}: ${notice.object} ${notice.detail}`);
|
|
692
692
|
}
|
|
693
|
+
const hiddenExtent = fields.requireHiddenExtent?.filter(({ part, occluder }) => altPlanNames.has(part) || altPlanNames.has(occluder));
|
|
694
|
+
const incompleteExtent = hiddenExtent?.filter(({ part, occluder }) => !altPlanNames.has(part) || !altPlanNames.has(occluder)) ?? [];
|
|
695
|
+
if (incompleteExtent.length > 0) {
|
|
696
|
+
for (const { part, occluder } of incompleteExtent) altProblems.push({
|
|
697
|
+
code: 'ASSEMBLE_HIDDEN_EXTENT_UNMEASURED',
|
|
698
|
+
object: `alternate set "${alt.name}", part "${part}" under "${occluder}"`,
|
|
699
|
+
detail: 'replaces only one declared source family; original selected material for both families is required to measure their enclosed overlap',
|
|
700
|
+
});
|
|
701
|
+
continue;
|
|
702
|
+
}
|
|
693
703
|
let altRes: ReturnType<typeof assemble>;
|
|
694
704
|
try {
|
|
695
705
|
altRes = assemble({
|
|
@@ -700,6 +710,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
|
|
|
700
710
|
capOwnership: input.setCapOwnership ?? 'target',
|
|
701
711
|
full: altRuns.full,
|
|
702
712
|
head: altRuns.head,
|
|
713
|
+
...(hiddenExtent === undefined ? {} : { requireHiddenExtent: hiddenExtent }),
|
|
703
714
|
...(fields.keepUnderOccluders === undefined ? {} : { keepUnderOccluders: fields.keepUnderOccluders.filter(name => altPlanNames.has(name)) }),
|
|
704
715
|
resolution: fields.resolution,
|
|
705
716
|
headBox: altHeadBox,
|
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';
|
|
@@ -333,6 +334,8 @@ export interface Assemble {
|
|
|
333
334
|
yield_refused?: boolean;
|
|
334
335
|
/** Named plan parts retain their own pixels beneath a drawn-in-front soft occluder. */
|
|
335
336
|
keep_under_occluders?: string[];
|
|
337
|
+
/** Require original material in enclosed source holes beneath a named moving cover. */
|
|
338
|
+
require_hidden_extent?: HiddenExtentDeclaration[];
|
|
336
339
|
}
|
|
337
340
|
|
|
338
341
|
export interface SingleBone {
|
|
@@ -1671,7 +1674,7 @@ export interface EarlyConfig {
|
|
|
1671
1674
|
depth?: DepthConfig;
|
|
1672
1675
|
key: string;
|
|
1673
1676
|
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[] };
|
|
1677
|
+
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[]; require_hidden_extent?: HiddenExtentDeclaration[]; extend_painting?: PaintingExtension[] };
|
|
1675
1678
|
}
|
|
1676
1679
|
|
|
1677
1680
|
/** What plain `assemble` reads: the early config plus the plan `--propose-plan` printed. */
|
|
@@ -1749,7 +1752,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null, p
|
|
|
1749
1752
|
if (door === 'layers') {
|
|
1750
1753
|
if ('seethrough' in t) checkSeeThrough(c, t.seethrough);
|
|
1751
1754
|
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']);
|
|
1755
|
+
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', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
|
|
1753
1756
|
if (a !== null) {
|
|
1754
1757
|
checkAssembleRules(c, a);
|
|
1755
1758
|
if ('rig_scale' in a) c.number('config.assemble.rig_scale', a.rig_scale, 'positive');
|
|
@@ -1757,6 +1760,7 @@ function parseEarlyConfigFrom(raw: Json, door: EarlyDoor, base: string | null, p
|
|
|
1757
1760
|
c.fail('CONFIG_FIELD_TYPE', 'config.assemble.head_face_underfill', `is ${show(a.head_face_underfill)}; true or false is required`);
|
|
1758
1761
|
}
|
|
1759
1762
|
checkKeepUnderOccluders(c, a, null);
|
|
1763
|
+
checkRequiredHiddenExtent(c, a, null);
|
|
1760
1764
|
if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
|
|
1761
1765
|
if ('take' in a) checkTakeLayers(c, a.take);
|
|
1762
1766
|
if ('editor_receipts' in a) checkEditorReceipts(c, a.editor_receipts);
|
|
@@ -2489,6 +2493,21 @@ function checkPaintingExtensions(c: Check, value: Json, names: ReadonlySet<strin
|
|
|
2489
2493
|
}
|
|
2490
2494
|
}
|
|
2491
2495
|
|
|
2496
|
+
function checkRequiredHiddenExtent(c: Check, a: Record<string, Json>, names: readonly string[] | null): void {
|
|
2497
|
+
if (!('require_hidden_extent' in a)) return;
|
|
2498
|
+
const at = 'config.assemble.require_hidden_extent';
|
|
2499
|
+
if (!c.array(at, a.require_hidden_extent, false)) return;
|
|
2500
|
+
const declarations: HiddenExtentDeclaration[] = [];
|
|
2501
|
+
(a.require_hidden_extent as Json[]).forEach((value, i) => {
|
|
2502
|
+
const row = c.object(`${at}[${i}]`, value, ['part', 'occluder'], []);
|
|
2503
|
+
if (row === null) return;
|
|
2504
|
+
const partOk = c.string(`${at}[${i}].part`, row.part);
|
|
2505
|
+
const coverOk = c.string(`${at}[${i}].occluder`, row.occluder);
|
|
2506
|
+
if (partOk && coverOk) declarations.push({ part: row.part as string, occluder: row.occluder as string });
|
|
2507
|
+
});
|
|
2508
|
+
c.problems.push(...hiddenExtentNameProblems(declarations, names));
|
|
2509
|
+
}
|
|
2510
|
+
|
|
2492
2511
|
function checkKeepUnderOccluders(c: Check, a: Record<string, Json>, plan: readonly string[] | null): void {
|
|
2493
2512
|
if (!('keep_under_occluders' in a)) return;
|
|
2494
2513
|
const at = 'config.assemble.keep_under_occluders';
|
|
@@ -2608,7 +2627,7 @@ function checkAssembleRules(c: Check, a: Record<string, Json>): void {
|
|
|
2608
2627
|
|
|
2609
2628
|
function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: string[]; patches: string[]; cuts: string[] } {
|
|
2610
2629
|
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']);
|
|
2630
|
+
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', 'require_hidden_extent', 'extend_painting', 'take', 'seam', 'project', 'ground', 'editor_receipts']);
|
|
2612
2631
|
if (a === null) return { parts: [], patches: [], cuts: [] };
|
|
2613
2632
|
checkAssembleRules(c, a);
|
|
2614
2633
|
if (required.includes('plan') && !('plan' in a)) {
|
|
@@ -2644,6 +2663,7 @@ function checkAssemble(c: Check, v: Json, door: 'assemble' | 'full'): { parts: s
|
|
|
2644
2663
|
});
|
|
2645
2664
|
}
|
|
2646
2665
|
checkKeepUnderOccluders(c, a, parts);
|
|
2666
|
+
checkRequiredHiddenExtent(c, a, parts);
|
|
2647
2667
|
if ('extend_painting' in a) checkPaintingExtensions(c, a.extend_painting);
|
|
2648
2668
|
if ('take' in a) checkTakeLayers(c, a.take, parts);
|
|
2649
2669
|
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
|
+
}
|