rig-parts 2.0.5 → 2.1.0

package/cli.ts

@@ -40,7 +40,7 @@ import { meshStatsStage } from './src/meshstats.ts';
 import { chainsLeftBehind, clothConfigEdits, editPaths, plainCount, previousCount, writtenClothConfig } from './src/clothconfig.ts';
 import { INPUT_CHECK_FILE, INPUT_CHECK_SPEC, PROVENANCE_FILE, REMESH_SPEC, remeshStage } from './src/remesh.ts';
 import { RETUNE_FILE, RETUNE_SPEC, retuneStage } from './src/retune.ts';
-import { checkPainting } from './src/paintcheck.ts';
+import { checkPainting, DEFAULT_PAINTING_FORM, isPaintingForm, PAINTING_FORMS, paintingFormOf } from './src/paintcheck.ts';
 import { readPng, writePng } from './src/raster/png.ts';
 import { REQUIREMENTS_SENTENCE } from './src/requirements.ts';
 import { composeStage, IMAGE_SEP, PLATE, PROVENANCES, SCENE_REPORT_FILE, SCENE_REPORT_SPEC, SCENE_SPEC } from './src/scene.ts';
@@ -947,20 +947,28 @@ usage:
       line and ${SCENE_REPORT_FILE} name what was accepted, and the run exits 1.
       Exit 0 when the check is PASS and nothing was accepted, 1 otherwise.
 
-  rig-parts painting --keypoints <keypoints.json> [--person <id>] <painting.png>
+  rig-parts painting --keypoints <keypoints.json> [--person <id>] [--form standee|illustration] <painting.png>
       Before See-through: read the painting against its body-18 joints (the
       file propose --keypoints reads, measured on this painting) and refuse,
-      by name, what a rig cannot be cut from. Background is near-white
-      (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,
-      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.
+      by name, what a rig cannot be cut from. --form defaults to
+      ${DEFAULT_PAINTING_FORM} (${PAINTING_FORMS.join(', ')}). Under standee,
+      background is near-white (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, 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). Under --form illustration (a
+      framed illustration with a painted room or a figure cut by the crop),
+      the source, keypoint canvas and bounds checks still run,
+      PAINTING_JOINTS_STATED requires at least one joint with a position and
+      PAINTING_JOINT_ON_FIGURE requires every stated joint's pixel to be
+      painted (alpha above 8); the standee border, 8-joint and gap rules do
+      not apply and print SKIP with the reason, never PASS. Prints the
+      figure, every joint and every gap or SKIP line; writes nothing.
       docs/PAINTING.md says why each one matters. Exit 0 PASS, 1 refused.
 
   rig-parts guide <RULE | §<n> | §<n>.<m> | §<n>.<m>.<k>>
@@ -1108,7 +1116,7 @@ const TAKES = {
   'mesh-stats': { valued: ['--config', '--parts'], switches: [] },
   remesh: { valued: ['--rig', '--config', '--parts', '--part', '--mesh', '--delta', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape', '--input-check'], switches: ['--record-input-check'] },
   retune: { valued: ['--rig', '--config', '--parts', '--out', '--requirements', '--idle-keys', '--page-edges', '--pack-shape', '--input-check'], switches: ['--record-input-check'] },
-  painting: { valued: ['--keypoints', '--person'], switches: [] },
+  painting: { valued: ['--keypoints', '--person', '--form'], switches: [] },
 } as const satisfies Record<string, { valued: readonly string[]; switches: readonly string[] }>;
 
 type Command = keyof typeof TAKES;
@@ -2153,8 +2161,9 @@ function cmdRetune(args: string[]): number {
 }
 
 /**
- * `painting --keypoints <k.json> [--person <id>] <painting.png>` (issue #350): what the painting must be before
- * See-through runs on it, read off its pixels and the body-18 joints `propose --keypoints` reads. Writes nothing.
+ * `painting --keypoints <k.json> [--person <id>] [--form standee|illustration] <painting.png>` (issues #350, #931):
+ * what the painting must be before See-through runs on it, read off its pixels and the body-18 joints
+ * `propose --keypoints` reads. Writes nothing.
  */
 function cmdPainting(args: string[]): number {
   const flags = new Map<string, string>();
@@ -2174,6 +2183,8 @@ function cmdPainting(args: string[]): number {
   }
   const kpPath = flags.get('--keypoints');
   if (kpPath === undefined) return usage('painting needs --keypoints <file>, the body-18 joints of the figure in painting px (the file propose --keypoints reads)');
+  const form = paintingFormOf(flags.get('--form'));
+  if (!isPaintingForm(form)) return usage(form);
   if (paths.length !== 1) return usage(`painting takes one painting path; got ${paths.length}`);
   const source = paths[0];
   try {
@@ -2187,11 +2198,15 @@ function cmdPainting(args: string[]): number {
     const kp = loadKeypoints(kpPath);
     checkImageSize(kp, painting.width, painting.height, kpPath, source);
     const person = choosePerson(kp, flags.get('--person'), kpPath);
-    console.log(`rig-parts painting: ${source}, joints from ${kpPath} person "${person.id}" (source: ${kp.source})`);
-    const r = checkPainting(painting, person, source, kpPath);
+    console.log(`rig-parts painting${form === 'illustration' ? ' (--form illustration)' : ''}: ${source}, joints from ${kpPath} person "${person.id}" (source: ${kp.source})`);
+    const r = checkPainting(painting, person, source, kpPath, form);
     for (const l of r.lines) console.log(l);
     if (r.problems.length > 0) throw new PartsError(r.problems);
-    console.log('  PASS  the painting holds every requirement this check reads (docs/PAINTING.md); what only an eye reads is listed there');
+    console.log(
+      form === 'illustration'
+        ? '  PASS  the painting holds the framed-illustration checks that apply (source, keypoint canvas and bounds, stated joints on painted pixels); standee background and gap rules reported SKIP above, not passed (docs/PAINTING.md)'
+        : '  PASS  the painting holds every requirement this check reads (docs/PAINTING.md); what only an eye reads is listed there',
+    );
     return EXIT_OK;
   } catch (err) {
     return printRefusal(err);

package/docs/AUTHORING.md

@@ -3657,7 +3657,7 @@ existing hardlinks are refused before artifact output; the ordinary mode names
 | `compose --scene <scene.json> --out [--requirements] [--accept]` | bind several characters' green builds into one rig (or, under `--accept`, builds failing only the bars named — for looking, not shipping): every name prefixed `<id>:` under one shared root, each character's offset added at its first-level bones, an optional background plate (its provenance recorded, judged by nothing) drawn first, and the draw order between the characters' slots as the scene file declares it — nothing inferred, nothing scaled; gated through rig-c as `rig` is, then checked ([AUTHORING §7](AUTHORING.md), *Composing several characters*) |
 | `mesh-draft --config <json> --parts <dir> --out <dir>` | draft contour meshes for configured lattices, keeping each only where it holds against its lattice through rig-c; write the revised config and measurement report |
 | `mesh-stats --config <json> --parts <dir>` | print each configured mesh's vertex and triangle counts and their total through the rig stage's construction; write nothing |
-| `painting --keypoints <json> [--person <id>] <png>` | before See-through, read the painting against its declared joints and refuse named background, joint or limb-gap problems; write nothing |
+| `painting --keypoints <json> [--person <id>] [--form standee\|illustration] <png>` | before See-through, read the painting against its declared joints (`standee` by default, or `illustration` for a framed illustration where standee border, 8-joint and gap rules report `SKIP`) and refuse named problems; write nothing |
 | `remesh --rig <dir> --config <json> --parts <dir> --part <name> --out <dir>` | with exactly one of `--mesh <entry.json>` or `--delta <mesh-edit.json>`, re-fit one part of a gated rig into a fresh revision, preserving the input |
 | `retune --rig <dir> --config <json> --parts <dir> --out <dir>` | splice the config's constraints and idle onto a gated rig in a fresh revision, carrying its attachments over as bytes |
 | `guide <RULE \| §<n> \| §<n>.<m> \| §<n>.<m>.<k>>` | print the one row of [docs/AUTHORING.md](AUTHORING.md) that names a rule (a refusal and the bar it enforces, `CHECK_<LINE>` and `<LINE>`, print together), or one section, `###` subsection or `####` under it, read from the installed file when it runs |
@@ -4609,21 +4609,26 @@ See-through with another seed.
 
 ### painting
 
-`rig-parts painting --keypoints <k.json> <painting.png>` (issue #350) reads the painting
-before See-through runs on it. *Background* is ground (alpha 8 or less, or every channel
+`rig-parts painting --keypoints <k.json> [--person <id>] [--form standee|illustration] <painting.png>` (issues #350, #931) reads the painting
+before See-through runs on it. Under `--form standee` (the default), *background* is ground (alpha 8 or less, or every channel
 above 235) connected to the painting's edge; the *figure* is the rest; a *gap* is one
-background pixel on the straight line between two joints. [PAINTING.md](PAINTING.md)
+background pixel on the straight line between two joints. Under `--form illustration`
+(a framed illustration with a painted room or a figure cut by the crop), the source
+and keypoint checks still run, `PAINTING_JOINTS_STATED` requires at least one joint
+with a position, `PAINTING_JOINT_ON_FIGURE` checks that every stated joint's pixel is
+painted (alpha above 8), and the standee border, 8-joint and gap rules report `SKIP`
+with their reason, never `PASS`. [PAINTING.md](PAINTING.md)
 says why each requirement exists and what breaks without it.
 
 | rule | means | change |
 | --- | --- | --- |
 | <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, 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*) |
+| <a id="PAINTING_BACKGROUND_PLAIN"></a>`PAINTING_BACKGROUND_PLAIN` | under `--form standee`, 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 (`SKIP` under `--form illustration`) | a painting on a plain light background with the whole figure inside the frame, or `--form illustration` for a framed illustration (PAINTING.md, *Background* and *Framed illustrations*) |
+| <a id="PAINTING_JOINTS_STATED"></a>`PAINTING_JOINTS_STATED` | under `--form standee`, 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. Under `--form illustration`, the eight standee gap joints report `SKIP`, and the rule refuses when the person states 0 joints with a position (`propose --keypoints` places bones only from joints with a position) | 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* and *Framed illustrations*) |
+| <a id="PAINTING_JOINT_ON_FIGURE"></a>`PAINTING_JOINT_ON_FIGURE` | under `--form standee`, 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). Under `--form illustration`, the near-white border flood reports `SKIP`, and any joint with a position whose pixel is unpainted (alpha 8 or less) is refused | 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` | under `--form standee`, 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 (`SKIP` under `--form illustration`) | a painting with the arm held away from the body (PAINTING.md, *Arms*) |
+| <a id="PAINTING_HANDS_APART"></a>`PAINTING_HANDS_APART` | under `--form standee`, the line between the two wrists crosses no background: hands clasped or touching (`SKIP` under `--form illustration`) | a painting with the hands apart and open (PAINTING.md, *Hands*) |
+| <a id="PAINTING_LEGS_APART"></a>`PAINTING_LEGS_APART` | under `--form standee`, 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; `SKIP` under `--form illustration`) | a painting with the legs apart and a visible gap at the knees and the ankles (PAINTING.md, *Legs*) |
 
 ### The optional ComfyUI adapter (`comfy paint`, `comfy seethrough`)
 

package/docs/PAINTING.md

@@ -47,14 +47,16 @@ Each requirement says what the pipeline needs, what fails without it, and whethe
 ## The check: `rig-parts painting`
 
 ```
-rig-parts painting --keypoints <keypoints.json> [--person <id>] <painting.png>
+rig-parts painting --keypoints <keypoints.json> [--person <id>] [--form standee|illustration] <painting.png>
 ```
 
 It runs on the CPU, before See-through, on the painting and its body-18 joints:
 the same keypoint file `propose --keypoints` reads (AUTHORING §3, *A posed
 figure*), from any estimator or written by hand, measured on this painting (its
-`width` and `height` are the painting's, `KEYPOINTS_IMAGE_SIZE`). It writes
-nothing. It prints the figure, every joint and every gap with its count, then
+`width` and `height` are the painting's, `KEYPOINTS_IMAGE_SIZE`). `--form`
+defaults to `standee` (`standee` or `illustration`). It writes
+nothing. It prints the figure, every joint and every gap (or under
+`--form illustration`, the `SKIP` lines for rules that do not apply), then
 `PASS` and exit 0, or a `FAIL` line per refusal and exit 1. Each `FAIL` line ends
 with `(see rig-parts guide <RULE>)`, which prints the rule's row in
 [AUTHORING §6](AUTHORING.md#6-refusals-the-rule-and-what-has-to-change).
@@ -132,6 +134,63 @@ 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.
 
+### Framed illustrations (`--form illustration`, issue #931)
+
+The default `--form standee` checks a full-body figure on a plain near-white or
+unpainted ground, with gaps for articulated limb cuts (`config.limbs`). Measured
+on the five 1664x2432 public examples (`demo`, `scarf`, `reference-demo`,
+`reference-sample`, `wind` — all five of which build and pass `rig-parts check`),
+only `wind` (the one example that declares `config.limbs`) passes the standee gap
+rules; the four non-limb standees fail `PAINTING_ARM_CLEAR` and
+`PAINTING_HANDS_APART` (on `demo` and `scarf` the wrists are 840 px and 392 px
+apart on opposite sides of the figure, yet the straight wrist-to-wrist line
+crosses the torso in between, so 0 of 841 and 0 of 393 sampled pixels are
+background), and three (`demo`, `reference-demo`, `reference-sample`) fail
+`PAINTING_LEGS_APART`:
+
+| public example (1664x2432) | `borderNotGround` | `r_wrist..r_hip` | `l_wrist..l_hip` | `r_wrist..l_wrist` | `r_knee..l_knee` | `r_ankle..l_ankle` | `--form standee` | `--form illustration` |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `demo` (`pose.json` x2) | 0 / 8188 | 0 / 345 (`FAIL`) | 0 / 345 (`FAIL`) | 0 / 841 (`FAIL`) | 0 / 129 (`FAIL`) | 0 / 113 (`FAIL`) | `FAIL` (5) | `PASS` (6 `SKIP`) |
+| `scarf` (`stand_sides` x2) | 0 / 8188 | 0 / 121 (`FAIL`) | 0 / 121 (`FAIL`) | 0 / 393 (`FAIL`) | 34 / 129 (`PASS`) | 32 / 113 (`PASS`) | `FAIL` (3) | `PASS` (6 `SKIP`) |
+| `reference-demo` (`stand_clasp` x2) | 0 / 8188 | 0 / 93 (`FAIL`) | 0 / 93 (`FAIL`) | 0 / 57 (`FAIL`) | 0 / 129 (`FAIL`) | 0 / 113 (`FAIL`) | `FAIL` (5) | `PASS` (6 `SKIP`) |
+| `reference-sample` (`stand_clasp` x2) | 0 / 8188 | 0 / 93 (`FAIL`) | 0 / 93 (`FAIL`) | 0 / 57 (`FAIL`) | 0 / 129 (`FAIL`) | 0 / 113 (`FAIL`) | `FAIL` (5) | `PASS` (6 `SKIP`) |
+| `wind` (`keypoints.json`) | 0 / 8188 | 60 / 429 (`PASS`) | 76 / 415 (`PASS`) | 157 / 1011 (`PASS`) | 137 / 261 (`PASS`) | 248 / 351 (`PASS`) | `PASS` | `PASS` (6 `SKIP`) |
+
+On a framed illustration — a character in a painted room, or framed at the waist
+or thighs so the figure touches the crop border and lower-body joints lie outside
+the canvas — near-white border flood-fill (`backgroundMask`) fails in both
+directions:
+
+1. **A painted room is not near-white ground.** Non-white room walls at the
+   border (`R,G,B <= 235`) are not seeded by `backgroundMask`, so `backgroundPx`
+   is 0 across the painted room and `PAINTING_JOINT_ON_FIGURE` cannot tell a room
+   wall from the figure before See-through runs.
+2. **White clothing touching the crop edge floods into the figure.** Measured on
+   `demo` cropped at `y = 1230` (1664x1230) and `wind` cropped at `y = 1250`
+   (1664x1250) over a painted room (`[80, 70, 65, 255]`): the character's white
+   dress/skirt touches the bottom border at `y = 1229` / `1249` with RGB channel
+   values above 235, so `backgroundMask` floods 31,806 px into `demo`'s dress
+   (covering `r_hip` at `[756, 1224]` RGB `[250, 241, 244]` and `l_hip` at
+   `[908, 1224]` RGB `[250, 239, 242]`) and 36,247 px into `wind`'s skirt
+   (covering `r_hip` at `[748, 1224]` RGB `[244, 245, 250]` and `l_hip` at
+   `[916, 1224]` RGB `[240, 241, 246]`), and `PAINTING_JOINT_ON_FIGURE` falsely
+   refuses both hips on the character.
+
+Under `--form illustration`, every rule is either kept because it still predicts a
+real downstream failure, or skipped with an explicit `SKIP` line naming the reason
+(never a pass):
+
+| rule | under `--form illustration` | why |
+| --- | --- | --- |
+| `PAINTING_SOURCE_PRESENT`, `PAINTING_SOURCE_DECODES` | **applies** | `inputs` and `assemble` read the same PNG; a missing or corrupt file fails every stage |
+| `KEYPOINTS_*` (`KEYPOINTS_FILE_PRESENT`, `KEYPOINTS_IS_JSON`, `KEYPOINTS_SPEC_KNOWN`, `KEYPOINTS_SPACE_STATED`, `KEYPOINTS_IMAGE_SIZE`, `KEYPOINTS_PERSON_CHOSEN`, `KEYPOINTS_POSITION_INSIDE`, …) | **applies** | `propose --keypoints` runs the same reader: a keypoint file measured on an uncropped 1664x2432 canvas fails `KEYPOINTS_IMAGE_SIZE` on a 1664x1230 framed crop, and a joint whose coordinates lie past the crop edge fails `KEYPOINTS_POSITION_INSIDE` |
+| `PAINTING_BACKGROUND_PLAIN` | **`SKIP`** | a painted room or a figure cut by the frame has non-ground border pixels (`5784 / 5784` on `demo` 1664x1230 and `5824 / 5824` on `wind` 1664x1250 over a painted room) |
+| `PAINTING_JOINTS_STATED` | **partial (`SKIP` + check)** | the 8 standee gap-line joints (`r_wrist`, `l_wrist`, `r_hip`, `l_hip`, `r_knee`, `l_knee`, `r_ankle`, `l_ankle`) report `SKIP` because knees, ankles, hips or hands may lie outside the frame or under clothing; the rule still refuses a person that states **0 joints with a position**, because `propose --keypoints` places bones only from joints with a position |
+| `PAINTING_JOINT_ON_FIGURE` | **partial (`SKIP` + check)** | the near-white border flood (`backgroundMask`) reports `SKIP` because a painted room is not near-white ground and white clothing at the crop edge floods into the figure (`r_hip` and `l_hip` on cropped `demo` and `wind`); the rule still checks every joint with a position against unpainted pixels (`alpha <= 8`, `OPAQUE_ALPHA_ABOVE`) and refuses a joint placed on an unpainted border or transparent hole (`inputs` also requires an opaque painting, `INPUTS_PAINTING_OPAQUE`) |
+| `PAINTING_ARM_CLEAR` | **`SKIP`** | arm-to-hip lines cannot cross border-connected near-white background over a painted room, and an illustration without articulated arm cuts (`config.limbs`) does not require an A-pose gap (4 of 5 public examples build and pass `check` with 0 arm-gap pixels) |
+| `PAINTING_HANDS_APART` | **`SKIP`** | the straight wrist-to-wrist line crosses the torso or painted room even when the hands are wide apart (`demo` 840 px apart, `scarf` 392 px apart: 0 background px) |
+| `PAINTING_LEGS_APART` | **`SKIP`** | knees and ankles may lie outside the frame on a waist/thigh crop or under a skirt, and over a painted room there is no border-connected near-white background between the legs |
+
 ## A recipe that is one way, not the only way
 
 Anyone with a different generator reads the requirements above, not this. This is

package/docs/STABILITY.md

@@ -70,7 +70,7 @@ defaults are the help's too, and none is guessed from the art.
 | `mesh-stats` | `--config`, `--parts` (issue #566, additive: prints, writes nothing) |
 | `remesh` | `--rig`, `--config`, `--parts`, `--part`, `--out`, and one of `--mesh` or `--delta` (issue #526); optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--record-input-check` and `--input-check` (issue #617, additive: without them nothing `remesh` prints or writes changes) |
 | `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--record-input-check` and `--input-check` (as for `remesh`, issue #617, additive) |
-| `painting` | one positional path, the painting; `--keypoints`; optional `--person` |
+| `painting` | one positional path, the painting; `--keypoints`; optional `--person`, `--form` (`standee` or `illustration`, issue #931) |
 | `guide` | one positional argument: a rule name, `§<n>`, `§<n>.<m>` or `§<n>.<m>.<k>` |
 | (none) | `--version`, `--help` |
 <!-- /stable:commands -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rig-parts",
-  "version": "2.0.5",
+  "version": "2.1.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/src/paintcheck.ts

@@ -54,6 +54,29 @@
  * - `PAINTING_LEGS_APART` — a gap between the two knees and a gap between the
  *   two ankles. None is legs painted as one column at that joint.
  *
+ * **Framed illustrations (`--form illustration`, issue #931):**
+ *
+ * The default form (`--form standee`) checks a full-body standee on a plain
+ * near-white or unpainted ground. A framed illustration with a painted room or a
+ * figure cut by the crop edge fails the border and gap rules for reasons that do
+ * not touch whether it can be rigged, and near-white border flood-fill
+ * (`backgroundMask`) both fails to mark a painted room as background and floods
+ * from the crop border into white clothing on the character (`r_hip` / `l_hip`
+ * on `demo` cropped at y=1230 and `wind` cropped at y=1250). Under
+ * `--form illustration`:
+ *
+ * - `PAINTING_BACKGROUND_PLAIN`, `PAINTING_ARM_CLEAR`, `PAINTING_HANDS_APART`
+ *   and `PAINTING_LEGS_APART` do not apply and report `SKIP` with the reason,
+ *   never `PASS`.
+ * - `PAINTING_JOINTS_STATED` reports `SKIP` for the eight standee gap-line
+ *   joints (wrists, hips, knees and ankles may lie outside the frame or under
+ *   clothing), and still refuses a person that states zero joints with a
+ *   position (`propose --keypoints` places bones only from joints with a
+ *   position).
+ * - `PAINTING_JOINT_ON_FIGURE` reports `SKIP` for the near-white border flood
+ *   and still refuses any joint with a position whose pixel is unpainted
+ *   (`alpha <= OPAQUE_ALPHA_ABOVE`).
+ *
  * Pure: the caller reads the files and hands over a raster and a person.
  */
 import type { Problem } from './errors.ts';
@@ -62,18 +85,38 @@ import { NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE } from './layers.ts';
 import type { Raster } from './raster/types.ts';
 import type { KeypointName } from './skeleton.ts';
 
+/** The forms `painting --form` accepts: a full-body standee on a plain ground (the default) or a framed illustration. */
+export const PAINTING_FORMS = ['standee', 'illustration'] as const;
+export type PaintingForm = (typeof PAINTING_FORMS)[number];
+export const DEFAULT_PAINTING_FORM: PaintingForm = 'standee';
+
+/** Parse `--form`, returning a usage refusal detail when unknown. */
+export function paintingFormOf(value: string | undefined): PaintingForm | string {
+  const f = value ?? DEFAULT_PAINTING_FORM;
+  return (PAINTING_FORMS as readonly string[]).includes(f) ? (f as PaintingForm) : `--form ${f}; one of ${PAINTING_FORMS.join(', ')} is required`;
+}
+
+export function isPaintingForm(v: PaintingForm | string): v is PaintingForm {
+  return (PAINTING_FORMS as readonly string[]).includes(v);
+}
+
 /** 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. */
+/** Whether the standee 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));
 }
 
+/** Whether the illustration check reads joint `j`: any observed or occluded joint that carries a position. */
+function statedWithPosition(j: KeypointPerson['joints'][KeypointName]): j is KeypointPerson['joints'][KeypointName] & { state: 'observed' | 'occluded'; at: [number, number] } {
+  return j.at !== null && (j.state === 'observed' || j.state === 'occluded');
+}
+
 /** 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)'],
@@ -112,8 +155,10 @@ export interface PaintingReading {
   firstBorderNotGround: [number, number] | null;
   backgroundPx: number;
   figurePx: number;
-  /** 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 }>;
+  /** Pixels with alpha above {@link OPAQUE_ALPHA_ABOVE}. */
+  opaquePx: number;
+  /** In `standee`, every observed joint and occluded hip with a position (`onFigure` = not border-connected ground); in `illustration`, every joint with a position (`onFigure` = alpha above {@link OPAQUE_ALPHA_ABOVE}). */
+  joints: Array<{ name: KeypointName; state: 'observed' | 'occluded'; at: [number, number]; pixel: [number, number]; alpha: 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[];
 }
@@ -172,17 +217,20 @@ export function linePixels(a: readonly [number, number], b: readonly [number, nu
 }
 
 /** Read the painting against the person's joints: every figure the rules decide on, before any rule decides. */
-export function readPainting(r: Raster, person: KeypointPerson): PaintingReading {
+export function readPainting(r: Raster, person: KeypointPerson, form: PaintingForm = DEFAULT_PAINTING_FORM): PaintingReading {
   const { width: w, height: h } = r;
   const bg = backgroundMask(r);
   let border = 0;
   let borderNotGround = 0;
   let firstBorderNotGround: [number, number] | null = null;
+  let opaquePx = 0;
   for (let y = 0; y < h; y++) {
     for (let x = 0; x < w; x++) {
+      const idx = y * w + x;
+      if (r.data[idx * 4 + 3] > OPAQUE_ALPHA_ABOVE) opaquePx++;
       if (y !== 0 && y !== h - 1 && x !== 0 && x !== w - 1) continue;
       border++;
-      if (!isGround(r, y * w + x)) {
+      if (!isGround(r, idx)) {
         borderNotGround++;
         firstBorderNotGround ??= [x, y];
       }
@@ -192,28 +240,62 @@ 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 (form === 'illustration') {
+      if (!statedWithPosition(j)) continue;
+      const pixel = pixelOf(j.at, w, h);
+      const alpha = r.data[(pixel[1] * w + pixel[0]) * 4 + 3];
+      joints.push({ name, state: j.state, at: j.at, pixel, alpha, onFigure: alpha > OPAQUE_ALPHA_ABOVE });
+      continue;
+    }
     if (!readable(name, j)) continue;
     const pixel = pixelOf(j.at, w, h);
-    joints.push({ name, state: j.state === 'observed' ? 'observed' : 'occluded', at: j.at, pixel, onFigure: bg[pixel[1] * w + pixel[0]] === 0 });
+    const alpha = r.data[(pixel[1] * w + pixel[0]) * 4 + 3];
+    joints.push({ name, state: j.state === 'observed' ? 'observed' : 'occluded', at: j.at, pixel, alpha, 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 (!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];
-    gaps.push({ rule, a, b, what, from: ja.at, to: jb.at, samples: line.length, background });
+  if (form === 'standee') {
+    for (const [rule, a, b, what] of PAINTING_GAPS) {
+      const ja = person.joints[a];
+      const jb = person.joints[b];
+      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];
+      gaps.push({ rule, a, b, what, from: ja.at, to: jb.at, samples: line.length, background });
+    }
   }
-  return { width: w, height: h, border, borderNotGround, firstBorderNotGround, backgroundPx, figurePx: w * h - backgroundPx, joints, gaps };
+  return { width: w, height: h, border, borderNotGround, firstBorderNotGround, backgroundPx, figurePx: w * h - backgroundPx, opaquePx, joints, gaps };
 }
 
 const pt = (p: readonly [number, number]): string => `[${p[0]}, ${p[1]}]`;
 
 /** The refusals a reading earns, every one at once, in the order the module's comment lists the rules. */
-export function paintingProblems(reading: PaintingReading, person: KeypointPerson, painting: string, keypoints: string): Problem[] {
+export function paintingProblems(
+  reading: PaintingReading,
+  person: KeypointPerson,
+  painting: string,
+  keypoints: string,
+  form: PaintingForm = DEFAULT_PAINTING_FORM,
+): Problem[] {
   const problems: Problem[] = [];
+  if (form === 'illustration') {
+    if (reading.joints.length === 0) {
+      problems.push({
+        code: 'PAINTING_JOINTS_STATED',
+        object: `${keypoints} person "${person.id}"`,
+        detail: 'states 0 joints with a position; at least one observed or occluded joint with a position is required — propose --keypoints places bones only from joints that carry a position',
+      });
+    }
+    for (const j of reading.joints) {
+      if (j.onFigure) continue;
+      problems.push({
+        code: 'PAINTING_JOINT_ON_FIGURE',
+        object: `${keypoints} person "${person.id}" joint ${j.name}`,
+        detail: `is ${j.state === 'occluded' ? 'occluded ' : ''}at ${pt(j.at)}, and pixel ${pt(j.pixel)} is unpainted (alpha ${j.alpha} <= ${OPAQUE_ALPHA_ABOVE}); a joint on painted canvas (alpha above ${OPAQUE_ALPHA_ABOVE}) is required — a file measured on another painting, or a joint placed on an empty border`,
+      });
+    }
+    return problems;
+  }
   if (reading.borderNotGround > 0) {
     const f = reading.firstBorderNotGround as [number, number];
     problems.push({
@@ -253,8 +335,25 @@ export function paintingProblems(reading: PaintingReading, person: KeypointPerso
   return problems;
 }
 
-/** The lines a reading prints, before any refusal: the figure, every joint and every gap, each with its numbers. */
-export function paintingLines(reading: PaintingReading): string[] {
+/** The lines a reading prints, before any refusal: the figure, every joint and every gap (or in `illustration`, the `SKIP` lines), each with its numbers. */
+export function paintingLines(reading: PaintingReading, form: PaintingForm = DEFAULT_PAINTING_FORM): string[] {
+  if (form === 'illustration') {
+    const unpainted = reading.width * reading.height - reading.opaquePx;
+    const on = reading.joints.filter((j) => j.onFigure).length;
+    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(', ')})`;
+    return [
+      `  painting ${reading.width}x${reading.height} (form: illustration): opaque ${reading.opaquePx} px, unpainted ${unpainted} px; border ${reading.border} px, ${reading.borderNotGround} not near-white or unpainted`,
+      `  joints: ${observed} observed${occ}, ${on} on painted canvas${on === reading.joints.length ? '' : ` (unpainted: ${reading.joints.filter((j) => !j.onFigure).map((j) => j.name).join(', ')})`}`,
+      `  SKIP  PAINTING_BACKGROUND_PLAIN: framed illustration; a painted room or a figure cut by the frame has non-ground border pixels (${reading.borderNotGround} of ${reading.border} border pixels not near-white or unpainted)`,
+      `  SKIP  PAINTING_JOINTS_STATED (standee gap joints): framed illustration; wrists, hips, knees and ankles may lie outside the frame or under clothing (${reading.joints.length} joint(s) stated with a position)`,
+      `  SKIP  PAINTING_JOINT_ON_FIGURE (near-white border flood): framed illustration; a painted room is not near-white ground and white clothing at the crop edge floods into the figure (opaque pixel alpha > ${OPAQUE_ALPHA_ABOVE} is still checked)`,
+      '  SKIP  PAINTING_ARM_CLEAR: framed illustration; arm-to-hip lines do not cross plain border-connected background over a painted room or a pose with arms against the body',
+      '  SKIP  PAINTING_HANDS_APART: framed illustration; the wrist-to-wrist line crosses the torso or painted room rather than plain border-connected background',
+      '  SKIP  PAINTING_LEGS_APART: framed illustration; knees and ankles may lie outside the frame or over a painted room without plain border-connected background',
+    ];
+  }
   const out = [
     `  painting ${reading.width}x${reading.height}: background ${reading.backgroundPx} px, figure ${reading.figurePx} px; border ${reading.border} px, ${reading.borderNotGround} not background-coloured`,
   ];
@@ -271,7 +370,13 @@ export function paintingLines(reading: PaintingReading): string[] {
 }
 
 /** Read and judge: the lines to print and every refusal, which the caller prints before it throws them at once. */
-export function checkPainting(r: Raster, person: KeypointPerson, painting: string, keypoints: string): { lines: string[]; problems: Problem[] } {
-  const reading = readPainting(r, person);
-  return { lines: paintingLines(reading), problems: paintingProblems(reading, person, painting, keypoints) };
+export function checkPainting(
+  r: Raster,
+  person: KeypointPerson,
+  painting: string,
+  keypoints: string,
+  form: PaintingForm = DEFAULT_PAINTING_FORM,
+): { lines: string[]; problems: Problem[] } {
+  const reading = readPainting(r, person, form);
+  return { lines: paintingLines(reading, form), problems: paintingProblems(reading, person, painting, keypoints, form) };
 }