@rig-c/parts 1.65.0 → 1.67.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/README.md +6 -5
- package/cli.ts +43 -16
- package/docs/AUTHORING.md +125 -37
- package/docs/MIGRATION.md +30 -1
- package/docs/STABILITY.md +50 -1
- package/package.json +1 -1
- package/skills/rig-parts/SKILL.md +2 -2
- package/src/assemble.ts +17 -7
- package/src/check.ts +124 -3
- package/src/clothconfig.ts +3 -2
- package/src/config.ts +14 -4
- package/src/layers.ts +62 -0
- package/src/motionseampose.ts +117 -0
- package/src/motionseams.ts +91 -0
- package/src/parts.ts +11 -3
- package/src/propose.ts +43 -3
- package/src/rig.ts +20 -3
- package/tools/configwrite.ts +3 -3
package/docs/AUTHORING.md
CHANGED
|
@@ -140,6 +140,7 @@ read by no CPU stage).
|
|
|
140
140
|
| `scene` | assemble (the recomposite, its holes and the figure's mask); check, through `parts.json`'s `scene` block (`RECOMPOSITE_HOLES`, the seam) | **authored**, optional; `propose` writes none (issue #242). `{}` declares the painting a scene: the figure and its surroundings in one image, See-through's full run holding only the figure. With it, `assemble` reads the recomposite figures, the hole list and the `uncovered:` lines inside the figure — the rig pixels where any full-run layer's alpha is above 8 (`OPAQUE_ALPHA_ABOVE`, the cut every layer's painted pixels are read by) — each line starting `inside the figure (config.scene: …, <n> of <m> rig px)`; writes that figure as `figure_rig.png` (white on black) beside the recomposite, and a `scene` block in `parts.json`; flags error pixels on the error map inside it only (outside, the painting grey); and `check` leaves out of the seam every frame pixel whose composite sample reaches the painting's outermost row or column, saying how many (`seam_border` in `check.json`, and on the seam line). It takes no field: the figure and its threshold are derived. A key in it other than a record or an annotation is `CONFIG_KEY_KNOWN`. Absent, no byte of any output moves |
|
|
141
141
|
| `cloth` | `propose --cloth` only; no other stage reads it, so it moves no byte of any build | **authored**, optional (issue #364): one recipe per tag, `{"bottomwear": {…}, "back hair": {…}, "front hair": {…}}`, each `{chains, links, wind, gravity, split?, length_ratio?, strength?, damping?, alternate_damping?, translate?, swing?, part?, influence?}`. `influence` (issue #518) — `{across, max, shape, radius?}`: the parts this recipe meshes are drafted in the influence mode (`meshes.<part>.influence` above) at their lattice's cell, with `across`, `max` and `shape` as declared (each required — the reading behind the radius did not vary them) and `radius` as declared or, absent, drafted as the farthest vertex's distance plus 3 cells (the `influence.radius` row); without it the parts keep their lattice. `chains` — trees across the piece (for `back hair`, per side of the eye axis), a whole number, 1 or more; `links` — links from root to tip on every path, 1 or more; `split` — `{at, into}`: the first `at` links are the trunk, which forks into `into` (2 or more) branches; `at` below `links` (`CONFIG_CLOTH_SPLIT_BEFORE_TIP`); `length_ratio` — a path's last link over its first, above 0, default 0.5; `strength` — `{trunk, branch, edge}`, each above 0 and below the spring's stability bound (`CONFIG_CLOTH_SPRING_STABLE`), default 100 / 100 / 50; `damping` — in [0, 1], absent: rig-c's default; `alternate_damping` — the odd trees' damping, in [0, 1], beside `damping` and different from it (`CONFIG_CLOTH_ALTERNATE_DIFFERS`); `wind`, `gravity` — `[root, tip]`, each 0 or more, tip at or above root (`CONFIG_CLOTH_RESPONSE_GROWS_TO_TIP`); `translate` — the x and y mix of a dangling end's flutter, above 0 and at most 1; `swing` — `bottomwear` only, `{scales}`, one positive scale per tree (`CONFIG_CLOTH_SWING_SCALE_PER_TREE`); `part` — `bottomwear` only (`CONFIG_CLOTH_PART_ON_BOTTOMWEAR`), a non-empty part or cut-piece name: the `topwear` part that holds a skirt See-through returned inside it (a dress), or its skirt piece cut by `assemble.cuts`, which takes the skirt's trees (issue #402, *A skirt inside topwear* below; the part is checked by `propose`, `PROPOSE_CLOTH_PART`). The two defaults are the recipe's own, measured on its synthetic fixture (the recipe below). The recipe below says what each field drafts. The config written: `propose --cloth <config.json> --write-config <out.json>` (issue #537) writes this config's own text back with the sections the recipe drafts spliced in — `meshes.<part>` and `regions.<part>`, and `bones`, `constraints` and `motion.tracks` entry by entry by name (issue #552) — and every other byte as read; `--from <previous config>` (issue #571) takes an entry equal to the previous recipe's draft as the recipe's (*The config written*, under the recipe below) |
|
|
142
142
|
| `proposed_rig_scale` | assemble, rig, build, `propose --from-config`/`--compare` | **proposed** by `propose` (issue #354): `parts.json`'s `scale_rig_per_source`, the `assemble.rig_scale` the rig sections (`bones`, `meshes`, `limbs`, `motion`) were drafted at. Held equal to `assemble.rig_scale` when present (`CONFIG_PROPOSED_RIG_SCALE`; 0, negative or not a number: `CONFIG_FIELD_TYPE`). Absent on a hand-authored config, where no byte of any output moves |
|
|
143
|
+
| `motion_seams` | propose, assemble, check | Optional `[{part, neighbour}]`, using output part names. Each unordered pair is declared once; self-pairs, unknown names, wrong shapes and unknown fields refuse (`CONFIG_MOTION_SEAM`, `PARTS_MOTION_SEAM`, `CHECK_MOTION_SEAM_DECLARATION`). Empty adds no pair. Assemble copies the declaration into `parts.json`; check merges it with existing pairs and never regenerates a removed declaration. It uses the existing non-root WARN floor and changes no bar or exit status. See *Explicit motion seam observations* below. |
|
|
143
144
|
| `requirements` | build (read in place of `--requirements` when the flag is not given), and so its check | **authored**, optional, never proposed (issue #556): a path, relative to the config file's directory, to the `spine-parts-requirements/1` file the build's check reads (§7, *Declared requirements*) — so a rig that needs one (a `not_swinging` part, a `may_fold`) rebuilds from its config alone. `build` reads it before assemble, as it reads the flag's file, and `check.json`'s `requirements.file` records it with `path` as declared. Given beside `--requirements`, the two must name the same file once resolved, or a file of the same bytes, and the declaration is read and recorded (a build given both writes what the config alone writes); otherwise `BUILD_REQUIREMENTS_CONFLICT`, naming both. Not a non-empty string: `CONFIG_FIELD_TYPE`; no such file, where the config is read from a path: `CONFIG_FILE_PRESENT`. `check`, `compose`, `mesh-draft`, `remesh` and `retune` do not read it: their `--requirements` is the only door. Absent, nothing is read and no byte of any output moves |
|
|
144
145
|
|
|
145
146
|
A skeleton alternate may declare `anchor: {neck: "head"}` (issue #543):
|
|
@@ -282,8 +283,14 @@ costs nothing a bar reads (`demo`, tips 371 px apart: 1.050 for the pair, as for
|
|
|
282
283
|
alone), and on one mass with the two chains close it squeezes the lattice between them
|
|
283
284
|
(issue #314: tips 39 px apart, an edge at 0.065 of its rest length). Whether the hair is one
|
|
284
285
|
mass is not something the proposer can read off the opaque shape — both chains always hang
|
|
285
|
-
on the one `back hair` part —
|
|
286
|
-
|
|
286
|
+
on the one `back hair` part — but their lattice and motion are readable. A fresh draft now
|
|
287
|
+
uses the squeeze reading above (issue #751): when an opposed pair fails and reversing the
|
|
288
|
+
second chain's signs passes the unchanged bar, it drafts that passing sign and adds a
|
|
289
|
+
`shared-mesh chain signs` note with both figures and the reason. Magnitudes and timing
|
|
290
|
+
stay unchanged. Every shared pair is re-read; an alternative introducing a new or worse
|
|
291
|
+
finding is not adopted. When no measured alternative passes, the draft and LINT remain.
|
|
292
|
+
Already-clean and unread pairs are unchanged. `propose --from-config` only observes the
|
|
293
|
+
supplied config: it still prints the original LINT and never rewrites its amplitudes.
|
|
287
294
|
|
|
288
295
|
**A posed figure: `propose --keypoints`.** Without joints the proposer reads the
|
|
289
296
|
torso by screen y: the hip 0.14 face heights below `bottomwear`'s top edge (or below
|
|
@@ -1274,7 +1281,7 @@ silhouette holds besides the art, each pixel counted once: `filledHolePixels` (t
|
|
|
1274
1281
|
holes), `grownPixels` (added by the margin), `pinchFilledPixels` (added by the pinch fill) and
|
|
1275
1282
|
`grownHolePixels` (transparent pixels the grown silhouette encloses — a notch whose mouth grew
|
|
1276
1283
|
shut))
|
|
1277
|
-
and, per region, the vertices its bone reaches (`g > 0`) and holds alone (`g
|
|
1284
|
+
and, per region (`regions: [{ name, bone, reached, whole }, ...]`, `src/rig.ts`), the vertices its bone reaches (`reached`, where the region owns a nonzero contribution, `g > 0`) and holds alone (`whole`, where `g >= 1`) — static setup-weight vertex counts, not a rendered frame-to-frame or `> 0.5 px` counterfactual-motion count.
|
|
1278
1285
|
Across contour, automatic and influence reports, `regions[].bone` and `reach.nearest`
|
|
1279
1286
|
name the authored template bones used to calculate the regions and reach. Stops and turn
|
|
1280
1287
|
can rebind the emitted attachment after those calculations; these diagnostic names are
|
|
@@ -1834,8 +1841,8 @@ that crosses the region with no point of it inside to split at — is still stop
|
|
|
1834
1841
|
|
|
1835
1842
|
The package proposes no expression and keys nothing but the idle; what it gives is a rig whose
|
|
1836
1843
|
face is bones (`eye_r`, `eye_l`, `brow_r`, `brow_l`, `mouth` on `reference-sample`) and one door for
|
|
1837
|
-
animations you write over them, `motion.animations_from` (the row above, issues #183 and #569).
|
|
1838
|
-
Name a file in rig-c's motion-spec shape, its path relative to the directory `config.json` sits
|
|
1844
|
+
animations you write over them, `motion.animations_from` (the `motion.animations_from` row in the §3 field table above, issues #183 and #569).
|
|
1845
|
+
Name a file in rig-c's motion-spec shape whose top-level keys are `"spec"` (`"rigc-motion/1"`) and `"animations"` (plus optional `"note"` / `"<name>_note"` strings and `"x-<name>"` records; any other top-level key — rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` included — is refused by `CONFIG_KEY_KNOWN`), its path relative to the directory `config.json` sits
|
|
1839
1846
|
in — not the working directory:
|
|
1840
1847
|
|
|
1841
1848
|
```jsonc
|
|
@@ -1867,8 +1874,8 @@ same shape over the face bones, and `examples/demo/animations.json` holds seven
|
|
|
1867
1874
|
defines `curve` as four numbers per value channel: absolute control-point
|
|
1868
1875
|
`[time, value, time, value]`, not normalized graph handles. The first chest key above
|
|
1869
1876
|
shapes its span to the next key. A key carries `ease` or `curve`, never both, and
|
|
1870
|
-
the final key carries neither. Top-level motion fields are a separate contract:
|
|
1871
|
-
`animations_from`
|
|
1877
|
+
the final key carries neither. Top-level motion fields are a separate contract (the `motion.animations_from` row in the §3 field table):
|
|
1878
|
+
`animations_from` accepts only `spec` and `animations` at the top level (plus `note` / `<name>_note` and `x-<name>`), refusing rig-c's `easings`, `groups`, `setup`, `physics`, `mix`, `archetype` and `cut` with `CONFIG_KEY_KNOWN` (`known: spec, animations`); tracks inside `animations` may use the easings `shut` and `open` and the groups `eyes` and `brows` that `motion.json` already holds.
|
|
1872
1879
|
- **Key times strictly increase within a track, and the last is at `duration`** — rig-c's rule
|
|
1873
1880
|
(its AUTHORING §4.5, "`t` is in seconds and must strictly increase"; R7: no key past the
|
|
1874
1881
|
declared duration, and a duration more than a frame longer than the last key is refused).
|
|
@@ -2091,7 +2098,7 @@ fragment below, cut to the bust:
|
|
|
2091
2098
|
|
|
2092
2099
|
A region adds vertices: its `spacing` is finer than the mesh's, and every one of them is a
|
|
2093
2100
|
triangle more for the runtime to skin. Before the first build, count them:
|
|
2094
|
-
`rig-parts mesh-stats --config config.json --parts work/rig` (issue #566; `work`
|
|
2101
|
+
`rig-parts mesh-stats --config config.json --parts work/rig` (issue #566; `--parts` is the directory holding `parts.json` and `parts/`: `work/rig` from step 7's `assemble --out work`, or `out` from `build --out out`, not `work` itself — §4) runs the rig stage's own
|
|
2095
2102
|
mesh construction over the assembled parts, without rigc, without `check`, and prints one line
|
|
2096
2103
|
per mesh — `mesh-stats: topwear — contour 320 vertices, 568 triangles` on `reference-sample` —
|
|
2097
2104
|
and the total, `mesh-stats: total 1908 triangles over 6 mesh(es)`, the counts the build's
|
|
@@ -2102,8 +2109,8 @@ it runs in under a second; the build it saves runs the render and `check` as wel
|
|
|
2102
2109
|
roughly as area / spacing², including the transition band: for a circle that area
|
|
2103
2110
|
extends to `r + band`, not just `r`. The outline, background grid and sampled region
|
|
2104
2111
|
rings also contribute, so multiplying the *whole* triangle count by that ratio
|
|
2105
|
-
incorrectly scales the fixed part. Read the part's `mesh_report.json` row first, and use
|
|
2106
|
-
`mesh-stats` for the candidate rather than waiting for a rendered build.
|
|
2112
|
+
incorrectly scales the fixed part. Read the part's `mesh_report.json` row first (`regions[].{name, bone, reached, whole}` and `contour` in `rig/mesh_report.json` or `out/rig/mesh_report.json` — see *A contour mesh*, *What it reports*, above, which `mesh-stats` does not print), and use
|
|
2113
|
+
`mesh-stats` for the candidate's `{part, mode, vertices, triangles}` dry count rather than waiting for a rendered build.
|
|
2107
2114
|
|
|
2108
2115
|
A bounded calibration on the public [family office config](https://github.com/rig-c/examples/blob/d5a1768ce4a2d1e3f5726d1739cd0da4a63b0e13/family/roa/config.json)
|
|
2109
2116
|
uses both `topwear` bust regions at spacing 14. Its pinned
|
|
@@ -2246,15 +2253,15 @@ the wind — is the consumer's, and the recipe drafts no key and no stimulus.
|
|
|
2246
2253
|
```
|
|
2247
2254
|
|
|
2248
2255
|
(The selftest's fixture recipe, `fixtures/cloth.ts`: values chosen to exercise every
|
|
2249
|
-
rule, not advice. It leaves `length_ratio` and `strength` out, so the recipe's own
|
|
2256
|
+
rule, not advice — in particular, `"back hair": { "chains": 2, … }` exercises explicit multi-tree splitting and is not a recommendation to declare two trees on a one-mass side. It leaves `length_ratio` and `strength` out, so the recipe's own
|
|
2250
2257
|
defaults are what is built and measured below.)
|
|
2251
2258
|
|
|
2252
2259
|
What each rule drafts (`src/cloth.ts` holds them):
|
|
2253
2260
|
|
|
2254
2261
|
| rule | drafts | from |
|
|
2255
2262
|
| --- | --- | --- |
|
|
2256
|
-
| where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the cloth's own bottom under each column (4 px above the part box's bottom when every column reaches the bottom band, or 4 px above where the cloth's alpha ends under that column on a floor-spread skirt whose middle hem ends above bare thighs; a column with no cloth below the root row gets no tree drafted there and emits a note saying so, issue #438). `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each strand that hangs below the chin (the lock rule's), from `head`, 0.22 face heights above the eye line to 5 px below the strand
|
|
2257
|
-
| trees | tree k of `chains` owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. On `back hair`, `chains` is optional (issues #390, #445, #461): when omitted, `propose --cloth` derives the tree count on each side from the side's **visible hair masses** — connected components of the `back hair` part's alpha below the eye-line root row (after skipping any undivided crown rows that bridge continuously across the eye axis), merged when they touch within one mesh grid cell — placing `max(1, floor(w / (4 * grid)) + 1)` trees inside each mass across its root-row opaque width `w` (one tree per `4 * grid` of horizontal reach, where a tree's segment weight `1 / (d + r)^2` with `r ≈ 0.42 * grid` drops to `MIN_WEIGHT = 0.03` at `2 * grid` on each side of the trunk), rooted at that mass's own top row and with every link inside that mass's column range; `propose`'s `LINT` names the masses it found and their columns when a side's tree count or link leaves them. An explicit `chains` that exceeds what the narrower side's opaque width at the eye-line root row holds (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`) or places a root off the 15 px dilated art is refused (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`). With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issues #403, #392), sibling branches keep `strength.branch` across the fork, the mesh's `r` is raised to `grid`, and the rig stage blends each fork's sibling branch weight shares across four passes of 1-ring mesh-edge averaging (self weight 0.5, floor 0.005, cap 8 influences) — every share alike, trunk, branch and fixed bones, none held in place — holding the triangles where two branches' cells meet; when the recipe also declares `influence`, the drafted influence mesh carries `hold_tip: true` and `max` at least 8, and the rig stage smooths it by the same passes capped at that `max` (issue #615, the `meshes.<part>.influence` row) | `chains`, `links`, `split` |
|
|
2263
|
+
| where | `bottomwear`: from `hip`, the root row 20 px below hip's y (the keyed chains' row), the tip row 4 px above the cloth's own bottom under each column (4 px above the part box's bottom when every column reaches the bottom band, or 4 px above where the cloth's alpha ends under that column on a floor-spread skirt whose middle hem ends above bare thighs; a column with no cloth below the root row gets no tree drafted there and emits a note saying so, issue #438). `back hair` that reaches below the shoulders: from `head`, per side of the eye axis (twin tails are a side each), the eye line to 4 px above its bottom. `front hair`: each qualifying strand that hangs below the chin (the lock rule's: each connected component below `chin + 4` of height at least `0.3` face heights, `src/propose.ts`), from `head`, 0.22 face heights above the eye line to 5 px below the strand — the recipe's `chains`, `links` and `split` are applied separately to each qualifying hanging strand and do not replace the fringe's fixed three two-link columns (`bang_r`, `bang_c`, `bang_l` keep their two links and their places and take physics on both links) | the keyed chains' own rows, which these replace |
|
|
2264
|
+
| trees | tree k of `chains` (`N`) owns the cell k/N .. (k+1)/N of the art's width in every row, and its links sit at the cell's centre in the 24-row band there, so a piece that widens fans its trees. **Count unit of `chains`:** on `back hair`, an explicit `chains: N` is passed to **each emitted side of the eye axis** (`N` trees on `r` and `N` on `l` when both sides emit, not a combined total across both sides; `src/cloth.ts`, `src/propose.ts`); on `front hair`, `chains: N` is applied **separately to each qualifying hanging strand** and does not replace the fringe's fixed two-link columns (`src/propose.ts`). On `back hair`, `chains` is optional (issues #390, #445, #461): when omitted, `propose --cloth` derives the tree count on each side from the side's **visible hair masses** and root-row reach — it is **not** a universal default of 1 or 2 trees for every painting (`RECIPE_BACK_HAIR_CHAINS = 2` in `src/cloth.ts` is only the fallback when `draftTrees` is called with neither `masses` nor `chains`) — connected components of the `back hair` part's alpha below the eye-line root row (after skipping any undivided crown rows that bridge continuously across the eye axis), merged when they touch within one mesh grid cell — placing `max(1, floor(w / (4 * grid)) + 1)` trees inside each mass across its root-row opaque width `w` (one tree per `4 * grid` of horizontal reach, where a tree's segment weight `1 / (d + r)^2` with `r ≈ 0.42 * grid` drops to `MIN_WEIGHT = 0.03` at `2 * grid` on each side of the trunk), rooted at that mass's own top row and with every link inside that mass's column range; `propose`'s `LINT` names the masses it found and their columns when a side's tree count or link leaves them. An explicit `chains` that exceeds what the narrower side's opaque width at the eye-line root row holds (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`) or places a root off the 15 px dilated art is refused (`PROPOSE_CLOTH_BACK_HAIR_CHAINS`). With `split`, the trunk's tip is the fork, and branch b of `into` follows the centre of its share of the cell. Chains are named `<prefix><k>_` (trunk) and `<prefix><k><a, b, …>_` (branches): `skirt`, `hairback_r`/`hairback_l`, `lockt`. With `split.hold_tip: true` (issues #403, #392), sibling branches keep `strength.branch` across the fork, the mesh's `r` is raised to `grid`, and the rig stage blends each fork's sibling branch weight shares across four passes of 1-ring mesh-edge averaging (self weight 0.5, floor 0.005, cap 8 influences) — every share alike, trunk, branch and fixed bones, none held in place — holding the triangles where two branches' cells meet; when the recipe also declares `influence`, the drafted influence mesh carries `hold_tip: true` and `max` at least 8, and the rig stage smooths it by the same passes capped at that `max` (issue #615, the `meshes.<part>.influence` row) | `chains`, `links`, `split` |
|
|
2258
2265
|
| lengths | link j's length is the first's times q^j, q = `length_ratio`^(1/(links − 1)), the whole spanning root row to tip row: the links shorten toward the tip | `length_ratio` (default 0.5, below) |
|
|
2259
2266
|
| stiffness | a trunk link takes `strength.trunk`, a branch link `strength.branch`, and the edge — the outermost branch on each outer side of the piece (both sides of a skirt or a strand; the outer side of each back-hair side; or, under `split.hold_tip: true` with `strength` left out, kept at `strength.branch` so a fork's sibling branches do not pull apart at the default 2:1 stiffness), or without `split` the outermost tree — `strength.edge`; a fringe column is a trunk, its outer two the edge. **Strength does not fall along a chain**: a tip reads soft because each link turns on top of every link above it, so the motion accumulates down the chain at one strength. Only the edge is declared softer | `strength` (default trunk 100, branch 100, edge 50, below) |
|
|
2260
2267
|
| response | link j of an n-link path takes `wind` and `gravity` at j/(n − 1) of the way from the root value to the tip value; a single-link path takes the tip value. Each is a scalar **multiplier** of the environment the consumer sets (spine-core's skeleton `windX, windY`, `gravityX, gravityY`; rig-c 2.52.0's live track `setEnvironment`, rig-play 1.10.0's `environment()`): no direction is drafted | `wind`, `gravity` |
|
|
@@ -2311,8 +2318,8 @@ chain, a constraint or a track added by hand survives a `--write-config`. An ent
|
|
|
2311
2318
|
recipe re-drafts or removes that the author changed by hand (it equals neither draft) is
|
|
2312
2319
|
not dropped: the run is refused, `PROPOSE_WRITE_CONFIG_CONFLICT`, naming the entry
|
|
2313
2320
|
(`config.constraints[40] "skirt0a_0_physics"` in CL207), the first field the hand edit holds and
|
|
2314
|
-
what the draft writes there, every conflict at once and nothing written; take the draft
|
|
2315
|
-
|
|
2321
|
+
what the draft writes there, every conflict at once and nothing written; to take the recipe's draft,
|
|
2322
|
+
remove the hand-edited track, bone or constraint from `config.<section>` (or revert the hand edit) and run `propose --cloth` again, or leave the recipe out for that part. **A changed recipe
|
|
2316
2323
|
(issue #571).** The draft of the recipe as it stood before a change is neither of the
|
|
2317
2324
|
two drafts, so a config holding that draft untouched would read as hand-edited at every
|
|
2318
2325
|
entry the change moves (29 refusals on the public `wind` example with
|
|
@@ -2780,6 +2787,66 @@ full loader before its assemble stage writes anything.
|
|
|
2780
2787
|
files, not the art (§6, *Reading the inputs*). A `WARN` line is about the art: a
|
|
2781
2788
|
layer See-through made that is not plausibly part of the figure, which step 6
|
|
2782
2789
|
leaves out (§6, *Plausibility*). It refuses nothing.
|
|
2790
|
+
The trailing `drawn(a>8)_left,top`, `drawn(a>8)_right,bottom`, `drawn(a>8)_size`
|
|
2791
|
+
and `opaque(a>=250)_left,top`, `opaque(a>=250)_right,bottom`,
|
|
2792
|
+
`opaque(a>=250)_size` columns give two boxes of each drawn layer's original
|
|
2793
|
+
source alpha, in **input-canvas px**, beside the unchanged manifest/layer box.
|
|
2794
|
+
All original columns stay as read: legacy `opaque_px` still counts **alpha >8**.
|
|
2795
|
+
The second box uses the existing **alpha >=CORE_ALPHA (250)** cut, shared with
|
|
2796
|
+
assemble's opaque ownership, projection and seam logic. Only that alpha cut is
|
|
2797
|
+
applied here: no owner clipping, projection-core erosion, ghost cleanup or
|
|
2798
|
+
rig resampling. Alpha 249 is drawn but not CORE; 250 and 251 meet both cuts.
|
|
2799
|
+
Add the reader's `left,top` to a PNG-local pixel; right and bottom are exclusive,
|
|
2800
|
+
so one painted pixel has a 1x1 box. `none` and a line naming the layer say that
|
|
2801
|
+
it has no box at that threshold. A fully transparent layer has neither box;
|
|
2802
|
+
a layer with drawn support but no CORE support is explicitly named as such.
|
|
2803
|
+
Hidden art remains listed apart and is never drawn.
|
|
2804
|
+
|
|
2805
|
+
**Body-group union (issue #757).** The summary unions exactly the drawn layers
|
|
2806
|
+
whose reader tag has `group === 'body'`: the existing body tags include front
|
|
2807
|
+
and back hair, head, neck/neckwear, topwear, handwear (including its sides),
|
|
2808
|
+
bottomwear, legwear, footwear, tail, wings and objects, plus the derived
|
|
2809
|
+
`hand-r/l` and `drape-r/l`. Face, eyes, headwear and the other head-group tags,
|
|
2810
|
+
author layers and hidden art do not contribute. A tag classifies a layer; it
|
|
2811
|
+
does not prove anatomical identity. The main height line uses **alpha >=250**;
|
|
2812
|
+
the raw **alpha >8** union is printed separately and can span the whole input
|
|
2813
|
+
canvas because of boundary support. Each union's height is `bottom - top`,
|
|
2814
|
+
never a sum of layer heights, and an empty union has height unavailable.
|
|
2815
|
+
This is a per-layer thresholded-mask union (OR), not RGBA-over compositing:
|
|
2816
|
+
overlapping source alpha below the applicable cut cannot accumulate into it:
|
|
2817
|
+
two alpha-8 layers do not become drawn support, and two alpha-249 layers do not
|
|
2818
|
+
become CORE support. Neither union is an anatomical height or the height of
|
|
2819
|
+
the final assembled parts. A head-run
|
|
2820
|
+
reading is still only that input's body-group union.
|
|
2821
|
+
|
|
2822
|
+
**Units before choosing `assemble.rig_scale`.** `layers` reads one input and
|
|
2823
|
+
knows no painting size or full/head role or registration. For scale guidance,
|
|
2824
|
+
run `layers` on the **full run** and use its **alpha >=250** body-group extent
|
|
2825
|
+
as the source reference, with the mapping below when it is known. At the
|
|
2826
|
+
[public task-01 input pin](https://github.com/rig-c/exam/tree/131e80f794830238520aae8709db7155719813db/tasks/01-build/inputs),
|
|
2827
|
+
the full-run source CORE union is 911 input-canvas px tall; the head-run 964
|
|
2828
|
+
is a crop extent and is not the full scale reference. These input roles are
|
|
2829
|
+
supplied by that fixture's contract, not inferred by this CLI from a file name.
|
|
2830
|
+
The CLI prints generic body-group unions, without a figure-height or rig-scale
|
|
2831
|
+
advice line. Only with a known full-run
|
|
2832
|
+
mapping from `inputs` can its coordinates be converted: for painting `w x h`,
|
|
2833
|
+
square side `L = max(w,h)`, run resolution `R`, and padding
|
|
2834
|
+
`padX = floor((L-w)/2)`, `padY = floor((L-h)/2)`, a run point maps to painting
|
|
2835
|
+
`(x*L/R-padX, y*L/R-padY)`. This is `checkGeometry`'s `fullK = L/R` and the
|
|
2836
|
+
full `runMap` before rig scale; the mapped vertical extent is `height*L/R`.
|
|
2837
|
+
It is an affine extent, not a newly resampled or clipped painting-pixel mask.
|
|
2838
|
+
For an artist's single run at one file pixel per painting pixel, the raw
|
|
2839
|
+
file's height needs no scale conversion; assemble's internal square padding
|
|
2840
|
+
only translates it. A separately generated head crop has its own crop map
|
|
2841
|
+
and cannot supply a full-body height. Contact-sheet tiles resize independently
|
|
2842
|
+
and preserve no common placement, so their pixels are not measurement inputs.
|
|
2843
|
+
The 1,100–1,200 rig-px advice in §3 uses the union of assembled parts' boxes,
|
|
2844
|
+
the `H` of `propose`'s `mesh spacing:` note. Ghost cleanup, the run-to-rig
|
|
2845
|
+
resampling and the chosen parts can change the bounds and threshold coverage:
|
|
2846
|
+
the analytic conversion above does not measure that final `H`. Instead,
|
|
2847
|
+
use a known painting-space extent for scale guidance and inspect the parts
|
|
2848
|
+
after assembly. Do not substitute this tag-group union for anatomy or assume
|
|
2849
|
+
its input pixels are painting pixels. `layers` performs no registration.
|
|
2783
2850
|
4. `rig-parts propose --head-box --full inputs/layers/full --canvas <W>x<H> --write-config config.json`
|
|
2784
2851
|
saves `seethrough.head_box` in the existing config. `<W>x<H>` is the original
|
|
2785
2852
|
painting's size, not the padded square's. The existing optional `--no-back-hair`
|
|
@@ -2825,7 +2892,7 @@ full loader before its assemble stage writes anything.
|
|
|
2825
2892
|
no later stage can see — then
|
|
2826
2893
|
`rig-parts propose --parts work/rig --source inputs/painting.png --out work --write-config config.json` →
|
|
2827
2894
|
`work/proposal.json` and `work/render/landmarks.png` (+ `_head`). The flag saves
|
|
2828
|
-
each of `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn` and `proposed_rig_scale` it
|
|
2895
|
+
each of `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `motion_seams` and `proposed_rig_scale` it
|
|
2829
2896
|
wrote into the config: `limbs` is written only with `--keypoints`, `constraints`
|
|
2830
2897
|
only with `--cloth` and `turn` only with `--full`/`--head` (`PROPOSAL_CONFIG_SECTIONS` in `src/propose.ts` is the list,
|
|
2831
2898
|
and the selftest's `TY18` holds this sentence to it). A `limbs` block left out
|
|
@@ -2864,11 +2931,14 @@ full loader before its assemble stage writes anything.
|
|
|
2864
2931
|
For a posed figure (seated, reclining), add `--keypoints keypoints.json` (and
|
|
2865
2932
|
`--person <id>` when the file holds more than one person): the joints it gives
|
|
2866
2933
|
place the neck, hip, chest and sleeves (§3, *A posed figure*).
|
|
2867
|
-
8. Correct, then `rig-parts propose
|
|
2934
|
+
8. Correct, then `rig-parts propose --parts work/rig --source inputs/painting.png --out work --from-config config.json` to redraw the
|
|
2868
2935
|
config's own bones and LINT them — every chain link against its mesh's art, and
|
|
2869
2936
|
the single bones `hip` and `chest` against each other and the figure (a config
|
|
2870
2937
|
without them prints a `note:` that those lines did not run); repeat until it
|
|
2871
|
-
prints no LINT line (exit 0). Add the same `--keypoints` to lint by the joints
|
|
2938
|
+
prints no LINT line (exit 0). Add the same `--keypoints` (and `--person`) to lint by the joints;
|
|
2939
|
+
`--from-config` proposes nothing and takes `--parts`, `--source`, `--out`, `--from-config` and
|
|
2940
|
+
optional `--keypoints` (`--person`) only (not `--full`, `--head`, `--cloth`, `--write-config`,
|
|
2941
|
+
`--wrist-snap`, `--grid-rule`, `--only-missing` or `--compare`).
|
|
2872
2942
|
Config from here on: the `full` row.
|
|
2873
2943
|
`rig-parts compare --left work/proposal.json --right config.json` says what the
|
|
2874
2944
|
correction changed, bone by bone: each origin, parent, tip, length and direction
|
|
@@ -2979,16 +3049,18 @@ full loader before its assemble stage writes anything.
|
|
|
2979
3049
|
The command-order selftest runs these stages on each fetched example from a
|
|
2980
3050
|
config holding only `key`, `seethrough` and `assemble.rig_scale` (`RL01`). For
|
|
2981
3051
|
the proposal step, copy `bones`, `meshes`, `regions`, `limbs`, `motion`,
|
|
2982
|
-
`constraints`, `turn` and `proposed_rig_scale` into the config, each section the
|
|
3052
|
+
`constraints`, `turn`, `motion_seams` and `proposed_rig_scale` into the config, each section the
|
|
2983
3053
|
proposal wrote. `RL01` exercises that manual route and does not execute
|
|
2984
3054
|
`--write-config`. The save forms above write the fields owned by their mode;
|
|
2985
3055
|
a saved draft still needs validation.
|
|
2986
3056
|
|
|
2987
3057
|
### Counting the triangles before a build (`mesh-stats`, issue #566)
|
|
2988
3058
|
|
|
2989
|
-
`rig-parts mesh-stats --config config.json --parts work/rig`
|
|
2990
|
-
|
|
2991
|
-
|
|
3059
|
+
`rig-parts mesh-stats --config config.json --parts work/rig` (after `assemble --out work`) or
|
|
3060
|
+
`rig-parts mesh-stats --config config.json --parts out` (after `build --out out`) prints the
|
|
3061
|
+
vertices and triangles of every mesh the config states and their total, against the parts
|
|
3062
|
+
`assemble` wrote (`--parts` is the directory holding `parts.json` and `parts/`: step 7's
|
|
3063
|
+
`work/rig` from `assemble --out work`, or `out` from `build --out out` — not `work` itself), in seconds.
|
|
2992
3064
|
It is the rig stage's mesh construction itself — the same function the rig stage writes
|
|
2993
3065
|
`mesh_report.json` from — run without rigc, without `check` and without writing a file, so a
|
|
2994
3066
|
config can be tuned to a triangle budget before the first build and between builds:
|
|
@@ -3000,14 +3072,14 @@ mesh-stats: total 1816 triangles over 9 mesh(es)
|
|
|
3000
3072
|
```
|
|
3001
3073
|
|
|
3002
3074
|
(`demo` as tracked, nine lattices.) The package holds no triangle budget: a budget is the
|
|
3003
|
-
consumer's, and the command prints no line against one.
|
|
3075
|
+
consumer's, and the command prints no line against one. `mesh-stats` runs `buildRig` (`src/meshstats.ts`) and projects its `meshReport` via `meshStatsRows` to `{part, mode, vertices, triangles}` and the total (`meshStatsLines`) — one line per mesh, in parts.json's
|
|
3004
3076
|
order, the row order of `mesh_report.json`; the mode is `lattice` for a `grid` entry,
|
|
3005
|
-
`contour`, `auto` or `
|
|
3077
|
+
`contour`, `auto`, `influence` or `explicit`. It writes no `mesh_report.json` or skeleton data and runs no `rigc` or `check`. For per-region vertex counts on a contour mesh (`regions: [{ name, bone, reached, whole }, ...]`, where `reached` counts vertices with a nonzero region contribution, `g > 0`, and `whole` counts vertices where `g >= 1`; `src/rig.ts`), read the built rig's `mesh_report.json` (`rig/mesh_report.json` from `rig`, or `out/rig/mesh_report.json` from `build --out out` — see §3, *A contour mesh*, *What it reports*, and *Recipe: a soft region driven by physics*): those fields are written by `rig` / `build` and are not printed by `mesh-stats`. Neither `mesh-stats`'s dry totals nor `mesh_report.json`'s static `regions[].{reached, whole}` setup-weight counts are a rendered `> 0.5 px` counterfactual-motion count or a claim that the config passed the compiler, coverage, motion or visual `check` gates (§3, *Recipe: a soft region driven by physics*). An `auto` part's count is its reduction's result: when rigc's
|
|
3006
3078
|
motion gate refuses that result, the rig stage replays an earlier accepted step, which needs
|
|
3007
3079
|
rigc, and the line says so. A problem the rig stage would refuse — a part with no PNG, an
|
|
3008
3080
|
outline that does not close, a name `bones` does not declare — is the rig stage's own refusal,
|
|
3009
|
-
by the same name, exit 1; it takes no `--requirements`, because the rig stage's meshes read
|
|
3010
|
-
none, and no `--idle-keys`, because where the idle's keys go moves no vertex.
|
|
3081
|
+
by the same name, exit 1; it takes `--config` and `--parts` alone (no `--candidate`, `--regions`, `--report`, `--requirements`, because the rig stage's meshes read
|
|
3082
|
+
none, and no `--idle-keys`, because where the idle's keys go moves no vertex).
|
|
3011
3083
|
|
|
3012
3084
|
### For artists: your own layered file (issue #359)
|
|
3013
3085
|
|
|
@@ -3140,13 +3212,13 @@ one of them occluded, so nothing shows it at rest; paint it there if the face wi
|
|
|
3140
3212
|
move off it (`AS245`).
|
|
3141
3213
|
|
|
3142
3214
|
**Saving proposed config fields (`--write-config`, issue #356).** The flag is a
|
|
3143
|
-
valued destination path. Its modes have different ownership:
|
|
3215
|
+
valued destination path with two destination rules — **in place on an existing regular config** without `--cloth` (and for `assemble --propose-plan`, `--write-config` must name `--config` itself; §4, step 6), versus **a new file** for `propose --cloth --write-config` (`PROPOSE_WRITE_CONFIG_FRESH`, never over the `--cloth` config or an earlier one; §3, *The config written*). Its modes have different ownership:
|
|
3144
3216
|
|
|
3145
3217
|
| proposal mode | destination | fields written |
|
|
3146
3218
|
| --- | --- | --- |
|
|
3147
3219
|
| `propose --head-box` | existing regular config | `seethrough.head_box` |
|
|
3148
3220
|
| `assemble --propose-plan` | existing regular config; must name `--config` itself | `assemble.plan`, `assemble.extend_below_crop` |
|
|
3149
|
-
| ordinary `propose --parts` without `--cloth` | existing regular config | each present `PROPOSAL_CONFIG_SECTIONS` value: `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `proposed_rig_scale` |
|
|
3221
|
+
| ordinary `propose --parts` without `--cloth` | existing regular config | each present `PROPOSAL_CONFIG_SECTIONS` value: `bones`, `meshes`, `regions`, `limbs`, `motion`, `constraints`, `turn`, `motion_seams`, `proposed_rig_scale` |
|
|
3150
3222
|
| ordinary `propose --parts … --only-missing` (issues #671, #679) | existing regular config | only resolvable `meshes.<part>` or `regions.<part>` for an unattached part: attached covers existing `meshes` and `regions`, source parts consumed by the config's own `limbs.<name>.segments[].from`, and `assemble.patches` (always regions), with or without `--keypoints`. Entries are checked against the config's bones and chains, including mesh and `auto` bone/region references; an unresolved entry is never written. Each skipped part gets a note naming its attachment or the unresolved reference and why. An accepted split part from `full:drape-<s>` / `full:hand-<s>` also gains its missing `assemble.plan` row (drape before the full run's `handwear-<s>` row, hand after it); added row by row and entry by entry, every existing byte as read |
|
|
3151
3223
|
| `propose --cloth <input.json>` | new file | the recipe's edits spliced into the cloth config; §3, *The config written*, gives entry ownership, hand-edit conflicts and `--from <previous.json>` |
|
|
3152
3224
|
|
|
@@ -3170,14 +3242,12 @@ loader validates the candidate after unresolved entries have been skipped with a
|
|
|
3170
3242
|
naming the part, reference and reason; a skipped entry gets no plan row, and a part of any
|
|
3171
3243
|
other origin gets no plan row; nothing missing keeps the bytes and mtime; stderr names each added row and entry. It is a usage error with `--head-box`, `--cloth`
|
|
3172
3244
|
or `--from-config`, or without `--parts` or `--write-config`.
|
|
3173
|
-
All four modes use one file-writing adapter
|
|
3174
|
-
already-checked splice text and intentional partial-config contract
|
|
3175
|
-
loader is not imposed on it. Publication links the complete same-directory
|
|
3245
|
+
All four modes use one file-writing adapter, split between the two destination
|
|
3246
|
+
rules above: without `--cloth`, `--write-config` updates an existing regular config in place (`CONFIG_FILE_PRESENT` when absent) so the stage's loader (§4, *What each step requires of the config*) validates a same-directory candidate in place before replacement, and for `assemble --propose-plan` `--write-config` must name `--config` itself (a different `--write-config` destination for `assemble --propose-plan` is a usage error, §4 step 6); with `--cloth`, `propose --cloth <input.json> --write-config <out.json>` writes to a new file (`PROPOSE_WRITE_CONFIG_FRESH` when the path exists) because it splices the recipe's drafted entries into `--cloth`'s own text the way `mesh-draft` writes its config, keeping its already-checked splice text and intentional partial-config contract without imposing the full loader on it (§3, *The config written*). Publication links the complete same-directory
|
|
3176
3247
|
staged file into a destination that must still be absent, so an intervening
|
|
3177
3248
|
creator is refused without overwrite. Removing the staged temporary happens
|
|
3178
3249
|
after publication: if that cleanup fails, `CONFIG_WRITE_FAILED` may accompany
|
|
3179
|
-
an already-published complete config. Inspect both named paths before retrying.
|
|
3180
|
-
`--write-config` destination for `assemble --propose-plan` is a usage error.
|
|
3250
|
+
an already-published complete config. Inspect both named paths before retrying.
|
|
3181
3251
|
For ordinary and cloth proposals, the destination must be separate from all four
|
|
3182
3252
|
artifacts under `--out`: `proposal.json`, `basis.json`, `render/landmarks.png` and
|
|
3183
3253
|
`render/landmarks_head.png`. Matching paths, directory-symlink aliases and
|
|
@@ -3190,7 +3260,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
|
|
|
3190
3260
|
| --- | --- | --- | --- |
|
|
3191
3261
|
| `layers` | the table, then one `author-made: layer "author:<label>" — …` line per layer the author made (group `author` in the table; §5, *A layer the author made*), then the `WARN` lines | every tag the plan will need has opaque pixels; one `face` in the head run; `0 WARN line(s)` | a run whose layer PNG is not its box's size (`LAYERS_PNG_MATCHES_BBOX`); a `WARN PLAN_LAYER_…` line (§6, *Plausibility*) |
|
|
3192
3262
|
| `sheet` of both runs | the tile list (and the sheet, if you can see) | eyes, irises, lashes and brows as left/right pairs in the head run | a head box that cut off an ornament: move `head_box`, re-run the head crop |
|
|
3193
|
-
| `assemble` | one line per part — its counts (`op=` opaque, `vis=` visible, `src=` taken / candidates, `unproj=` visible but not projected, `drift=<n> (<p>% of core)`, `merged=`, `seam=`; *parts.json*, below). `drift=` is `refused_drift_px` in rig px and its share of the part's candidates, `projected_core_px`, which it is a subset of (issue #314); no bar reads either. On the four public examples the share runs to 94.5 % (`scarf` `hair_back`, 479 of 507) and the count to 26,472 (`scarf` `topwear`, 22.3 %), and the seam override repaints refused top-most pixels afterwards, so a large count says where See-through's colour was not taken, not that the part is unlike the painting: the `drift:` line below is the one that names a body of them another part holds. Then the `pixels:` totals (opaque = visible + occluded; taken; visible but not projected), then `recomposite vs source: mean \|d\|, within 8, error px > 40, uncovered error px`, then `uncovered holes (8-connected): N` and the largest five as `uncovered hole K: <px> px at x,y wxh (between "<part>" <px> px, …)`, then one `uncovered: <n> of the <N> uncovered error px lie on the full run's "<tag>", in a body of <px> px at x,y wxh; <the rule that left it out>` line per full-run layer the plan does not take from the full run whose uncovered error holds a body (5x5-opened, 8-connected, at least 150 full-run px in rig px), then one `drift: "<part>" refuses <n> px of <run>:<tag> (its colour more than 90 off the painting, max channel), in a body of <px> px at x,y wxh (…); by the plan's draw order "<holder>" holds <px> px of it (…), "<holder>" drawn in front of "<part>"` line per part whose drift refusals hold a body (the same opening and bar) that another part holds in the draw order — that layer is not what the painting shows there (none on the five public paintings), then, per subset alternate set, one `LINT set "<set>" <part>: <layer part> holds <n> islands (8-connected, alpha above 8)[, and <s> speck(s) under 1 % of the largest (<f> px), each with the island nearest it], kept the one under <joints> (<k> px), dropped <m> (<d> px)` line per limb part cut from a layer of more than one island when the set names one limb side of it (issue #588; issue #608: a joint taken to the nearest island reads `<bone> [x, y] (<e> px off it, within its cap's radius <r>)`, and a part that lost no pixel `dropped none`), then one `LINT set "<set>" <part>: <layer part> holds <limb> and <other limb> in one island (8-connected, alpha above 8), split by the nearest segment line at the set's bones: kept <k> px (<share>), gave <m> px (<share>) to <other limb>; <b> px in the overlap band (nearer one line than the other by 0.5 px or less) went to the limb drawn in front, <bk> kept and <bg> given` line per limb part cut from a layer of one island that a limb the set does not carry also takes (issue #609; k, m and b count the part's pixels above alpha 8, each share of the part's pixels before the split, 3 places) and one `LINT set "<set>" <part>: <n> px under <base part> excluded` line per subset alternate set's limb part and base part drawn over it that the set does not replace which took a pixel (issue #587, `assemble.alternates` above; none on the public examples, which declare no alternate set); and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, one `author-made: part "<part>" (<run>:author:<label>) — …` line per part from a layer the author made (below, *A layer the author made*), then one `cut: "<part>" opaque <n> = "<part>" <kept> + "<piece>" <taken> …` line per part an `assemble.cuts` entry cut (below; it ends `; under <n> px filled, <m> px left empty` when a cut of that part has `under`), then — with `config.limbs` (issue #349) — one `limb cut: "<part>" opaque <n> = "<segment part>" <px> + …` line per part a limb takes and one `limb cap:` line per joint, its cap's pixels from the cap image, from the layer and missing, and its box (under `cap_shape: "ball"`, issue #579, then the lower half's pixels written, left as painted and missing), followed on a short cap by one `LINT "<part>" cap at [x, y] … short_px left <n>, right <m>: no layer gives them …` line (issue #557) — from the upper segment where it gave a pixel (under `cap_shape: "disc"` always), under `edge: "feather"` the pixels faded, under `cut_band` the line the cut was placed on and the stroke pixels it and the joint line cross (issue #360) (§3, *Limbs: cut at their joints*), then one `fringe pushed back: "<part>" <px> px, where the painting shows "<holder>" <px> px, …` line per part whose fringe was cleared (below) | on the examples: `reference-sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `reference-demo` 2.34 / 95.8 % / 10,340 / 1,564, 453 holes, the largest 70 px (default rule) — many slivers along part edges, no hole a region could hide | one large hole: part of the figure is in no layer — a plan entry is missing, hair left the head crop sideways (reference-demo's `hair_back` is taken from the full run for that reason), or See-through split one garment into two and left the space between them in neither (a skirt as two trouser legs); the `between` parts say where. When neither run holds it at all, an `assemble.patches` entry cuts it from the painting (below) |
|
|
3263
|
+
| `assemble` | one line per part — its counts (`op=` opaque, `vis=` visible, `src=` taken / candidates, `unproj=` visible but not projected, `drift=<n> (<p>% of core)`, `merged=`, `seam=`; *parts.json*, below). `drift=` is `refused_drift_px` in rig px and its share of the part's candidates, `projected_core_px`, which it is a subset of (issue #314); no bar reads either. On the four public examples the share runs to 94.5 % (`scarf` `hair_back`, 479 of 507) and the count to 26,472 (`scarf` `topwear`, 22.3 %), and the seam override repaints refused top-most pixels afterwards, so a large count says where See-through's colour was not taken, not that the part is unlike the painting: the `drift:` line below is the one that names a body of them another part holds. Then the `pixels:` totals (opaque = visible + occluded; taken; visible but not projected), then `recomposite vs source: mean \|d\|, within 8, error px > 40, uncovered error px`, then `uncovered holes (8-connected): N` and the largest five as `uncovered hole K: <px> px at x,y wxh (between "<part>" <px> px, …)`, then one `uncovered: <n> of the <N> uncovered error px lie on the full run's "<tag>", in a body of <px> px at x,y wxh; <the rule that left it out>` line per full-run layer the plan does not take from the full run whose uncovered error holds a body (5x5-opened, 8-connected, at least 150 full-run px in rig px), then one `drift: "<part>" refuses <n> px of <run>:<tag> (its colour more than 90 off the painting, max channel), in a body of <px> px at x,y wxh (…); by the plan's draw order "<holder>" holds <px> px of it (…)[, "<holder>" drawn in front of "<part>"][; the painting is within 90 of "<behind>" (<px> px at alpha >= 250, drawn behind "<part>")]; informational: no gate reads this. Swapping the plan order of the parts named here can clear it (when only the front one differs from the painting) or move it to the other part (when both do): swap, rebuild and read this line again; if it moves, removing it needs different input layers. At rest, the seam pass repaints the holder's pixels that pass its rule from the painting` line per part whose drift refusals hold a body (the same opening and bar) that another part holds in the draw order or that a part drawn behind it matches within 90 of the painting (issues #255, #351, #758) — that layer is not what the painting shows there; no gate reads this line, swapping the plan order of the parts named here can clear it (when only the front one differs from the painting) or move it to the other part (when both do) — swap, rebuild and read this line again, and if it moves, removing it needs different input layers — and at rest the seam pass repaints the holder's pixels that pass its rule from the painting (none on the five public paintings), then, per subset alternate set, one `LINT set "<set>" <part>: <layer part> holds <n> islands (8-connected, alpha above 8)[, and <s> speck(s) under 1 % of the largest (<f> px), each with the island nearest it], kept the one under <joints> (<k> px), dropped <m> (<d> px)` line per limb part cut from a layer of more than one island when the set names one limb side of it (issue #588; issue #608: a joint taken to the nearest island reads `<bone> [x, y] (<e> px off it, within its cap's radius <r>)`, and a part that lost no pixel `dropped none`), then one `LINT set "<set>" <part>: <layer part> holds <limb> and <other limb> in one island (8-connected, alpha above 8), split by the nearest segment line at the set's bones: kept <k> px (<share>), gave <m> px (<share>) to <other limb>; <b> px in the overlap band (nearer one line than the other by 0.5 px or less) went to the limb drawn in front, <bk> kept and <bg> given` line per limb part cut from a layer of one island that a limb the set does not carry also takes (issue #609; k, m and b count the part's pixels above alpha 8, each share of the part's pixels before the split, 3 places) and one `LINT set "<set>" <part>: <n> px under <base part> excluded` line per subset alternate set's limb part and base part drawn over it that the set does not replace which took a pixel (issue #587, `assemble.alternates` above; none on the public examples, which declare no alternate set); and look at `render/recomposite_error_rig.png`. Between the part lines and the totals, one `author-made: part "<part>" (<run>:author:<label>) — …` line per part from a layer the author made (below, *A layer the author made*), then one `cut: "<part>" opaque <n> = "<part>" <kept> + "<piece>" <taken> …` line per part an `assemble.cuts` entry cut (below; it ends `; under <n> px filled, <m> px left empty` when a cut of that part has `under`), then — with `config.limbs` (issue #349) — one `limb cut: "<part>" opaque <n> = "<segment part>" <px> + …` line per part a limb takes and one `limb cap:` line per joint, its cap's pixels from the cap image, from the layer and missing, and its box (under `cap_shape: "ball"`, issue #579, then the lower half's pixels written, left as painted and missing), followed on a short cap by one `LINT "<part>" cap at [x, y] … short_px left <n>, right <m>: no layer gives them …` line (issue #557) — from the upper segment where it gave a pixel (under `cap_shape: "disc"` always), under `edge: "feather"` the pixels faded, under `cut_band` the line the cut was placed on and the stroke pixels it and the joint line cross (issue #360) (§3, *Limbs: cut at their joints*), then one `fringe pushed back: "<part>" <px> px, where the painting shows "<holder>" <px> px, …` line per part whose fringe was cleared (below) | on the examples: `reference-sample` 0.83 / 98.0 % / 4,359 / 1,185, 259 holes, the largest 94 px; `reference-demo` 2.34 / 95.8 % / 10,340 / 1,564, 453 holes, the largest 70 px (default rule) — many slivers along part edges, no hole a region could hide | one large hole: part of the figure is in no layer — a plan entry is missing, hair left the head crop sideways (reference-demo's `hair_back` is taken from the full run for that reason), or See-through split one garment into two and left the space between them in neither (a skirt as two trouser legs); the `between` parts say where. When neither run holds it at all, an `assemble.patches` entry cuts it from the painting (below) |
|
|
3194
3264
|
| `propose` | `note:` lines, `LINT` lines, the `coverage` lines, `landmarks.png`, `basis.json` | no LINT line: every chain link lies on its mesh's art, and the hip is below the chest and the figure's top quarter; the `coverage:` summary says how many bones that verdict covers — a `not checked` bone was read by no check (its line says why), and a `ratio` or `fallback` bone in `basis.json` is a guess | a link off the art (a bone on the background) — move it onto the layer; `LINT <link> at … runs to … N degrees off the head's down axis …` — a fringe link that does not lean with the head (§3, the fringe in the head's frame): move it along the lock it drives; `LINT <bone> under <parent>: amplitude <a> below the link above's <b> in the keyed chain …` — under `--cloth`, a keyed sibling the recipe left the only keyed child of its parent, which `CHAIN_LAG` would refuse (issue #572, §3 *A keyed sibling left behind*): raise the field it names to `<b>` or more in size; `LINT hairback_… on mesh '<part>' (side <r\|l>): <N> tree(s) for <M> visible hair mass(es) (mass 0 columns x=<minX>..<maxX>, y=<minY>..<maxY>; …)` — back-hair cloth trees whose count does not match the side's visible hair masses (`max(1, floor(w / (4 * grid)) + 1)` per mass) or whose link or tip leaves its mass's column range (issues #445, #461): omit `chains` on `cloth."back hair"` or draft trees per visible hair mass inside its columns; `LINT <a_limb> and <b_limb> on <part> (<from>) cross at [x, y] with no per-limb split: …` — two limbs sharing one layer cross in an X without a per-limb split (issue #446): declare `config.limbs.<covering>.split` (`{ "line": [[x, y], …] }` or `{ "edge": "painting" }`, §3 *Which limb*); `LINT foot_<s> at [x, y], the <s>_ankle joint and leg_<s>1's tip, lies on none of leg_<s>'s art within 1 px along its joint line (the nearest of it on that line is the pixel [x, y], D px from the joint): …` — an ankle keypoint off its leg's art on the line `assemble` sizes the ankle's cap by (issue #517): `propose` drafts every leg without its ankle cut, the shoe layer stays one part, and nothing is moved onto the art; move that ankle keypoint onto the leg's or the shoe's art and re-run `propose` (`(the line crosses none of it)` when no art lies on that line at all); `LINT stop on <chain> (<firstLink> at [x0, y0]) against <against> (at [ax, ay]) places <chain>_touch at [tx, ty], above <firstLink>'s root (rest R deg, \|rest\| + outward B deg): …` — a stop's contact point `<chain>_touch` lies above `links[0]`'s root in rig px or pushes `\|rest\| + outward` past `180°` (issue #447, §2 `stops`): stop against the descending limb bone below `firstLink`, set `links` to start at a link below `<chain>_touch`, or omit the stop on a rising limb; `LINT hip at [x, y] is not below chest at [x, y]: …` or `LINT hip at [x, y] is above 0.25 of the figure height (figure y T..B, so hip y must be at least L): a hip at the shoulders` — move `hip` down to the waist (and `chest` between it and the neck); a `hanging strand … -- no chain proposed` note — that strand hangs stiff until you add a chain down the x and rows it names (§3); a `no blink: …` or `blink without brows: …` note — the idle will not blink (or its brows will not drop), because no part came from an `eyewhite` (or `eyebrow`) layer; the note names the tags looked for; a `no eyewhite part for eye_<s> …` note — the iris and lash parts it names ride `head` and do not blink, because no `eyewhite-<s>` part made that side's eye bone: take the eyewhite from the other run, or keep them on `head`; a `no face part: face box derived from …` note (always the first) — `head`, `neck` and every face-height scale come from a box guessed off the hair and neck (§3): check `head` and `neck` on `landmarks_head.png` and move them; when it adds `the blink shuts the eyes over no face part`, read `BLINK_NO_HOLE` after `check` — an eye with no face under it can open a hole (the `reference-sample` with only its face removed: 587 px). Under `--keypoints`: the `lint rule set:` line first (joints, or screen and why), then the joint notes — `missing: the rule "…" placed bone X instead` is a bone still guessed; `not used — …` names why an arm's joints did not place its sleeve (for a wrist on no part, the nearest part and the `--wrist-snap` that would bind it); a `wrist snap: …` note is a wrist bound past 15 px by the flag — check that chain's tip on `landmarks.png`; a `one handwear part holds both wrists` note is two chains on one mesh — cut the part with `assemble.cuts` to separate them; `LINT chest at … is not between the neck joint …`, `LINT hip at … is not past chest …`, `LINT hip at … is nearer the neck joint …` and `LINT <chain><i> at … does not advance from <s>_shoulder toward <s>_wrist` are the joint-frame lines: move that bone between, past or along the joints they name |
|
|
3195
3265
|
| `compare` | one line per pair (origin, parent, tip, length, direction — or SKIP and why), then the per-row summary, the unmapped bones of each side, `required:`, each side's roles and the `controls:` line | proposal against the config you corrected: the rows you changed and no others. Config against the `rig.json` `build` writes for it: measured on both examples, every origin within 6.19e-7 px (the rig's offsets are written to 6 places) and every chain link's tip and length within 4.99e-4 px (`length` is written to 3), printed to three places as `0.000` (a signed figure as `+0.000` or `-0.000`); `parent … is the right's ancestor at depth 2, <bone>_ctl between` for every keyed mesh bone, no `DIFFERENT` and no `NOT MAPPED` | `parent DIFFERENT: left a, right b` — a bone hangs from another parent than the other side's; `frames not related` — a rig with no stage (`skeleton.width`/`height`), two configs at different `rig_scale`: the distance rows SKIP, so declare the frame in a `--map` file if the author knows it; `FAIL STRUCTURE_REQUIRED_PRESENT` — a bone the map requires is missing through its pairs |
|
|
3196
3266
|
| `rig` (inside `build`) | one line per mesh: vertices, triangles, bones, influences, `cover`; the `bones` line; the `idle keys` line; then rigc's gate lines (with A15's declared SKIP under `--idle-keys direct`); in `rig.json`, each chain link's (or its `_ctl`'s) `length` and `rotation` | `cover 1.00000` on every mesh, both gate summaries `0 failed` (the compile and the packed pages); every link's `length` the distance to the next link and `rotation` its direction (Spine degrees, counter-clockwise, y up, local to the parent), every offset under it — a child bone's `x, y`, a weight's bind `x, y`, a region's `x, y` — in that turned frame, and a region on a link carrying `rotation` that turns it back upright. Nothing moved: `flattenRig` (`src/rig.ts`) turns every offset back and gives the unturned numbers | `RIG_LATTICE_ONE_LOOP`: change that mesh's `grid` |
|
|
@@ -3710,6 +3780,9 @@ See-through with another seed.
|
|
|
3710
3780
|
| <a id="CONFIG_TAG_KNOWN"></a><a id="CONFIG_PART_NAME"></a><a id="CONFIG_PART_UNIQUE"></a>`CONFIG_TAG_KNOWN`, `CONFIG_PART_NAME`, `CONFIG_PART_UNIQUE` | a plan or extend entry names neither a v3 tag nor `author:<label>` (an `author:` tag with a malformed label says what the label must be), a part name that is not a file name, or a part or layer twice — a patch named like a plan part or another patch, and a cut's `into` named like a plan part, a patch or another cut's, included | `assemble.plan`, `assemble.patches`, `assemble.cuts` |
|
|
3711
3781
|
| <a id="CONFIG_SET_FOCUS"></a>`CONFIG_SET_FOCUS` | optional `assemble.alternates[i].focus` (issue #719) must be exactly two finite painting-pixel coordinates `[x, y]`, x right/y down, inside that alternate painting (edges included); the loader checks the tuple and `assemble` checks the actual canvas before writing. Only with focus, `parts.json` carries the original point and `focus_source_size`; `sets.json` carries the point in setup-world coordinates through the accepted rig-canvas resize and `src/coords.ts`. Absent means no focus field or inferred hand position | author a point inside the painting or omit `focus`; after changing or removing it, re-run `assemble` and `rig`. Scene placement belongs to the consumer |
|
|
3712
3782
|
| <a id="CONFIG_SET_LAYERS"></a>`CONFIG_SET_LAYERS` | `assemble.alternates[i].layers` names an unknown, uncovered or hidden part, or a painting patch with no run-layer source | name a covered layer-backed output part (a limb segment name, not its consumed source); use `author:<label>` for author art |
|
|
3783
|
+
| <a id="CONFIG_MOTION_SEAM"></a>`CONFIG_MOTION_SEAM` | motion_seams has a malformed entry, an unknown output part, a self-pair, duplicate/reversed pair or unknown entry field | declare each unordered pair once with two resolved output part names |
|
|
3784
|
+
| <a id="PARTS_MOTION_SEAM"></a>`PARTS_MOTION_SEAM` | parts.json motion_seams violates the same declaration shape/name/uniqueness contract | reassemble with the declared output part names |
|
|
3785
|
+
| <a id="CHECK_MOTION_SEAM_DECLARATION"></a>`CHECK_MOTION_SEAM_DECLARATION` | a directly supplied parts record has an invalid explicit motion seam declaration | supply a valid parts.json declaration; check never infers a replacement |
|
|
3713
3786
|
| <a id="CONFIG_NAME_RESOLVES"></a>`CONFIG_NAME_RESOLVES` | a parent, segment, region, track, blink member, blink still part or bone, extend part, patch or cut `draw.before`, or cut `from` names nothing declared above it (a cut's `from` must be a plan part); or a constraint's `bones`, `target`, `source` or `bone` names a bone `bones` does not declare (the detail names the constraint and lists the bones that exist); in `meshes.<part>.auto`, a bone or region name nothing declares; or `bones[i].link_inherit` names a link outside its own chain (the detail lists that chain's expanded links) | the named reference, or the declaration it needs |
|
|
3714
3787
|
| <a id="CONFIG_BONE_UNIQUE"></a>`CONFIG_BONE_UNIQUE` | a bone or chain declared twice, or `root` declared | `bones` |
|
|
3715
3788
|
| <a id="CONFIG_BONE_INHERIT"></a>`CONFIG_BONE_INHERIT` | a single bone's `inherit`, or a chain's `link_inherit.<link>`, is a string that is not one of rig-c's five mode names as its table spells them (issue #348); the line lists all five. `"NoScale"` is refused too: the runtime would fold the first letter, and this loader folds and maps nothing | `bones[i].inherit` or `bones[i].link_inherit.<link>` — `normal`, `onlyTranslation`, `noRotationOrReflection`, `noScale` or `noScaleOrReflection` (§3, `bones`) |
|
|
@@ -3843,8 +3916,8 @@ says why each requirement exists and what breaks without it.
|
|
|
3843
3916
|
| <a id="PROPOSE_FIGURE_LAYER"></a>`PROPOSE_FIGURE_LAYER` | with `--keypoints` (issue #577): a limb is drafted from the figure layer (no handwear or legwear part over 500 px for it), and two or more `topwear` parts each hold every joint and the trunk bones' origins within 15 px with the same opaque px in the 31x31 squares about them, so nothing says which is the figure; or the only `topwear` parts that hold them are named by a cloth recipe (`config.cloth.<tag>.part` or `.parts`, issue #631), whose mesh a limb would take (§3, *A figure of one material*) | leave the others out of `assemble.plan`, or give the arms and legs their own handwear and legwear layers; for a recipe's part, take it out of the recipe |
|
|
3844
3917
|
| <a id="PROPOSE_CLOTH_DRAFTED"></a>`PROPOSE_CLOTH_DRAFTED` | with `--cloth` (issue #364): the config's `cloth` block holds a recipe for a tag the proposer drafts no chain on — no part has that tag, or every `back hair` part ends above the shoulders (a bun bone, no chain). A `bottomwear` recipe with no `bottomwear` part names every `topwear` part shaped like a skirt (issue #402) | leave that recipe out, or assemble the layer it is for, or declare the named part in `cloth.bottomwear.part` |
|
|
3845
3918
|
| <a id="PROPOSE_CLOTH_PART"></a>`PROPOSE_CLOTH_PART` | with `--cloth` (issues #402, #437): `cloth.bottomwear.part` (a string) names no part, a part or cut piece whose source is not `topwear` (a `bottomwear` part takes the recipe by its tag already), or a target whose box ends above the hip + 0.25 face heights, the topwear rule's waist line; or `cloth.<tag>.parts` (or `part` as a list, issue #437) names a part not in `parts.json`, a part no link of the drafted tree crosses (`spanCrosses == 0`), or parts out of root-to-tip depth order along the chain | name the `topwear` part or its cut skirt piece that holds the skirt (or leave `part` out), or list only parts in `parts.json` that the drafted tree links cross in root-to-tip order |
|
|
3846
|
-
| <a id="PROPOSE_WRITE_CONFIG_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--cloth … --write-config` (issues #537, #356): the out path exists or collides with one of the four artifacts under `--out` — `proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png` — including directory-symlink and hardlink aliases; the config is written to a new file, never over the `--cloth` config or an earlier one | name a file that does not exist yet, beside the `--cloth` config and separate from all four artifact paths and their aliases |
|
|
3847
|
-
| <a id="PROPOSE_WRITE_CONFIG_CONFLICT"></a>`PROPOSE_WRITE_CONFIG_CONFLICT` | with `--write-config` (issue #552): an entry of `bones`, `constraints` or `motion.tracks` the recipe re-drafts or removes was changed by hand in the `--cloth` config — it equals neither the draft with the recipe nor the draft without it — so the write would drop the hand edit; the object is the entry (`config.constraints[40] "skirt0a_0_physics"` in CL207), the detail names the first field the hand edit holds and what the draft writes there. With `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's too, and the conflict is an entry that equals neither the draft, the draft without the recipe, nor the previous recipe's draft: the detail says so and reads the first differing field against the previous recipe's draft. Also a name the config states twice where the recipe drafts it. Every conflict is named at once and nothing is written | take the draft
|
|
3919
|
+
| <a id="PROPOSE_WRITE_CONFIG_FRESH"></a>`PROPOSE_WRITE_CONFIG_FRESH` | with `--cloth … --write-config` (issues #537, #356): the out path exists or collides with one of the four artifacts under `--out` — `proposal.json`, `basis.json`, `render/landmarks.png`, `render/landmarks_head.png` — including directory-symlink and hardlink aliases; the config is written to a new file, never over the `--cloth` config or an earlier one (unlike `assemble --propose-plan` and `propose` without `--cloth`, which update an existing `--config` in place; §4, *Saving proposed config fields*) | name a file that does not exist yet, beside the `--cloth` config and separate from all four artifact paths and their aliases |
|
|
3920
|
+
| <a id="PROPOSE_WRITE_CONFIG_CONFLICT"></a>`PROPOSE_WRITE_CONFIG_CONFLICT` | with `--write-config` (issue #552): an entry of `bones`, `constraints` or `motion.tracks` the recipe re-drafts or removes was changed by hand in the `--cloth` config — it equals neither the draft with the recipe nor the draft without it — so the write would drop the hand edit; the object is the entry (`config.constraints[40] "skirt0a_0_physics"` in CL207), the detail names the first field the hand edit holds and what the draft writes there. With `--from <previous config>` (issue #571) an entry equal to the previous recipe's draft is the recipe's too, and the conflict is an entry that equals neither the draft, the draft without the recipe, nor the previous recipe's draft: the detail says so and reads the first differing field against the previous recipe's draft. Also a name the config states twice where the recipe drafts it. Every conflict is named at once and nothing is written | to take the recipe's draft, remove the hand-edited track, bone or constraint from `config.<section>` (or revert the hand edit) and run `propose --cloth` again, or leave the recipe out for that part (its `cloth` block); state a name once |
|
|
3848
3921
|
| <a id="PROPOSE_WRITE_CONFIG_SPLICE"></a>`PROPOSE_WRITE_CONFIG_SPLICE` | with `--write-config` (issue #537): the `--cloth` config's text with the drafted sections spliced in does not parse to that config with them set, and the message names the first key that moved — the text states a key twice, so the splice lands on the first and the parse keeps the last | state each key once in the `--cloth` config |
|
|
3849
3922
|
| <a id="PROPOSE_CLOTH_BACK_HAIR_CHAINS"></a>`PROPOSE_CLOTH_BACK_HAIR_CHAINS` | with `--cloth` (issues #390, #445, #461): `cloth."back hair".chains` exceeds what the narrower side's opaque width at the eye-line root row holds at the part's mesh grid (`max(1, min(floor(w_r / grid), floor(w_l / grid)))`), or places a tree root outside the 15 px dilated art mask of the `back hair` part (e.g. an inner twin-tail root over the face where the hair has no pixel); the message names the part, each side's root-row width, the grid spacing, and any off-art root with its pixel alpha | lower `cloth."back hair".chains` to at most the max fit named in the message, or omit `chains` so `propose --cloth` derives the tree count per visible hair mass on each side from its root-row width |
|
|
3850
3923
|
| <a id="PROPOSE_ACCESSORY_BODY"></a>`PROPOSE_ACCESSORY_BODY` | an accessory has nothing above its pendant rows to hang its bone on | that part's plan entry, or author its bones by hand |
|
|
@@ -3855,7 +3928,7 @@ says why each requirement exists and what breaks without it.
|
|
|
3855
3928
|
| <a id="KEYPOINTS_JOINT_KNOWN"></a><a id="KEYPOINTS_JOINT_STATE"></a><a id="KEYPOINTS_POSITION_STATED"></a><a id="KEYPOINTS_POSITION_INSIDE"></a>`KEYPOINTS_JOINT_KNOWN`, `KEYPOINTS_JOINT_STATE`, `KEYPOINTS_POSITION_STATED`, `KEYPOINTS_POSITION_INSIDE` | a joint name outside body-18, a state outside observed / occluded / missing, an observed joint with no `at` or a missing one with one, or a position outside the `width`x`height` image | that joint |
|
|
3856
3929
|
| <a id="KEYPOINTS_PERSON_UNIQUE"></a><a id="KEYPOINTS_PERSON_CHOSEN"></a>`KEYPOINTS_PERSON_UNIQUE`, `KEYPOINTS_PERSON_CHOSEN` | two people share an id; or the file holds more than one person and no `--person` names one, or `--person` names none of them (the message lists the ids) | `--person <id>` |
|
|
3857
3930
|
| <a id="KEYPOINTS_IMAGE_SIZE"></a>`KEYPOINTS_IMAGE_SIZE` | the file's `width`x`height` is not the `--source` painting's | a file measured on this painting |
|
|
3858
|
-
| <a id="PARTS_FILE_PRESENT"></a><a id="PARTS_IS_JSON"></a><a id="PARTS_KEY_KNOWN"></a><a id="PARTS_FIELD_PRESENT"></a><a id="PARTS_FIELD_TYPE"></a><a id="PARTS_NAME_UNIQUE"></a><a id="PARTS_FROM_KNOWN"></a><a id="PARTS_CUT_FROM_KNOWN"></a><a id="PARTS_BOX_INSIDE_RIG"></a><a id="PARTS_COUNTS_ADD_UP"></a><a id="PARTS_HOLES_LARGEST_FIRST"></a><a id="PARTS_HOLE_PART_KNOWN"></a><a id="PARTS_SINGLE_RUN_PAD"></a>`PARTS_*` (`PARTS_FILE_PRESENT`, `PARTS_IS_JSON`, `PARTS_KEY_KNOWN`, `PARTS_FIELD_PRESENT`, `PARTS_FIELD_TYPE`, `PARTS_NAME_UNIQUE`, `PARTS_FROM_KNOWN`, `PARTS_CUT_FROM_KNOWN`, `PARTS_BOX_INSIDE_RIG`, `PARTS_COUNTS_ADD_UP`, `PARTS_HOLES_LARGEST_FIRST`, `PARTS_HOLE_PART_KNOWN`, `PARTS_SINGLE_RUN_PAD`) | the `parts.json` read is not assemble's contract (`PARTS_COUNTS_ADD_UP`: `visible_px + occluded_px` is not `opaque_px`, `visible_not_projected_px` is above `visible_px`, or the `recomposite` block's figures disagree — more uncovered than error pixels, a hole larger than its box, the wrong number of holes listed, listed areas that do not sum to `uncovered_error_px`; the last two codes are the block's order and its border names; `PARTS_SINGLE_RUN_PAD`: the `single_run_pad` block's margins are not the centring, its file is not smaller than its square, or `rig_size` is not the file at the scale, issue #366 — §5) | re-run assemble; do not edit `parts.json` |
|
|
3931
|
+
| <a id="PARTS_FILE_PRESENT"></a><a id="PARTS_IS_JSON"></a><a id="PARTS_KEY_KNOWN"></a><a id="PARTS_FIELD_PRESENT"></a><a id="PARTS_FIELD_TYPE"></a><a id="PARTS_NAME_UNIQUE"></a><a id="PARTS_FROM_KNOWN"></a><a id="PARTS_CUT_FROM_KNOWN"></a><a id="PARTS_BOX_INSIDE_RIG"></a><a id="PARTS_COUNTS_ADD_UP"></a><a id="PARTS_HOLES_LARGEST_FIRST"></a><a id="PARTS_HOLE_PART_KNOWN"></a><a id="PARTS_SINGLE_RUN_PAD"></a>`PARTS_*` (`PARTS_FILE_PRESENT`, `PARTS_IS_JSON`, `PARTS_KEY_KNOWN`, `PARTS_FIELD_PRESENT`, `PARTS_FIELD_TYPE`, `PARTS_NAME_UNIQUE`, `PARTS_FROM_KNOWN`, `PARTS_CUT_FROM_KNOWN`, `PARTS_BOX_INSIDE_RIG`, `PARTS_COUNTS_ADD_UP`, `PARTS_HOLES_LARGEST_FIRST`, `PARTS_HOLE_PART_KNOWN`, `PARTS_SINGLE_RUN_PAD`) | the `parts.json` read is not assemble's contract (`PARTS_FILE_PRESENT`: no `parts.json` under `--parts`, which names the directory holding `parts.json` and `parts/` — `work/rig` from `assemble --out work`, or `out` from `build --out out`; `PARTS_COUNTS_ADD_UP`: `visible_px + occluded_px` is not `opaque_px`, `visible_not_projected_px` is above `visible_px`, or the `recomposite` block's figures disagree — more uncovered than error pixels, a hole larger than its box, the wrong number of holes listed, listed areas that do not sum to `uncovered_error_px`; the last two codes are the block's order and its border names; `PARTS_SINGLE_RUN_PAD`: the `single_run_pad` block's margins are not the centring, its file is not smaller than its square, or `rig_size` is not the file at the scale, issue #366 — §5) | pass the directory holding `parts.json` and `parts/` (`work/rig` or `out`), or re-run assemble; do not edit `parts.json` |
|
|
3859
3932
|
|
|
3860
3933
|
### compare
|
|
3861
3934
|
|
|
@@ -4218,6 +4291,14 @@ flag) and 8 `CLOTH_SETTLES` warnings for 9 (selftest `CK515`).
|
|
|
4218
4291
|
**Steady-wind seam band** (`--wind-band`, issue #590). `check --wind-band <spec.json>` (or `build --wind-band <spec.json>`, forwarded) sweeps steady horizontal wind across a caller-declared grid and reports the contiguous `[x_lo, x_hi]` band in which each declared seam pair holds `gap <= max_gap` and `ghost <= max_ghost` across every animation in `motion.json`. Every field in `{ "spec": "rig-parts-wind-band/1", "min", "max", "step", "fps", "max_gap", "max_ghost", "pairs" }` is required — nothing falls back to `SEAM_OVER_MOTION`'s pairs, one-cell floor, or fps. At each swept step `x = min + k * step`, `check` runs `rigc render --seam <pairs> --fps <fps> --max 16 --environment` with a single-step steady schedule `{ "spec": "rigc-environment/1", "steps": [{ "t": 0, "wind": [x, 0], "gravity": [0, 1] }] }` (`seam.json` cells are in each pair's coarser drawing texels, independent of `--max`). **What it does not measure:** the sweep is steady wind (`wind: [x, 0], gravity: [0, 1]` at `t = 0`), not a time-varying gust (`x ± a` at 0.2 Hz); transient overshoot from a changing wind is not read by a steady sweep, and the band is documented and reported as the steady-wind band (`mode: "steady"`, `gravity: [0, 1]`). It is a reported line (`status: "REPORTED"`), never a bar: it prints one `WIND_BAND:` summary line plus one `WIND_BAND:` line per pair that breaks inside `[min, max]`, and writes `WIND_BAND` in `check.json` before `PASS`.
|
|
4219
4292
|
|
|
4220
4293
|
|
|
4294
|
+
**Explicit motion seam observations** (issue #750). `motion_seams` is optional in a proposal, config and `parts.json`. The pure `draftMotionSeams(config, parts)` generator reads source provenance and the final declared carrier hierarchy: a non-limb `topwear` mesh on exactly two single-bone carriers which are a named parent and child, and non-limb `handwear-r`/`handwear-l` whose carriers are strict descendants with the same nearest trunk carrier, either that parent or that child. A sleeve may branch from the parent as a sibling of the child; it binds neither trunk carrier itself, and carriers with different nearest trunks do not qualify. This establishes declared structure, not positive compiled vertex weights or setup alpha overlap; the stock seam reader observes the band. Other structures add nothing. No part spelling, motion keys, distance heuristic or ancestor in common supplies identity. Proposal copy/write-config and turn preserve this field. For an older authored config, retain its original and use the same generator on its frozen structure/source parts, adding only this declaration in a derived config with a provenance receipt; regenerating its other rig or motion sections changes the experiment. Check reads the declaration, never calls this generator, and never restores a removed pair. A duplicate with an existing limb/requirement/root pair retains each source; an independently proven body-root pair keeps its existing FAIL policy.
|
|
4295
|
+
|
|
4296
|
+
Every played non-root WARN, including existing limb pairs, additionally records the actual above-floor `worst` hit (`kind`, `index`, `px`, `cell`, `box`; maximum count, earliest frame on a tie, gap before ghost on a remaining tie) and `pose_at_worst` (`index`, actual raw `time`, `joints`). Each joint records `bone`, `parent`, `world_x_axis_degrees`, `parent_relative_setup_axis_delta_degrees_mod360`, `static_range`, `comparison` and, when needed, `reason`. Carrier paths come from the drawings actually shown at that frame and their positive weights or rigid binding, followed through the declared hierarchy. The SAME seam render supplies `--geometry`; animation, viewport, frame index and raw hit time are bound before its actual `setup.bones` and posed matrices are read. Animation frame 0 can already be posed and is never substituted for setup. Missing/mismatched geometry or matrices is a named refusal, never a zero angle or an estimate from source keys or frame/fps.
|
|
4297
|
+
|
|
4298
|
+
Parent-relative axes use the full inverse parent matrix; parent-only rotation cancels. Angles are CCW in world y-up, and the setup-relative delta is explicitly modulo 360 in [-180,180). A static range is copied unchanged from its limb record, or null when absent. `comparison: "axis-modulo-360"` describes normal, unsheared, nondegenerate axes and a range within that branch; it does not certify unwrapped winding or impose an angle bar. Special inheritance, shear/reflection, singular or degenerate axes, absent ranges and ambiguous winding report `comparison: "unavailable"` with a reason. These fields are observation evidence only. Existing `opens`, `px`, `max_px`, under-floor counts, root partitions and FAIL ownership keep their definitions.
|
|
4299
|
+
|
|
4300
|
+
Absent declaration retains existing output bytes except optional new evidence on existing WARN rows. With a declared no-chest control, compare standalone checks at identical paths: exclude only the newly selected seam line's selection, rows, derived status and reason when the baseline already has that container. The historical absent-container bar required seven keys, CLEAR and zero warnings in every animation; its measured raw exit 1 remains red because the original idle keys the chest even though the added greeting keys only the head, and optional `worlds` is valid source data. [HQ's post-verdict restatement](https://github.com/rig-c/parts/issues/750#issuecomment-6398631279) instead requires the complete source-derived `MotionSeamLine` schema, including optional reference worlds, exact metadata and generated selection, and independent raw-row audits. All added greeting rows must be clean; any WARN must have an actual keyed pair-joint witness from the original motion, compiled tracks and carrier ancestry. STABILITY's *Explicit motion seam observations* section defines this audit and lossless removal of the new container: every outside byte stays identical. Keep the historical red beside the separate re-evaluation. No input, threshold, angle gate, exit behavior or animation selector is changed. Whether an open armhole should eventually fail is an open severity decision outside this WARN contract.
|
|
4301
|
+
|
|
4221
4302
|
**Body-root seam identity** (issue #686). A limb must have exactly one segment0 part. Its declared bone must have one named immediate parent; the root slot must bind that bone (or its declared turn child). Non-limb parts with `topwear` or `bottomwear` source provenance, a slot on that parent (directly or through its verified generated turn child) and a named default-skin drawing are candidates. The body-side child must match `applyTurn`'s exact generated name, unique identity bone and parent, control and per-part transform binding; a similarly named bone alone is not proof (issue #708). The original carrier and pair slot names do not change under turn; stock setup pose `render --seam` selects all matching drawings with `banded > 0` (its existing alpha-overlap band, without dilation), so one selects one pair and two select both pairs. When eligible candidates all return valid setup banded 0, that limb has no selected root pair: `unmeasuredRoots` retains its limb, bone, parent, segment0 part, candidates and named reason, reported as SKIP, not measured PASS. Part spelling, nearest geometry and shared mesh influences select nothing. On `wind` the pairs are `topwear|upperarm_r`, `topwear|upperarm_l`, `bottomwear|thigh_r` and `bottomwear|thigh_l`; “trunk” is not a part name. Existing pairs keep their order; a reversed explicit declaration deduplicates with the root pair and retains both declarations. An ambiguous/missing named binding, no eligible candidate, or unreadable/undrawn setup data is `CHECK_MOTION_SEAM_ROOT`, naming the part and candidates. Valid zero-band metadata is carried separately as optional `roots.unmeasured`, never as a fabricated measured pair. The all-zero root block remains present and its bar is skipped; measured FAIL takes precedence over SKIP, while measured PASS plus any unmeasured root stays SKIP. No body provenance leaves legacy pair selection unchanged and supplies no body-root coverage.
|
|
4222
4303
|
|
|
4223
4304
|
Renderer metadata and exact raster reads use the promised `rig-c/render-shared` entry (rig-c >=2.69.0 <3.0.0). It registers no Spine runtime; where that runtime resolves from rig-c's own package root, the existing `rig-c/render` entry registers the official Spine side explicitly. An install without Spine keeps rig-c's own candidate chooser and gate; candidate or loader failures never select a guessed fallback.
|
|
@@ -5238,3 +5319,10 @@ missing a path, given twice, or combined with `--shard`):
|
|
|
5238
5319
|
enter `holes`; check names or indented detail lines containing `HOLE` or `SKIP` (such as
|
|
5239
5320
|
`RG82_BLINK_NO_HOLE_…` or `SO21_ZERO_SETUP_BANDS_REMAIN_NAMED_SKIPS_…`) are counted as `PASS` or
|
|
5240
5321
|
`FAIL` controls and never as `skips` or `holes` (`RT16`, `RT17`).
|
|
5322
|
+
|
|
5323
|
+
The WARN pose reader also requires the published stock coordinate header and
|
|
5324
|
+
the required source bone/parent roster. It binds the complete geometry frame
|
|
5325
|
+
cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
|
|
5326
|
+
including unselected frames, before reading the worst pose. Identical static
|
|
5327
|
+
ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
|
|
5328
|
+
never described as no declared range.
|
package/docs/MIGRATION.md
CHANGED
|
@@ -301,7 +301,7 @@ either (the examples' `expected/` and every existing control are unchanged).
|
|
|
301
301
|
|
|
302
302
|
What to do: nothing. To draft a skirt or hair that the consumer's wind and gravity move,
|
|
303
303
|
add a `cloth` block and propose with `--cloth`; copy each of `bones`, `meshes`, `regions`,
|
|
304
|
-
`limbs`, `motion`, `constraints`, `turn` and `proposed_rig_scale` the proposal wrote into the config, as before
|
|
304
|
+
`limbs`, `motion`, `constraints`, `turn`, `motion_seams` and `proposed_rig_scale` the proposal wrote into the config, as before
|
|
305
305
|
(`constraints` is the one `--cloth` adds).
|
|
306
306
|
|
|
307
307
|
## After 1.20.0: the seam over a joint's range
|
|
@@ -443,3 +443,32 @@ bands* for the source, name, width and overlap refusals. Existing configs need
|
|
|
443
443
|
no change. The parts reader gains `limb.hybrid` and `limb.band` records only
|
|
444
444
|
for this mode, and the recorded lower range is measured once. The normal
|
|
445
445
|
one-bone rule and existing range thresholds remain unchanged.
|
|
446
|
+
|
|
447
|
+
## Explicit motion seam declarations and posed WARN evidence (issue #750)
|
|
448
|
+
|
|
449
|
+
New proposals can include optional `motion_seams: [{part, neighbour}]` alongside
|
|
450
|
+
the other proposed config sections. Carry it through assemble into parts.json.
|
|
451
|
+
Each pair names two existing output parts, once regardless of direction; the
|
|
452
|
+
strict readers name malformed, self, duplicate and unresolved declarations.
|
|
453
|
+
Check observes declared pairs in every supplied animation with the existing
|
|
454
|
+
non-root WARN floor; bars and exit status are unchanged. Existing body-root
|
|
455
|
+
FAIL semantics remain in force for independently selected root pairs.
|
|
456
|
+
|
|
457
|
+
Older authored configs acquire no declaration automatically. Keep the originals
|
|
458
|
+
and use exported `draftMotionSeams(config, parts)` on the frozen authored
|
|
459
|
+
structure and source-provenance parts, preserving every other config value in
|
|
460
|
+
a derived input and recording the added declaration. Check does not run that
|
|
461
|
+
generator; removing a declaration silences its independently declared pair.
|
|
462
|
+
|
|
463
|
+
Existing played limb WARNs as well as newly declared WARNs gain same-render
|
|
464
|
+
worst-frame pose evidence. Read relative angles as setup-axis deltas modulo
|
|
465
|
+
360, alongside unchanged static ranges; unsupported comparisons carry an
|
|
466
|
+
unavailable reason. The geometry setup, actual raw frame/time and parent
|
|
467
|
+
matrices replace no source motion keys and introduce no angle threshold.
|
|
468
|
+
|
|
469
|
+
The WARN pose reader also requires the published stock coordinate header and
|
|
470
|
+
the required source bone/parent roster. It binds the complete geometry frame
|
|
471
|
+
cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
|
|
472
|
+
including unselected frames, before reading the worst pose. Identical static
|
|
473
|
+
ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
|
|
474
|
+
never described as no declared range.
|
package/docs/STABILITY.md
CHANGED
|
@@ -118,7 +118,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
|
|
|
118
118
|
part name, `[i]` an entry of a list):
|
|
119
119
|
|
|
120
120
|
<!-- stable:config -->
|
|
121
|
-
- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged)
|
|
121
|
+
- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `stops`, `turn`, `scene`, `cloth`, `proposed_rig_scale`, `requirements` (issue #556, additive: a path beside the config that build reads in place of its requirements flag, whose behaviour is unchanged), `motion_seams`
|
|
122
122
|
- **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
|
|
123
123
|
- **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
|
|
124
124
|
- **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
|
|
@@ -381,3 +381,52 @@ carrier and measured geometry must agree; the lower rigid piece alone carries
|
|
|
381
381
|
existing `LIMB_ONE_BONE` line checks ordinary segments as before; the band
|
|
382
382
|
requires exactly its two adjacent carriers. `SEAM_OVER_RANGE` uses the stored
|
|
383
383
|
radius and existing rest-art comparison, without changing its bar.
|
|
384
|
+
|
|
385
|
+
## Explicit motion seam observations (issue #750)
|
|
386
|
+
|
|
387
|
+
`motion_seams: [{part, neighbour}]` is optional in proposal/config/parts.json.
|
|
388
|
+
Absent leaves the existing declaration path unchanged. Readers refuse unknown
|
|
389
|
+
parts, self-pairs, unordered duplicates, malformed entries and unknown entry
|
|
390
|
+
fields by name. Empty declares no additional pair. Proposal turn/copy/write and
|
|
391
|
+
assemble preserve it; check never infers a removed declaration. A declared pair
|
|
392
|
+
uses the existing non-root WARN floor and unchanged exits, unless independently
|
|
393
|
+
selected by the existing proven body-root FAIL contract.
|
|
394
|
+
|
|
395
|
+
All played non-root WARN rows may add `worst` and `pose_at_worst`, including
|
|
396
|
+
existing limb rows. Worst is the maximum above-floor raw hit, earliest frame
|
|
397
|
+
on a tie, gap before ghost on a remaining tie. Pose evidence binds the same
|
|
398
|
+
seam geometry's actual setup, frame index, animation, viewport and raw time.
|
|
399
|
+
It records carrier-path world axes, parent-relative setup-axis deltas modulo
|
|
400
|
+
360, unchanged static ranges and explicit unavailable comparison reasons;
|
|
401
|
+
frame0 and source key endpoints are not setup or measured pose substitutes.
|
|
402
|
+
No angle bar or new threshold is added. Missing/mismatched data refuses.
|
|
403
|
+
Without a declaration only optional WARN evidence changes existing check bytes.
|
|
404
|
+
For the declared no-chest control at identical paths, the exact byte projection
|
|
405
|
+
of an existing seam container excludes only its selection, rows, derived status
|
|
406
|
+
and reason. The historical optional-container bar required exactly seven keys,
|
|
407
|
+
`CLEAR` and zero warnings across every animation. Its measured raw exit 1 stays
|
|
408
|
+
red: the added greeting keys only the head, but the original idle also keys the
|
|
409
|
+
chest and reports an above-floor opening at frames 8–12. The source type also
|
|
410
|
+
permits informational `worlds`; neither finding changes the product contract.
|
|
411
|
+
|
|
412
|
+
[HQ's post-verdict restatement](https://github.com/rig-c/parts/issues/750#issuecomment-6398631279)
|
|
413
|
+
corrects that premise. When the baseline omits `SEAM_OVER_MOTION` entirely, audit
|
|
414
|
+
the new container against the complete `MotionSeamLine` source type, including
|
|
415
|
+
its required and optional fields and referenced types, rather than a hand-kept
|
|
416
|
+
key list. Independently verify fps 12, the exact source floor, compiled animation
|
|
417
|
+
roster, generated selection and every row against the raw readings. All added
|
|
418
|
+
greeting rows must be readable and clean. Any WARN must name an animation that
|
|
419
|
+
actually keys a joint on the pair's carrier ancestry, witnessed by the original
|
|
420
|
+
authored motion, compiled tracks and actual drawing carriers. The original idle
|
|
421
|
+
WARN remains reported with the unchanged floor and exit behavior. Only after
|
|
422
|
+
those audits may lossless removal of the new container establish exact equality
|
|
423
|
+
of every outside byte. An existing baseline container keeps the narrower field
|
|
424
|
+
exclusions above. The original red and the separate post-verdict re-evaluation
|
|
425
|
+
are retained together; no input, animation selector or threshold is changed.
|
|
426
|
+
|
|
427
|
+
The WARN pose reader also requires the published stock coordinate header and
|
|
428
|
+
the required source bone/parent roster. It binds the complete geometry frame
|
|
429
|
+
cohort to the actual PNG frame set through `readFrameSet` and `boneTrackOf`,
|
|
430
|
+
including unselected frames, before reading the worst pose. Identical static
|
|
431
|
+
ranges on a bone deduplicate; conflicting ranges are explicitly ambiguous,
|
|
432
|
+
never described as no declared range.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rig-c/parts",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.67.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": {
|
|
@@ -85,7 +85,7 @@ under that.
|
|
|
85
85
|
gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
|
|
86
86
|
not in the rig. Then `rig-parts propose --parts work/rig
|
|
87
87
|
--source <painting> --out work` → copy `bones`, `meshes`, `regions`, `limbs`,
|
|
88
|
-
`motion`, `constraints`, `turn`, `proposed_rig_scale` from `proposal.json` into the config, each it
|
|
88
|
+
`motion`, `constraints`, `turn`, `motion_seams`, `proposed_rig_scale` from `proposal.json` into the config, each it
|
|
89
89
|
wrote (`limbs` only with `--keypoints`, `constraints` only with `--cloth`, `turn`
|
|
90
90
|
only with `--full`/`--head`; a `limbs` block left out is refused at the next step). `assemble` needs the plan and none of
|
|
91
91
|
those sections; do not stub them to get past it (AUTHORING §4 says what each step
|
|
@@ -125,7 +125,7 @@ under that.
|
|
|
125
125
|
6. Correct against `render/landmarks.png` and `note:` lines; a
|
|
126
126
|
`coverage … not checked` line is a bone no check read (the line says why),
|
|
127
127
|
and `basis.json` beside the proposal says what each bone rests on — check
|
|
128
|
-
the `ratio` bones and any with a `fallback` first. `propose
|
|
128
|
+
the `ratio` bones and any with a `fallback` first. `rig-parts propose --parts work/rig --source <painting> --out work
|
|
129
129
|
--from-config config.json` (with the same `--keypoints`) until it prints no
|
|
130
130
|
`LINT` line. `rig-parts compare
|
|
131
131
|
--left work/proposal.json --right config.json` lists what the correction changed,
|