spine-rigc 2.55.0 → 2.56.0

package/src/anglerange.ts

@@ -0,0 +1,190 @@
+/**
+ * How far one bone turns against another over an animation — the reading behind
+ * `rigc render --angle-range <bone>:<relative-to>[,…]` (issue #1414).
+ *
+ * ⭐ **A reading, not a gate**, as `--folds` and `--pass-through` are. A physics
+ * value has no scale an author can see: §4.6 lists `inertia`, `strength` and the
+ * rest with their bounds, and nothing said what `inertia` 0.5 does to a 54-unit
+ * chain under a hip swing — the first try on a real rig was four times too big.
+ * The answer is a number the pose already holds: how far the link turned against
+ * the bone it hangs from. So this reads it off the frames `render` draws and
+ * decides nothing.
+ *
+ * ## What the range is
+ *
+ * At each frame the bones are posed by whichever poser draws the frames, and each
+ * bone's **world direction** is that poser's own `rotationX` — the direction its x
+ * axis points, degrees counter-clockwise, y up (`BoneSnapshot`), never a second
+ * opinion recomputed from the matrix here. The relative angle is
+ *
+ *     rotationX(bone) − rotationX(relative-to)
+ *
+ * taken into (−180, 180] on the first frame read, and then **followed**: each
+ * later frame's difference is moved by whole turns to within half a turn of the
+ * frame before it. So a link that sweeps 200° reads 200°, not −160°, and one that
+ * sways through ±180° does not read a jump of a whole turn. Following assumes no
+ * two consecutive frames are half a turn or more apart, which a frame grid that
+ * coarse could not show anyway.
+ *
+ * ⚠️ It is the angle **drawn**, not the bone's local `rotation`. The two agree for
+ * a child of the other bone when the parent carries no non-uniform scale or shear;
+ * otherwise they differ, and the drawn one is what a viewer sees.
+ *
+ * The range is over the frames on the render's own grid — `--fps`, from t = 0 to
+ * the animation's last frame — so a peak between two frames is not read. A bone
+ * the posed skin leaves unposed, or one scaled to nothing, has no direction: its
+ * world matrix is zero, and the reading is refused naming the bone and the frame
+ * rather than read as 0°.
+ *
+ * Pure: no clock, no randomness, no runtime. The bone snapshots are handed in by
+ * whichever poser drew the frames.
+ */
+import type { BoneSnapshot } from './render_shared.ts';
+
+/** One pair as the flag names it: the bone whose angle is read, and the bone it is read against. */
+export interface BonePair {
+  bone: string;
+  relativeTo: string;
+}
+
+/** A malformed `--angle-range` value, or a pose the reading has no angle for — said by name. */
+export class AngleRangeError extends Error {}
+
+/**
+ * `--angle-range`'s value — `<bone>:<relative-to>[,<bone>:<relative-to>…]` —
+ * read against the skeleton's bones, or refused naming the entry: an empty
+ * entry, one without exactly one `:`, an empty name, a bone the skeleton does not
+ * have (with the bones it does), a bone read against itself (always 0°), and a
+ * pair named twice.
+ */
+export function readBonePairs(raw: string, bones: readonly string[]): BonePair[] {
+  const form = '<bone>:<relative-to>[,<bone>:<relative-to>…]';
+  const pairs: BonePair[] = [];
+  const entries = raw.split(',');
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i].trim();
+    if (entry === '') throw new AngleRangeError(`--angle-range ${JSON.stringify(raw)}: entry ${i} is empty — it takes ${form}`);
+    const parts = entry.split(':');
+    if (parts.length !== 2) {
+      throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} has ${parts.length - 1} ":" — it takes ${form}, one ":" per pair`);
+    }
+    const [bone, relativeTo] = parts.map((p) => p.trim());
+    for (const [role, name] of [['bone', bone], ['relative-to bone', relativeTo]] as const) {
+      if (name === '') throw new AngleRangeError(`--angle-range: entry ${i} ${JSON.stringify(entry)} names no ${role} — it takes ${form}`);
+      if (!bones.includes(name)) {
+        throw new AngleRangeError(`--angle-range: entry ${i} names ${role} ${JSON.stringify(name)}, which this skeleton does not have; its bones are [${bones.join(', ')}]`);
+      }
+    }
+    if (bone === relativeTo) {
+      throw new AngleRangeError(`--angle-range: entry ${i} reads bone ${JSON.stringify(bone)} against itself, which is 0° on every frame — name a second bone`);
+    }
+    const again = pairs.findIndex((p) => p.bone === bone && p.relativeTo === relativeTo);
+    if (again >= 0) throw new AngleRangeError(`--angle-range: entry ${i} names "${bone}:${relativeTo}" again — entry ${again} already reads it`);
+    pairs.push({ bone, relativeTo });
+  }
+  return pairs;
+}
+
+/** One sampled frame: its index, its time, and every bone's world transform. */
+export interface AngleFrame {
+  index: number;
+  time: number;
+  bones: readonly BoneSnapshot[];
+}
+
+/** One extreme of a range: the angle, degrees, and the frame that reached it first. */
+export interface AngleExtreme {
+  degrees: number;
+  index: number;
+  time: number;
+}
+
+/** One pair's reading over one set. */
+export interface AngleRangeReading {
+  bone: string;
+  relativeTo: string;
+  /** Frames read — every frame of the set. */
+  frames: number;
+  low: AngleExtreme;
+  high: AngleExtreme;
+}
+
+/**
+ * Wrong readings the suite plants to see its controls go red (issue #1414):
+ * `worldAngle` reads the bone's own world direction and ignores the bone it is
+ * read against; `noFollow` leaves each frame's difference in (−180, 180] rather
+ * than following it from the frame before.
+ */
+export interface AnglePlant {
+  worldAngle?: true;
+  noFollow?: true;
+}
+
+/** `d` taken into (−180, 180]. */
+function wrapped(d: number): number {
+  let r = d % 360;
+  if (r <= -180) r += 360;
+  if (r > 180) r -= 360;
+  return r;
+}
+
+/** A world matrix with no direction — every entry zero: an unposed bone, or one scaled to nothing. */
+function directionless(b: BoneSnapshot): boolean {
+  return b.a === 0 && b.b === 0 && b.c === 0 && b.d === 0;
+}
+
+/**
+ * Each pair's range over `frames`, in the pairs' order — refused by
+ * `AngleRangeError`, naming the bone and the frame, where a bone has no
+ * direction (`directionless`), and naming the bone where a frame carries no
+ * snapshot of it at all (frames sampled without `{ bones: true }`).
+ */
+export function angleRangesOf(pairs: readonly BonePair[], frames: readonly AngleFrame[], where: string, plant: AnglePlant = {}): AngleRangeReading[] {
+  return pairs.map(({ bone, relativeTo }) => {
+    let previous: number | null = null;
+    let low: AngleExtreme | null = null;
+    let high: AngleExtreme | null = null;
+    for (const frame of frames) {
+      const at = (name: string): BoneSnapshot => {
+        const found = frame.bones.find((b) => b.name === name);
+        if (found === undefined) throw new AngleRangeError(`--angle-range, ${where} frame ${frame.index}: no world transform for bone ${JSON.stringify(name)} was sampled`);
+        if (directionless(found)) {
+          throw new AngleRangeError(
+            `--angle-range, ${where} frame ${frame.index} (t=${frame.time.toFixed(4)}s): bone ${JSON.stringify(name)} has no direction — its world matrix is zero ` +
+              '(a bone the posed skin leaves unposed, or one scaled to nothing), so it has no angle to read',
+          );
+        }
+        return found;
+      };
+      const a = at(bone);
+      const b = at(relativeTo);
+      const difference = plant.worldAngle === true ? a.rotationX : a.rotationX - b.rotationX;
+      let angle = wrapped(difference);
+      if (previous !== null && plant.noFollow !== true) angle += 360 * Math.round((previous - angle) / 360);
+      previous = angle;
+      if (low === null || angle < low.degrees) low = { degrees: angle, index: frame.index, time: frame.time };
+      if (high === null || angle > high.degrees) high = { degrees: angle, index: frame.index, time: frame.time };
+    }
+    if (low === null || high === null) throw new AngleRangeError(`--angle-range, ${where}: no frame was sampled`);
+    return { bone, relativeTo, frames: frames.length, low, high };
+  });
+}
+
+/** Degrees to four places, with a rounding to zero printed as `0.0000` rather than `-0.0000`. */
+export function degreesText(d: number): string {
+  const text = d.toFixed(4);
+  return text === '-0.0000' ? '0.0000' : text;
+}
+
+/**
+ * The printed line: the set, the pair, the low and the high with the frame each
+ * was first reached on, the span, and the grid it was read on.
+ */
+export function angleRangeLine(animation: string | null, fps: number, r: AngleRangeReading): string {
+  const where = animation === null ? 'the setup pose' : JSON.stringify(animation);
+  return (
+    `${where}: bone ${JSON.stringify(r.bone)} against ${JSON.stringify(r.relativeTo)} ranges ${degreesText(r.low.degrees)}° to ${degreesText(r.high.degrees)}° ` +
+    `(a span of ${degreesText(r.high.degrees - r.low.degrees)}°) over ${r.frames} frame(s) at ${fps} fps; ` +
+    `lowest at frame ${r.low.index} (t=${r.low.time.toFixed(4)}s), highest at frame ${r.high.index} (t=${r.high.time.toFixed(4)}s)`
+  );
+}

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,10 +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';
@@ -556,6 +559,59 @@ function readPassThroughFlag(raw: string | undefined, facts: SkeletonFacts): Pas
   }
 }
 
+/**
+ * `--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.
  *
@@ -574,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
@@ -643,6 +701,8 @@ export function cmdRender(flags: Record<string, string>): void {
   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
@@ -686,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
@@ -702,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 || passPairs !== undefined ? { ...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)
@@ -755,9 +826,22 @@ export function cmdRender(flags: Record<string, string>): void {
         }
       }
     }
-    return { viewport, sampled, geometryTexts, foldReadings, passReadings };
+    // 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, passReadings } = posed.value;
+  const { viewport, fitted, sampled, geometryTexts, foldReadings, passReadings, angleReadings } = posed.value;
   console.log(`  ..    poser    ${posed.note}`);
   if (environment !== undefined) {
     const response = environmentResponse(skeletonText);
@@ -768,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[] = [];
@@ -776,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
@@ -825,6 +920,9 @@ export function cmdRender(flags: Record<string, string>): void {
       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:
@@ -842,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.
@@ -895,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;
@@ -1176,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
@@ -1372,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}`,
               );
@@ -1436,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

@@ -39,6 +39,7 @@ import { compile, CompileError, droppedStateReason, headerBoundsOf, type Compile
 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';
@@ -675,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
@@ -1021,6 +1022,17 @@ const FLAG_MEANINGS: Record<string, string> = {
     '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 ' +
@@ -1035,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 ' +
@@ -1211,6 +1229,8 @@ const FLAG_VALUES: Record<string, string> = {
   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}>`,
@@ -1225,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>',
@@ -1476,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',
@@ -1618,11 +1640,24 @@ export const COMMANDS: CommandDoc[] = [
       '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', 'pass-through', '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',
+      },
     },
   },
   {