@rig-c/parts 1.18.0 → 1.19.0

package/cli.ts

@@ -644,10 +644,11 @@ usage:
       (every channel above 235) or unpainted (alpha 8 or less) ground
       connected to the edge; the figure is the rest; a gap is one background
       pixel on the line between two joints. PAINTING_BACKGROUND_PLAIN (a
-      border pixel that is not ground), PAINTING_JOINTS_STATED (a wrist, hip,
-      knee or ankle not observed), PAINTING_JOINT_ON_FIGURE (an observed
-      joint on the background), PAINTING_ARM_CLEAR (no gap from a wrist to
-      its hip), PAINTING_HANDS_APART (none between the wrists),
+      border pixel that is not ground), PAINTING_JOINTS_STATED (a wrist,
+      knee or ankle not observed, or a hip neither observed nor occluded
+      with a position), PAINTING_JOINT_ON_FIGURE (an observed joint, or an
+      occluded hip, on the background), PAINTING_ARM_CLEAR (no gap from a
+      wrist to its hip), PAINTING_HANDS_APART (none between the wrists),
       PAINTING_LEGS_APART (none between the knees, or the ankles). Prints the
       figure, every joint and every gap with its count; writes nothing.
       docs/PAINTING.md says why each one matters. Exit 0 PASS, 1 refused.

package/docs/AUTHORING.md

@@ -2391,8 +2391,8 @@ says why each requirement exists and what breaks without it.
 | --- | --- | --- |
 | <a id="PAINTING_SOURCE_PRESENT"></a><a id="PAINTING_SOURCE_DECODES"></a>`PAINTING_SOURCE_PRESENT`, `PAINTING_SOURCE_DECODES` | the painting is missing or not a PNG | the path |
 | <a id="PAINTING_BACKGROUND_PLAIN"></a>`PAINTING_BACKGROUND_PLAIN` | a border pixel is neither near-white nor unpainted: scenery, a floor, a gradient or a vignette reaches the edge, or the figure is cut by the frame; the detail counts them and names the first | a painting on a plain light background with the whole figure inside the frame (PAINTING.md, *Background*) |
-| <a id="PAINTING_JOINTS_STATED"></a>`PAINTING_JOINTS_STATED` | a wrist, hip, knee or ankle is `occluded` or `missing` in the keypoint file: the gap rules read those eight joints, and a hand or foot the painting does not show is a limb nothing can rig | a painting that shows it; or the joint, if the estimator missed one the painting shows |
-| <a id="PAINTING_JOINT_ON_FIGURE"></a>`PAINTING_JOINT_ON_FIGURE` | an observed joint's pixel is background | the keypoint file (measured on this painting?), or the painting |
+| <a id="PAINTING_JOINTS_STATED"></a>`PAINTING_JOINTS_STATED` | a wrist, knee or ankle is `occluded` or `missing` in the keypoint file, or a hip has no position: the gap rules read those eight joints, and a hand or foot the painting does not show is a limb nothing can rig. A hip may be `occluded` (a skirt hides it on most clothed figures, issue #372) when its arm's gap is **well defined**: it carries a position — inside the image, which the keypoint reader holds (`KEYPOINTS_POSITION_INSIDE`), so the wrist-to-hip line's every sample is a pixel of the painting — and that pixel is figure (`PAINTING_JOINT_ON_FIGURE`). A hip `occluded` with no position, or `missing`, is refused: there is no line to read | a painting that shows it; or the joint, if the estimator missed one the painting shows; for a hip under a skirt, `occluded` with its estimated position (PAINTING.md, *An occluded hip*) |
+| <a id="PAINTING_JOINT_ON_FIGURE"></a>`PAINTING_JOINT_ON_FIGURE` | an observed joint's pixel, or an occluded hip's, is background. For an occluded hip the detail adds that the arm's gap would be the estimate's own background, not one between the arm and the body | the keypoint file (measured on this painting?), or the painting; an occluded hip's estimate, moved onto the figure it is hidden under |
 | <a id="PAINTING_ARM_CLEAR"></a>`PAINTING_ARM_CLEAR` | the line from a wrist to the hip of its side crosses no background: the arm is painted against the body. Hands that meet close a loop round the torso, so this fires with `PAINTING_HANDS_APART` on both sides | a painting with the arm held away from the body (PAINTING.md, *Arms*) |
 | <a id="PAINTING_HANDS_APART"></a>`PAINTING_HANDS_APART` | the line between the two wrists crosses no background: hands clasped or touching | a painting with the hands apart and open (PAINTING.md, *Hands*) |
 | <a id="PAINTING_LEGS_APART"></a>`PAINTING_LEGS_APART` | the line between the knees, or between the ankles, crosses no background: the legs are one column there (a long skirt over the knees is refused here too) | a painting with the legs apart and a visible gap at the knees and the ankles (PAINTING.md, *Legs*) |

package/docs/MIGRATION.md

@@ -262,3 +262,24 @@ and writes nothing; no other command changed, and no byte any build writes moves
 | the README's input bullet for the painting | one sentence | the requirements, linked to `docs/PAINTING.md`, which ships in the package |
 
 What to do: nothing. Run `painting` on a new painting before See-through.
+
+### And `painting` reads an occluded hip (issue #372)
+
+A skirt hides the hips on most clothed figures, and the keypoint file says so with
+`occluded`. `painting` refused that state, which taught a writer to call an
+estimated hip `observed`. It now reads an occluded hip when the arm's gap from it is
+well defined: the hip carries a position (inside the image, as the keypoint reader
+holds every position) and that position's pixel is figure (PAINTING.md, *An occluded
+hip*). No other command changed, and no byte any build writes moves.
+
+| change | before | after |
+| --- | --- | --- |
+| a hip `occluded` with a position, on the figure | `PAINTING_JOINTS_STATED` (exit 1) | read: its arm's gap is measured from it, and the run passes or fails on the gaps |
+| a hip `occluded` with a position, on the background | `PAINTING_JOINTS_STATED` | `PAINTING_JOINT_ON_FIGURE`, as an observed joint there is |
+| a hip `occluded` with no position, or `missing` | `PAINTING_JOINTS_STATED` | the same rule; the detail now says a hip may be occluded with a position |
+| a wrist, knee or ankle `occluded` | `PAINTING_JOINTS_STATED` | unchanged; the detail adds that only a hip may be occluded |
+| the `joints:` line | `joints: <n> observed, <m> on the figure` | the same when no hip is occluded; otherwise `joints: <n> observed, <k> occluded with a position (<hips>), <m> on the figure` |
+| a gap line read from an occluded hip | — | ends ` (<hip> occluded, read at its position)` |
+
+What to do: write a hip a skirt hides as `occluded` with its estimate. A file that
+wrote it `observed` reads the same gaps as before.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/parts",
-  "version": "1.18.0",
+  "version": "1.19.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": {

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

package/src/paintcheck.ts

@@ -33,11 +33,20 @@
  *   background is what makes the figure readable at all; a border pixel that is
  *   not ground is scenery, a floor, a gradient, or the figure cut by the frame.
  * - `PAINTING_JOINTS_STATED` — the eight joints the gap rules read (wrists,
- *   hips, knees, ankles) are `observed` with a position. An occluded wrist is a
- *   hand the painting does not show.
- * - `PAINTING_JOINT_ON_FIGURE` — every observed joint's pixel is figure, not
- *   background. A joint off the figure is a keypoint file for another painting,
- *   or a limb the painting does not hold where the file says.
+ *   hips, knees, ankles) are `observed` with a position, except that a hip may
+ *   be `occluded` with a position (issue #372). An occluded wrist is a hand the
+ *   painting does not show; an occluded hip is the honest state of a hip under
+ *   a skirt, and the arm's gap read from it is **well defined** when the hip
+ *   carries a position — which the keypoint reader holds inside the image
+ *   (`KEYPOINTS_POSITION_INSIDE`), so every sample of the wrist-to-hip line is
+ *   a pixel of the painting — and that position's pixel is figure (the next
+ *   rule). A hip with no position is still refused: there is no line to read.
+ * - `PAINTING_JOINT_ON_FIGURE` — every observed joint's pixel, and every
+ *   occluded hip's, is figure, not background. A joint off the figure is a
+ *   keypoint file for another painting, or a limb the painting does not hold
+ *   where the file says; an occluded hip on the background would also put a
+ *   background pixel at the end of the arm's line, a gap the hip's own position
+ *   makes rather than one between the arm and the body.
  * - `PAINTING_ARM_CLEAR` — on each side, a gap between the wrist and the hip
  *   of the same side. None is an arm painted against the body.
  * - `PAINTING_HANDS_APART` — a gap between the two wrists. None is hands
@@ -56,6 +65,15 @@ import type { KeypointName } from './skeleton.ts';
 /** The joints the gap rules read, in the order a refusal lists them. */
 export const PAINTING_JOINTS: readonly KeypointName[] = ['r_wrist', 'l_wrist', 'r_hip', 'l_hip', 'r_knee', 'l_knee', 'r_ankle', 'l_ankle'];
 
+/** The joints that may be `occluded` with a position and still be read (issue #372): a skirt hides the hips on most clothed figures. */
+export const PAINTING_OCCLUDABLE: readonly KeypointName[] = ['r_hip', 'l_hip'];
+
+/** Whether the check reads joint `name` as given: observed with a position, or an occludable joint occluded with one. */
+function readable(name: KeypointName, j: KeypointPerson['joints'][KeypointName]): j is KeypointPerson['joints'][KeypointName] & { at: [number, number] } {
+  if (j.at === null) return false;
+  return j.state === 'observed' || (j.state === 'occluded' && PAINTING_OCCLUDABLE.includes(name));
+}
+
 /** The four gap rules' pairs: the rule, the two joints, and what the pair is called in a line. */
 export const PAINTING_GAPS: ReadonlyArray<readonly [string, KeypointName, KeypointName, string]> = [
   ['PAINTING_ARM_CLEAR', 'r_wrist', 'r_hip', 'right arm (r_wrist to r_hip)'],
@@ -94,9 +112,9 @@ export interface PaintingReading {
   firstBorderNotGround: [number, number] | null;
   backgroundPx: number;
   figurePx: number;
-  /** Every observed joint, its pixel, and whether that pixel is figure. */
-  joints: Array<{ name: KeypointName; at: [number, number]; pixel: [number, number]; onFigure: boolean }>;
-  /** The gap readings whose two joints are both observed with a position. */
+  /** Every observed joint and every occluded hip with a position, its state, its pixel, and whether that pixel is figure. */
+  joints: Array<{ name: KeypointName; state: 'observed' | 'occluded'; at: [number, number]; pixel: [number, number]; onFigure: boolean }>;
+  /** The gap readings whose two joints are both read as given (observed with a position, or an occluded hip with one). */
   gaps: GapReading[];
 }
 
@@ -174,15 +192,15 @@ export function readPainting(r: Raster, person: KeypointPerson): PaintingReading
   for (const v of bg) backgroundPx += v;
   const joints: PaintingReading['joints'] = [];
   for (const [name, j] of Object.entries(person.joints) as Array<[KeypointName, KeypointPerson['joints'][KeypointName]]>) {
-    if (j.state !== 'observed' || j.at === null) continue;
+    if (!readable(name, j)) continue;
     const pixel = pixelOf(j.at, w, h);
-    joints.push({ name, at: j.at, pixel, onFigure: bg[pixel[1] * w + pixel[0]] === 0 });
+    joints.push({ name, state: j.state === 'observed' ? 'observed' : 'occluded', at: j.at, pixel, onFigure: bg[pixel[1] * w + pixel[0]] === 0 });
   }
   const gaps: GapReading[] = [];
   for (const [rule, a, b, what] of PAINTING_GAPS) {
     const ja = person.joints[a];
     const jb = person.joints[b];
-    if (ja.state !== 'observed' || jb.state !== 'observed' || ja.at === null || jb.at === null) continue;
+    if (!readable(a, ja) || !readable(b, jb)) continue;
     const line = linePixels(ja.at, jb.at, w, h);
     let background = 0;
     for (const [x, y] of line) background += bg[y * w + x];
@@ -206,11 +224,14 @@ export function paintingProblems(reading: PaintingReading, person: KeypointPerso
   }
   for (const n of PAINTING_JOINTS) {
     const j = person.joints[n];
-    if (j.state === 'observed' && j.at !== null) continue;
+    if (readable(n, j)) continue;
+    const hip = PAINTING_OCCLUDABLE.includes(n);
     problems.push({
       code: 'PAINTING_JOINTS_STATED',
       object: `${keypoints} person "${person.id}" joint ${n}`,
-      detail: `is ${j.listed ? j.state : 'not listed'}${j.at === null ? '' : ` at ${pt(j.at)}`}; observed with a position is required — the gap rules read ${PAINTING_JOINTS.join(', ')}, and a joint the painting does not show is a limb it cannot rig`,
+      detail: hip
+        ? `is ${j.listed ? j.state : 'not listed'} with no position; observed or occluded with a position is required — the arm's gap is read on the line from the wrist to this hip, and a hip with no position gives no line to read`
+        : `is ${j.listed ? j.state : 'not listed'}${j.at === null ? '' : ` at ${pt(j.at)}`}; observed with a position is required — the gap rules read ${PAINTING_JOINTS.join(', ')}, and a joint the painting does not show is a limb it cannot rig (only a hip may be occluded, with a position)`,
     });
   }
   for (const j of reading.joints) {
@@ -218,7 +239,7 @@ export function paintingProblems(reading: PaintingReading, person: KeypointPerso
     problems.push({
       code: 'PAINTING_JOINT_ON_FIGURE',
       object: `${keypoints} person "${person.id}" joint ${j.name}`,
-      detail: `is at ${pt(j.at)}, and pixel ${pt(j.pixel)} is background (ground connected to the painting's edge); a joint on the figure is required — a file measured on another painting, or a limb that is not where the file says`,
+      detail: `is ${j.state === 'occluded' ? 'occluded ' : ''}at ${pt(j.at)}, and pixel ${pt(j.pixel)} is background (ground connected to the painting's edge); a joint on the figure is required — a file measured on another painting, or a limb that is not where the file says${j.state === 'occluded' ? '; an occluded hip is read only from a point on the figure, or the arm\'s gap would be the hip\'s own background' : ''}`,
     });
   }
   for (const g of reading.gaps) {
@@ -238,8 +259,14 @@ export function paintingLines(reading: PaintingReading): string[] {
     `  painting ${reading.width}x${reading.height}: background ${reading.backgroundPx} px, figure ${reading.figurePx} px; border ${reading.border} px, ${reading.borderNotGround} not background-coloured`,
   ];
   const on = reading.joints.filter((j) => j.onFigure).length;
-  out.push(`  joints: ${reading.joints.length} observed, ${on} on the figure${on === reading.joints.length ? '' : ` (off: ${reading.joints.filter((j) => !j.onFigure).map((j) => j.name).join(', ')})`}`);
-  for (const g of reading.gaps) out.push(`  gap ${g.what}: ${g.background} of ${g.samples} sampled pixels are background`);
+  const observed = reading.joints.filter((j) => j.state === 'observed').length;
+  const occluded = reading.joints.filter((j) => j.state === 'occluded').map((j) => j.name);
+  const occ = occluded.length === 0 ? '' : `, ${occluded.length} occluded with a position (${occluded.join(', ')})`;
+  out.push(`  joints: ${observed} observed${occ}, ${on} on the figure${on === reading.joints.length ? '' : ` (off: ${reading.joints.filter((j) => !j.onFigure).map((j) => j.name).join(', ')})`}`);
+  for (const g of reading.gaps) {
+    const hidden = [g.a, g.b].filter((n) => occluded.includes(n));
+    out.push(`  gap ${g.what}: ${g.background} of ${g.samples} sampled pixels are background${hidden.length === 0 ? '' : ` (${hidden.join(', ')} occluded, read at its position)`}`);
+  }
   return out;
 }