spine-rigc 2.54.0 → 2.56.0

package/src/cli/core_commands.ts

@@ -21,7 +21,8 @@ import { chainFitLines, type ChainFitOptions, estimateChainFit } from '../chainf
 import { checkLines, CheckPlates } from '../check.ts';
 import { writeCheckPictures } from '../checkpics.ts';
 import { compile, type CompileOptions, droppedStateReason, relativeImagesPath } from '../compile.ts';
-import { CoreInputError } from '../core/index.ts';
+import { CoreInputError, readModel } from '../core/index.ts';
+import { leverFractionWhy, leverHeader, leverLines, leverReading, type LeverReading, type WhirlAnimation, WHIRL_HEADER, whirlLines, whirlReading } from '../whirl.ts';
 import { surveyOfBuild } from '../deformbuild.ts';
 import type { DeformSurvey } from '../deformsurvey.ts';
 import { deformReportBlock } from '../deformreport.ts';
@@ -32,9 +33,12 @@ import { MODEL_DOCUMENT_FILE, modelDocument } from '../model.ts';
 import { parseMotionSpec } from '../motion.ts';
 import { type InspectCompare, type InspectFrame, InspectError, inspectCandidate, INSPECT_DEFAULT_FPS, legendText, readBonePatterns, readShow, readTimes, readZoom } from '../inspect.ts';
 import { FOLDS_FILE, foldLine, foldsFileOf, foldsOf, foldsText, setupFaultLine } from '../folds.ts';
+import { AngleRangeError, angleRangeLine, type AngleRangeReading, angleRangesOf, type BonePair, readBonePairs } from '../anglerange.ts';
+import { outsideLine, outsideViewport, pinnedRecord, readViewportBox, viewportOfFramesFile, ViewportError } from '../viewportpin.ts';
+import { PASS_THROUGH_FILE, passFrameLine, type PassPair, passSummaryLine, passThroughFileOf, passThroughOf, passThroughText, PassThroughError, readPassPairs } from '../passthrough.ts';
 import { environmentCollisions, environmentFrame, EnvironmentError, environmentResponse, readEnvironmentSchedule, type EnvironmentStep } from '../environment.ts';
 import { estimatePose, poseLines, type PoseOptions } from '../pose.ts';
-import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser } from '../render_shared.ts';
+import { BACKGROUND, contactSheet, type Frame, FRAMES_SIDECAR, FRAMES_SPEC, frameSetDir, type FrameSet, type FramesSidecar, framingViewport, GEOMETRY_FILE, geometryFileOf, geometryText, loadCandidate, POSER_NAMES, type PoserName, PROTOCOL_FPS, refuseUnchosen, renderFrame, sampleAll, sampleAnimation, SETUP_POSE_DIR, SHEET_FILE, SHEET_TILE, sidecarViewport, type SkeletonFacts, type SlotSubset, SlotSubsetError, throughPoser, type Viewport, viewportFor } from '../render_shared.ts';
 import { type CompileResult } from '../types.ts';
 import { attachmentRegionJoins } from '../region_joins.ts';
 import { cmdRepack } from './repack.ts';
@@ -539,6 +543,75 @@ function environmentRefusal(given: string, steps: readonly EnvironmentStep[], sk
   return null;
 }
 
+/**
+ * `--pass-through <cloth>:<leg>[,…]` read against the skeleton's slots (issue
+ * #1413, `../passthrough.ts`), or refused as a usage error before anything is
+ * posed: a malformed list, an empty name, a slot the skeleton does not have, a
+ * pair named twice — each by its entry. `undefined` without the flag.
+ */
+function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): PassPair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readPassPairs(raw, facts.slots.map((slot) => slot.name));
+  } catch (err) {
+    if (err instanceof PassThroughError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/**
+ * `--angle-range`'s pairs, read against the skeleton's bones (issue #1414,
+ * `../anglerange.ts`), or refused as a usage error before anything is posed: a
+ * malformed list, an empty name, a bone the skeleton does not have, a bone read
+ * against itself, a pair named twice — each by its entry. `undefined` without the flag.
+ */
+function readAngleRangeFlag(raw: string | undefined, facts: SkeletonFacts): BonePair[] | undefined {
+  if (raw === undefined) return undefined;
+  try {
+    return readBonePairs(raw, facts.bones.map((bone) => bone.name));
+  } catch (err) {
+    if (err instanceof AngleRangeError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
+/** A box `render` was given rather than fitting one (issue #1414): the box flag's numbers, or an earlier render's grid. */
+type GivenViewport =
+  | { by: '--viewport'; box: { x: number; y: number; width: number; height: number } }
+  | { by: '--viewport-from'; path: string; viewport: Viewport };
+
+/**
+ * `--viewport` and `--viewport-from`, read before anything is read off the
+ * candidate (`../viewportpin.ts`): the two together are refused, and so is
+ * `--max` beside `--viewport-from`, whose file already fixes the pixel size; a
+ * malformed box, a path with no `frames.json` and a file whose grid is not one
+ * are refused by name. `undefined` without either flag.
+ */
+function readGivenViewport(flags: Record<string, string>): GivenViewport | undefined {
+  const box = flags.viewport;
+  const from = flags['viewport-from'];
+  if (box !== undefined && from !== undefined) {
+    throw new UsageError('--viewport and --viewport-from both give the box the frames are of; give one of them');
+  }
+  try {
+    if (box !== undefined) return { by: '--viewport', box: readViewportBox(box) };
+    if (from === undefined) return undefined;
+    if (flags.max !== undefined) {
+      throw new UsageError(
+        `--viewport-from takes no --max: the frames.json it reads fixes the pixel size as well as the box, so --max ${flags.max} ` +
+          'would put this render on another grid. Give --viewport <x,y,w,h> with --max for a box at another size',
+      );
+    }
+    const given = resolve(from);
+    const path = existsSync(given) && statSync(given).isDirectory() ? join(given, FRAMES_SIDECAR) : given;
+    if (!existsSync(path)) throw new UsageError(`--viewport-from ${from}: no ${FRAMES_SIDECAR} at ${path} — it takes an earlier render's ${FRAMES_SIDECAR}, or the directory \`render --out\` wrote it into`);
+    return { by: '--viewport-from', path, viewport: viewportOfFramesFile(readJsonFile(path), path) };
+  } catch (err) {
+    if (err instanceof ViewportError) throw new UsageError(err.message);
+    throw err;
+  }
+}
+
 /**
  * render — the frame series, drawn by the same rasteriser `check` measures with.
  *
@@ -557,6 +630,8 @@ export function cmdRender(flags: Record<string, string>): void {
   // Read before anything is read off the candidate, so a malformed schedule is refused before a line is printed.
   const environment = readEnvironmentFlag(flags);
   const maxSide = readPositiveNumber(flags, 'max', 256, 16);
+  // A box given rather than fitted (issue #1414), read before a line is printed, so a malformed one is refused first.
+  const given = readGivenViewport(flags);
   const outRoot = resolve(flags.out ?? 'render');
   const geometry = flags.geometry !== undefined;
   // The fold reading (issue #1383) is its own flag rather than a part of --geometry, so a caller that asked for
@@ -580,6 +655,8 @@ export function cmdRender(flags: Record<string, string>): void {
       }
     }
   }
+  // The pass-through reading (issue #1413) is its own flag for --folds' reason: without it, every file is the bytes it was.
+  const passThrough = flags['pass-through'];
   // The same refusal for the same reason: the reading is of every mesh the pose shows, whatever a picture leaves out.
   if (folds) {
     for (const flag of ['slot', 'hide'] as const) {
@@ -593,6 +670,19 @@ export function cmdRender(flags: Record<string, string>): void {
     }
   }
 
+  // And for the pass-through reading: it reads the two slots as the frame draws them, and a subset changes which draw.
+  if (passThrough !== undefined) {
+    for (const flag of ['slot', 'hide'] as const) {
+      if (flags[flag] !== undefined) {
+        throw new UsageError(
+          `--pass-through takes no --${flag}: it reads the cloth and the leg as the whole rig draws them, which a subset of the ` +
+            `drawn slots would change. Run \`rigc render --pass-through\` on the whole rig for the reading, and --${flag} ${flags[flag]} ` +
+            'without --pass-through for the pictures — both land on the same grid',
+        );
+      }
+    }
+  }
+
   console.log('rigc render');
   console.log(`  ..    skeleton ${skeletonPath}`);
   console.log(`  ..    atlas    ${atlasPath}${atlasText === null ? ` — not there (${ATLAS_ABSENT})` : ''}`);
@@ -610,6 +700,9 @@ export function cmdRender(flags: Record<string, string>): void {
   const only = readAnimationFlag(flags, [...facts.animations]);
   const skin = readSkinFlag(flags, [...facts.skins]);
   const subset = readSlotSubsetFlags(flags, facts, skin);
+  const passPairs = readPassThroughFlag(passThrough, facts);
+  // The angle reading (issue #1414) reads bones, which a subset of the drawn slots does not change, so it takes --slot/--hide.
+  const anglePairs = readAngleRangeFlag(flags['angle-range'], facts);
   // One object, so the framing and the frames cannot be posed under two
   // different skins — which would frame one shot with another shot's box.
   // Not annotated `PoseOptions`: that name is `src/pose.ts`'s in this file, and
@@ -653,14 +746,22 @@ export function cmdRender(flags: Record<string, string>): void {
     // sits at one point — every drawn bone unposed by the skin, or collapsed — as
     // an `UnframeablePoseError` (issue #997); neither reaches this. The roster is what
     // lets the second name the skins that pose a bone, whichever poser draws.
-    const viewport = framingViewport(poser, maxSide, pose, roster);
-    if (!viewport) {
+    const fitted = framingViewport(poser, maxSide, pose, roster);
+    if (!fitted) {
       throw new UsageError(
         `${skeletonPath} posed no drawable attachment in any animation or in its setup pose${
           skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`
         } — there is nothing to draw`,
       );
     }
+    // ⭐ A given box replaces the fitted one, and the framing still runs: it is what refuses a pose with nothing to draw,
+    // one that is not finite and one with no extent, and a box given over such a pose would draw it in silence.
+    const viewport =
+      given === undefined
+        ? fitted
+        : given.by === '--viewport'
+          ? viewportFor(given.box.x, given.box.y, given.box.x + given.box.width, given.box.y + given.box.height, maxSide)
+          : given.viewport;
 
     // `sampleAll` covers the skeleton with no animation at all, which files its one
     // setup-pose frame under the reserved name. Narrowing to one animation reuses
@@ -669,7 +770,10 @@ export function cmdRender(flags: Record<string, string>): void {
     // `--geometry` rides on the SAME call (issue #864): the bones and the whole
     // attachments are read off the skeleton at the step that drew each frame, so
     // the export's grid is this frame set's by construction.
-    const sampling = geometry ? { ...pose, bones: true, geometry: true } : folds ? { ...pose, geometry: true } : pose;
+    // The bones ride along for --geometry and --angle-range, the whole attachments for --geometry and the two readings off them.
+    const wantsBones = geometry || anglePairs !== undefined;
+    const wantsGeometry = geometry || folds || passPairs !== undefined;
+    const sampling = !wantsBones && !wantsGeometry ? pose : { ...pose, ...(wantsBones ? { bones: true } : {}), ...(wantsGeometry ? { geometry: true } : {}) };
     const sampled: Map<string, Frame[]> =
       only === undefined
         ? sampleAll(poser, fps, sampling)
@@ -694,9 +798,50 @@ export function cmdRender(flags: Record<string, string>): void {
         foldReadings.set(name, foldsFileOf(animation, fps, skin, foldsOf(poser.rest(skin, shown), read)));
       }
     }
-    return { viewport, sampled, geometryTexts, foldReadings };
+    // The pass-through reading, off the very pieces the frames are drawn from, in their draw order — one per set, every
+    // pair the flag names. A pair whose slot draws on no frame of any set drawn is refused rather than read as 0.
+    const passReadings = new Map<string, ReturnType<typeof passThroughFileOf>>();
+    if (passPairs !== undefined) {
+      const draws = new Set<string>();
+      for (const frames of sampled.values()) for (const frame of frames) for (const piece of frame.pieces) draws.add(piece.slot);
+      for (const pair of passPairs) {
+        for (const slot of [pair.cloth, pair.leg]) {
+          if (!draws.has(slot)) {
+            throw new UsageError(
+              `--pass-through: slot ${JSON.stringify(slot)} draws on no frame of [${[...sampled.keys()].join(', ')}]${skin === undefined ? '' : ` under skin ${JSON.stringify(skin)}`} ` +
+                '— it shows no region or mesh there, so it has no drawn outline to read',
+            );
+          }
+        }
+      }
+      for (const [name, frames] of sampled) {
+        const animation = name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name;
+        const shown = frames.map((frame) => frame.attachments ?? []);
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, pieces: frame.pieces, attachments: frame.attachments ?? [] }));
+        try {
+          passReadings.set(name, passThroughFileOf(animation, fps, skin, passThroughOf(passPairs, poser.rest(skin, shown), read, pages)));
+        } catch (err) {
+          if (err instanceof PassThroughError) throw new UsageError(`--pass-through, ${JSON.stringify(name)}: ${err.message}`);
+          throw err;
+        }
+      }
+    }
+    // The angle reading, off the very bones the frames were posed with — one per set, every pair the flag names.
+    const angleReadings = new Map<string, AngleRangeReading[]>();
+    if (anglePairs !== undefined) {
+      for (const [name, frames] of sampled) {
+        const read = frames.map((frame) => ({ index: frame.index, time: frame.time, bones: frame.bones ?? [] }));
+        try {
+          angleReadings.set(name, angleRangesOf(anglePairs, read, JSON.stringify(name)));
+        } catch (err) {
+          if (err instanceof AngleRangeError) throw new UsageError(err.message);
+          throw err;
+        }
+      }
+    }
+    return { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings };
   });
-  const { viewport, sampled, geometryTexts, foldReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -707,6 +852,17 @@ export function cmdRender(flags: Record<string, string>): void {
   }
   console.log(`  ..    ${viewport.width}x${viewport.height}px at ${fps} fps, ${sampled.size} set(s) -> ${outRoot}`);
   if (!facts.declaresStage) console.log(`  ..    ${STAGELESS_FRAMING.render}`);
+  // A given box (issue #1414): said with the box it replaced, and every slot it leaves part of out, by set and frame.
+  const outside = given === undefined ? [] : outsideViewport(sampled, viewport);
+  if (given !== undefined) {
+    const f = (n: number): string => String(Number(n.toFixed(4)));
+    const box = (v: Viewport): string => `world x ${f(v.minX)}..${f(v.maxX)}, y ${f(v.minY)}..${f(v.maxY)}`;
+    console.log(
+      `  ..    viewport given by ${given.by}${given.by === '--viewport-from' ? ` ${given.path}` : ''}: ${box(viewport)} at ${f(viewport.scale)} px per unit, y up ` +
+        `(fitted, the box would be ${box(fitted)}) — ${outside.length === 0 ? 'every drawn piece of every frame is inside it' : `${outside.length} slot(s) reach past it, named below`}`,
+    );
+    for (const reading of outside) console.log(`  ..    outside  ${outsideLine(reading, fps)}`);
+  }
 
   mkdirSync(outRoot, { recursive: true });
   const sets: FrameSet[] = [];
@@ -715,7 +871,7 @@ export function cmdRender(flags: Record<string, string>): void {
   for (const [name, frames] of sampled) {
     // Same naming as a reference render: the protocol rate says nothing, any
     // other rate says itself, so two rates of one animation sit side by side.
-    const dirName = fps === PROTOCOL_FPS ? name : `${name}@${fps}fps`;
+    const dirName = frameSetDir(name, fps);
     const dir = join(outRoot, dirName);
     // Cleared rather than written over: a shorter animation would otherwise leave
     // the tail of a longer previous run on disk, and stale frames in a frame set
@@ -733,6 +889,8 @@ export function cmdRender(flags: Record<string, string>): void {
     if (geometryOut !== undefined) writeFileSync(join(dir, GEOMETRY_FILE), geometryOut);
     const foldReading = foldReadings.get(name);
     if (foldReading !== undefined) writeFileSync(join(dir, FOLDS_FILE), foldsText(foldReading));
+    const passReading = passReadings.get(name);
+    if (passReading !== undefined) writeFileSync(join(dir, PASS_THROUGH_FILE), passThroughText(passReading));
     const duration = frames[frames.length - 1].time;
     sets.push({
       dir: dirName,
@@ -746,7 +904,9 @@ export function cmdRender(flags: Record<string, string>): void {
     const how = frames.length === 1 ? 'a single pose' : `${duration.toFixed(3)}s`;
     const folding = foldReading?.meshes.filter((m) => m.worst !== null).length ?? 0;
     const foldNote = foldReading === undefined ? '' : ` + ${FOLDS_FILE} (${folding} of ${foldReading.meshes.length} mesh(es) fold)`;
-    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}`;
+    const passing = passReading?.pairs.filter((p) => p.frames.length > 0).length ?? 0;
+    const passNote = passReading === undefined ? '' : ` + ${PASS_THROUGH_FILE} (${passing} of ${passReading.pairs.length} pair(s) pass through)`;
+    const extras = `${sheet ? ` + ${SHEET_FILE}` : ''}${geometryOut === undefined ? '' : ` + ${GEOMETRY_FILE}`}${foldNote}${passNote}`;
     console.log(`  ..    ${name.padEnd(16)} ${frames.length} frame(s), ${how}${extras} -> ${dir}`);
     for (const mesh of foldReading?.meshes ?? []) {
       const key = `${mesh.slot}\u0000${mesh.attachment}`;
@@ -756,6 +916,13 @@ export function cmdRender(flags: Record<string, string>): void {
       const line = foldLine(foldReading?.animation ?? null, fps, mesh);
       if (line !== null) console.log(`  ..    folds    ${line}`);
     }
+    for (const pair of passReading?.pairs ?? []) {
+      console.log(`  ..    pass     ${passSummaryLine(passReading?.animation ?? null, fps, pair)}`);
+      for (const frame of pair.frames) console.log(`  ..    pass     ${passFrameLine(passReading?.animation ?? null, pair, frame)}`);
+    }
+    for (const reading of angleReadings.get(name) ?? []) {
+      console.log(`  ..    angle    ${angleRangeLine(name === SETUP_POSE_DIR && facts.animations.length === 0 ? null : name, fps, reading)}`);
+    }
   }
 
   // The sidecar is what makes this a frame SET rather than a pile of pictures:
@@ -773,6 +940,8 @@ export function cmdRender(flags: Record<string, string>): void {
     ...subsetFields(subset),
     // Written only when a schedule was given (issue #1416): a render without one says nothing and stays the bytes it was.
     ...(environment === undefined ? {} : { environment: environment.steps }),
+    // Written only when the box was given (issue #1414): a fitted render says nothing and stays the bytes it was.
+    ...(given === undefined ? {} : { pinned: pinnedRecord(given.by, outside) }),
     background: BACKGROUND,
     // The one spelling `geometry.json` repeats, so the two files cannot state
     // two boxes for one grid.
@@ -826,12 +995,12 @@ export function cmdInspect(flags: Record<string, string>): void {
   let frame: InspectFrame = { kind: 'shot' };
   if (flags.zoom !== undefined) frame = { kind: 'zoom', ...readZoom(flags.zoom) };
   if (flags.viewport !== undefined) {
-    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    try {
+      frame = { kind: 'viewport', ...readViewportBox(flags.viewport) };
+    } catch (err) {
+      if (err instanceof ViewportError) throw new UsageError(err.message);
+      throw err;
     }
-    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
-    frame = { kind: 'viewport', x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   const target = resolve(flags.out ?? DEFAULT_INSPECT_OUT);
   const out = existsSync(target) && statSync(target).isDirectory() ? join(target, DEFAULT_INSPECT_OUT) : target;
@@ -1107,6 +1276,11 @@ function refuseUnposableArt(result: CompileResult, opts: CompileOptions): void {
 export function cmdExplain(flags: Record<string, string>): void {
   // `--poser` is refused by its spelling before anything compiles (issue #1019): it chooses the deform survey's reader and poser.
   const poser = readPoserFlag(flags);
+  // `--lever-fold` is refused by its value before anything compiles, too (issue #1427): the fraction is the caller's and
+  // has no default, so a value that is not one is a usage error rather than a reading taken at a guess.
+  const leverFold = flags['lever-fold'] === undefined ? null : Number(flags['lever-fold']);
+  const leverWhy = leverFold === null ? null : leverFractionWhy(leverFold);
+  if (leverWhy !== null) throw new UsageError(`--lever-fold ${JSON.stringify(flags['lever-fold'])}: ${leverWhy}`);
   const { label, opts } = resolveCut(flags);
   console.log(`rigc explain ${label}`);
   // See the identical pair of lines in `cmdBuild` for why both paths are named
@@ -1303,6 +1477,24 @@ export function cmdExplain(flags: Record<string, string>): void {
               console.log(`               transform ${gen.kind}  ${gen.stated}`);
               console.log(`               ${gen.formula}`);
               for (const line of gen.derived) console.log(`                 ${line}`);
+              // The envelope's weights, one per vertex, because they are half
+              // of every number below (issue #1413): each offset is
+              // round(w × the un-enveloped offset), and a reader holding these
+              // and the model reproduces the run without a second evaluation.
+              if (gen.envelope !== undefined) {
+                const env = gen.envelope;
+                console.log(`               envelope  ${env.stated}`);
+                console.log(`               ${env.formula}`);
+                console.log(
+                  `                 each offset below is round(w × the un-enveloped offset): ${env.zero} vertex(es) at w 0, ` +
+                    `${env.full} at 1, ${gen.vertexCount - env.zero - env.full} between`,
+                );
+                for (let v = 0; v < env.weights.length; v += 8) {
+                  const ws: string[] = [];
+                  for (let k = v; k < Math.min(v + 8, env.weights.length); k++) ws.push(`v${String(k).padStart(3)} ${env.weights[k]}`);
+                  console.log(`                 w  ${ws.join('  ')}`);
+                }
+              }
               console.log(
                 `               ${gen.vertexCount} vertices, largest offset ${gen.maxOffset}px at vertex ${gen.maxOffsetVertex}`,
               );
@@ -1367,6 +1559,36 @@ export function cmdExplain(flags: Record<string, string>): void {
     for (const ph of result.physics) {
       console.log(`  ${ph.name.padEnd(12)} bone=${ph.bone.padEnd(14)} components=[${ph.components.join(', ')}] mix=${ph.mix} drivesMesh=${ph.drivesMesh}`);
     }
+    // The whirl reading (issue #1423): how far each constraint's bone turns in one step, walked by the core from the
+    // setup pose — `src/whirl.ts` says why that walk and not render's. It decides nothing, so it sits in the report
+    // rather than in the gate, and explain's exit is the same whatever it prints.
+    console.log(`\n${WHIRL_HEADER}`);
+    let reading: WhirlAnimation[] | null = null;
+    try {
+      reading = whirlReading(readModel(modelDocument(result.model, result.skeletonText, result.atlasText), `the whirl reading of ${label}`));
+    } catch (err) {
+      if (!(err instanceof CoreInputError)) throw err;
+      console.log(`  ..    turn     not read — the core refused the model document: ${err.message}`);
+    }
+    if (reading !== null && reading.length === 0) console.log('  ..    turn     not read — the skeleton declares no animation to walk');
+    for (const line of whirlLines(reading ?? [])) console.log(`  ..    turn     ${line}`);
+    // The lever reading (issue #1427): on the same walk, the steps a scaleX drive's inertia lever divides by a collapsed
+    // divisor, and the steps its scale factor jumps. Only when asked for, because its fraction has no default —
+    // and said so when not asked, rather than left out in silence.
+    if (leverFold === null) {
+      console.log('\n  ..    lever    not read — `--lever-fold <fraction>` states the fraction of its setup divisor a scaleX lever is named for dividing below, and it has no default');
+    } else {
+      console.log(`\n${leverHeader(leverFold)}`);
+      let levers: LeverReading | null = null;
+      try {
+        levers = leverReading(readModel(modelDocument(result.model, result.skeletonText, result.atlasText), `the lever reading of ${label}`), leverFold);
+      } catch (err) {
+        if (!(err instanceof CoreInputError)) throw err;
+        console.log(`  ..    lever    not read — the core refused the model document: ${err.message}`);
+      }
+      if (levers !== null && levers.animations.length === 0 && levers.unread.length < result.physics.length) console.log('  ..    lever    not read — the skeleton declares no animation to walk');
+      for (const line of levers === null ? [] : leverLines(levers)) console.log(`  ..    lever    ${line}`);
+    }
   }
 
   // Path constraints, with the curve each one follows MEASURED — its length and

package/src/cli/shared.ts

@@ -38,6 +38,8 @@ import { checkAgainstFrames, type CheckOptions, CheckPlates, type CheckReport }
 import { compile, CompileError, droppedStateReason, headerBoundsOf, type CompileOptions } from '../compile.ts';
 import { depthStepLevels, type FoldLimit, type TurnCeiling } from '../depth.ts';
 import { FOLDS_FILE } from '../folds.ts';
+import { PASS_THROUGH_FILE, PASS_THROUGH_RUN } from '../passthrough.ts';
+import { readViewportBox, ViewportError } from '../viewportpin.ts';
 import { parseJsonWithPosition } from '../json-position.ts';
 import { RUNG_IDS } from '../ladder.ts';
 import { MODEL_DOCUMENT_FILE, MODEL_DOCUMENT_SPEC, modelDocument, spineFileSha256 } from '../model.ts';
@@ -674,12 +676,12 @@ function readCheckFlags(
     out.fps = fps;
   }
   if (flags.viewport !== undefined) {
-    const parts = flags.viewport.split(',').map((s) => Number(s.trim()));
-    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
-      throw new UsageError('--viewport takes four numbers: <x>,<y>,<width>,<height> — the world box, y up');
+    try {
+      out.viewport = readViewportBox(flags.viewport);
+    } catch (err) {
+      if (err instanceof ViewportError) throw new UsageError(err.message);
+      throw err;
     }
-    if (parts[2] <= 0 || parts[3] <= 0) throw new UsageError('--viewport width and height must be positive');
-    out.viewport = { x: parts[0], y: parts[1], width: parts[2], height: parts[3] };
   }
   if (flags.as !== undefined) out.as = flags.as;
   // The name is not checked against the candidate here: `check` owns that
@@ -1013,6 +1015,24 @@ const FLAG_MEANINGS: Record<string, string> = {
     'with where they are (the world box of their posed vertices) and how big (their setup-pose area, and its share of the mesh\'s). ' +
     'One line per mesh that folds; a triangle degenerate or inverted at the setup pose is said once and never counted. ' +
     'A reading, not a gate. Not with --slot/--hide: it reads every mesh the pose shows',
+  'pass-through':
+    `also read where a cloth slot passes through a leg slot, for each <cloth>:<leg> pair, and write ${PASS_THROUGH_FILE} into ` +
+    'each frame directory: the frames where the cloth draws over the leg and its drawn side lies inside the leg\'s drawn ' +
+    `outline by ${PASS_THROUGH_RUN} steps or more — rows read in the cloth's setup pose from its hem's corner up, the run stepped in ` +
+    'world units, one texel of the coarser drawing to a step — each with the depth and the world box. One line per pair, and one per frame that passes through. ' +
+    'The order is the declaration: the first name must draw over the second for a frame to be read. A reading, not a gate. ' +
+    'An unknown slot, a slot that draws on no frame, a malformed list and a pair named twice are refused by name. Not with --slot/--hide',
+  'angle-range':
+    'also read, for each <bone>:<relative-to> pair, the range of the first bone\'s world direction against the second\'s over each set\'s ' +
+    'frames — its rotationX less the other\'s, followed from frame to frame so a sweep past ±180° reads as itself — and print one line per ' +
+    'pair per set: the lowest and the highest angle in degrees, the span, and the frame each was first reached on. Read on the frames\' own ' +
+    'grid, so a peak between two frames is not read. A reading, not a gate: nothing is written. An unknown bone, a bone against itself, ' +
+    'a malformed list and a pair named twice are refused by name, and so is a bone with no direction on a frame (a world matrix of zero)',
+  'viewport-from':
+    "draw on an earlier render's grid exactly — the box, the scale and the pixel size its frames.json records (the file, or the " +
+    'directory `render --out` wrote it into) — so a world point lands on the same pixel in both renders. A slot that reaches past ' +
+    'the box is named as under --viewport, and frames.json records the same under `pinned`. Not with --viewport, and not with --max: ' +
+    'the file fixes the pixel size',
   environment:
     'the world the rig\'s physics answers, in time: a file { "spec": "rigc-environment/1", "steps": [{ "t": <seconds>, ' +
     '"wind"?: [x, y], "gravity"?: [x, y] }, …] }, x right and y down, each step holding from its t until the next and set ' +
@@ -1027,6 +1047,12 @@ const FLAG_MEANINGS: Record<string, string> = {
     'line of the render or the check report says which and why. `--poser core` on an input that cannot carry it is refused by name. ' +
     "`explain`: which reads and poses the DEFORM block's survey — `core` (the model document the compile writes, spine-core untouched) or " +
     '`spine` (the Spine skeleton parsed and posed by spine-core); default `core`, and `spine` where the core refuses the document, which the block names',
+  'lever-fold':
+    '`explain` only: also read, on the turn lines\' walk, the steps where a physics constraint that drives scaleX has its inertia lever ' +
+    'divide by less than this fraction (above 0, at most 1) of the divisor it takes at the setup pose — the bone\'s length times its world x-axis ' +
+    'length, less scaleLag × shown on a drive that does not rotate — and the steps where the scale factor it applies moves by more than the ' +
+    'bone\'s setup scale in one step: each line the constraint, the steps, the extreme value and its step. No default: without it the reading ' +
+    'is not taken, and says so; a value that is not such a fraction is refused by name. A reading, not a gate',
   'texture-from':
     "also measure this run through this atlas's texels, keeping the candidate's own geometry, and report how much " +
     'of the MAE is texture resampling rather than the rig — pass the atlas the reference frames were rendered ' +
@@ -1202,6 +1228,9 @@ const FLAG_VALUES: Record<string, string> = {
   'texture-from': '<path>',
   poser: 'core|spine',
   environment: '<schedule.json>',
+  'pass-through': '<cloth>:<leg>[,<cloth>:<leg>…]',
+  'angle-range': '<bone>:<relative-to>[,…]',
+  'viewport-from': '<frames.json|dir>',
   reference: '<dir|skeleton.json>',
   'reference-atlas': '<path>',
   bones: `<correspondence.json|${IDENTITY_CORRESPONDENCE}>`,
@@ -1216,6 +1245,7 @@ const FLAG_VALUES: Record<string, string> = {
   scale: '<min,max>',
   rotation: '<min,max>',
   'max-residual': '<0..1>',
+  'lever-fold': '<fraction>',
   anchor: '<pose.json>',
   hinge: '<min,max>',
   stretch: '<ratio>',
@@ -1467,8 +1497,9 @@ export const COMMANDS: CommandDoc[] = [
       'rigc explain --rig <path> --motion <path> --out <dir> [--manifest <path>] [--images <dir>] [--poser core|spine]   (it never gates, and writes nothing)',
       'rigc explain … --atlas-in <skeleton.atlas>                  (resolve the parts against a pack somebody already made, as build does)',
       'rigc explain --cut <name> --cuts <cuts.json>',
+      'rigc explain … --lever-fold <fraction>                     (also name the steps a scaleX lever divides by a collapsed length)',
     ],
-    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser'],
+    flags: ['rig', 'motion', 'out', 'manifest', 'images', 'atlas-in', 'cut', 'cuts', 'poser', 'lever-fold'],
     notes: [
       'this line said "the same arguments as build, minus --profile" and was false in both',
       'directions (issue #697): --atlas-in was not listed here, so the one flag that lets this',
@@ -1608,11 +1639,25 @@ export const COMMANDS: CommandDoc[] = [
       'rigc render --candidate <dir | skeleton.json> [--animation <name>] [--skin <name>] [--fps 12] [--max 256] [--geometry] [--folds] [--poser core|spine] [--out render/]',
       'rigc render … --slot <name[,name…]> | --hide <name[,name…]>   (a subset of the slots, on the whole rig\'s grid)',
       'rigc render … --environment <schedule.json>   (the wind and gravity the physics answers, in time)',
+      'rigc render … --pass-through <cloth>:<leg>[,…]   (the frames where a cloth drawn over a leg passes through it)',
+      'rigc render … --angle-range <bone>:<relative-to>[,…]   (how far a bone turns against another, per animation)',
+      'rigc render … --viewport <x,y,w,h> | --viewport-from <frames.json>   (a box given, not fitted: two renders on one pixel grid)',
     ],
-    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'geometry', 'folds', 'environment', 'poser', 'out'],
+    flags: ['candidate', 'atlas', 'animation', 'skin', 'slot', 'hide', 'fps', 'max', 'viewport', 'viewport-from', 'geometry', 'folds', 'pass-through', 'angle-range', 'environment', 'poser', 'out'],
     overrides: {
       out: { value: '<dir>', meaning: 'directory to write the frame series into (default `render/`)' },
-      fps: { meaning: `frames per second to sample the animation at (default ${PROTOCOL_FPS})` },
+      fps: {
+        meaning:
+          `frames per second to sample the animation at (default ${PROTOCOL_FPS}). A set drawn at any rate but the default is written to ` +
+          '`<anim>@<fps>fps/` rather than `<anim>/`, so two rates sit side by side: `--fps 24` writes `<anim>@24fps/`, and the default 12 writes `<anim>/`',
+      },
+      viewport: {
+        meaning:
+          'draw every frame over this world box, y up — x,y its bottom-left corner, the numbers frames.json\'s `viewport` records — ' +
+          'instead of the box fitted to the rig; its pixel size follows from --max. A slot that reaches past the box is named by set and ' +
+          'frame, with how far and on which side: what lies past it is not drawn, since each frame is the box. frames.json records that ' +
+          'the box was given, and those slots, under `pinned`. Not with --viewport-from',
+      },
     },
   },
   {