@rig-c/parts 1.17.0 → 1.19.0

package/src/paintcheck.ts

@@ -0,0 +1,277 @@
+/**
+ * `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, except that a hip may
+ *   be `occluded` with a position (issue #372). An occluded wrist is a hand the
+ *   painting does not show; an occluded hip is the honest state of a hip under
+ *   a skirt, and the arm's gap read from it is **well defined** when the hip
+ *   carries a position — which the keypoint reader holds inside the image
+ *   (`KEYPOINTS_POSITION_INSIDE`), so every sample of the wrist-to-hip line is
+ *   a pixel of the painting — and that position's pixel is figure (the next
+ *   rule). A hip with no position is still refused: there is no line to read.
+ * - `PAINTING_JOINT_ON_FIGURE` — every observed joint's pixel, and every
+ *   occluded hip's, is figure, not background. A joint off the figure is a
+ *   keypoint file for another painting, or a limb the painting does not hold
+ *   where the file says; an occluded hip on the background would also put a
+ *   background pixel at the end of the arm's line, a gap the hip's own position
+ *   makes rather than one between the arm and the body.
+ * - `PAINTING_ARM_CLEAR` — on each side, a gap between the wrist and the hip
+ *   of the same side. None is an arm painted against the body.
+ * - `PAINTING_HANDS_APART` — a gap between the two wrists. None is hands
+ *   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 joints that may be `occluded` with a position and still be read (issue #372): a skirt hides the hips on most clothed figures. */
+export const PAINTING_OCCLUDABLE: readonly KeypointName[] = ['r_hip', 'l_hip'];
+
+/** Whether the check reads joint `name` as given: observed with a position, or an occludable joint occluded with one. */
+function readable(name: KeypointName, j: KeypointPerson['joints'][KeypointName]): j is KeypointPerson['joints'][KeypointName] & { at: [number, number] } {
+  if (j.at === null) return false;
+  return j.state === 'observed' || (j.state === 'occluded' && PAINTING_OCCLUDABLE.includes(name));
+}
+
+/** The four gap rules' pairs: the rule, the two joints, and what the pair is called in a line. */
+export const PAINTING_GAPS: ReadonlyArray<readonly [string, KeypointName, KeypointName, string]> = [
+  ['PAINTING_ARM_CLEAR', 'r_wrist', 'r_hip', 'right arm (r_wrist to r_hip)'],
+  ['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 and every occluded hip with a position, its state, its pixel, and whether that pixel is figure. */
+  joints: Array<{ name: KeypointName; state: 'observed' | 'occluded'; at: [number, number]; pixel: [number, number]; onFigure: boolean }>;
+  /** The gap readings whose two joints are both read as given (observed with a position, or an occluded hip with one). */
+  gaps: GapReading[];
+}
+
+/** 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 (!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 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 });
+  }
+  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 (readable(n, j)) continue;
+    const hip = PAINTING_OCCLUDABLE.includes(n);
+    problems.push({
+      code: 'PAINTING_JOINTS_STATED',
+      object: `${keypoints} person "${person.id}" joint ${n}`,
+      detail: hip
+        ? `is ${j.listed ? j.state : 'not listed'} with no position; observed or occluded with a position is required — the arm's gap is read on the line from the wrist to this hip, and a hip with no position gives no line to read`
+        : `is ${j.listed ? j.state : 'not listed'}${j.at === null ? '' : ` at ${pt(j.at)}`}; observed with a position is required — the gap rules read ${PAINTING_JOINTS.join(', ')}, and a joint the painting does not show is a limb it cannot rig (only a hip may be occluded, with a position)`,
+    });
+  }
+  for (const j of reading.joints) {
+    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 background (ground connected to the painting's edge); a joint on the figure is required — a file measured on another painting, or a limb that is not where the file says${j.state === 'occluded' ? '; an occluded hip is read only from a point on the figure, or the arm\'s gap would be the hip\'s own background' : ''}`,
+    });
+  }
+  for (const g of reading.gaps) {
+    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;
+  const observed = reading.joints.filter((j) => j.state === 'observed').length;
+  const occluded = reading.joints.filter((j) => j.state === 'occluded').map((j) => j.name);
+  const occ = occluded.length === 0 ? '' : `, ${occluded.length} occluded with a position (${occluded.join(', ')})`;
+  out.push(`  joints: ${observed} observed${occ}, ${on} on the figure${on === reading.joints.length ? '' : ` (off: ${reading.joints.filter((j) => !j.onFigure).map((j) => j.name).join(', ')})`}`);
+  for (const g of reading.gaps) {
+    const hidden = [g.a, g.b].filter((n) => occluded.includes(n));
+    out.push(`  gap ${g.what}: ${g.background} of ${g.samples} sampled pixels are background${hidden.length === 0 ? '' : ` (${hidden.join(', ')} occluded, read at its position)`}`);
+  }
+  return out;
+}
+
+/** 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

@@ -62,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
@@ -140,11 +144,13 @@ export interface CapRecord {
   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', 'missing_px'] 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> {
@@ -184,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;
 }
 
 /**
@@ -199,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;
@@ -275,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`;
 }
@@ -454,8 +483,9 @@ function checkParts(raw: unknown, path: string): PartsFile {
           pt(co.box, 4) &&
           isCount(co.layer_px) &&
           isCount(co.missing_px) &&
-          (!('image_px' in co) || isCount(co.image_px));
-        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?, missing_px} is required`);
+          (!('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`);
       }
     }
   }
@@ -471,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);
@@ -481,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

package/src/propose.ts

@@ -470,6 +470,7 @@ export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null;
   const read: Array<{ part: string; run: 'full' | 'head'; tag: string; base: string | null; own: number; area: number; order: number; piece: boolean }> = [];
   const patches: string[] = [];
   const unread = new Map<string, string[]>();
+  const depthless: Array<{ part: string; from: string; set: LayerSet }> = [];
   P.recs.forEach((r, order) => {
     const [run, tag] = splitFrom(r.from);
     if (run === PAINTING_RUN) {
@@ -487,7 +488,7 @@ export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null;
       return;
     }
     if (layer.depth === null) {
-      problems.push({ code: 'PROPOSE_TURN_DEPTH_PRESENT', object: `part "${r.name}" (${r.from})`, detail: `its layer in ${set.source} carries no depth_median (a ${set.form} input); the turn orders parts by See-through's per-layer depth, so a run that carries one is required` });
+      depthless.push({ part: r.name, from: r.from, set });
       return;
     }
     read.push({ part: r.name, run: run as 'full' | 'head', tag, base: 'base' in layer.tag ? layer.tag.base : null, own: layer.depth, area: r.opaque_px, order, piece: r.cut_from !== undefined });
@@ -495,6 +496,15 @@ export function draftTurn(P: PartSet, runs: TurnRuns): { turn: TurnSpec | null;
   for (const [run, names] of unread) {
     problems.push({ code: 'PROPOSE_TURN_RUN_GIVEN', object: `the ${run} run`, detail: `part(s) ${names.map((n) => `"${n}"`).join(', ')} came from it and its layers were not given; --${run} <dir | layers.json> is required to read their depth` });
   }
+  // Issue #359: runs that carry no depth at all (a PSD, or an export of one) are skipped by name, never passed and never
+  // given an invented depth; a run where some parts' layers carry one and others do not is refused part by part.
+  if (problems.length === 0 && read.length === 0 && depthless.length > 0) {
+    const sources = [...new Set(depthless.map((d) => d.set.source))];
+    return { turn: null, notes: [`turn: SKIP — ${sources.join(', ')} carr${sources.length === 1 ? 'ies' : 'y'} no depth_median (${[...new Set(depthless.map((d) => (d.set.form === 'psd' ? 'a PSD carries none' : 'null on every layer')))].join('; ')}), so no turn control is drafted from ${depthless.length} part(s); the turn orders parts by See-through's per-layer depth, and none was measured — a config.turn written by hand sets one`] };
+  }
+  for (const d of depthless) {
+    problems.push({ code: 'PROPOSE_TURN_DEPTH_PRESENT', object: `part "${d.part}" (${d.from})`, detail: `its layer in ${d.set.source} carries no depth_median (a ${d.set.form} input) while other parts' layers carry one; the turn orders parts by See-through's per-layer depth, so a run that carries one for every part — or for none, which skips the turn — is required` });
+  }
   refuseIfAny(problems);
   const notes: string[] = [];
   if (patches.length > 0) {

package/src/tags.ts

@@ -187,6 +187,9 @@ export function isAuthorTag(name: string): boolean {
  * other names the accepted v3 tags and the author form.
  */
 export function layerTagRequirement(name: string): string {
+  if (name.endsWith(HIDDEN_SUFFIX)) {
+    return `is a hidden-art layer's name (issue #359) for ${JSON.stringify(name.slice(0, -HIDDEN_SUFFIX.length))}, which is no layer name; ${HIDDEN_NAME_RULE} is required`;
+  }
   if (name.startsWith(AUTHOR_PREFIX)) {
     return `is an author-made layer's name with the label ${JSON.stringify(name.slice(AUTHOR_PREFIX.length))}; ${AUTHOR_LABEL_RULE} is required after "${AUTHOR_PREFIX}"`;
   }
@@ -205,3 +208,47 @@ export const AUTHOR_NO_ROLE =
 export function authorLayerLine(name: string): string {
   return `author-made: layer "${name}" — ${AUTHOR_NO_ROLE}`;
 }
+
+/**
+ * ⭐ **A hidden-art layer** (issue #359) holds the art of a layer where
+ * something else covers it — the forearm under the sleeve, the inside of the
+ * knee, the shirt under a scarf's tail — painted by an artist who has it,
+ * because See-through cannot see it. It is named by the layer it belongs to
+ * and {@link HIDDEN_SUFFIX}: `handwear-r:hidden` is `handwear-r`'s art where
+ * it is covered, `author:hand:hidden` is `author:hand`'s.
+ *
+ * Why this form and not `author:` with a declared target: the name alone says
+ * what the layer is and whose it is, so every reader knows at read time that
+ * it is not a part (the proposer never drafts one from it) and which layer it
+ * belongs to, with no config field to agree with it. The suffix holds a colon,
+ * which no v3 tag holds and an author-made label may not hold
+ * ({@link AUTHOR_LABEL_RULE}), so `<name>:hidden` can never be read as a tag,
+ * a side, or a label.
+ *
+ * It is never drawn and never a part. `assemble` reads it as the art the
+ * layer's part takes where a stage takes art from under something: a cut's
+ * `under` (issue #193) and a limb segment's cap (issue #349) — see
+ * `hiddenArt` in `src/assemble.ts`.
+ */
+export const HIDDEN_SUFFIX = ':hidden';
+
+/** A hidden-art layer's name read: the layer it belongs to. */
+export interface HiddenTagReading {
+  /** The name as the layer carries it: `handwear-r:hidden`. */
+  name: string;
+  /** The layer it belongs to: `handwear-r`, a v3 tag or an author-made layer's name. */
+  of: string;
+}
+
+/**
+ * Read a layer name as a hidden-art layer's, or `null` when it does not end in
+ * {@link HIDDEN_SUFFIX} or what precedes it is no layer name ({@link readLayerTag}).
+ */
+export function readHiddenTag(name: string): HiddenTagReading | null {
+  if (!name.endsWith(HIDDEN_SUFFIX)) return null;
+  const of = name.slice(0, -HIDDEN_SUFFIX.length);
+  return readLayerTag(of) === null ? null : { name, of };
+}
+
+/** What a hidden-art layer's name must be, as a refusal quotes it. */
+export const HIDDEN_NAME_RULE = `"<layer>${HIDDEN_SUFFIX}", where <layer> is a See-through v3 tag or "${AUTHOR_PREFIX}<label>" that the same input also holds`;