@rig-c/parts 1.51.0 → 1.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/PAINTING.md CHANGED
@@ -59,6 +59,27 @@ nothing. It prints the figure, every joint and every gap with its count, then
59
59
  with `(see rig-parts guide <RULE>)`, which prints the rule's row in
60
60
  [AUTHORING §6](AUTHORING.md#6-refusals-the-rule-and-what-has-to-change).
61
61
 
62
+ **DWPose on a faceless figure** (issue #578). Measured on eight seeds of one
63
+ frontal, faceless wooden-mannequin painting (SDXL base 1.0, legs apart,
64
+ 1664x2432), DWPose `dw-ll_ucoco_384` through ComfyUI's DWPreprocessor at
65
+ resolution 1024, it did three things a keypoint file must not keep:
66
+
67
+ - **It may find no person.** With its default bbox detector (`yolox_l.onnx`) it
68
+ returned no person on 8 of the 8 seeds; with `bbox_detector` None it returned
69
+ one on 8 of 8. Run it with `bbox_detector` None.
70
+ - **It may read the figure from behind.** With `bbox_detector` None the sides came
71
+ back mirrored on 7 of the 8: `r_shoulder` image-right of `l_shoulder` (on one
72
+ seed x 978 against 697) and `r_hip` image-right of `l_hip` (907 against 753).
73
+ The keypoint file's `r` / `l` are the subject's sides, so on a figure facing the
74
+ viewer `r_shoulder` is on the image's left (`src/keypoints.ts`, AUTHORING §3).
75
+ Check that `r_shoulder` lies image-left of `l_shoulder` and `r_hip` image-left of
76
+ `l_hip`, and swap each `r_` / `l_` pair of a file where they do not.
77
+ - **Its hips may sit on the pelvis.** On that seed, after the swap, the hips were
78
+ at painting y 1117.0 and 1113.1 and the hip domes at y 1246 — 129 and 133
79
+ painting px lower (64.5 and 66.5 rig px at an `assemble.rig_scale` of 0.5). The shoulders
80
+ landed on the torso's edge (x 697.4 and 978.5) rather than on the balls (652 and
81
+ 1010). Move the hips and the shoulders onto the joints before `propose`.
82
+
62
83
  What it reads, each a definition with no tuned number:
63
84
 
64
85
  - **Ground** — a pixel the package already calls background: alpha 8 or less
@@ -100,8 +121,12 @@ joints line counts occluded hips apart (`joints: 16 observed, 2 occluded with a
100
121
  position (r_hip, l_hip), 18 on the figure`), and an arm's gap line says when it was
101
122
  read from one.
102
123
 
103
- What it does not read: a front view, the feet, a prop that does not join the
104
- hands, anything on an elbow (a cape, a sleeve's frill, a bow), the hands' fingers,
124
+ What it does not read: a front view (a file with every `r_` / `l_` pair swapped
125
+ draws the same lines between the same points — the two arm lines trade names, the
126
+ hands, knees and ankles lines run between the same two joints — so it reads as the
127
+ unswapped file does: on the selftest's painting fixture both print the same counts
128
+ and `PASS`), the feet, a prop that does not join the hands, anything on an elbow (a
129
+ cape, a sleeve's frill, a bow), the hands' fingers,
105
130
  the face. A green `painting` says
106
131
  the joints and the silhouette hold the requirements it reads, not that the
107
132
  painting is good. A shadow or a floor enclosed by the background is figure to it;
package/docs/STABILITY.md CHANGED
@@ -61,6 +61,7 @@ defaults are the help's too, and none is guessed from the art.
61
61
  | `build` | `--config`, `--source`, `--full`, `--out`; optional `--head` (as for `assemble`), `--seam`, `--project`, `--page-edges`, `--pack-shape`, `--loop`, `--lead-in`, `--requirements`, `--idle-keys`, `--seam-pairs`, `--keep-stills`, `--alt` (as for `assemble`, issue #454), `--set` or `--all-sets` (as for `check`, issue #454), `--environment` (as for `check`, issue #538, additive) |
62
62
  | `compose` | `--scene`, `--out`; optional `--requirements`, `--accept` |
63
63
  | `mesh-draft` | `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon), `--more-triangles` |
64
+ | `mesh-stats` | `--config`, `--parts` (issue #566, additive: prints, writes nothing) |
64
65
  | `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) |
65
66
  | `retune` | `--rig`, `--config`, `--parts`, `--out`; optional `--requirements`, `--idle-keys` (ctl, direct), `--page-edges` (pot, free), `--pack-shape` (rect, polygon) |
66
67
  | `painting` | one positional path, the painting; `--keypoints`; optional `--person` |
@@ -190,7 +191,7 @@ every number) are AUTHORING §3's tables, and the loader refuses any other by na
190
191
 
191
192
  | file | written by | what is stable |
192
193
  | --- | --- | --- |
193
- | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
194
+ | `parts.json`, `parts/<name>.png` | `assemble`, `build` | one record per part: `from` (`<run>:<tag>` with a See-through v3 tag, `<run>:author:<label>` for a layer the author made — issue #256, read by no role rule — or `painting:<name>` for a patch), `cut_from` on a cut's piece only (the plan part it was cut from, issue #230), `limb` on a limb segment's part only (issue #349: `name`, `segment`, `of`, `bone`, and below a joint `joint`, `range` when the config segment declares one (issue #360), and `cap` — `at`, `width`, `radius`, `box`, `layer_px`, `image_px` with a cap image, `image_layer` after it when that image was a hidden-art layer — issue #359, `<run>:<layer>:hidden` — `missing_px`, `short_px` (`left`, `right`) after it only when `missing_px` is above 0 (issue #557, additive), then `shape` and `upper_px` under the segment's `cap_shape` — `upper_px` without the shape only when the upper segment gave a pixel (issue #557, additive) — and after them `lower_px`, `lower_kept_px` and `lower_missing_px` under `cap_shape: "ball"` (issue #579, additive), and `edge`, `feather_radius` and `feathered_px` under its `edge`, and `cut_band`, `cut_offset`, `cut_at`, `cut_crossed`, `joint_crossed`, `band_px` and `stroke_luma_max` (when the band has a split) under its `cut_band`, issue #360), the box `x`, `y`, `w`, `h` (rig px), the pixel counts `src/parts.ts` documents (`opaque_px`, `visible_px`, `occluded_px`, `projected_core_px`, `source_px_taken`, `visible_not_projected_px`, `refused_drift_px`, `merged_px`, `seam_override_px`, and `fringe_pushed_back` when not empty); `rig_size`, `scale_rig_per_source`, `ghost_px`, `recomposite`, and `scene` (`figure_alpha_above`, `figure_px`, `figure_mask`) under `config.scene` only, with the figure's mask `figure_rig.png` beside the recomposite (issue #242); `single_run_pad` (`file_size`, `side`, `left`, `top`) last, only for one run whose file is not the `seethrough.resolution` square (issue #366) |
194
195
  | `rig/rig.json`, `rig/motion.json`, `rig/images/` | `rig`, `build`, `compose` | rig-c's rig spec and motion spec, `spec` `rigc-rig/1` and `rigc-motion/1`: the format is rig-c's, and this package writes only what rig-c's parser accepts; a bone carries `inherit` only where config.bones declares one, rig-c's mode name as written (issue #348) |
195
196
  | `rig/mesh_report.json` | `rig`, `build` | one row per mesh: `part`, `vertices`, `triangles`, `hull`, `bones` (the sorted names the attachment's weights bind in the written `rig.json`, in every mode — since 1.49.1 (issue #536) a rig with `turn` or `stops` names the twins and `<link>_d` bones there, where the row named the segment bones they replace: a fix of a wrong name, not a format change; a rig with neither writes the bytes it wrote), `max_influences`, `mean_influences`, `art_coverage`, then `grid` (a lattice); `mode` "contour" with `params`, `contour`, `regions` (`params.maxEdge` and `contour.outlineCut` only when the mesh declares `contour.maxEdge`; `params.bridges` and `contour.bridges` — `islands`, `units`, `joins`, and `faint` only when an island was left out as faint — only when it declares `contour.bridges`); or `mode` "influence" with `influence` (as declared), `reach` (`farthest`, `at`, `nearest`, `capped`, `widest`) and `lattice` (rig-c's `SegmentsLatticeReport`: `cols`, `rows`, `artCells`, `keptCells`, `passes`, `islands`) (issue #378); or `mode` "auto" with `settings`, `source`, `result`, `residuals`, `worst_residual`, `worst_region`, `motion_amplitude`, `termination`, `weights`, `regions`, `deformation`, `quality_report` (rig-c's `mesh-quality-report/1` document whole), `motion_report`, and, only when they apply, `stray_cleared` (after `source`, when `source.stray` is declared), `skinning_residual` and `replay` (`AutoMeshReport` in `src/rig.ts`); in every mode, `exponent` when the mesh declares one (after `grid`, or after `mode`); `influences`, as declared, when a lattice or contour mesh declares it (after `exponent`, or where `exponent` would be); `stray` and `stray_cleared` when a lattice mesh declares `stray` (after `influences`, or where `influences` would be); `ribs` when a contour or auto mesh declares them (after `exponent`, or after `mode`), and then `contour.ribs` (`source.contour.ribs` in the automatic mode) |
196
197
  | `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`, `environment` after it under `--environment` only (issue #538, additive: `path` as given, `sha256`, `steps`), `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 (issues #320, #363: `status`, `animations`, `fps`, `physics_left_out`, `folding` — each `animation`, `slot`, `attachment`, `frames`, `worst_frame`, `worst_triangles`, `triangles`, `physics_on`, `physics_off`, `physics_constraints`, `declared`, `line` — `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`), `SEAM_OVER_RANGE` after it when a limb record carries a `range` (issue #360: `status`, `frame_scale`, `physics_left_out`, `bar` — `mean`, `rig_px_over_40`, `level` — and `joints`, each `part`, `limb`, `segment`, `joint`, `bone`, `range`, `at`, `radius`, `under_px`, `status`, `poses` — each `degrees`, `status`, `mean`, `px_over_40`, `px_over_80`, `rig_px_over_40`, and `step_px` (`left`, `right`) only on a joint whose cap record carries `short_px` (issue #557, additive) — and `unread` on a joint not read), `SEAM_OVER_MOTION` after it when `parts.json` holds a limb segment or `--requirements` a `seam` (issue #493, a warning and not a bar: `status` — `WARN`, `CLEAR` or `SKIP` — `reason` on a SKIP only, `fps`, `floor`, `pairs` — each `pair`, `a`, `b`, `declared`, and `unread` on a pair not read — `animations`, `warnings`, `rows` — each `pair`, `animation`, `status`, `drawn`, `banded`, `opens`, `px`, `max_px`, `under_floor`), `CLOTH_SETTLES` after it when the rig declares a physics constraint and has an idle (issue #501, a warning and not a bar: `status` — `WARN` or `CLEAR` — `fps`, `frames`, `duration`, `floor_rig_px_per_s`, `floor`, `levers`, `warnings`, `rows` — each `tip`, `root`, `links`, `point`, `settles_at`, `max_rig_px_per_s`, `min_rig_px_per_s`), `RECOMPOSITE_HOLES` (its first figure `declared_scene` when `parts.json` declares a scene), `SETUP_POSE_VS_SOURCE`, `skipped`, a `requirements` block under `--requirements` (or `build`'s `config.requirements`) — `file` first from issue #556, additive: `path` as typed or declared, `sha256`, `keys` — and `PASS`; `check/build/skeleton.json`, `.atlas` and `.png` are the packed artifact rig-c writes |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rig-c/parts",
3
- "version": "1.51.0",
3
+ "version": "1.53.0",
4
4
  "description": "AI-authored 2D character parts from one anime painting and its See-through layer decomposition: measured parts, weighted-mesh rig specs, verified through rig-c before anything is written. A CLI for agents that cannot see the image.",
5
5
  "type": "module",
6
6
  "bin": {
package/src/assemble.ts CHANGED
@@ -2571,6 +2571,8 @@ export interface CutCount {
2571
2571
  underEmpty?: number;
2572
2572
  /** With `under_fill: "colour"` only (issue #360): the `under` pixels took the image's colour at the alpha the cut removed; absent without it. */
2573
2573
  underFill?: 'colour';
2574
+ /** Issue #564, only on a cut from a part a limb takes, lying past the limb: the joint it lies past and the segment below it, with its bone. */
2575
+ limb?: { limb: string; joint: string; part: string; bone: string };
2574
2576
  }
2575
2577
 
2576
2578
  /**
@@ -2588,7 +2590,8 @@ export function cutLines(cuts: readonly CutCount[]): string[] {
2588
2590
  const colour = cs.some((c) => c.underFill === 'colour') ? ` (${cs.reduce((a, c) => a + (c.underFill === 'colour' ? (c.under ?? 0) : 0), 0)} colour only, at the alpha the cut removed)` : '';
2589
2591
  return (
2590
2592
  ` cut: "${from}" opaque ${cs[0].before} = "${from}" ${cs[0].kept} + ${cs.map((c) => `"${c.into}" ${c.taken}`).join(' + ')}; band ${cs.reduce((a, c) => a + c.band, 0)} px held by both` +
2591
- (cs.some((c) => c.under !== undefined) ? `; under ${cs.reduce((a, c) => a + (c.under ?? 0), 0)} px filled${colour}, ${cs.reduce((a, c) => a + (c.underEmpty ?? 0), 0)} px left empty` : '')
2593
+ (cs.some((c) => c.under !== undefined) ? `; under ${cs.reduce((a, c) => a + (c.under ?? 0), 0)} px filled${colour}, ${cs.reduce((a, c) => a + (c.underEmpty ?? 0), 0)} px left empty` : '') +
2594
+ cs.map((c) => (c.limb === undefined ? '' : `; "${c.into}" lies past joint "${c.limb.joint}" of limb "${c.limb.limb}", in the band of "${c.limb.part}" on bone "${c.limb.bone}"`)).join('')
2592
2595
  );
2593
2596
  });
2594
2597
  }
@@ -2752,17 +2755,26 @@ export function shortCapLint(j: LimbCount['joints'][number]): string | null {
2752
2755
  ...(k.image_px === undefined ? [] : [`${k.image_px} px from ${k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`}`]),
2753
2756
  `${k.layer_px} px from "${j.part}"'s layer`,
2754
2757
  `${k.upper_px ?? 0} px from "${j.upper}"`,
2758
+ // Issue #579: under cap_shape "ball", the lower half's written and kept pixels.
2759
+ ...(k.shape === 'ball' ? [`on the lower side ${k.lower_px ?? 0} px written, ${k.lower_kept_px ?? 0} px left as painted`] : []),
2755
2760
  ].join(', ');
2761
+ const lowerMiss = k.lower_missing_px ?? 0;
2762
+ const which =
2763
+ lowerMiss === 0
2764
+ ? `${n} px of the disc on the upper side of the cut, where ${where}`
2765
+ : lowerMiss === n
2766
+ ? `${n} px of the disc on the lower side of the cut (cap_shape "ball"), where "${j.part}"'s layer is transparent and no cap image gives a pixel`
2767
+ : `${n} px of the disc, ${n - lowerMiss} on the upper side of the cut, where ${where}, and ${lowerMiss} on the lower side (cap_shape "ball"), where "${j.part}"'s layer is transparent and no cap image gives a pixel`;
2756
2768
  const half = j.half ?? 0;
2757
2769
  const disc =
2758
- k.shape === 'disc' || j.shortInHalf === undefined
2770
+ k.shape !== undefined || j.shortInHalf === undefined
2759
2771
  ? ''
2760
2772
  : j.shortInHalf === 0
2761
2773
  ? `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and none of them lies within it`
2762
2774
  : `; under cap_shape "disc" the disc is the half-width about the joint, ${half} px, and ${j.shortInHalf} of them lie within it`;
2763
2775
  return (
2764
2776
  ` LINT "${j.part}" cap at [${k.at[0]}, ${k.at[1]}] (limb "${j.limb}", joint "${j.joint}", radius ${k.radius} px): short_px left ${k.short_px.left}, right ${k.short_px.right}: ` +
2765
- `no layer gives them — ${n} px of the disc on the upper side of the cut, where ${where}; the rest of the disc is filled, ${filled}${disc}`
2777
+ `no layer gives them — ${which}; the rest of the disc is filled, ${filled}${disc}`
2766
2778
  );
2767
2779
  }
2768
2780
 
@@ -2784,15 +2796,21 @@ export function limbLines(counts: readonly LimbCount[]): string[] {
2784
2796
  const radius =
2785
2797
  k.shape === undefined
2786
2798
  ? `a disc of radius ${k.radius} px (the limb ${k.width} px across the joint line)`
2787
- : `a disc of radius ${k.radius} px (cap_shape "disc": the joint's distance to the nearer side of the limb, ${k.width} px across the joint line)`;
2799
+ : `a disc of radius ${k.radius} px (cap_shape "${k.shape}": the joint's distance to the nearer side of the limb, ${k.width} px across the joint line)`;
2800
+ // Issue #579: the ball's lower half, counted apart; the missing pixels the line names on the upper side are that side's.
2801
+ const lowerMiss = k.lower_missing_px ?? 0;
2802
+ const upperMiss = k.missing_px - lowerMiss;
2803
+ const paintThem = `paint them into a ${k.box[2]}x${k.box[3]} image whose pixel (i, j) is rig pixel (${k.box[0]} + i, ${k.box[1]} + j), and name it in the segment's "cap"`;
2788
2804
  const shaped = [
2805
+ ...(k.shape === 'ball'
2806
+ ? [
2807
+ `cap_shape "ball": on the lower side of the line ${k.lower_px ?? 0} px written into "${j.part}" from ${k.image_px === undefined ? 'a cap image (none is named)' : k.image_layer === undefined ? 'the cap image' : `the hidden-art layer ${k.image_layer}`} where its layer is transparent (alpha 0), ${k.lower_kept_px ?? 0} px left as painted, ${lowerMiss === 0 ? 'none missing' : `${lowerMiss} px missing — the layer is transparent there and no cap image gives a pixel, and the tool invents none: ${paintThem}`}`,
2808
+ ]
2809
+ : []),
2789
2810
  ...(k.edge === undefined ? [] : [`edge "feather": ${k.feathered_px ?? 0} px of "${j.upper}" faded across the ${k.feather_radius ?? 0} px about the joint that "${j.part}" covers at every turn`]),
2790
2811
  ...(k.cut_band === undefined ? [] : [cutPhrase(k, j.upper, j.part)]),
2791
2812
  ];
2792
- const miss =
2793
- k.missing_px === 0
2794
- ? 'none missing'
2795
- : `${k.missing_px} px missing — the layer has no pixel there (hidden in the painting, or past the limb's outline), and the tool invents none: paint them into a ${k.box[2]}x${k.box[3]} image whose pixel (i, j) is rig pixel (${k.box[0]} + i, ${k.box[1]} + j), and name it in the segment's "cap"`;
2813
+ const miss = upperMiss === 0 ? 'none missing' : `${upperMiss} px missing — the layer has no pixel there (hidden in the painting, or past the limb's outline), and the tool invents none: ${paintThem}`;
2796
2814
  out.push(
2797
2815
  ` limb cap: "${j.limb}" joint "${j.joint}" at [${k.at[0]}, ${k.at[1]}], on "${j.part}": ${radius}, box [${k.box.join(', ')}] — on the upper side of the line ${from}, ${miss}${shaped.map((q) => `; ${q}`).join('')}`,
2798
2816
  );
@@ -2838,6 +2856,108 @@ function shiftedAt(line: JointLine, offset: number): [number, number] {
2838
2856
  return [pyRound(line.at[0] + offset * line.axis[0], 3), pyRound(line.at[1] + offset * line.axis[1], 3)];
2839
2857
  }
2840
2858
 
2859
+ /**
2860
+ * Issue #564: where an `assemble.cuts` entry from a part a limb takes lies
2861
+ * against that limb. The segments of a limb that take the part are a run
2862
+ * `k0 .. k1` (`CONFIG_LIMB_FROM_RUN` keeps them consecutive), and the run's
2863
+ * pixels lie between two joint lines: the line of the joint above `k0` when
2864
+ * `k0` sits below one (a joint between two layers), and the line of the joint
2865
+ * below `k1` when a segment follows it (the ankle under a shin that takes the
2866
+ * legwear). A pixel the cut takes (alpha above 0 in its piece) is outside the
2867
+ * run when it lies past the lower line, or not past the upper line and — read
2868
+ * after the limbs are cut, with `caps` — outside the disc of that joint's cap,
2869
+ * which the run's own layer fills there first. Anything else lies in a
2870
+ * segment's band, and the cut is refused: the pixels would leave a segment
2871
+ * that holds them, and the bend would open where the layer was cut. Every
2872
+ * limb taking the part is read. `past` is the segment a taken pixel lies in
2873
+ * when every one lies past the lower line — the one below that joint, or
2874
+ * below the deepest joint line all of them are past — and is what the `cut:`
2875
+ * line names. Without `caps` the lines alone are read; with them only the
2876
+ * discs, for the pixels the lines let through.
2877
+ */
2878
+ function limbBands(
2879
+ cuts: readonly Cut[],
2880
+ pieces: ReadonlyArray<Built | null>,
2881
+ limbs: Readonly<Record<string, Limb>>,
2882
+ bones: readonly BoneEntry[],
2883
+ W: number,
2884
+ H: number,
2885
+ caps: ((limb: string, segment: number) => CapRecord | undefined) | null,
2886
+ ): { problems: Problem[]; past: Map<number, { limb: string; joint: string; part: string; bone: string }> } {
2887
+ const problems: Problem[] = [];
2888
+ const past = new Map<number, { limb: string; joint: string; part: string; bone: string }>();
2889
+ const places = bonePlaces(bones);
2890
+ const lineAbove = (l: string, k: number): JointLine | null => {
2891
+ const segs = limbs[l].segments;
2892
+ const up = places.get(segs[k - 1].bone);
2893
+ const me = places.get(segs[k].bone);
2894
+ if (up === undefined || me === undefined) return null;
2895
+ const end = me.end ?? (k + 1 < segs.length ? (places.get(segs[k + 1].bone)?.at ?? null) : null);
2896
+ return jointLine(up.at, me.at, end);
2897
+ };
2898
+ const fmt = (q: readonly number[]): string => `[${q.map((n) => pyRound(n, 3)).join(', ')}]`;
2899
+ cuts.forEach((q, i) => {
2900
+ const piece = pieces[i];
2901
+ if (piece === null) return;
2902
+ const taken: number[] = [];
2903
+ for (let p = 0; p < W * H; p++) if (piece.r.data[p * 4 + 3] > 0) taken.push(p);
2904
+ for (const l of Object.keys(limbs)) {
2905
+ const segs = limbs[l].segments;
2906
+ const k0 = segs.findIndex((sg) => sg.from === q.from);
2907
+ if (k0 < 0) continue;
2908
+ let k1 = k0;
2909
+ while (k1 + 1 < segs.length && segs[k1 + 1].from === q.from) k1++;
2910
+ const upper = k0 > 0 ? lineAbove(l, k0) : null;
2911
+ const lower = k1 + 1 < segs.length ? lineAbove(l, k1 + 1) : null;
2912
+ // A joint with no line is ASSEMBLE_LIMB_JOINT, refused by cutLimbs by name; nothing is read about it here.
2913
+ if ((k0 > 0 && upper === null) || (k1 + 1 < segs.length && lower === null)) continue;
2914
+ const cap = caps === null || upper === null ? undefined : caps(l, k0);
2915
+ const inside: number[] = [];
2916
+ let below = 0;
2917
+ for (const p of taken) {
2918
+ const x = p % W;
2919
+ const y = Math.floor(p / W);
2920
+ if (lower !== null && pastJoint(lower, x, y)) {
2921
+ below++;
2922
+ continue;
2923
+ }
2924
+ if (upper !== null && !pastJoint(upper, x, y)) {
2925
+ if (caps === null || cap === undefined || !inDisc(cap.at, cap.radius, x, y)) continue;
2926
+ } else if (caps !== null) continue;
2927
+ inside.push(p);
2928
+ }
2929
+ const object = `config.assemble.cuts[${i}] (part "${q.into}")`;
2930
+ const wanted = [
2931
+ ...(lower === null ? [] : [`past joint "${String(segs[k1 + 1].joint)}"'s line (through ${fmt(lower.at)}, axis ${fmt(lower.axis)})`]),
2932
+ ...(upper === null ? [] : [`before joint "${String(segs[k0].joint)}"'s line (through ${fmt(upper.at)}, axis ${fmt(upper.axis)})${cap === undefined ? '' : ` and outside its cap's disc, radius ${cap.radius} px about ${fmt(cap.at)}`}`]),
2933
+ ];
2934
+ if (inside.length > 0) {
2935
+ const f = inside[0];
2936
+ const fx = f % W;
2937
+ const fy = Math.floor(f / W);
2938
+ let k = k0;
2939
+ if (caps === null) {
2940
+ for (let ln = k < k1 ? lineAbove(l, k + 1) : null; ln !== null && pastJoint(ln, fx, fy); ln = k < k1 ? lineAbove(l, k + 1) : null) k++;
2941
+ }
2942
+ const band =
2943
+ caps !== null
2944
+ ? `the cap of joint "${String(segs[k0].joint)}" on "${segs[k0].part}" (radius ${(cap as CapRecord).radius} px about ${fmt((cap as CapRecord).at)}), which "${q.from}"'s pixels fill there`
2945
+ : `the band of "${segs[k].part}"${k > 0 ? ` below joint "${String(segs[k].joint)}"` : ''}${k + 1 < segs.length ? `${k > 0 ? ' and' : ''} above joint "${String(segs[k + 1].joint)}"` : ' to the limb\'s end'}`;
2946
+ problems.push({
2947
+ code: 'ASSEMBLE_CUT_CROSSES_LIMB',
2948
+ object,
2949
+ detail: `takes ${inside.length} of its ${taken.length} pixel(s) of "${q.from}" inside limb "${l}", the first at ${fx},${fy}, in ${band}; "${q.from}" is the layer config.limbs.${l} cuts at its joints, and a cut from it may lie only where no segment of the limb holds it — every pixel it takes ${wanted.length === 0 ? `outside the limb, and the limb has no joint before or past its segments that take "${q.from}" (they are all of it), so no pixel is` : wanted.join(', or ')} is required: move the polygon, or give the pixels to a segment of the limb instead`,
2950
+ });
2951
+ } else if (caps === null && lower !== null && below === taken.length && taken.length > 0) {
2952
+ let j = k1 + 1;
2953
+ for (let ln = j + 1 < segs.length ? lineAbove(l, j + 1) : null; ln !== null && taken.every((p) => pastJoint(ln as JointLine, p % W, Math.floor(p / W))); ln = j + 1 < segs.length ? lineAbove(l, j + 1) : null) j++;
2954
+ if (!past.has(i)) past.set(i, { limb: l, joint: String(segs[j].joint), part: segs[j].part, bone: segs[j].bone });
2955
+ }
2956
+ }
2957
+ });
2958
+ return { problems, past };
2959
+ }
2960
+
2841
2961
  /**
2842
2962
  * Cut every declared limb (module comment of `src/limbs.ts`): each part a limb
2843
2963
  * takes is split among the limbs that take it (nearest polyline), then each
@@ -3056,13 +3176,15 @@ function cutLimbs(
3056
3176
  // The width to 3 places (src/round.ts): a measured length, and a radius the line and the record print as read.
3057
3177
  const w3 = pyRound(run[1] - run[0] + 1, 3);
3058
3178
  // Issue #360: under cap_shape "disc" the radius is the half-width about the joint (src/limbs.ts), to 3 places as well.
3059
- const disc = sg.cap_shape === 'disc';
3179
+ // Issue #579: cap_shape "ball" is that disc and its upper half, and its lower half too (below).
3180
+ const ball = sg.cap_shape === 'ball';
3181
+ const disc = sg.cap_shape === 'disc' || ball;
3060
3182
  const half = halfWidthAbout(run);
3061
3183
  if (disc && half <= 0) {
3062
3184
  problems.push({
3063
3185
  code: 'ASSEMBLE_LIMB_JOINT_ON_ART',
3064
3186
  object,
3065
- detail: `the joint, "${sg.bone}"'s origin at [${line.at.join(', ')}], lies on the edge of the limb's art along its joint line — the run of art reaches ${pyRound(run[1] + 0.5, 3)} px from it one way and ${pyRound(0.5 - run[0], 3)} px the other — so cap_shape "disc" has no half-width about it; a bone origin inside the limb's art is required — move the bone onto the joint`,
3187
+ detail: `the joint, "${sg.bone}"'s origin at [${line.at.join(', ')}], lies on the edge of the limb's art along its joint line — the run of art reaches ${pyRound(run[1] + 0.5, 3)} px from it one way and ${pyRound(0.5 - run[0], 3)} px the other — so cap_shape "${String(sg.cap_shape)}" has no half-width about it; a bone origin inside the limb's art is required — move the bone onto the joint`,
3066
3188
  });
3067
3189
  return;
3068
3190
  }
@@ -3105,11 +3227,32 @@ function cutLimbs(
3105
3227
  let shortLeft = 0;
3106
3228
  let shortRight = 0;
3107
3229
  let shortInHalf = 0;
3230
+ // Issue #579: the ball's lower half — written from the image where the lower piece's pixel is transparent, kept
3231
+ // where the piece has a pixel, missing where neither gives one.
3232
+ let lowerPx = 0;
3233
+ let lowerKept = 0;
3234
+ let lowerMissing = 0;
3108
3235
  for (let y = Math.max(0, box[1]); y < Math.min(H, box[1] + box[3]); y++) {
3109
3236
  for (let x = Math.max(0, box[0]); x < Math.min(W, box[0] + box[2]); x++) {
3110
- if (!inDisc(line.at, radius, x, y) || pastJoint(cut, x, y)) continue;
3237
+ if (!inDisc(line.at, radius, x, y)) continue;
3111
3238
  const p = y * W + x;
3112
3239
  const u = img === null ? -1 : ((y - box[1]) * img.width + (x - box[0])) * 4;
3240
+ if (pastJoint(cut, x, y)) {
3241
+ if (!ball) continue;
3242
+ // Transparent is alpha 0, the reading the upper half's fill gives a layer's and the image's pixel: no pixel the
3243
+ // lower piece paints, however faint, changes.
3244
+ if (lower.data[p * 4 + 3] > 0) lowerKept++;
3245
+ else if (img !== null && img.data[u + 3] > 0) {
3246
+ lower.data.set(img.data.subarray(u, u + 4), p * 4);
3247
+ lowerPx++;
3248
+ } else {
3249
+ lowerMissing++;
3250
+ missing++;
3251
+ if (jointOffsets(line, x, y).across >= 0) shortLeft++;
3252
+ else shortRight++;
3253
+ }
3254
+ continue;
3255
+ }
3113
3256
  if (img !== null && img.data[u + 3] > 0) {
3114
3257
  lower.data.set(img.data.subarray(u, u + 4), p * 4);
3115
3258
  imagePx++;
@@ -3130,8 +3273,14 @@ function cutLimbs(
3130
3273
  }
3131
3274
  }
3132
3275
  }
3133
- if (img !== null && imagePx === 0 && hidden === null) {
3134
- problems.push({ code: 'ASSEMBLE_LIMB_CAP_EMPTY', object: `${object}.cap`, detail: `${String(sg.cap)} is transparent over every one of the cap's pixels; an image that gives at least one is required — to keep the layer's cap, drop cap` });
3276
+ if (img !== null && imagePx + lowerPx === 0 && hidden === null) {
3277
+ problems.push({
3278
+ code: 'ASSEMBLE_LIMB_CAP_EMPTY',
3279
+ object: `${object}.cap`,
3280
+ detail: ball
3281
+ ? `${String(sg.cap)} gives none of the cap's pixels: it is transparent over the disc's upper half and over every pixel of its lower half where "${sg.part}"'s layer is transparent (cap_shape "ball", issue #579); an image that gives at least one is required — to keep the layer's cap, drop cap`
3282
+ : `${String(sg.cap)} is transparent over every one of the cap's pixels; an image that gives at least one is required — to keep the layer's cap, drop cap`,
3283
+ });
3135
3284
  return;
3136
3285
  }
3137
3286
  // Issue #360: under edge "feather", the upper piece fades out across the cap, over the lower's opaque pixels only.
@@ -3173,7 +3322,13 @@ function cutLimbs(
3173
3322
  ...(hidden === null ? {} : { image_layer: hidden.layer }),
3174
3323
  missing_px: missing,
3175
3324
  ...(missing === 0 ? {} : { short_px: { left: shortLeft, right: shortRight } }),
3176
- ...(disc ? { shape: 'disc' as const, upper_px: upperPx } : upperPx === 0 ? {} : { upper_px: upperPx }),
3325
+ ...(ball
3326
+ ? { shape: 'ball' as const, upper_px: upperPx, lower_px: lowerPx, lower_kept_px: lowerKept, lower_missing_px: lowerMissing }
3327
+ : disc
3328
+ ? { shape: 'disc' as const, upper_px: upperPx }
3329
+ : upperPx === 0
3330
+ ? {}
3331
+ : { upper_px: upperPx }),
3177
3332
  ...(sg.edge === 'feather' ? { edge: 'feather' as const, feather_radius: band, feathered_px: featheredPx } : {}),
3178
3333
  ...(placed === undefined
3179
3334
  ? {}
@@ -3719,6 +3874,15 @@ export function assemble(input: AssembleInput): AssembleResult {
3719
3874
  // In cut order, as the config lists them.
3720
3875
  cutCounts.sort((a, b) => cuts.findIndex((q) => q.into === a.into) - cuts.findIndex((q) => q.into === b.into));
3721
3876
 
3877
+ // Issue #564: a cut from a part a limb takes lies outside the limb's segments, read before the limbs are cut.
3878
+ const bands = input.limbs === undefined || cuts.length === 0 ? null : limbBands(cuts, pieces, input.limbs, input.bones ?? [], W, H, null);
3879
+ if (bands !== null) {
3880
+ refuseIfAny(bands.problems);
3881
+ for (const [i, at] of bands.past) {
3882
+ const c = cutCounts.find((q) => q.into === cuts[i].into);
3883
+ if (c !== undefined) c.limb = at;
3884
+ }
3885
+ }
3722
3886
  // Issue #349: the limbs, after the cuts (a limb may take a cut's piece, and a cut's under image fills its base first).
3723
3887
  const lim = cutLimbs(input.limbs ?? {}, input.bones ?? [], input.caps ?? new Map(), W, H, (name) => {
3724
3888
  const pi = plan.findIndex((e) => e[0] === name);
@@ -3726,6 +3890,8 @@ export function assemble(input: AssembleInput): AssembleResult {
3726
3890
  const ci = cuts.findIndex((q) => q.into === name);
3727
3891
  return ci >= 0 ? pieces[ci] : null;
3728
3892
  }, opaqueOf, mergedIn, count, (name) => hiddenArt.get(name) ?? null, (layer, by) => hiddenUses.get(layer)?.push(by));
3893
+ // Issue #564: and the cap a run's own layer fills above its upper joint, read once the limbs are cut.
3894
+ if (bands !== null) refuseIfAny(limbBands(cuts, pieces, input.limbs ?? {}, input.bones ?? [], W, H, (l, k) => lim.parts.find((q) => q.limb === l && q.segment === k)?.record.cap).problems);
3729
3895
  const limbPieces = lim.pieces;
3730
3896
  const order = limbOrder(order0, plan, cuts, lim.parts);
3731
3897
  const pieceAt = (d: { plan: number } | { cut: number } | { limb: number }): { name: string; b: Built } =>
package/src/build.ts CHANGED
@@ -1146,21 +1146,39 @@ function multiIntervalRun(
1146
1146
  * the gate is green — and, for every automatic mesh, only when its motion gate
1147
1147
  * accepted it (issue #126 item 3; {@link motionGates}).
1148
1148
  */
1149
- export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log): RigOutput {
1150
- const { config: cfg, animations: from } = loadConfigAndAnimations(input.config);
1151
- const parts = readParts(join(input.parts, 'parts.json'));
1149
+ /** What the rig stage reads before it builds anything: the config with its `animations_from` table, parts.json, and each part's PNG (and each alternate set's) that exists. */
1150
+ export interface RigInputs {
1151
+ cfg: ReturnType<typeof loadConfigAndAnimations>['config'];
1152
+ from: ReturnType<typeof loadConfigAndAnimations>['animations'];
1153
+ parts: ReturnType<typeof readParts>;
1154
+ images: Map<string, Raster>;
1155
+ }
1156
+
1157
+ /**
1158
+ * The rig stage's inputs, read as {@link rigStage} reads them: `rigStage` and `mesh-stats` (issue #566,
1159
+ * `src/meshstats.ts`) both start here, so the two read the same config, the same parts and the same images, and a
1160
+ * PNG that is missing is left out of the map for `buildRig` to refuse by name (`RIG_PNG_PRESENT`).
1161
+ */
1162
+ export function readRigInputs(config: string, partsDir: string): RigInputs {
1163
+ const { config: cfg, animations: from } = loadConfigAndAnimations(config);
1164
+ const parts = readParts(join(partsDir, 'parts.json'));
1152
1165
  const images = new Map<string, Raster>();
1153
1166
  for (const p of parts.parts) {
1154
- const png = join(input.parts, 'parts', `${p.name}.png`);
1167
+ const png = join(partsDir, 'parts', `${p.name}.png`);
1155
1168
  if (existsSync(png)) images.set(p.name, readPng(png));
1156
1169
  }
1157
1170
  for (const alt of parts.alternates ?? []) {
1158
1171
  for (const p of alt.records) {
1159
1172
  const attName = `${alt.name}_${p.name}`;
1160
- const png = join(input.parts, 'parts', `${attName}.png`);
1173
+ const png = join(partsDir, 'parts', `${attName}.png`);
1161
1174
  if (existsSync(png)) images.set(attName, readPng(png));
1162
1175
  }
1163
1176
  }
1177
+ return { cfg, from, parts, images };
1178
+ }
1179
+
1180
+ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string, log: Log): RigOutput {
1181
+ const { cfg, from, parts, images } = readRigInputs(input.config, input.parts);
1164
1182
  const first = buildRig(cfg, parts, images, undefined, input.idleKeys ?? DEFAULT_IDLE_KEYS, input.reduce);
1165
1183
  const textsOf = (r: RigOutput): Array<[string, string]> => {
1166
1184
  const mergedMotion = withAnimations(r.motion, from === null ? null : from.table);