@rig-c/parts 1.16.0 → 1.18.0

package/src/paintcheck.ts

@@ -0,0 +1,250 @@
+/**
+ * `rig-parts painting`: what a painting must be before See-through runs on it,
+ * read off the painting and its body-18 joints alone (issue #350).
+ *
+ * A painting with the arms against the body, the hands together or the legs
+ * painted as one column is found today at the far end of the pipeline — a
+ * sleeve layer that holds the torso, a leg chain that drags the other leg, a
+ * dance clip that tears. Every one of those is decidable at minute one from two
+ * things: where the figure is (the painting's pixels) and where its joints are
+ * (the keypoint file `propose --keypoints` reads, `src/keypoints.ts`). This
+ * module decides them, and `docs/PAINTING.md` says why each one matters.
+ *
+ * **Definitions, each one a sentence and no tuned number:**
+ *
+ * - **Ground** is a pixel the repository already calls background: alpha at or
+ *   below {@link OPAQUE_ALPHA_ABOVE} (not painted, `src/layers.ts`), or every
+ *   colour channel above {@link NEAR_WHITE_MIN} (near-white, the one test the
+ *   assemble stage and the layer plausibility figures share).
+ * - **The background** is the ground that reaches the image's edge: every
+ *   ground pixel 4-connected to a ground pixel on the border. A white highlight
+ *   inside the figure is ground and not background, because line art closes it
+ *   off; so a blouse that is white does not read as a hole in the figure.
+ * - **The figure** is every pixel that is not background.
+ * - **A gap between two joints** is at least one background pixel on the
+ *   straight line between them, sampled at `n + 1` evenly spaced points with
+ *   `n = max(ceil(max(|dx|, |dy|)), 1)` — at least one point per pixel crossed
+ *   — each read at the pixel that holds it (floor, the image's right and bottom
+ *   edges taken as the last column and row).
+ *
+ * **The rules, each a refusal by name:**
+ *
+ * - `PAINTING_BACKGROUND_PLAIN` — every border pixel is ground. A plain light
+ *   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.
+ * - `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
+ *   together: clasped, or touching.
+ * - `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.
+ *
+ * Pure: the caller reads the files and hands over a raster and a person.
+ */
+import type { Problem } from './errors.ts';
+import type { KeypointPerson } from './keypoints.ts';
+import { NEAR_WHITE_MIN, OPAQUE_ALPHA_ABOVE } from './layers.ts';
+import type { Raster } from './raster/types.ts';
+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 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)'],
+  ['PAINTING_ARM_CLEAR', 'l_wrist', 'l_hip', 'left arm (l_wrist to l_hip)'],
+  ['PAINTING_HANDS_APART', 'r_wrist', 'l_wrist', 'hands (r_wrist to l_wrist)'],
+  ['PAINTING_LEGS_APART', 'r_knee', 'l_knee', 'knees (r_knee to l_knee)'],
+  ['PAINTING_LEGS_APART', 'r_ankle', 'l_ankle', 'ankles (r_ankle to l_ankle)'],
+];
+
+/** What each gap rule requires, in the words its refusal ends with. */
+const GAP_REQUIRED: Readonly<Record<string, string>> = {
+  PAINTING_ARM_CLEAR: 'the arm painted clear of the body, so the line from the wrist to the hip of its side crosses background',
+  PAINTING_HANDS_APART: 'the hands painted apart, so the line between the wrists crosses background',
+  PAINTING_LEGS_APART: 'the legs painted apart, so the line between the two joints crosses background',
+};
+
+/** One gap reading: the pair, the line's length and samples, and how many of them are background. */
+export interface GapReading {
+  rule: string;
+  a: KeypointName;
+  b: KeypointName;
+  what: string;
+  from: [number, number];
+  to: [number, number];
+  samples: number;
+  background: number;
+}
+
+export interface PaintingReading {
+  width: number;
+  height: number;
+  /** Pixels on the border, counted once each. */
+  border: number;
+  /** Border pixels that are not ground, and the first one in raster order. */
+  borderNotGround: number;
+  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. */
+  gaps: GapReading[];
+}
+
+/** Whether pixel `i` of `r` is ground: not painted, or near-white in every channel. */
+function isGround(r: Raster, i: number): boolean {
+  const d = r.data;
+  const o = i * 4;
+  return d[o + 3] <= OPAQUE_ALPHA_ABOVE || (d[o] > NEAR_WHITE_MIN && d[o + 1] > NEAR_WHITE_MIN && d[o + 2] > NEAR_WHITE_MIN);
+}
+
+/** The background: every ground pixel 4-connected to a ground pixel on the border. One byte per pixel, 1 = background. */
+export function backgroundMask(r: Raster): Uint8Array {
+  const { width: w, height: h } = r;
+  const bg = new Uint8Array(w * h);
+  const stack: number[] = [];
+  const seed = (i: number): void => {
+    if (bg[i] === 0 && isGround(r, i)) {
+      bg[i] = 1;
+      stack.push(i);
+    }
+  };
+  for (let x = 0; x < w; x++) {
+    seed(x);
+    seed((h - 1) * w + x);
+  }
+  for (let y = 0; y < h; y++) {
+    seed(y * w);
+    seed(y * w + w - 1);
+  }
+  while (stack.length > 0) {
+    const i = stack.pop() as number;
+    const x = i % w;
+    const y = (i - x) / w;
+    if (x > 0) seed(i - 1);
+    if (x < w - 1) seed(i + 1);
+    if (y > 0) seed(i - w);
+    if (y < h - 1) seed(i + w);
+  }
+  return bg;
+}
+
+/** The pixel holding a continuous painting point: floor, the right and bottom edges taken as the last column and row. */
+export function pixelOf(at: readonly [number, number], w: number, h: number): [number, number] {
+  return [Math.min(Math.floor(at[0]), w - 1), Math.min(Math.floor(at[1]), h - 1)];
+}
+
+/** The pixels the line from `a` to `b` is sampled at: `n + 1` evenly spaced points, `n = max(ceil(max(|dx|, |dy|)), 1)`. */
+export function linePixels(a: readonly [number, number], b: readonly [number, number], w: number, h: number): Array<[number, number]> {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const n = Math.max(Math.ceil(Math.max(Math.abs(dx), Math.abs(dy))), 1);
+  const out: Array<[number, number]> = [];
+  for (let i = 0; i <= n; i++) out.push(pixelOf([a[0] + (dx * i) / n, a[1] + (dy * i) / n], w, h));
+  return out;
+}
+
+/** 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 {
+  const { width: w, height: h } = r;
+  const bg = backgroundMask(r);
+  let border = 0;
+  let borderNotGround = 0;
+  let firstBorderNotGround: [number, number] | null = null;
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (y !== 0 && y !== h - 1 && x !== 0 && x !== w - 1) continue;
+      border++;
+      if (!isGround(r, y * w + x)) {
+        borderNotGround++;
+        firstBorderNotGround ??= [x, y];
+      }
+    }
+  }
+  let backgroundPx = 0;
+  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;
+    const pixel = pixelOf(j.at, w, h);
+    joints.push({ name, 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;
+    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 };
+}
+
+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[] {
+  const problems: Problem[] = [];
+  if (reading.borderNotGround > 0) {
+    const f = reading.firstBorderNotGround as [number, number];
+    problems.push({
+      code: 'PAINTING_BACKGROUND_PLAIN',
+      object: `painting ${painting}`,
+      detail: `${reading.borderNotGround} of its ${reading.border} border pixels are not background-coloured, the first at ${pt(f)}; every border pixel near-white (each channel above ${NEAR_WHITE_MIN}) or unpainted (alpha ${OPAQUE_ALPHA_ABOVE} or less) is required — a plain light background, with the whole figure inside the frame`,
+    });
+  }
+  for (const n of PAINTING_JOINTS) {
+    const j = person.joints[n];
+    if (j.state === 'observed' && j.at !== null) continue;
+    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`,
+    });
+  }
+  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 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`,
+    });
+  }
+  for (const g of reading.gaps) {
+    if (g.background > 0) continue;
+    problems.push({
+      code: g.rule,
+      object: `painting ${painting} ${g.what}`,
+      detail: `the line from ${pt(g.from)} to ${pt(g.to)} crosses no background: 0 of its ${g.samples} sampled pixels; ${GAP_REQUIRED[g.rule]}`,
+    });
+  }
+  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[] {
+  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`,
+  ];
+  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`);
+  return out;
+}
+
+/** 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) };
+}

package/src/parts.ts

@@ -42,7 +42,10 @@
  * cut from, which shares its `from`. The record is in draw order, and a piece
  * drawn `"back"` comes before its base, so order cannot say which of two parts
  * sharing a layer is the piece; this field does. A `parts.json` written before
- * 1.6.0 has none, and still reads.
+ * 1.6.0 has none, and still reads. `limb`, written only on a part a
+ * `config.limbs` segment made (issue #349), names the limb, the segment's
+ * index (0 the upper), the part it was cut from (`of`), the one bone it rides
+ * and, below a joint, the joint and its cap ({@link LimbRecord}).
  *
  * ⭐ **A patch is 100 % source.** Every pixel of a `painting:` part is the
  * painting's own, so it is all visible (the painting shows it; nothing of it
@@ -59,6 +62,10 @@
  * per source-painting pixel, and `ghost_px` the sub-threshold specks removed
  * from each `<run>:<tag>` layer before anything else.
  *
+ * `single_run_pad` (issue #366), written only for one run whose file is not
+ * the `seethrough.resolution` square, says where the file sat on the run's
+ * square ({@link SingleRunPad}); the rig itself holds no pad.
+ *
  * `recomposite` is the flat stack of every part against the painting (this
  * port's, issue #25; a `parts.json` the reference wrote has none and reads as
  * it did): the four figures the assemble summary prints, the limits they were
@@ -104,6 +111,51 @@ export interface PartRecord {
   seam_override_px: number;
   /** Absent when the part had no fringe pushed back (and in a `parts.json` the reference wrote). */
   fringe_pushed_back?: Array<{ part: string; px: number }>;
+  /** Written only on a part a `config.limbs` segment made (issue #349). */
+  limb?: LimbRecord;
+}
+
+/**
+ * A limb segment's provenance (issue #349): the limb, the segment's index
+ * (0 the upper), the part its pixels were cut from (`of`), the bone it rides
+ * with weight 1, and, on a segment below a joint, the joint's name and its cap.
+ */
+export interface LimbRecord {
+  name: string;
+  segment: number;
+  of: string;
+  bone: string;
+  joint?: string;
+  cap?: CapRecord;
+}
+
+/**
+ * The cap a lower segment carries past its joint (issue #349): the disc's
+ * centre (the joint, rig px), its radius (half the limb's width across the
+ * joint line, `width`), the box its image covers `[x, y, w, h]`, and its
+ * pixels on the upper side of the joint line counted by where each came from
+ * — the layer (`layer_px`), the config's cap image (`image_px`, only with one)
+ * — or none (`missing_px`: no pixel in the layer and none in an image).
+ */
+export interface CapRecord {
+  at: [number, number];
+  width: number;
+  radius: number;
+  box: [number, number, number, number];
+  layer_px: number;
+  image_px?: number;
+  /** Issue #359: with `image_px`, the hidden-art layer the cap's image came from (`<run>:<layer>:hidden`), when it came from one rather than the config's cap file. */
+  image_layer?: string;
+  missing_px: number;
+}
+
+const LIMB_KEYS = ['name', 'segment', 'of', 'bone', 'joint', 'cap'] as const;
+const CAP_KEYS = ['at', 'width', 'radius', 'box', 'layer_px', 'image_px', 'image_layer', 'missing_px'] as const;
+
+/** The limb record with its keys in the fixed order, so two runs write the same bytes. */
+function orderedLimb(l: LimbRecord): Record<string, unknown> {
+  const cap = l.cap === undefined ? undefined : Object.fromEntries(CAP_KEYS.filter((k) => (l.cap as CapRecord)[k] !== undefined).map((k) => [k, (l.cap as CapRecord)[k]]));
+  return Object.fromEntries(LIMB_KEYS.filter((k) => (k === 'cap' ? cap : l[k]) !== undefined).map((k) => [k, k === 'cap' ? cap : l[k]]));
 }
 
 /** One listed hole: its area, its box in rig pixels, and the parts beside it (`src/assemble.ts` `uncoveredHoles`). */
@@ -138,6 +190,27 @@ export interface PartsFile {
   recomposite?: RecompositeRecord;
   /** Written only under `config.scene` (issue #242): the recomposite was read inside this figure; absent otherwise. */
   scene?: SceneRecord;
+  /** Written only for one run whose file is not the resolution square (issue #366): where the file sat on the run's square; absent otherwise. */
+  single_run_pad?: SingleRunPad;
+}
+
+/**
+ * `parts.json`'s `single_run_pad` block (issue #366): one run (no `--head`)
+ * whose file — the artist's PSD or its wrapper export — is not the
+ * `seethrough.resolution` square was padded to it, centred, before it was
+ * read: `file_size` is the file's `[w, h]` (and the painting's), `side` the
+ * square's, `left` and `top` the margins (`floor((side - w) / 2)` and
+ * `floor((side - h) / 2)`, `squarePad`'s centring; the right and the bottom
+ * take the remainder). Run pixel `(x, y)` is file pixel `(x - left, y - top)`,
+ * and the rig is the file times `scale_rig_per_source` with no pad in it, so a
+ * part's box over the scale is its box in the file. Absent for two runs and
+ * for a file that is the square, whose run pixel is its file pixel.
+ */
+export interface SingleRunPad {
+  file_size: [number, number];
+  side: number;
+  left: number;
+  top: number;
 }
 
 /**
@@ -153,8 +226,9 @@ export interface SceneRecord {
   figure_mask: string;
 }
 
-const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene'] as const;
-const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene');
+const TOP_KEYS = ['rig_size', 'scale_rig_per_source', 'parts', 'ghost_px', 'recomposite', 'scene', 'single_run_pad'] as const;
+const REQUIRED_TOP_KEYS = TOP_KEYS.filter((k) => k !== 'recomposite' && k !== 'scene' && k !== 'single_run_pad');
+export const SINGLE_RUN_PAD_KEYS = ['file_size', 'side', 'left', 'top'] as const;
 export const SCENE_KEYS = ['figure_alpha_above', 'figure_px', 'figure_mask'] as const;
 export const RECOMPOSITE_KEYS = ['mean_abs', 'within_limit', 'within_share', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed', 'holes'] as const;
 const RECOMPOSITE_COUNTS = ['within_limit', 'error_limit', 'error_px', 'covered_alpha', 'uncovered_error_px', 'hole_count', 'holes_listed'] as const;
@@ -178,15 +252,18 @@ export const PART_KEYS = [
   'merged_px',
   'seam_override_px',
   'fringe_pushed_back',
+  'limb',
 ] as const;
 /** The one part field that is not a count: a list of `{part, px}`, written only when it is not empty. */
 const FRINGE_KEY = 'fringe_pushed_back';
 /** The one part field that names another part: a cut's piece names its base, written only on a piece. */
 const CUT_FROM_KEY = 'cut_from';
-const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY) as ReadonlyArray<(typeof PART_KEYS)[number]>;
+/** The one part field that is a record of its own: a limb segment's provenance (issue #349), written only on one. */
+const LIMB_KEY = 'limb';
+const COUNT_KEYS = PART_KEYS.slice(2).filter((k) => k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY) as ReadonlyArray<(typeof PART_KEYS)[number]>;
 /** The port's own counts: all three or none (none = a record the reference wrote). */
 export const VISIBILITY_KEYS = ['visible_px', 'occluded_px', 'visible_not_projected_px'] as const;
-const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY);
+const REQUIRED_KEYS = PART_KEYS.filter((k) => !(VISIBILITY_KEYS as readonly string[]).includes(k) && k !== FRINGE_KEY && k !== CUT_FROM_KEY && k !== LIMB_KEY);
 
 /** Where a part came from: a See-through run and a v3 tag or an author-made layer's `author:<label>` (issue #256), or the painting itself for a patch. */
 export type From = { run: 'full' | 'head'; tag: string } | { run: 'painting'; patch: string };
@@ -214,7 +291,7 @@ export function serializeParts(file: PartsFile): string {
     rig_size: file.rig_size,
     scale_rig_per_source: file.scale_rig_per_source,
     parts: file.parts.map((p) =>
-      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : p[k]])),
+      Object.fromEntries(PART_KEYS.filter((k) => p[k] !== undefined).map((k) => [k, k === FRINGE_KEY ? (p.fringe_pushed_back ?? []).map((q) => ({ part: q.part, px: q.px })) : k === LIMB_KEY ? orderedLimb(p.limb as LimbRecord) : p[k]])),
     ),
     ghost_px: Object.fromEntries(Object.keys(file.ghost_px).sort().map((k) => [k, file.ghost_px[k]])),
     ...(file.recomposite === undefined
@@ -226,6 +303,7 @@ export function serializeParts(file: PartsFile): string {
           },
         }),
     ...(file.scene === undefined ? {} : { scene: Object.fromEntries(SCENE_KEYS.map((k) => [k, (file.scene as SceneRecord)[k]])) }),
+    ...(file.single_run_pad === undefined ? {} : { single_run_pad: Object.fromEntries(SINGLE_RUN_PAD_KEYS.map((k) => [k, (file.single_run_pad as SingleRunPad)[k]])) }),
   };
   return `${JSON.stringify(ordered, null, 2)}\n`;
 }
@@ -374,6 +452,43 @@ function checkParts(raw: unknown, path: string): PartsFile {
       else if (b.from !== r.from) fail('PARTS_CUT_FROM_KNOWN', object, `names "${base}", whose from is ${show(b.from)}; this piece's is ${show(r.from)}, and a piece shares its base's layer`);
     }
   }
+  if (Array.isArray(o.parts)) {
+    // A limb segment (issue #349) names its limb, its index, the part it was cut from, its bone, and below a joint the joint and its cap.
+    for (const p of o.parts) {
+      if (typeof p !== 'object' || p === null || Array.isArray(p) || !(LIMB_KEY in p)) continue;
+      const r = p as Record<string, unknown>;
+      const object = `part "${String(r.name)}" field "${LIMB_KEY}"`;
+      const l = r[LIMB_KEY];
+      if (typeof l !== 'object' || l === null || Array.isArray(l)) {
+        fail('PARTS_FIELD_TYPE', object, `is ${show(l)}; an object {name, segment, of, bone, joint?, cap?} is required`);
+        continue;
+      }
+      const q = l as Record<string, unknown>;
+      for (const k of Object.keys(q)) if (!(LIMB_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${object} key "${k}"`, `is not a limb field; known: ${LIMB_KEYS.join(', ')}`);
+      for (const k of ['name', 'of', 'bone'] as const) if (!(typeof q[k] === 'string' && q[k] !== '')) fail('PARTS_FIELD_TYPE', `${object} "${k}"`, `is ${show(q[k])}; a non-empty string is required`);
+      if (!isCount(q.segment)) fail('PARTS_FIELD_TYPE', `${object} "segment"`, `is ${show(q.segment)}; the segment's index, a non-negative integer, is required`);
+      const below = isCount(q.segment) && q.segment > 0;
+      if (below !== ('joint' in q) || below !== ('cap' in q)) fail('PARTS_FIELD_PRESENT', object, `segment ${show(q.segment)} with${'joint' in q ? '' : 'out'} a joint and with${'cap' in q ? '' : 'out'} a cap; a segment below a joint (index above 0) has both, the upper segment neither`);
+      if ('joint' in q && !(typeof q.joint === 'string' && q.joint !== '')) fail('PARTS_FIELD_TYPE', `${object} "joint"`, `is ${show(q.joint)}; the joint's name is required`);
+      if ('cap' in q) {
+        const c = q.cap;
+        const co = typeof c === 'object' && c !== null && !Array.isArray(c) ? (c as Record<string, unknown>) : null;
+        const pt = (v: unknown, n: number): boolean => Array.isArray(v) && v.length === n && v.every((x) => typeof x === 'number' && Number.isFinite(x));
+        const ok =
+          co !== null &&
+          Object.keys(co).every((k) => (CAP_KEYS as readonly string[]).includes(k)) &&
+          pt(co.at, 2) &&
+          typeof co.width === 'number' &&
+          typeof co.radius === 'number' &&
+          pt(co.box, 4) &&
+          isCount(co.layer_px) &&
+          isCount(co.missing_px) &&
+          (!('image_px' in co) || isCount(co.image_px)) &&
+          (!('image_layer' in co) || ('image_px' in co && typeof co.image_layer === 'string' && co.image_layer !== ''));
+        if (!ok) fail('PARTS_FIELD_TYPE', `${object} "cap"`, `is ${show(c)}; {at: [x, y], width, radius, box: [x, y, w, h], layer_px, image_px?, image_layer? (with image_px), missing_px} is required`);
+      }
+    }
+  }
   if ('scene' in o) {
     const sc = o.scene;
     if (typeof sc !== 'object' || sc === null || Array.isArray(sc)) fail('PARTS_FIELD_TYPE', `${path} field "scene"`, `is ${show(sc)}; an object is required`);
@@ -386,6 +501,7 @@ function checkParts(raw: unknown, path: string): PartsFile {
       if (!('recomposite' in o)) fail('PARTS_FIELD_PRESENT', `${path} field "recomposite"`, 'is absent; a scene block says how the recomposite block beside it was measured, so it is required with one');
     }
   }
+  if ('single_run_pad' in o) checkSingleRunPad(o.single_run_pad, path, sizeOk ? (size as [number, number]) : null, typeof scale === 'number' ? scale : null, fail);
   if ('recomposite' in o && sizeOk) {
     const names = Array.isArray(o.parts) ? new Set(o.parts.map((p) => (typeof p === 'object' && p !== null ? (p as Record<string, unknown>).name : undefined)).filter((n): n is string => typeof n === 'string')) : new Set<string>();
     checkRecomposite(o.recomposite, path, size as [number, number], names, fail);
@@ -396,6 +512,51 @@ function checkParts(raw: unknown, path: string): PartsFile {
 
 const isCount = (v: unknown): v is number => Number.isInteger(v) && (v as number) >= 0;
 
+/**
+ * The `single_run_pad` block (issue #366): every key known and present, each
+ * an integer of its kind, and the block consistent with its definition and
+ * with the rig — the margins are the centring of `file_size` on `side`
+ * (`PARTS_SINGLE_RUN_PAD`, with the margins that centring gives), no side of
+ * the file above `side`, and `rig_size` the file times `scale_rig_per_source`,
+ * truncated, as `assemble` makes it. A record that disagrees would map a part
+ * back to somewhere else in the file.
+ */
+function checkSingleRunPad(r: unknown, path: string, size: [number, number] | null, scale: number | null, fail: (code: string, object: string, detail: string) => void): void {
+  const at = `${path} field "single_run_pad"`;
+  if (typeof r !== 'object' || r === null || Array.isArray(r)) {
+    fail('PARTS_FIELD_TYPE', at, `is ${show(r)}; an object is required`);
+    return;
+  }
+  const o = r as Record<string, unknown>;
+  for (const k of Object.keys(o)) if (!(SINGLE_RUN_PAD_KEYS as readonly string[]).includes(k)) fail('PARTS_KEY_KNOWN', `${path} single_run_pad key "${k}"`, `is not a single_run_pad field; known: ${SINGLE_RUN_PAD_KEYS.join(', ')}`);
+  for (const k of SINGLE_RUN_PAD_KEYS) if (!(k in o)) fail('PARTS_FIELD_PRESENT', `${path} single_run_pad field "${k}"`, 'is absent and required');
+  const fs = o.file_size;
+  const fsOk = Array.isArray(fs) && fs.length === 2 && fs.every((n) => Number.isInteger(n) && (n as number) > 0);
+  if ('file_size' in o && !fsOk) fail('PARTS_FIELD_TYPE', `${path} single_run_pad field "file_size"`, `is ${show(fs)}; [width, height] in positive integers is required`);
+  const sideOk = Number.isInteger(o.side) && (o.side as number) > 0;
+  if ('side' in o && !sideOk) fail('PARTS_FIELD_TYPE', `${path} single_run_pad field "side"`, `is ${show(o.side)}; a positive integer is required`);
+  for (const k of ['left', 'top'] as const) if (k in o && !isCount(o[k])) fail('PARTS_FIELD_TYPE', `${path} single_run_pad field "${k}"`, `is ${show(o[k])}; a non-negative integer is required`);
+  if (!fsOk || !sideOk || !isCount(o.left) || !isCount(o.top)) return;
+  const [w, h] = fs as [number, number];
+  const side = o.side as number;
+  if (w > side || h > side) {
+    fail('PARTS_SINGLE_RUN_PAD', at, `file_size is ${w}x${h} and side ${side}; a file no side of which is above the square it was padded to is required`);
+    return;
+  }
+  if (w === side && h === side) {
+    fail('PARTS_SINGLE_RUN_PAD', at, `file_size is ${w}x${h}, the ${side} square itself; a file that is the square has no pad, and no single_run_pad is written for it`);
+    return;
+  }
+  const left = Math.floor((side - w) / 2);
+  const top = Math.floor((side - h) / 2);
+  if (o.left !== left || o.top !== top) {
+    fail('PARTS_SINGLE_RUN_PAD', at, `has left ${String(o.left)}, top ${String(o.top)}; a ${w}x${h} file centred on a ${side} square is padded left ${left}, top ${top} (each margin floors, the right and the bottom take the remainder), and those are required`);
+  }
+  if (size !== null && scale !== null && (Math.trunc(w * scale) !== size[0] || Math.trunc(h * scale) !== size[1])) {
+    fail('PARTS_SINGLE_RUN_PAD', at, `file_size ${w}x${h} times scale_rig_per_source ${scale} makes a ${Math.trunc(w * scale)}x${Math.trunc(h * scale)} rig, and rig_size is ${size[0]}x${size[1]}; the rig is the file at that scale, so they must agree`);
+  }
+}
+
 /**
  * The `recomposite` block: every key known and present, every figure its
  * type, and the counts consistent with one another — the listed holes are the