@rig-c/parts 1.5.5 → 1.7.0

package/src/build.ts

@@ -43,7 +43,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { type AnimFrame, EncodeError, encodeApng, encodeIndexedApng, INDEXED_DEFAULTS } from './apng.ts';
-import { assemble, type AssembleResult, cutLines, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields } from './assemble.ts';
+import { assemble, type AssembleResult, cutLines, figuresLine, holeLines, type ProjectRule, type SeamRule, stageFields, uncoveredLine } from './assemble.ts';
 import { allocationClause, type Reducer, stageBClause, unboundedClause } from './automesh.ts';
 import { residualClause } from './autoenvelope.ts';
 import { type AutoMotionCase, failingRows, idleSchedule, localRow, motionClause, motionDeformation, motionDocument, motionInput, motionRowText, motionStimulus, motionVerdict, noStimulusProblem, type ReplayCandidate, runComparison, stimulusMotion, withStimulus } from './automotion.ts';
@@ -70,7 +70,7 @@ import {
   splitSchedule,
   untestedIntervals,
 } from './autoreplay.ts';
-import { BARS, besideIdleLine, causeLines, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
+import { BARS, besideIdleLine, buildGateLines, causeLines, IDLE_FPS, IDLE_MAX_PX, maxRgbDiff, REQUIREMENTS_DIR, type CheckReport, type PackLine, DEFAULT_PACK_SHAPE, DEFAULT_PAGE_EDGES, JUDGEMENT_LINES, type JudgementLine, packedBuildArgs, packedBuildLabel, type PackMode, type PackShape, type PageEdges, readFrameSet, rigcFailed, REPORTED_LINES, type ReportedLine, type RigcRunner, runCheck, SEAM_DIR, SEAM_MEAN_BAR, seamPairText, seamRigPxText, SOURCE_LINE, SEAM_PX_BAR, SEAM_PX_LEVEL, SEAM_PX_LEVEL_HIGH, SPINEBOY_YARDSTICK, STILL_DIR } from './check.ts';
 import { type Cut, loadConfig, loadConfigAndAnimations, loadEarlyConfig } from './config.ts';
 import { PartsError, type Problem, problemLine, refuseIfAny } from './errors.ts';
 import type { MeshQualityReport, MotionSchedule } from 'rig-c/mesh';
@@ -82,7 +82,8 @@ import { type PartRecord, readParts, writeParts } from './parts.ts';
 import { encodePngBytes, readPng, writePng } from './raster/png.ts';
 import type { Raster } from './raster/types.ts';
 import { readRequirements, type RequirementLine, summaryText } from './requirements.ts';
-import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, type StrayCleared } from './rig.ts';
+import { type AutoMeshReport, buildRig, DEFAULT_IDLE_KEYS, type FaceAxis, type IdleKeys, type MeshReport, type RigCommand, rigJsonText, type RigOutput, type RigSpec, type StrayCleared } from './rig.ts';
+import { pyRound } from './round.ts';
 
 /** Where a stage's lines go. The commands hand it `console.log`; `build` hands it a prefixing wrapper. */
 export type Log = (line: string) => void;
@@ -228,6 +229,7 @@ export function assembleStage(input: AssembleStageInput, outs: AssembleOutputs,
   log(`  ghost px removed: ${ghosts} over ${Object.keys(result.parts.ghost_px).length} layer(s)`);
   log(figuresLine(result.figures));
   for (const l of holeLines(result.figures)) log(l);
+  for (const u of result.uncovered) log(uncoveredLine(u));
   log(`wrote ${outs.partsJson}, ${result.images.length} PNG(s) in ${outs.partsDir}, ${outs.recomposite}, ${outs.errorMap} (uncovered error px red, covered error px blue, the painting grey)`);
   return result;
 }
@@ -818,6 +820,7 @@ export function rigStage(input: RigStageInput, rigc: RigcRunner, scratch: string
     `  bones ${rig.rig.bones.length} (${rig.controls.length} control) slots ${rig.rig.slots.length} meshes ${rig.meshReport.length} regions ${regions} vertices ${vertices}; idle ${rig.motion.animations.idle.duration} s, ${tracks.length} track(s), ${keys} key(s)`,
   );
   if (from !== null) log(`  animations beside the idle, from ${from.file} as written: ${Object.keys(from.table).join(', ') || 'none'}`);
+  log(faceAxisLine(rig.faceAxis));
   log(
     rig.idleKeys === 'ctl'
       ? `  idle keys ctl: ${rig.meshKeyed.length} mesh-driving bone(s) keyed by the idle, each keyed through a same-origin <bone>_ctl parent`
@@ -940,6 +943,24 @@ export function barsSummary(r: CheckReport): string {
   return `${measured.length} of ${BARS.length} bar(s) measured, ${skipped.length} skipped${skipped.length === 0 ? '' : ` (${skipped.map((s) => s.bar).join(', ')})`}`;
 }
 
+/**
+ * The rig stage's face-axis line (issue #239): the eye line's angle, the parts it runs between and the face bones
+ * turned to it, or why there is no line and the face bones keep the page's axes — the note a one-eyed painting gets.
+ * With a line it also names the `invariants.axes` entry written for rigc's A51, its tolerance, or why none was.
+ */
+export function faceAxisLine(f: FaceAxis): string {
+  const own = f.ownTip.length === 0 ? '' : `; ${f.ownTip.join(', ')} ${f.ownTip.length === 1 ? 'takes its' : 'take their'} own tip`;
+  if (f.degrees === null) return `  face axis: none — ${f.none}; ${f.ownTip.length === 0 ? 'the face bones keep' : 'the other face bones keep'} the page's axes${own}`;
+  const turned = f.turned.length === 0 ? 'no face bone to turn' : `${f.turned.join(', ')} turned to it`;
+  const held =
+    f.axis !== null
+      ? `; invariants.axes "${f.axis.name}" holds ${f.axis.bones.join(', ')} to the line through ${f.axis.through.join(' -> ')}, tolerance ${f.axis.tolerance} degrees (rigc's A51)`
+      : f.noAxis !== null
+        ? `; no invariants.axes entry: ${f.noAxis}`
+        : '';
+  return `  face axis: ${pyRound(f.degrees, 6)} degrees, the line through the eye bones eye_r and eye_l (on ${f.parts[0]} and ${f.parts[1]}); ${turned}${own}${held}`;
+}
+
 /** A judgement line as the console prints it: its name, its status, then its figures and bars as check.json holds them (a SKIP prints its reason). */
 export function judgementLine(name: string, line: JudgementLine | ReportedLine): string {
   if (line.status === 'SKIP') return `${name}: SKIP — ${String(line.reason)}`;
@@ -1026,19 +1047,141 @@ export interface LoopResult {
   error: PaletteError | null;
 }
 
+/**
+ * The idle `build --loop --lead-in <n>` renders (issue #224's follow-up):
+ * `idle` played n + 1 times back to back, of which the loop keeps the last
+ * period. rigc's render resets physics at frame 0, so an idle whose rig
+ * carries a physics constraint does not end where it starts; played on, a
+ * spring the idle drives settles into the idle's period, and the last period
+ * of the run is that steady state.
+ */
+export const LEAD_IN_ANIMATION = 'idle_lead_in';
+
+/** Which frames of a lead-in run the loop keeps: the last of `periods + 1` periods. */
+export interface LoopWindow {
+  periods: number;
+}
+
+const LEAD_IN_ANIMATION_KEYS = ['duration', 'loop', 'note', 'tracks'];
+
+/**
+ * `motion` with {@link LEAD_IN_ANIMATION} added: every idle track's keys
+ * repeated `periods + 1` times, each copy shifted by one idle duration, its
+ * Bezier `curve` times with it, and the key at the end of a copy dropped for
+ * the next copy's first key at the same time. Refused by name
+ * (`LOOP_LEAD_IN_IDLE`), every problem at once, when the motion has no idle,
+ * already has an animation of that name, or the idle is not a loop this can
+ * repeat without inventing a value: a field besides duration, loop, note and
+ * tracks; a track whose keys do not start at 0 and end at the duration; or one
+ * whose last value is not its first.
+ */
+export function repeatIdle(motion: Record<string, unknown>, periods: number): Record<string, unknown> {
+  const problems: Problem[] = [];
+  const fail = (object: string, detail: string): void => {
+    problems.push({ code: 'LOOP_LEAD_IN_IDLE', object, detail });
+  };
+  const anims = motion.animations;
+  const table = typeof anims === 'object' && anims !== null && !Array.isArray(anims) ? (anims as Record<string, unknown>) : null;
+  const idle = table?.idle;
+  if (table === null || typeof idle !== 'object' || idle === null || Array.isArray(idle)) {
+    fail('motion.json animations.idle', 'is absent; the lead-in repeats the idle');
+    refuseIfAny(problems);
+  }
+  const t = table as Record<string, unknown>;
+  const a = idle as Record<string, unknown>;
+  if (LEAD_IN_ANIMATION in t) fail(`motion.json animations.${LEAD_IN_ANIMATION}`, 'exists; the lead-in writes an animation of that name and never replaces one');
+  for (const k of Object.keys(a)) if (!LEAD_IN_ANIMATION_KEYS.includes(k)) fail(`motion.json animations.idle.${k}`, `is a field the lead-in does not repeat; the idle it repeats holds ${LEAD_IN_ANIMATION_KEYS.join(', ')}`);
+  const d = a.duration;
+  if (typeof d !== 'number' || !(d > 0)) fail('motion.json animations.idle.duration', `is ${JSON.stringify(d)}; a positive number is required`);
+  const tracks = Array.isArray(a.tracks) ? a.tracks : [];
+  const duration = d as number;
+  const out: unknown[] = [];
+  tracks.forEach((track, i) => {
+    const tr = track as Record<string, unknown>;
+    const keys = Array.isArray(tr.keys) ? (tr.keys as Array<Record<string, unknown>>) : [];
+    const at = `motion.json animations.idle.tracks[${i}]`;
+    const first = keys[0];
+    const last = keys[keys.length - 1];
+    if (first === undefined || first.t !== 0 || last.t !== duration) {
+      fail(at, `keys run from ${String(first?.t)} to ${String(last?.t)}; a track the lead-in repeats starts at 0 and ends at the duration ${duration}`);
+      return;
+    }
+    if (JSON.stringify(first.v) !== JSON.stringify(last.v)) {
+      fail(at, `ends at ${JSON.stringify(last.v)} and starts at ${JSON.stringify(first.v)}; repeated, the idle would jump where one copy meets the next`);
+      return;
+    }
+    const repeated: Array<Record<string, unknown>> = [];
+    for (let r = 0; r <= periods; r++) {
+      const shift = r * duration;
+      keys.forEach((k, j) => {
+        if (r < periods && j === keys.length - 1) return;
+        const moved: Record<string, unknown> = { ...k, t: (k.t as number) + shift };
+        if (Array.isArray(k.curve)) moved.curve = (k.curve as number[]).map((c, n) => (n % 2 === 0 ? c + shift : c));
+        repeated.push(moved);
+      });
+    }
+    out.push({ ...tr, keys: repeated });
+  });
+  refuseIfAny(problems);
+  return { ...motion, animations: { ...t, [LEAD_IN_ANIMATION]: { duration: duration * (periods + 1), loop: false, tracks: out } } };
+}
+
+/**
+ * Render {@link LEAD_IN_ANIMATION} of the rig in `rigDir` as `check` renders
+ * the idle (the packed build, `IDLE_FPS`, `IDLE_MAX_PX`), every other
+ * animation kept so the viewport is fitted as for the idle frames. Writes
+ * under `dir` and returns the frame set's directory.
+ */
+export function leadInFrames(rigDir: string, dir: string, periods: number, rigc: RigcRunner, mode: PackMode): string {
+  const rig = JSON.parse(readFileSync(join(rigDir, 'rig.json'), 'utf8')) as Record<string, unknown>;
+  const motion = repeatIdle(JSON.parse(readFileSync(join(rigDir, 'motion.json'), 'utf8')) as Record<string, unknown>, periods);
+  const images = typeof rig.images === 'string' ? resolve(rigDir, rig.images) : rig.images;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'rig.json'), JSON.stringify({ ...rig, images }));
+  writeFileSync(join(dir, 'motion.json'), JSON.stringify(motion));
+  const what = `the idle played ${periods + 1} times (${LEAD_IN_ANIMATION})`;
+  const b = rigc(['build', '--rig', join(dir, 'rig.json'), '--motion', join(dir, 'motion.json'), '--out', join(dir, 'build'), ...packedBuildArgs(mode)]);
+  if (b.status !== 0) refuseIfAny(rigcFailed(`${packedBuildLabel(mode)} (${what})`, b, buildGateLines(b.out)));
+  const r = rigc(['render', '--candidate', join(dir, 'build'), '--animation', LEAD_IN_ANIMATION, '--fps', String(IDLE_FPS), '--max', String(IDLE_MAX_PX), '--out', join(dir, 'frames')]);
+  if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation ${LEAD_IN_ANIMATION} (${what})`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
+  return join(dir, 'frames');
+}
+
+/** Pixels whose largest RGB channel difference between `a` and `b` is above `level`. */
+function pixelsOver(a: Raster, b: Raster, level: number): number {
+  let n = 0;
+  for (let p = 0; p < a.width * a.height; p++) {
+    let m = 0;
+    for (let c = 0; c < 3; c++) m = Math.max(m, Math.abs(a.data[p * 4 + c] - b.data[p * 4 + c]));
+    if (m > level) n++;
+  }
+  return n;
+}
+
 /**
  * Encode a rigc frame set as a looping APNG, indexed APNG or GIF and write it.
  * An encoder refusal is a PartsError coded `LOOP_ENCODE`, so it prints like
  * every other.
  */
-export function loopStage(frames: string, out: string, format: LoopFormat, log: Log): LoopResult {
+export function loopStage(frames: string, out: string, format: LoopFormat, log: Log, window?: LoopWindow): LoopResult {
   const set = readFrameSet(frames);
   const images = set.frames.map((fr) => fr.image);
   log(`rig-parts loop: ${set.dir} -> ${out}`);
   log(`  ${images.length} frame(s) ${images[0]?.width ?? 0}x${images[0]?.height ?? 0} at ${set.fps} fps (from frames.json), animation ${set.animation ?? '(none)'}`);
   let used = images;
   const lastName = set.frames[set.frames.length - 1]?.name ?? '';
-  if (images.length > 1 && sameRgba(images[0].data, images[images.length - 1].data)) {
+  if (window !== undefined) {
+    const per = (images.length - 1) / (window.periods + 1);
+    if (!Number.isInteger(per) || per < 1) {
+      throw new PartsError([{ code: 'LOOP_LEAD_IN_IDLE', object: set.dir, detail: `holds ${images.length} frame(s), which is not ${window.periods + 1} whole period(s) and the end frame; the lead-in keeps the last period` }]);
+    }
+    const start = window.periods * per;
+    const end = start + per;
+    const jump = maxRgbDiff(images[start], images[end]);
+    used = images.slice(start, end);
+    const name = (i: number): string => set.frames[i].name.replace('.png', '');
+    log(`  lead-in: ${window.periods} period(s) of the idle played ahead, physics running; ${name(start)}–${name(end - 1)} kept (${per} frame(s), the last period); ${name(end)}, one period after ${name(start)}, differs from it by max |d| ${jump.max}, ${pixelsOver(images[start], images[end], 40)} px over 40 — the jump at the wrap`);
+  } else if (images.length > 1 && sameRgba(images[0].data, images[images.length - 1].data)) {
     used = images.slice(0, -1);
     log(`  ${lastName} equals f0000.png byte for byte, so it is dropped: the loop wraps onto frame 0, and showing it twice would hold that pose for two ticks`);
   } else if (images.length > 1) {
@@ -1102,6 +1245,12 @@ export interface BuildInput {
   requirements?: string;
   /** `--idle-keys`, forwarded to the rig stage as `rig` takes it (issue #95); {@link DEFAULT_IDLE_KEYS} when absent. */
   idleKeys?: IdleKeys;
+  /**
+   * `--lead-in <n>`, with `loop` only: the loop is encoded from the last of n + 1
+   * idle periods played back to back ({@link leadInFrames}) instead of from
+   * `check/idle_frames/`; absent, the loop is as before.
+   */
+  leadIn?: number;
 }
 
 /**
@@ -1115,7 +1264,7 @@ export interface BuildRunners {
   check: RigcRunner;
   /** Where the check's rigc binary is, for its header line. */
   checkBin: string;
-  /** A directory the rig stage may stage its gate in; emptied before and after. */
+  /** A directory the rig stage may stage its gate in, and the loop its lead-in render after it; emptied before and after each. */
   scratch: string;
 }
 
@@ -1177,7 +1326,7 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   for (const p of BUILD_OWNS) rmSync(join(out, p), { recursive: true, force: true });
   // The idle-keys value is named only when it is not the default, so a build without the flag, or with the default, prints the line it printed before issue #95.
   const idleKeys = input.idleKeys ?? DEFAULT_IDLE_KEYS;
-  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? ', with the idle loop' : ''}`);
+  log(`rig-parts build: ${input.config} -> ${out}, seam rule ${input.seam}, projection rule ${input.project}, page edges ${input.pageEdges}, pack shape ${input.packShape ?? DEFAULT_PACK_SHAPE}${idleKeys === DEFAULT_IDLE_KEYS ? '' : `, idle keys ${idleKeys}`}${input.loop ? `, with the idle loop${input.leadIn === undefined ? '' : ` after a lead-in of ${input.leadIn} period(s)`}` : ''}`);
 
   try {
     // build runs rig next, which needs the whole config, so the full loader is
@@ -1214,12 +1363,15 @@ export function build(input: BuildInput, run: BuildRunners, log: Log): BuildResu
   }
 
   if (input.loop) {
-    const frames = join(out, 'check', 'idle_frames');
     try {
       const say = prefixed('loop');
-      const lossless = loopStage(frames, join(out, 'idle.png'), 'apng', say);
-      const indexed = loopStage(frames, join(out, 'idle-indexed.png'), 'indexed', say);
-      const gif = loopStage(frames, join(out, 'idle.gif'), 'gif', say);
+      const window = input.leadIn === undefined ? undefined : { periods: input.leadIn };
+      if (window !== undefined) rmSync(run.scratch, { recursive: true, force: true });
+      const frames = window === undefined ? join(out, 'check', 'idle_frames') : leadInFrames(join(out, 'rig'), run.scratch, window.periods, run.check, { pageEdges: input.pageEdges, packShape: input.packShape ?? DEFAULT_PACK_SHAPE });
+      const lossless = loopStage(frames, join(out, 'idle.png'), 'apng', say, window);
+      const indexed = loopStage(frames, join(out, 'idle-indexed.png'), 'indexed', say, window);
+      const gif = loopStage(frames, join(out, 'idle.gif'), 'gif', say, window);
+      if (window !== undefined) rmSync(run.scratch, { recursive: true, force: true });
       const fig = (e: PaletteError | null): string => (e === null ? 'lossless' : `max ${e.max}, mean ${e.mean.toFixed(3)}`);
       say(`loop: idle.png ${lossless.bytes} B (${fig(lossless.error)}); idle-indexed.png ${indexed.bytes} B (${fig(indexed.error)}); idle.gif ${gif.bytes} B (${fig(gif.error)}) — palette error per channel over all frames`);
     } catch (err) {

package/src/check.ts

@@ -111,6 +111,8 @@ import {
   topmostIndex,
   TORSO_TAGS,
   halfTravels,
+  chainToward,
+  type Toward,
   type WorldBox,
 } from './instruments.ts';
 import { type PartRecord, type PartsFile, readParts } from './parts.ts';
@@ -1757,6 +1759,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     const file = reqFile as RequirementsFile;
     const ready = inp;
     take(() => resolveRequirements(file, ready.rig, ready.motion, ready.rootBone));
+    take(() => refuseIfAny(exceptionProblems(file, ready.parts, ready.noParts)));
     // A seam's pairs are read off parts.json's art (issue #111); both resolvers' problems are named in one refusal.
     if (file.requirements.some((r) => r.kind === 'seam')) {
       const parts = ready.parts;
@@ -1873,12 +1876,14 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     if (r.status !== 0) refuseIfAny(rigcFailed(`render --animation idle --slot ${ps.map((p) => p.name).join(',')}`, r, r.out.split('\n').filter((l) => l.includes('FAIL') || l.includes('rigc:'))));
     return readFrameSet(dir);
   };
+  // Issue #231: the footwear parts the scene file declares not planted; none without --requirements or the field.
+  const notPlanted = reqFile === null ? [] : reqFile.not_planted;
   let breath: JudgementLine = skip(lacking);
   let tip: JudgementLine = skip(lacking);
   if (full !== null) {
     try {
-      breath = breathLine(full, isolated, problems);
-      if (idle !== null) tip = tipLine(full, join(idle.dir, GEOMETRY_FILE), idle.written, problems);
+      breath = breathLine(full, isolated, problems, notPlanted);
+      if (idle !== null) tip = tipLine(full, join(idle.dir, GEOMETRY_FILE), idle.written, problems, reqFile === null ? NO_TIP_EXCEPTIONS : { path: reqFile.path, not_swinging: reqFile.not_swinging, rises: reqFile.rises });
     } finally {
       rmSync(isoDir, { recursive: true, force: true });
     }
@@ -1892,7 +1897,7 @@ export function runCheck(rigDir: string, outDir: string, rigc: RigcRunner, parts
     const geometryPath = join(idle.dir, GEOMETRY_FILE);
     const geometry = readGeometry(geometryPath, idle.written);
     stretch = stretchLine(geometry, geometryPath, problems);
-    if (full !== null) still = stillLine(full, idle, geometry, geometryPath, problems);
+    if (full !== null) still = stillLine(full, idle, geometry, geometryPath, problems, notPlanted);
   }
 
   // 4. the setup pose as a one-key throwaway animation — the seam reads it against the parts, the source line against
@@ -2242,22 +2247,98 @@ function quoteParts(ps: readonly PartRecord[]): string {
 
 type Isolate = (label: string, ps: readonly PartRecord[]) => FrameSet;
 
-/** (1) The torso moves while the feet do not: each rendered alone, heat over its own box. */
-function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[]): JudgementLine {
+/**
+ * The scene file's three exceptions (issue #231), read against parts.json
+ * before anything is built: each name must be a part parts.json lists
+ * (`REQUIREMENTS_RESOLVES`), and one the bar it relaxes reads — a `footwear`
+ * part for `not_planted` (`REQUIREMENTS_NOT_PLANTED`), a `handwear` or
+ * `bottomwear` part for `not_swinging` and `rises`
+ * (`REQUIREMENTS_TIP_EXCEPTION`): an exception that excepts nothing is a miss,
+ * refused by name. With no parts.json every name is refused. Whether a `rises`
+ * part's chain does rise is read off the idle's geometry by `TIP_OVER_ROOT`.
+ */
+export function exceptionProblems(file: Pick<RequirementsFile, 'not_planted' | 'not_swinging' | 'rises' | 'path'>, parts: PartsFile | null, noParts: string | null): Problem[] {
+  const out: Problem[] = [];
+  // Issue #231: not_swinging and rises name swinging parts, the ones TIP_OVER_ROOT reads; whether a rises part's chain does rise is read off the idle's geometry, in the line.
+  for (const key of ['not_swinging', 'rises'] as const) {
+    file[key].forEach((name, i) => {
+      const object = `${file.path} field "${key}"[${i}]`;
+      if (parts === null) {
+        out.push({ code: 'REQUIREMENTS_TIP_EXCEPTION', object, detail: `names part "${name}", and the swinging parts are chosen by parts.json's See-through tags, of which none was read: ${noParts ?? 'no parts.json'}` });
+        return;
+      }
+      const rec = parts.parts.find((p) => p.name === name);
+      if (rec === undefined) {
+        out.push({ code: 'REQUIREMENTS_RESOLVES', object, detail: `names part "${name}", which parts.json does not list; it lists ${parts.parts.map((p) => `"${p.name}"`).join(', ') || 'none'}` });
+        return;
+      }
+      const swing = partsTagged(parts, SWING_TAGS).map((p) => p.name);
+      if (!swing.includes(name)) {
+        out.push({
+          code: 'REQUIREMENTS_TIP_EXCEPTION',
+          object,
+          detail: `names part "${name}" (from "${rec.from}"), which TIP_OVER_ROOT does not read; only a part from a See-through ${tagWords(SWING_TAGS)} layer is (${swing.map((n) => `"${n}"`).join(', ') || 'none here'}), so declaring it excepts nothing`,
+        });
+      }
+    });
+  }
+  file.not_planted.forEach((name, i) => {
+    const object = `${file.path} field "not_planted"[${i}]`;
+    if (parts === null) {
+      out.push({ code: 'REQUIREMENTS_NOT_PLANTED', object, detail: `names part "${name}", and the feet are chosen by parts.json's See-through tags, of which none was read: ${noParts ?? 'no parts.json'}` });
+      return;
+    }
+    const rec = parts.parts.find((p) => p.name === name);
+    if (rec === undefined) {
+      out.push({ code: 'REQUIREMENTS_RESOLVES', object, detail: `names part "${name}", which parts.json does not list; it lists ${parts.parts.map((p) => `"${p.name}"`).join(', ') || 'none'}` });
+      return;
+    }
+    const feet = partsTagged(parts, FEET_TAGS).map((p) => p.name);
+    if (!feet.includes(name)) {
+      out.push({
+        code: 'REQUIREMENTS_NOT_PLANTED',
+        object,
+        detail: `names part "${name}" (from "${rec.from}"), which is not read as a planted foot; only a part from a See-through ${tagWords(FEET_TAGS)} layer is (${feet.map((n) => `"${n}"`).join(', ') || 'none here'}), so declaring it excepts nothing`,
+      });
+    }
+  });
+  return out;
+}
+
+/** The feet a line holds still (issue #231): the `footwear` parts less those the scene file declares not planted, and the declared ones, in parts.json's order. */
+function plantedFeet(parts: PartsFile, notPlanted: readonly string[]): { all: PartRecord[]; held: PartRecord[]; declared: string[] } {
+  const all = partsTagged(parts, FEET_TAGS);
+  return { all, held: all.filter((p) => !notPlanted.includes(p.name)), declared: all.filter((p) => notPlanted.includes(p.name)).map((p) => p.name) };
+}
+
+/** The sentence a feet half carries when every footwear part is declared not planted (issue #231). */
+function noneHeldText(declared: readonly string[]): string {
+  return `every ${tagWords(FEET_TAGS)} part (${declared.map((n) => `"${n}"`).join(', ')}) is declared not planted by the scene file's not_planted, so there are no feet to hold still`;
+}
+
+/**
+ * (1) The torso moves while the feet do not: each rendered alone, heat over
+ * its own box. The feet are the `footwear` parts less those the scene file
+ * declares `not_planted` (issue #231); a declaration is the line's first
+ * figure, `declared_not_planted`, so the line never reads as though the feet
+ * it names were held still. With every foot declared, the torso is measured
+ * and the feet figures are an empty list and null.
+ */
+function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[], notPlanted: readonly string[] = []): JudgementLine {
   const torso = partsTagged(inp.parts, TORSO_TAGS);
-  const feet = partsTagged(inp.parts, FEET_TAGS);
-  if (torso.length === 0) return skip(`no part comes from a See-through ${tagWords(TORSO_TAGS)} layer, so there is no torso to see breathe`);
-  if (feet.length === 0) return skip(`no part comes from a See-through ${tagWords(FEET_TAGS)} layer, so there are no feet to hold still`);
+  const { all: allFeet, held: feet, declared } = plantedFeet(inp.parts, notPlanted);
+  if (torso.length === 0) return skip(`no part comes from a See-through ${tagWords(TORSO_TAGS)} layer, so there is no torso to see breathe${declared.length === 0 ? '' : `; ${declared.map((n) => `"${n}"`).join(', ')} declared not planted`}`);
+  if (allFeet.length === 0) return skip(`no part comes from a See-through ${tagWords(FEET_TAGS)} layer, so there are no feet to hold still`);
   const H = inp.parts.rig_size[1];
   const ts = isolated('torso', torso);
-  const fs = isolated('feet', feet);
+  const fs = feet.length === 0 ? null : isolated('feet', feet);
   const tb = frameBox(torso, H, inp.stage, ts.viewport);
-  const fb = frameBox(feet, H, inp.stage, fs.viewport);
-  if (tb === null || fb === null) return skip(`the ${tb === null ? 'torso' : 'feet'} box falls outside the idle frame`);
+  const fb = fs === null ? null : frameBox(feet, H, inp.stage, fs.viewport);
+  if (tb === null || (fs !== null && fb === null)) return skip(`the ${tb === null ? 'torso' : 'feet'} box falls outside the idle frame`);
   const th = regionHeat(heatField(ts.frames.map((f) => f.image)), ts.viewport.pixelWidth, tb);
-  const fh = regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, fb);
+  const fh = fs === null || fb === null ? null : regionHeat(heatField(fs.frames.map((f) => f.image)), fs.viewport.pixelWidth, fb);
   const mean = round3(th.mean);
-  const ok = mean >= BREATH_TORSO_MEAN_FLOOR && fh.max <= BREATH_FEET_MAX_CEILING;
+  const ok = mean >= BREATH_TORSO_MEAN_FLOOR && (fh === null || fh.max <= BREATH_FEET_MAX_CEILING);
   if (mean < BREATH_TORSO_MEAN_FLOOR) {
     problems.push({
       code: 'CHECK_BREATH_VISIBLE',
@@ -2265,24 +2346,34 @@ function breathLine(inp: FullInputs, isolated: Isolate, problems: Problem[]): Ju
       detail: `heat mean ${mean}/255 over the idle; >= ${BREATH_TORSO_MEAN_FLOOR} is required — the chest's breath track moves too little, or the torso is not weighted to the bone it keys`,
     });
   }
-  if (fh.max > BREATH_FEET_MAX_CEILING) {
+  if (fh !== null && fb !== null && fh.max > BREATH_FEET_MAX_CEILING) {
     problems.push({
       code: 'CHECK_BREATH_VISIBLE',
-      object: `feet ${quoteParts(feet)} rendered alone, frame box ${boxLabel(fb)}`,
+      object: `feet ${quoteParts(feet)} rendered alone, frame box ${boxLabel(fb)}${declared.length === 0 ? '' : ` (${declared.map((n) => `"${n}"`).join(', ')} declared not planted)`}`,
       detail: `heat max ${fh.max}/255 over the idle; <= ${BREATH_FEET_MAX_CEILING} is required — the feet move: their slot rides, or their mesh is weighted to, a bone the idle keys`,
     });
   }
   return {
     status: ok ? 'PASS' : 'FAIL',
+    ...(declared.length === 0 ? {} : { declared_not_planted: declared }),
     torso_parts: torso.map((p) => p.name),
     torso_heat_mean: mean,
     torso_floor: BREATH_TORSO_MEAN_FLOOR,
     feet_parts: feet.map((p) => p.name),
-    feet_heat_max: fh.max,
+    feet_heat_max: fh === null ? null : fh.max,
     feet_ceiling: BREATH_FEET_MAX_CEILING,
   };
 }
 
+/** The scene file's two exceptions to `TIP_OVER_ROOT` (issue #231), and the file they were read from, which a refusal names. */
+export interface TipExceptions {
+  path: string;
+  not_swinging: readonly string[];
+  rises: readonly string[];
+}
+
+const NO_TIP_EXCEPTIONS: TipExceptions = { path: '', not_swinging: [], rises: [] };
+
 /**
  * What `TIP_OVER_ROOT` is measured with, written into its line (issue #118):
  * the idle's posed geometry, not a render of the part. Until #118 the line
@@ -2301,37 +2392,139 @@ export const TIP_INSTRUMENT = 'geometry';
  * binary-coverage centroid per half; every root half on the three examples
  * travels under a frame pixel, where that centroid scatters by up to 0.3 px
  * with the grid, so the ratio was set by the grid.
+ *
+ * Issue #231: the scene file's `not_swinging` parts are left out, each row
+ * saying so, and its `rises` parts are read with the halves swapped once the
+ * chain carrying each is measured to rise ({@link chainDirection}; refused by
+ * name otherwise); both lists are the line's first figures. Without them the
+ * line is the one written before.
  */
-function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems: Problem[]): JudgementLine {
+function tipLine(inp: FullInputs, geometryPath: string, frames: number, problems: Problem[], excepted: TipExceptions = NO_TIP_EXCEPTIONS): JudgementLine {
   const swing = partsTagged(inp.parts, SWING_TAGS);
   if (swing.length === 0) return skip(`no part comes from a See-through ${tagWords(SWING_TAGS)} layer, so there is no hem or sleeve to swing`);
   const poses = attachmentPoses(geometryPath, frames);
+  // Issue #231: a part declared `rises` is read up only when the chain carrying it does rise, measured at the setup pose.
+  if (excepted.rises.length > 0) {
+    const geo = readGeometry(geometryPath, frames);
+    const origins = new Map<string, { x: number; y: number }>();
+    for (const b of Array.isArray(geo?.setupBones) ? geo.setupBones : []) {
+      if (isRecord(b) && typeof b.name === 'string' && typeof b.worldX === 'number' && typeof b.worldY === 'number') origins.set(b.name, { x: b.worldX, y: b.worldY });
+    }
+    const refused: Problem[] = [];
+    excepted.rises.forEach((name, i) => {
+      const dir = chainDirection(inp.rig, inp.motion, name, origins);
+      if ('toward' in dir && dir.toward === 'up') return;
+      refused.push({
+        code: 'REQUIREMENTS_TIP_EXCEPTION',
+        object: `${excepted.path} field "rises"[${i}]`,
+        detail: `names part "${name}", whose tip is not up: ${'none' in dir ? dir.none : `its chain runs ${dir.toward} — ${dir.chains.join('; ')}`}; a part declared rises must be carried by a chain whose last link's origin is above its first's at the setup pose`,
+      });
+    });
+    refuseIfAny(refused);
+  }
   const rows: Array<Record<string, unknown>> = [];
   let measured = 0;
   let failed = false;
   for (const p of swing) {
+    if (excepted.not_swinging.includes(p.name)) {
+      rows.push({ part: p.name, unmeasured: "declared not swinging by the scene file's not_swinging, so it is not held to the bar" });
+      continue;
+    }
+    const rises = excepted.rises.includes(p.name);
+    const [rootHalf, tipHalf] = rises ? ['lower', 'upper'] : ['upper', 'lower'];
     const art = placedArt(p.x, p.y, readPng(join(inp.partsDir, `${p.name}.png`)));
     const shown = poses.map((f) => f.get(p.name) ?? null);
-    const t = halfTravels(art, p, inp.stage, shown);
+    const t = halfTravels(art, p, inp.stage, shown, rises ? 'up' : 'down');
+    // A part not declared writes the row it wrote before issue #231; a declared one says which half is its tip's.
+    const said = rises ? { tip_half: tipHalf } : {};
     if (t.root === null || t.tip === null) {
-      rows.push({ part: p.name, unmeasured: shown[0] === null ? 'its slot shows no attachment on idle frame 0' : `on idle frame 0 the ${t.root === null ? 'upper' : 'lower'} half of its box holds no art its attachment draws` });
+      rows.push({ part: p.name, ...said, unmeasured: shown[0] === null ? 'its slot shows no attachment on idle frame 0' : `on idle frame 0 the ${t.root === null ? rootHalf : tipHalf} half of its box holds no art its attachment draws` });
       continue;
     }
     measured++;
     const ratio = t.root > 0 ? round3(t.tip / t.root) : null;
     const ok = ratio === null ? t.tip > 0 : ratio >= TIP_RATIO_FLOOR;
-    rows.push({ part: p.name, root_rig_px: round3(t.root), tip_rig_px: round3(t.tip), ratio });
+    rows.push({ part: p.name, ...said, root_rig_px: round3(t.root), tip_rig_px: round3(t.tip), ratio });
     if (!ok) {
       failed = true;
       problems.push({
         code: 'CHECK_TIP_OVER_ROOT',
-        object: `part "${p.name}", box ${p.x},${p.y} ${p.w}x${p.h} rig px, posed by the idle's geometry`,
-        detail: `the art in its lower half travels ${round3(t.tip)} rig px and in its upper half ${round3(t.root)} rig px (ratio ${ratio ?? 'undefined: nothing moves'}); a ratio >= ${TIP_RATIO_FLOOR} is required — the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain`,
+        object: `part "${p.name}", box ${p.x},${p.y} ${p.w}x${p.h} rig px, posed by the idle's geometry${rises ? ', declared rises' : ''}`,
+        detail: `the art in its ${tipHalf} half travels ${round3(t.tip)} rig px and in its ${rootHalf} half ${round3(t.root)} rig px (ratio ${ratio ?? 'undefined: nothing moves'}); a ratio >= ${TIP_RATIO_FLOOR} is required — the chain's amplitudes do not grow toward the tip, or the mesh is not weighted to the chain`,
       });
     }
   }
+  const declared = {
+    ...(excepted.not_swinging.length === 0 ? {} : { declared_not_swinging: swing.filter((p) => excepted.not_swinging.includes(p.name)).map((p) => p.name) }),
+    ...(excepted.rises.length === 0 ? {} : { declared_rises: swing.filter((p) => excepted.rises.includes(p.name)).map((p) => p.name) }),
+  };
   if (measured === 0) return { status: 'SKIP', reason: `none of ${quoteParts(swing)} could be measured: ${rows.map((r) => `${String(r.part)}: ${String(r.unmeasured)}`).join('; ')}` };
-  return { status: failed ? 'FAIL' : 'PASS', instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR };
+  return { status: failed ? 'FAIL' : 'PASS', ...declared, instrument: TIP_INSTRUMENT, parts: rows, ratio_floor: TIP_RATIO_FLOOR };
+}
+
+/**
+ * Which way the chain carrying a part runs (issue #231), for a part the scene
+ * declares `rises`: the bones its attachments are bound to in the default skin
+ * (a mesh's weights, or its slot's bone); the leaves among them — those with
+ * no other of them below — walked up the bone tree to the first link of a
+ * chain `CHAIN_LAG` reads ({@link chainFigures}: two or more rotate-keyed
+ * links, each under the one before at one period); each chain so found runs
+ * from its first link's setup-pose origin to its last link's
+ * ({@link chainToward}). `{ none }`, the reason, when no leaf is under a chain,
+ * when a chain runs as far across as along, or when the part's chains run
+ * different ways.
+ */
+export function chainDirection(rig: Record<string, unknown>, motion: Record<string, unknown>, part: string, origins: ReadonlyMap<string, { x: number; y: number }>): { toward: Toward; chains: string[] } | { none: string } {
+  const bones = (Array.isArray(rig.bones) ? rig.bones : []).filter(isRecord).filter((b) => typeof b.name === 'string');
+  const parent = new Map(bones.map((b) => [String(b.name), typeof b.parent === 'string' ? b.parent : null]));
+  const slot = (Array.isArray(rig.slots) ? rig.slots : []).filter(isRecord).find((sl) => sl.name === part);
+  const skins = isRecord(rig.skins) ? rig.skins : {};
+  const skin = isRecord(skins.default) ? skins.default : {};
+  const atts = isRecord(skin[part]) ? Object.values(skin[part]) : [];
+  const bound = new Set<string>();
+  for (const a of atts) {
+    if (isRecord(a) && Array.isArray(a.weights)) for (const v of a.weights) for (const w of Array.isArray(v) ? v : []) if (isRecord(w) && typeof w.bone === 'string') bound.add(w.bone);
+    if (!(isRecord(a) && Array.isArray(a.weights)) && slot !== undefined && typeof slot.bone === 'string') bound.add(slot.bone);
+  }
+  const under = (b: string, anc: string): boolean => {
+    const seen = new Set<string>();
+    for (let x = parent.get(b) ?? null; x !== null && !seen.has(x); x = parent.get(x) ?? null) {
+      if (x === anc) return true;
+      seen.add(x);
+    }
+    return false;
+  };
+  const leaves = [...bound].filter((b) => ![...bound].some((o) => o !== b && under(o, b)));
+  const chains = chainFigures(rig, motion).chains.filter((c) => c.length >= 2);
+  const chainOf = new Map<string, string[]>();
+  for (const c of chains) for (const l of c) chainOf.set(l.bone, c.map((x) => x.bone));
+  const found: string[][] = [];
+  for (const leaf of leaves) {
+    const seen = new Set<string>();
+    for (let b: string | null = leaf; b !== null && !seen.has(b); b = parent.get(b) ?? null) {
+      seen.add(b);
+      const c = chainOf.get(b);
+      if (c !== undefined) {
+        if (!found.some((f) => f[0] === c[0])) found.push(c);
+        break;
+      }
+    }
+  }
+  const boundText = [...bound].map((b) => `"${b}"`).join(', ') || 'no bone';
+  if (found.length === 0) return { none: `it rides no chain: none of the bones it is bound to (${boundText}) is under a chain of rotate-keyed links` };
+  const read = found.map((c) => {
+    const a = origins.get(c[0]);
+    const z = origins.get(c[c.length - 1]);
+    const label = c.join(' > ');
+    if (a === undefined || z === undefined) return { label, toward: null, text: `${label}: no setup-pose origin for ${a === undefined ? c[0] : c[c.length - 1]} in the idle's geometry` };
+    const dx = z.x - a.x;
+    const dy = z.y - a.y;
+    const toward = chainToward(dx, dy);
+    return { label, toward, text: `${label} ${toward ?? 'runs as far across as along'} (${round3(dx)}, ${round3(dy)} world px)` };
+  });
+  const ways = [...new Set(read.map((r) => r.toward))];
+  if (ways.length !== 1 || ways[0] === null) return { none: `its chains do not run one way: ${read.map((r) => r.text).join('; ')}` };
+  return { toward: ways[0], chains: read.map((r) => r.text) };
 }
 
 /**
@@ -2474,10 +2667,10 @@ interface StillHalf {
  * features go; `footwear` on top) is reported per slot, `crossing`, with no
  * bar ({@link crossingOf}). No render grid enters either half.
  */
-export function stillLine(inp: FullInputs, idle: FrameSet, geo: IdleGeometry | null, geometryPath: string, problems: Problem[]): JudgementLine {
+export function stillLine(inp: FullInputs, idle: FrameSet, geo: IdleGeometry | null, geometryPath: string, problems: Problem[], notPlanted: readonly string[] = []): JudgementLine {
   const face = partsTagged(inp.parts, FACE_TAGS);
-  const feet = partsTagged(inp.parts, FEET_TAGS);
-  if (face.length === 0 && feet.length === 0) return skip(`no part comes from a See-through ${tagWords([...FACE_TAGS, ...FEET_TAGS])} layer, so there is no still region to read`);
+  const { all: allFeet, held: feet, declared } = plantedFeet(inp.parts, notPlanted);
+  if (face.length === 0 && allFeet.length === 0) return skip(`no part comes from a See-through ${tagWords([...FACE_TAGS, ...FEET_TAGS])} layer, so there is no still region to read`);
   if (geo === null) return skip(`${geometryPath} does not exist; \`rigc render --geometry\` (rig-c ${RIGC_GEOMETRY_VERSION} or later) writes it, and the still regions are read off it`);
   const H = inp.parts.rig_size[1];
   const W = inp.parts.rig_size[0];
@@ -2618,7 +2811,8 @@ export function stillLine(inp: FullInputs, idle: FrameSet, geo: IdleGeometry | n
   };
 
   const feetHalf = (): Record<string, unknown> | string => {
-    if (feet.length === 0) return `no part comes from a See-through ${tagWords(FEET_TAGS)} layer`;
+    if (allFeet.length === 0) return `no part comes from a See-through ${tagWords(FEET_TAGS)} layer`;
+    if (feet.length === 0) return noneHeldText(declared);
     const names = feet.map((p) => p.name);
     const h = half(names, firstOf(names), poses.map(() => null), 1, 0, regionOf(new Set(feet.map((p) => index.get(p.name) as number)), []));
     for (const o of h.over) {
@@ -2635,7 +2829,9 @@ export function stillLine(inp: FullInputs, idle: FrameSet, geo: IdleGeometry | n
   const t = feetHalf();
   if (typeof f === 'string' && typeof t === 'string') return skip(`face: ${f}; feet: ${t}`);
   const failed = problems.some((q) => q.code === 'CHECK_STILL_REGIONS_DARK');
-  return { status: failed ? 'FAIL' : 'PASS', face: typeof f === 'string' ? { unmeasured: f } : f, feet: typeof t === 'string' ? { unmeasured: t } : t };
+  // Issue #231: a declaration is the feet half's first figure, measured or not.
+  const said = declared.length === 0 ? {} : { declared_not_planted: declared };
+  return { status: failed ? 'FAIL' : 'PASS', face: typeof f === 'string' ? { unmeasured: f } : f, feet: typeof t === 'string' ? { ...said, unmeasured: t } : { ...said, ...t } };
 }
 
 function fmt3(x: number): string {