@rig-c/parts 1.18.0 → 1.20.0

package/docs/PAINTING.md

@@ -5,7 +5,7 @@ yours — on your own GPU, with any generator, or by hand — and this package r
 no model. But a painting the pipeline cannot rig fails late: a sleeve layer that
 holds the torso, a leg chain that drags the other leg, a dance clip that tears.
 This page lists what the painting must be, why the pipeline needs each thing, and
-what breaks without it; gives one generation recipe as a starting point; says how
+what breaks without it; gives one generation recipe that passes the check, and what it measured; says how
 to paint alternate art for a limb; and describes `rig-parts painting`, the check
 that reads the painting before See-through runs on it.
 
@@ -31,14 +31,14 @@ Each requirement says what the pipeline needs, what fails without it, and whethe
 | requirement | why the pipeline needs it | what fails without it | read by |
 | --- | --- | --- | --- |
 | **Front view** | the proposer and the keypoint file read the subject's right on the image's left of a figure facing the viewer, and the eyes, the blink and the head turn are drafted from a face toward the viewer | a back view has no face part for `propose` to draft from (`PROPOSE_FACE_PRESENT`, or the face-less fallback its first note names) | an eye |
-| **Full body, inside the frame** | the figure's height is the proposer's yardstick, and the feet carry the leg chain's last link | a cropped foot is a leg with no ankle; a figure touching the edge reads as background that is not plain | `PAINTING_BACKGROUND_PLAIN` |
+| **Full body, inside the frame** — hair and ribbons too | the figure's height is the proposer's yardstick, and the feet carry the leg chain's last link | a cropped foot is a leg with no ankle; a figure touching the edge reads as background that is not plain. Long hair and trailing ribbons are figure: where they reach the edge they fail the border, and where they curl round the figure into a ring they close off the background between the arms and the body (*What the recipe measured*, below) | `PAINTING_BACKGROUND_PLAIN`; a ring, `PAINTING_ARM_CLEAR` and `PAINTING_HANDS_APART` |
 | **Arms clear of the body** (an A-pose: arms down and out, a gap under each arm) | See-through separates what it can see; an arm with background round it becomes its own `handwear` and sleeve layers | an arm painted against the side is cut into a layer that holds part of the torso, and no rotation of its bone can swing it clear without dragging the torso's pixels | `PAINTING_ARM_CLEAR`: a gap on the line from each wrist to the hip of its side |
 | **Hands apart and open** | each hand is a part on its own arm's chain; open fingers read as a hand at a thumbnail | clasped or touching hands are one `handwear` layer, split only by an `assemble.cuts` polygon drawn by hand; and the clasped hands the README showed until issue #227 did not read as hands above a thumbnail (`examples/demo/README.md`) | `PAINTING_HANDS_APART`: a gap on the line between the wrists. Hands that meet close a loop of arms round the torso, so both arms are refused with them |
 | **Legs apart, with a visible gap** | the leg chain needs the legs painted apart (two legs that touch are one column See-through cannot split), and limbs are cut at their joints (#349, AUTHORING §3, *Limbs*), so each knee must be its own | legs that touch at the knee or the ankle come back as one `legwear` silhouette, a cut at the knee takes the other leg's pixels, and a step drags both | `PAINTING_LEGS_APART`: a gap on the line between the knees and on the line between the ankles |
 | **Feet facing front** | a foot seen from the front stays inside its leg's column, below the ankle the leg chain ends at | not measured in this repository; read the leg parts on the `sheet` | an eye (body-18 has no foot points) |
 | **A plain light background** | See-through and `assemble` read near-white as background (every channel above 235, the one test the assemble rim and the layer plausibility figures share) | scenery, a floor, a cast shadow, a gradient or a vignette is read as more figure — a layer of haze (`PLAN_LAYER_BACKGROUND`), or pixels that belong to no part | `PAINTING_BACKGROUND_PLAIN`: every border pixel near-white or unpainted |
 | **Nothing held, no prop across a limb** | each part rides one bone; a prop belongs to no tag See-through knows | a held object joins the hands (`PAINTING_HANDS_APART`) or lands in a hand or garment layer and moves with the wrong bone | partly: a prop that joins the hands is `PAINTING_HANDS_APART`; anything else, an eye |
-| **Clothing that leaves the joints unoccluded** | limbs are cut at the elbow and the knee (#349); each lower part carries a cap painted from what the joint hides | long sleeves and tights are fine; a cape over the elbows, a wide skirt over the knees or a forearm in front of the skirt's flare puts two parts' pixels on one joint. `assemble` names the missing cap pixels in its `limb cap:` lines | partly: a skirt over the knees is `PAINTING_LEGS_APART`, a forearm across a skirt is `PAINTING_ARM_CLEAR`; a cape over an elbow, an eye |
+| **Clothing that leaves the joints unoccluded** | limbs are cut at the elbow and the knee (#349); each lower part carries a cap painted from what the joint hides | long sleeves and tights are fine; a cape over the elbows, a wide skirt over the knees or a forearm in front of the skirt's flare puts two parts' pixels on one joint. `assemble` names the missing cap pixels in its `limb cap:` lines | partly: a skirt over the knees is `PAINTING_LEGS_APART`, a forearm across a skirt is `PAINTING_ARM_CLEAR`; anything on an elbow — a cape, a sleeve's frill, a bow — an eye (no rule reads the elbow; *What the recipe measured*) |
 | **Resolution and aspect** | See-through runs on a square (`inputs` pads the painting white to a square of its longer side) at `seethrough.resolution` (1024 by default), and a second run on a crop round the head, because the eyes of a full-figure run are too small to separate. A standing figure is taller than wide; `comfy paint` writes twice its latent (832x1216 → 1664x2432) | a landscape painting is padded above and below and spends See-through's square on white; a small painting leaves the head crop too few pixels for the eyes | an eye; `inputs` refuses a translucent painting (`INPUTS_PAINTING_OPAQUE`) and a head box off it |
 
 **One painting, one character.** The keypoint file may hold several people, and
@@ -72,47 +72,150 @@ What it reads, each a definition with no tuned number:
   line between them, sampled once per pixel the line crosses.
 
 The rules: `PAINTING_BACKGROUND_PLAIN` (every border pixel is ground),
-`PAINTING_JOINTS_STATED` (the wrists, hips, knees and ankles are `observed` with a
-position), `PAINTING_JOINT_ON_FIGURE` (every observed joint's pixel is figure),
-`PAINTING_ARM_CLEAR`, `PAINTING_HANDS_APART` and `PAINTING_LEGS_APART` (the gaps in
-the table above).
+`PAINTING_JOINTS_STATED` (the wrists, knees and ankles are `observed` with a
+position; a hip is `observed` or `occluded` with a position),
+`PAINTING_JOINT_ON_FIGURE` (every observed joint's pixel, and every occluded hip's,
+is figure), `PAINTING_ARM_CLEAR`, `PAINTING_HANDS_APART` and `PAINTING_LEGS_APART`
+(the gaps in the table above).
+
+**An occluded hip** (issue #372). A skirt hides the hips on most clothed figures —
+on every one of the 24 paintings behind the recipe below — and `occluded` with a
+position is how the keypoint file says so: the joint is where its producer
+estimated it, and the painting does not show it. The check reads an occluded hip
+when the arm's gap read from it is **well defined**, which it decides from what it
+reads:
+
+- the hip **carries a position**. The keypoint reader already holds every position
+  inside the image (`KEYPOINTS_POSITION_INSIDE`), so every sample of the line from
+  the wrist to the hip is a pixel of the painting;
+- that position's pixel **is figure** (`PAINTING_JOINT_ON_FIGURE`, which reads an
+  occluded hip as it reads an observed joint). An estimate placed on the background
+  would put a background pixel at the end of the arm's own line, and the arm would
+  pass on the estimate rather than on the painting.
+
+A hip with no position is still refused (`PAINTING_JOINTS_STATED`): it gives the arm
+rule no line to read. Only the hips: an occluded wrist is a hand the painting does
+not show, and an occluded knee or ankle is a leg whose gap cannot be read. The
+joints line counts occluded hips apart (`joints: 16 observed, 2 occluded with a
+position (r_hip, l_hip), 18 on the figure`), and an arm's gap line says when it was
+read from one.
 
 What it does not read: a front view, the feet, a prop that does not join the
-hands, a cape over an elbow, the hands' fingers, the face. A green `painting` says
+hands, anything on an elbow (a cape, a sleeve's frill, a bow), the hands' fingers,
+the face. A green `painting` says
 the joints and the silhouette hold the requirements it reads, not that the
 painting is good. A shadow or a floor enclosed by the background is figure to it;
 the border rule sees it only where it reaches the edge.
 
 ## A recipe that is one way, not the only way
 
-Anyone with a different generator reads the requirements above, not this. This
-is the `generation` block of the public `demo` example (`examples/demo/config.json`,
-with its pose file `examples/demo/pose.json`), which `rig-parts comfy paint`
-painted, with three changes: its character's words in `identity` and `costume`
-are placeholders, and the words its idol costume needed in `negative_extra`
-("microphone, holding microphone, stage, stage lights") are left out; its full record — the candidates, the seed choice and a hand-detailer
-pass `comfy paint` does not run — is in
-[parts-examples](https://github.com/rig-c/parts-examples):
+Anyone with a different generator reads the requirements above, not this. This is
+one way that passes `painting`: the `generation` block and the pose file of seed
+372108, painted by `rig-parts comfy paint` for issue #372 as one of 24 candidates,
+and chosen to be the next public example — a character for a wind demo, where hair
+and cloth move by physics under a side gust. Its painting and See-through layers are
+not yet published; when they are, its record joins the others in
+[parts-examples](https://github.com/rig-c/parts-examples). The block:
 
 ```json
 "generation": {
   "checkpoint": "hassakuXLIllustrious_v13StyleA.safetensors",
   "loras": [],
   "trigger": "",
-  "identity": "1girl, solo, adult woman, <your character's hair, eyes, accessories>",
+  "identity": "1girl, solo, adult woman, very long twin tails reaching the knees, deep blue hair, amber eyes, large red hair ribbons with long trailing ends",
   "sampler": { "steps": 30, "cfg": 6.0, "sampler": "euler_ancestral", "scheduler": "normal" },
-  "costume": "<the costume>, fully clothed, empty hands",
-  "negative_extra": "revealing clothes, bare shoulders, off shoulder, 2girls, multiple girls, holding, bag, weapon, clouds, cloud, sun, sky, sky background, grey background, blue background, gradient background, scenery, outdoors, from behind, back view, back of head, facing away, vignette, beige background, brown background, dark background, black background, spotlight, lighting gradient, flat color, cel shading, monochrome, lineart",
-  "pose": "full body, head to toe, entire body in frame, front view, facing viewer, looking at viewer, standing, arms away from body, hands apart away from skirt, open hands, relaxed fingers, relaxed pose, gentle smile, feet visible, shoes",
+  "costume": "white blouse with long fitted sleeves, red ribbon bow at the collar with long trailing ribbon ends, very wide flared tiered skirt, three ruffled layers, petticoat, skirt above the knees, knees visible, white thighhighs, red ankle boots, fully clothed, empty hands",
+  "negative_extra": "revealing clothes, bare shoulders, off shoulder, 2girls, multiple girls, holding, bag, weapon, clouds, cloud, sun, sky, sky background, grey background, blue background, gradient background, scenery, outdoors, from behind, back view, back of head, facing away, vignette, beige background, brown background, dark background, black background, spotlight, lighting gradient, flat color, cel shading, monochrome, lineart, long skirt, knee-length skirt, cape, legs together, knees together, crossed legs, hands on skirt, holding skirt, wide sleeves",
+  "pose": "full body, head to toe, entire body in frame, front view, facing viewer, looking at viewer, standing, legs apart, arms spread away from body, arms out to the sides, hands apart away from skirt, open hands, spread fingers, relaxed pose, gentle smile, feet visible, feet facing forward, shoes",
   "style": "anime illustration, detailed, soft shading, (white background:1.3), simple background, plain background",
   "negative_pose": "cropped, out of frame, cut off feet, close-up, portrait, upper body, from side, profile, sitting, kneeling, dynamic pose, arms raised, hand on face, contact shadow, cast shadow, floor, multiple views, reference sheet",
   "latent": [832, 1216],
-  "seed": 71006,
+  "seed": 372108,
   "control": { "skeleton": "pose.json", "strength": 0.8, "end_percent": 0.7 }
 }
 ```
 
-Put your character in the two placeholders, and negate what its costume invites.
+and the pose file it names, `pose.json` (OpenPose body-18 points on the 832x1216
+latent canvas, x right, y down):
+
+```json
+{
+  "width": 832,
+  "height": 1216,
+  "points": {
+    "nose": [416, 176],
+    "neck": [416, 252],
+    "r_shoulder": [340, 272],
+    "r_elbow": [258, 418],
+    "r_wrist": [168, 540],
+    "l_shoulder": [492, 272],
+    "l_elbow": [574, 418],
+    "l_wrist": [664, 540],
+    "r_hip": [374, 612],
+    "r_knee": [352, 862],
+    "r_ankle": [326, 1100],
+    "l_hip": [458, 612],
+    "l_knee": [480, 862],
+    "l_ankle": [506, 1100],
+    "r_eye": [398, 160],
+    "l_eye": [434, 160],
+    "r_ear": [378, 170],
+    "l_ear": [454, 170]
+  }
+}
+```
+
+**What `comfy paint` adds.** The prompt the sampler reads is not only the block's
+words. `comfy paint` puts a fixed head in front of each side (`POSITIVE_HEAD` and
+`NEGATIVE_HEAD` in `src/graphs.ts`, the reference implementation's, verbatim) — on
+this Illustrious checkpoint as on the Pony one, where its `score_*` words come
+from. A reader copying this recipe to another generator copies these too, or
+knows they are left out:
+
+- positive head: `score_9, score_8_up, score_7_up, source_anime, masterpiece, best quality, highly detailed`
+- negative head: `score_4, score_3, score_2, score_1, worst quality, low quality, lowres, blurry, jpeg artifacts, nsfw, nude, naked, cleavage, underwear, sexual, suggestive, child, loli, shota, kid, toddler, text, watermark, signature, logo, bad anatomy, bad hands, extra fingers, deformed, mutated`
+
+The positive is then the head, `trigger`, `identity`, `costume`, `pose` and
+`style`, joined with `, `; the negative is the head, `negative_extra` and
+`negative_pose`. The two strings seed 372108 was sampled with, as `comfy paint`
+recorded them beside the painting:
+
+```
+positive: score_9, score_8_up, score_7_up, source_anime, masterpiece, best quality, highly detailed, 1girl, solo, adult woman, very long twin tails reaching the knees, deep blue hair, amber eyes, large red hair ribbons with long trailing ends, white blouse with long fitted sleeves, red ribbon bow at the collar with long trailing ribbon ends, very wide flared tiered skirt, three ruffled layers, petticoat, skirt above the knees, knees visible, white thighhighs, red ankle boots, fully clothed, empty hands, full body, head to toe, entire body in frame, front view, facing viewer, looking at viewer, standing, legs apart, arms spread away from body, arms out to the sides, hands apart away from skirt, open hands, spread fingers, relaxed pose, gentle smile, feet visible, feet facing forward, shoes, anime illustration, detailed, soft shading, (white background:1.3), simple background, plain background
+negative: score_4, score_3, score_2, score_1, worst quality, low quality, lowres, blurry, jpeg artifacts, nsfw, nude, naked, cleavage, underwear, sexual, suggestive, child, loli, shota, kid, toddler, text, watermark, signature, logo, bad anatomy, bad hands, extra fingers, deformed, mutated, revealing clothes, bare shoulders, off shoulder, 2girls, multiple girls, holding, bag, weapon, clouds, cloud, sun, sky, sky background, grey background, blue background, gradient background, scenery, outdoors, from behind, back view, back of head, facing away, vignette, beige background, brown background, dark background, black background, spotlight, lighting gradient, flat color, cel shading, monochrome, lineart, long skirt, knee-length skirt, cape, legs together, knees together, crossed legs, hands on skirt, holding skirt, wide sleeves, cropped, out of frame, cut off feet, close-up, portrait, upper body, from side, profile, sitting, kneeling, dynamic pose, arms raised, hand on face, contact shadow, cast shadow, floor, multiple views, reference sheet
+```
+
+**What `painting` read on it**, with the wrists, knees and ankles read by eye on the
+painting at full size (on a 50 px grid) and the hips — under the skirt — at the pose
+file's hips x2. Written `observed`, as the check required until this change (the
+two paths shortened):
+
+```
+rig-parts painting: painting_372108.png, joints from kp/eye_372108.json person "a" (source: read by eye from the painting at full resolution on a 50 px grid (wrists, knees, ankles); hips under the skirt taken from the pose file x2; head and shoulders from the pose file x2 (not read by the check))
+  painting 1664x2432: background 2558081 px, figure 1488767 px; border 8188 px, 0 not background-coloured
+  joints: 18 observed, 18 on the figure
+  gap right arm (r_wrist to r_hip): 60 of 429 sampled pixels are background
+  gap left arm (l_wrist to l_hip): 76 of 415 sampled pixels are background
+  gap hands (r_wrist to l_wrist): 157 of 1011 sampled pixels are background
+  gap knees (r_knee to l_knee): 137 of 261 sampled pixels are background
+  gap ankles (r_ankle to l_ankle): 248 of 351 sampled pixels are background
+  PASS  the painting holds every requirement this check reads (docs/PAINTING.md); what only an eye reads is listed there
+```
+
+The same file with the two hips `occluded` (their honest state, read since this
+change; *An occluded hip*, above) reads the same five gaps:
+
+```
+  painting 1664x2432: background 2558081 px, figure 1488767 px; border 8188 px, 0 not background-coloured
+  joints: 16 observed, 2 occluded with a position (r_hip, l_hip), 18 on the figure
+  gap right arm (r_wrist to r_hip): 60 of 429 sampled pixels are background (r_hip occluded, read at its position)
+  gap left arm (l_wrist to l_hip): 76 of 415 sampled pixels are background (l_hip occluded, read at its position)
+  gap hands (r_wrist to l_wrist): 157 of 1011 sampled pixels are background
+  gap knees (r_knee to l_knee): 137 of 261 sampled pixels are background
+  gap ankles (r_ankle to l_ankle): 248 of 351 sampled pixels are background
+  PASS  the painting holds every requirement this check reads (docs/PAINTING.md); what only an eye reads is listed there
+```
+
 What each part does:
 
 - **The checkpoint** is public: [Hassaku XL (Illustrious)](https://civitai.com/models/140272)
@@ -120,29 +223,81 @@ What each part does:
   [Pony Diffusion V6 XL](https://civitai.com/models/257749) with the same sampler.
 - **The control skeleton** is what holds the pose; a pose asked for in words
   alone is one the sampler is free to ignore (`src/skeleton.ts`). `comfy paint`
-  draws it as OpenPose body-18 in the annotator's own style and applies it through
-  `controlnet-openpose-sdxl-1.0` at strength 0.8, ending at 0.7 of the steps. The
-  two built-ins are `stand_sides` (arms nearly straight down at the sides) and
-  `stand_clasp` (hands clasped at the waist), neither an A-pose; `pose.json` is a
-  pose file (issue #198) with the arms held out: the wrists at (206, 590) and
-  (626, 590) on the 832x1216 canvas, the shoulders at (340, 272) and (492, 272).
-  A pose file carries no words, so `generation.pose` is required beside it.
-- **The pose words** repeat what the skeleton asks — arms away, hands apart and
-  open — and the **negatives** refuse what breaks a rig: a held object, a
-  background that is not plain, a back or side view, a crop, a cast shadow or a
-  floor.
-- **The seed** is chosen by looking: the demo's was the best of sixteen candidates,
-  read at the hands; generate several and run `rig-parts painting` on each.
-
-What this recipe did not hold, measured: on the demo painting itself, with joints
-read by eye, `rig-parts painting` refuses both arms (the forearms cross the
-skirt's flare) and the legs at the knees and the ankles (the pose file's knees
-and ankles are the built-ins', close together, and the thighhighs touch). So
-change the two things it did not ask for, and check the result: move the pose
-file's knees and ankles apart and add leg words ("legs apart") to `pose`, and keep
-a skirt short or narrow enough that the forearms hang clear of it. How far apart
-holds a gap on a given checkpoint is not measured here; `painting` is the
-instrument that says.
+  draws the pose file as OpenPose body-18 in the annotator's own style and applies
+  it through `controlnet-openpose-sdxl-1.0` at strength 0.8, ending at 0.7 of the
+  steps. A pose file carries no words, so `generation.pose` is required beside it.
+  This one is the public `demo`'s pose file (`examples/demo/pose.json`) with the
+  head, neck and shoulders unchanged and the limbs moved, latent px:
+
+  | joint | `demo` | this recipe |
+  | --- | --- | --- |
+  | wrists | (206, 590), (626, 590) | (168, 540), (664, 540) — 72 px above the hips' line, 206 px out from each hip |
+  | elbows | (282, 440), (550, 440) | (258, 418), (574, 418) |
+  | hips | (378, 612), (454, 612) | (374, 612), (458, 612) |
+  | knees | (384, 862), (448, 862) — 64 px apart | (352, 862), (480, 862) — 128 px apart |
+  | ankles | (388, 1100), (444, 1100) — 56 px apart | (326, 1100), (506, 1100) — 180 px apart |
+
+  The paintings followed it: on the seven candidates whose joints were read by
+  eye, every wrist, knee and ankle lies within 38 painting px (in x or in y) of the
+  pose file's x2. On this one the eye read the wrists at (320, 1080) and
+  (1330, 1080), the knees at (700, 1720) and (960, 1720), and the ankles at
+  (655, 2190) and (1005, 2190).
+- **The pose words** repeat what the skeleton asks — legs apart, arms out, hands
+  apart and open, feet forward — and the **negatives** refuse what breaks a rig: a
+  held object, a background that is not plain, a back or side view, a crop, a cast
+  shadow or a floor, and what closes the legs or covers them (`long skirt`,
+  `knee-length skirt`, `cape`, `legs together`, `knees together`, `crossed legs`).
+- **The seed** is chosen by looking and by `painting`: generate several, run the
+  check on each, then read what it cannot (below). This one was chosen over the
+  others that passed because its ribbons wrap the twin tails (free ribbon arcs
+  become the rest shape a physics constraint swings from), its hair hangs at rest
+  (a candidate painted with its tails already swept out was a blown rest shape),
+  it has the widest two-layer skirt (the largest wind surface), and its tails
+  hang behind the figure, so they come out under a side gust. Two other passing
+  candidates were set aside because they read as a well-known existing character.
+
+## What the recipe measured
+
+24 paintings, seeds 372001-372008, 372101-372108 and 372201-372208, on the pose
+file above under three wordings of the hair and the skirt (the block above is the
+second; the first asked for twin tails "reaching the thighs" and a "wide flared
+layered ruffled miniskirt", the third added "layered skirt"). Screened with
+`painting` on the pose file's joints x2 — a screen, not a reading: a pose-file
+joint can land off the limb, which three did (`PAINTING_JOINT_ON_FIGURE`, on a
+wrist or an ankle), and the seven best were then read by eye. On that screen:
+
+- **Spreading the knees and the ankles in the pose file holds a gap.** The knee
+  gap held in 23 of 24 paintings and the ankle gap in 24 of 24, on Hassaku XL
+  v1.3 Style A. The one knee miss painted an overskirt down to the shins, which
+  joins the legs whatever the skeleton says. On the `demo` painting, painted from
+  knees 64 and ankles 56 latent px apart, `painting` refuses both.
+- **What clears `PAINTING_ARM_CLEAR` is the wrists' height above the skirt's
+  flare, not a narrow skirt.** With the wrists 72 latent px above the hips' line
+  (the `demo`'s are 22), both arm gaps held in 23 of 24 paintings, the widest
+  skirts among them: this recipe's two-layer skirt, at 60 and 76 background px on
+  the eye-read arm lines, and a three-tier ruffled skirt at 59 and 74. The one miss
+  is the hair ring below. On the `demo` painting the forearms hang across the
+  flare and both arms are refused.
+- **Long hair and ribbons that reach the frame fail the border.** 6 of the 9
+  refusals were `PAINTING_BACKGROUND_PLAIN`: twin tails or a ribbon's trailing
+  end painted out to the edge: 1 of 8 under the first wording (tails "reaching the
+  thighs"), 5 of 16 under the other two (tails "reaching the knees", "large red
+  hair ribbons with long trailing ends") — counts, not a rate any other prompt will
+  repeat. One of the six
+  also curled its hair round the figure into a ring: the white between the arms
+  and the body was no longer connected to the edge, so it was not background, and
+  both arms and the hands were refused with the border (`PAINTING_ARM_CLEAR` x2,
+  `PAINTING_HANDS_APART`). The remedy, **untested here**: leave a margin round
+  where the hair falls — the pose file decides where the figure sits, and this
+  one puts the wrists 168 latent px from each side — and ask for hair no longer
+  than the frame holds; `painting` says whether a seed kept it inside.
+- **`painting` cannot see the elbow.** Body-18 has an elbow point, but no rule reads
+  it, and 3 of the 7 best candidates passed with something on it: two with short
+  puff sleeves whose frilled cuff ends on the elbow, one with ribbons tied in
+  bows at the elbows. The costume's "long fitted sleeves" did not prevent either.
+  It is an eye check: look at each elbow at full size before See-through runs.
+  Prompt advice, **untested here**: add `puffy sleeves, short sleeves, puff
+  sleeves, elbow ribbon, ribbon on arm` to `negative_extra`.
 
 ## Alternate art for a limb
 

package/docs/STABILITY.md

@@ -53,7 +53,7 @@ defaults are the help's too, and none is guessed from the art.
 | `comfy` | `seethrough`: `--image`, `--out`; optional `--resolution`, `--steps`, `--seed`, `--prefix`, `--offload`, `--lama`, `--nf4`, `--host`, `--wait`, `--timeout`, `--poll` |
 | `assemble` | `--propose-plan` with `--source`, `--full`, `--config`, optional `--head`; or `--source`, `--full`, `--config`, `--out`, optional `--head` (without it, one run: issue #359), `--seam` (near-white, silhouette), `--project` (core, visible) |
 | `propose` | `--head-box` with `--full`, `--canvas` |
-| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`) |
+| `propose` | `--parts`, `--source`, `--out`; optional `--compare` or `--from-config` (one of them), `--keypoints`, `--person` and `--wrist-snap` (each with `--keypoints`), `--full`, `--head` (the turn control's depths; not with `--from-config`), `--grid-rule` (`figure` or `part`, the drafted lattice's spacing; not with `--from-config`), `--cloth` (a config whose `cloth` block is the recipe, issue #364; not with `--from-config`) |
 | `compare` | `--left`, `--right`; optional `--map` |
 | `rig` | `--config`, `--parts`, `--out`; optional `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
 | `check` | `--rig`, `--out`; optional `--parts`, `--source`, `--page-edges`, `--pack-shape`, `--requirements`, `--seam-pairs`, `--keep-stills` |
@@ -112,7 +112,7 @@ The fields, object by object (a bold path is where the object sits; `<part>` is
 part name, `[i]` an entry of a list):
 
 <!-- stable:config -->
-- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `turn`, `scene`
+- **config** — required by the full loader, in front of rig and build: `key`, `assemble`, `bones`, `meshes`, `regions`, `motion`; optional: `generation`, `seethrough`, `limbs`, `constraints`, `turn`, `scene`, `cloth`
 - **generation** — required: `checkpoint`, `loras`, `trigger`, `identity`, `sampler`, `costume`, `negative_extra`, `style`, `negative_pose`, `latent`, `seed`; optional: `pose`, `control`
 - **generation.loras[i]** — required: `name`, `strength`; optional: `strength_clip`
 - **generation.sampler** — required: `steps`, `cfg`, `sampler`, `scheduler`
@@ -147,6 +147,10 @@ part name, `[i]` an entry of a list):
 - **meshes.&lt;part&gt;.auto.regions[i]** — required: `name`, `shape`, `maxEdgeLength`, `transition`, `grade`, `minArtSamples`, and `cx`, `cy`, `r` for a circle or `points` for a polygon; optional: `bone`, `band` (both or neither; with neither the region is density only)
 - **meshes.&lt;part&gt;.auto.boundaryRuns** — required: `maxVertices`
 - **meshes.&lt;part&gt;.auto.stimulus**, or each entry of it when a list — required: `chain`, `degrees`
+- **cloth.&lt;tag&gt;**, the tag bottomwear, back hair or front hair (issue #364; read by propose --cloth only) — required: `chains`, `links`, `wind`, `gravity`; optional: `split`, `length_ratio`, `strength`, `damping`, `alternate_damping`, `translate`, `swing` (on bottomwear only)
+- **cloth.&lt;tag&gt;.split** — required: `at`, `into`
+- **cloth.&lt;tag&gt;.strength** — required: `trunk`, `branch`, `edge`
+- **cloth.&lt;tag&gt;.swing** — required: `scales`
 - **regions.&lt;part&gt;** — a bone name
 - **motion** — required: `duration`, `tracks`; optional: `blink`, `animations_from`
 - **motion.tracks[i]**, a single track — required: `bone`, `prop`, `amp`, `period`, `phase`; optional: `base`
@@ -180,7 +184,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
 | `check/check.json` and the rest of `check/` | `check`, `build`, `compose` | the reference's fields in its order (`gate_spine_html_green`, `rigc_entry`, `pack_mode`, `loop_max_diff`, the seam figures — `seam_mean`, `seam_px_over_40`, `seam_px_over_80` and, from issue #216, `seam_frame_scale`, the frame scale the bar divides the count by), `loop_physics` after `loop_max_diff` when the rig declares a physics constraint, `seam_border` after the seam figures when `parts.json` declares a scene (issue #242), `seam_pairs` after the seam figures when the seam bar fails or `--seam-pairs` asks (each row's picture under `check/seam/`; `--keep-stills` leaves the setup-pose still and its `frames.json` under `check/setup_still/`), then the judgement lines (`BREATH_VISIBLE`, `BLINK_NO_HOLE`, `CHAIN_LAG`, `TIP_OVER_ROOT`, `STILL_REGIONS_DARK`, `TEXTURE_STRETCH`), `ANIMATIONS_DO_NOT_FOLD` after them when `motion.json` holds an animation, the idle included — on every rig with an idle since issue #333 (issue #320: `status`, `animations`, `fps`, `physics_left_out`, `folding`, `folding_undeclared`, `declared_not_folding`, `bar`), `FEET_STAY_LEVEL` after it when a `footwear` part rides a bone that hangs from another and `motion.json` holds an animation (issue #348: `status`, `reason` on a SKIP only, `animations`, `fps`, `physics_left_out`, `bar_degrees`, `bar`, `feet` — each `part`, `bone`, `hangs_from`, `status`, `frames_posed`, `worst`), `LIMB_ONE_BONE` after it (and after `STRESS_OFF_CHAIN` where that is written) when `parts.json` holds a limb segment's part (issue #349: `status`, `parts` — each `part`, `limb`, `bone`, `status`, `others`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements`, and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
 | `layers.json`, `<index>_<name>.png` | `layers --export` | the wrapper form `layers` reads (issue #359): `width`, `height`, then `layers` — each `name`, `filename`, `left`, `top`, `right`, `bottom`, `depth_median` (the input's own; `null` for a PSD, the manifest's order then being the draw order) — drawn layers in draw order, then the hidden-art layers; a PNG's name is its index and its layer's name, and the manifest, not the file name, says which layer it is |
 | the template `.psd` | `layers --template` | one empty layer per name `templateLayerNames` (`src/layers.ts`) holds, bottom first; the same canvas writes the same bytes |
-| `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `turn` with `--full`/`--head`, and `notes` |
+| `proposal.json`, `render/landmarks*.png` | `propose` | the config's four rig sections, `constraints` with `--cloth` (issue #364: a physics constraint per tree link named `<bone>_physics`, a dangling end's `<bone>_translate`, and a skirt swing's transforms `<swing>_<tree>`), `turn` with `--full`/`--head`, and `notes` |
 | `basis.json` | `propose` | spec `spine-parts-basis/1` |
 | `config.json`, `mesh_draft.json` | `mesh-draft` | `config.json` is the config read, byte for byte, but for each drafted part's `meshes` entry; `mesh_draft.json` is spec `rig-parts-mesh-draft/1`: `rules`, `lattice_check`, `draft_check`, `figure_overdraw`, and per lattice part `part`, `mode`, `lattice`, `candidate` (with `bridges` — `units`, `joins` of `span` and `area_px2`, `area_px2`, `overdraw`, and `faint` only when an island was left out as faint — only when the candidate is a bridged one, issue #326), `delta` (under `--more-triangles` only), `readings`, `gate` (each line's `reading`, `pass`, `text`, `margin`), `note`; and `not_compared` (issue #307), only when the config holds an `auto` or `contour` entry: per such entry, in config order, `part`, `mode` and `note` — the part was neither drafted nor compared, and a config of lattices alone writes no such key |
 | the scene report | `compose` | spec `spine-parts-scene-report/1` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "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.",
   "type": "module",
   "bin": {
@@ -61,7 +61,7 @@
   },
   "dependencies": {
     "ag-psd": "^31.0.2",
-    "rig-c": "^2.47.1"
+    "rig-c": "^2.54.0"
   },
   "devDependencies": {
     "@esotericsoftware/spine-core": "4.3.13",

package/skills/rig-parts/SKILL.md

@@ -65,8 +65,9 @@ under that.
    an arm against the body, hands together, legs with no gap, a joint off the
    figure, a background that is not plain — and the fix is a new painting, not a
    config field. `docs/PAINTING.md` lists every requirement, the ones only an eye
-   reads (front view, feet, a cape over an elbow), and one generation recipe;
-   report those as not checked.
+   reads (front view, feet, anything on an elbow: a cape, a sleeve's frill, a
+   bow), and one generation recipe; report those as not checked. A hip a skirt
+   hides is written `occluded` with its estimated position, not `observed`.
 1. `rig-parts inputs --source <painting> --config config.json --out <dir>` writes
    `st_input_full.png`, the painting on a white square. The config needs only `key`,
    `seethrough` and `assemble.rig_scale` at this point. Run See-through on it — any
@@ -83,9 +84,11 @@ under that.
    `work/render/recomposite_error_rig.png`; a large red hole between two parts is a
    gap See-through left (a skirt split into two legs), fixed in the plan or the layers,
    not in the rig. Then `rig-parts propose --parts work/rig
-   --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `motion`
-   from `proposal.json` into the config. `assemble` needs the plan and none of
-   those four; do not stub them to get past it (AUTHORING §4 says what each step
+   --source <painting> --out work` → copy `bones`, `meshes`, `regions`, `limbs`,
+   `motion`, `constraints`, `turn` from `proposal.json` into the config, each it
+   wrote (`limbs` only with `--keypoints`, `constraints` only with `--cloth`, `turn`
+   only with `--full`/`--head`; a `limbs` block left out is refused at the next step). `assemble` needs the plan and none of
+   those sections; do not stub them to get past it (AUTHORING §4 says what each step
    requires). If an `uncovered hole` stays large with the plan right — a piece
    of the figure neither run holds, red in `recomposite_error_rig.png` — add an
    `assemble.patches` entry (a rig-pixel box, `alpha: "silhouette"`, drawn
@@ -107,6 +110,18 @@ under that.
    again, and read each `limb cap:` line for the pixels a cap is missing. A clean
    LINT does not show a seated hip is right; the overlay does. Never write a joint you did not get from an
    estimator or the painting: say `missing` and let the rule stand in.
+   A skirt or hair that must answer the scene (wind, the body moving) rather than
+   loop a keyed swing: add a `cloth` block to the config — one recipe per tag,
+   `bottomwear`, `back hair`, `front hair`: `chains`, `links`, `wind` and `gravity`
+   as `[root, tip]` (multipliers of the consumer's environment, tip >= root), and
+   optionally `split`, `strength`, `damping`/`alternate_damping`, `translate`,
+   and on the skirt `swing.scales` (AUTHORING §3, *Recipe: cloth and hair*) —
+   and propose with `--cloth config.json`; copy its `constraints` too. Every
+   number is yours but `length_ratio` and `strength`, whose defaults the note
+   names. Weights across neighbouring trees are not drafted (issue #378). No
+   stop at the legs is drafted: on the recipe's fixture the environment alone
+   pushed no hem through a thigh, but the consumer's hip motion can
+   (rig-c/core#1413).
 6. Correct against `render/landmarks.png` and `note:` lines; a
    `coverage … not checked` line is a bone no check read (the line says why),
    and `basis.json` beside the proposal says what each bone rests on — check

package/src/build.ts

@@ -70,7 +70,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { besideIdleLine, FOLD_LINE, type FoldsLine, LEVEL_LINE, type LevelLine, LIMB_LINE, type LimbLine, STRESS_LINE, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, GATE_PROFILE, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, rigcIdentity, rigcRanClause, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, type Limb, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
 import { failLine, PartsError, type Problem, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
@@ -365,7 +365,7 @@ function gateRun(label: string, rigc: RigcRunner, args: string[]): GateRun {
  * written anywhere, so packing them was work nobody read. No render is asked
  * of rigc by either build.
  */
-export const REFERENCE_BUILD_ARGS: readonly string[] = ['--profile', 'spine-html'];
+export const REFERENCE_BUILD_ARGS: readonly string[] = ['--profile', GATE_PROFILE];
 
 /** The reference build's label, as the rig stage prints it. */
 export const REFERENCE_BUILD_LABEL = `build ${REFERENCE_BUILD_ARGS.join(' ')}`;

package/src/check.ts

@@ -30,7 +30,7 @@
  *
  * | output | what |
  * | --- | --- |
- * | `build/` | `rigc build --profile spine-html --pack --page-edges free --pack-shape polygon` (or `pot`, `rect`, when the caller names them; {@link PAGE_EDGES}, {@link PACK_SHAPES}) — the packed atlas is the final artifact |
+ * | `build/` | `rigc build --profile rig-play --pack --page-edges free --pack-shape polygon` (or `pot`, `rect`, when the caller names them; {@link PAGE_EDGES}, {@link PACK_SHAPES}) — the packed atlas is the final artifact |
  * | `gate_spine-html.txt` | that build's gate lines, verbatim — the one gate: rigc's `build` runs it once over the compile and once over the packed pages on disk, and `spine-html` holds every rule `spine` measures (selftest `CH09`) |
  * | `idle_frames/` | `rigc render --animation idle --fps 12 --max 640 --geometry`: `frames.json` + `idle/f*.png` + `idle/geometry.json` (each mesh's skinned vertices, which `TEXTURE_STRETCH` reads, every attachment's posed triangles, which `TIP_OVER_ROOT` and both halves of `STILL_REGIONS_DARK` read since issues #118 and #123, and every bone's world transform, which the face half reads its head bone from) |
  * | `contact.png` | rigc's own contact sheet of that render, copied out |
@@ -304,9 +304,17 @@ export interface PackMode {
 /** Both defaults, {@link DEFAULT_PAGE_EDGES} and {@link DEFAULT_PACK_SHAPE}. */
 export const DEFAULT_PACK_MODE: PackMode = { pageEdges: DEFAULT_PAGE_EDGES, packShape: DEFAULT_PACK_SHAPE };
 
+/**
+ * The profile every rigc build this package runs is gated under. rig-c 2.50.0
+ * renamed `spine-html` to `rig-play` and runs the same rules under it; the old
+ * name is accepted only until a later minor release and prints a deprecation
+ * line on stderr (selftest `CK20` holds every stage's build to the new name).
+ */
+export const GATE_PROFILE = 'rig-play';
+
 /** The packed build's rigc arguments after `--out <dir>`, as every stage that packs passes them. */
 export function packedBuildArgs(mode: PackMode): string[] {
-  return ['--profile', 'spine-html', '--pack', '--page-edges', mode.pageEdges, '--pack-shape', mode.packShape];
+  return ['--profile', GATE_PROFILE, '--pack', '--page-edges', mode.pageEdges, '--pack-shape', mode.packShape];
 }
 
 /** The packed build as a label: the rigc command line that was run, after `rigc`. */