@rig-c/pose 0.31.1 → 0.32.0

package/src/retarget.ts

@@ -81,8 +81,8 @@ import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
-import type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { figureScaleOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
+import type { BlendHold, Closure, Feet, Floor, LegScale, LegSegmentRatio, PathPose, Posing, Side, Stance } from './legs.ts';
+import { figureScaleOf, freeAnkleShiftOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, shiftOver, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
 import type { BodyReading, FaceReading, YawSetSwitch } from './face.ts';
 import { readBody, readFace, readFaceAngles, selectYawSets } from './face.ts';
 
@@ -124,12 +124,29 @@ export const NOD_RESIDUAL_HEAD_GAIN = 1.6;
  */
 export const HEAD_ANCHOR_FRAME: 'head-local' | 'world-fixed' | 'off' = 'head-local';
 
+/** How the nod's baseline was read (rig-c/pose#241): none on an in-place sequence (frame 0, no clamp), else the ±0.5 s detrend window, wrapped on a `clean --loop` sequence or cut at the clip's ends. */
+export type NodWindow = 'in-place' | 'wrapped' | 'cut';
+
 export interface HeadNodReading {
   bone: string;
+  /** The chain that carries the eye line (rig-c/pose#241). */
+  chain: string;
   maxNod: number;
   rawY: number[];
   clampedY: number[];
   residual: number[];
+  /** The baseline's window (#241), and its half width in frames (0 in place). */
+  window: NodWindow;
+  halfWin: number;
+  /** Whether a translate track was keyed (false: the eyes did not move against the neck past the writer's rounding). */
+  keyed: boolean;
+}
+
+/** Why the eye-line chain keys no nod (rig-c/pose#241): switched off in the map, or a reading it cannot take. */
+export interface NodSkipped {
+  bone: string;
+  chain: string;
+  why: string;
 }
 
 export interface RetargetOptions extends SwitchOptions {
@@ -153,8 +170,10 @@ export interface RetargetOptions extends SwitchOptions {
   floor?: number;
   /** While a set whose arm is drawn raised shows, its wrist is placed against the rig's head in eye distances (rig-c/pose#62); false (the default) keeps the pose's angles. */
   raisedByHead?: boolean;
-  /** The sequence's `travel` (rig-c/pose#92): "in-place" makes --plant-feet let the supporting foot follow its own track and close the loop; absent, nothing changes. */
+  /** The sequence's `travel` (rig-c/pose#92, #242): "in-place" reads the supports, the camera-zoom normalisations and the head nod as a loop, with or without --plant-feet, and makes --plant-feet let the supporting foot follow its own track and close the loop; absent, nothing changes. */
   travel?: Travel;
+  /** The sequence was cleaned with `--loop` (its `cleaned.params.loop`, rig-c/pose#241): the head nod's detrend window wraps, the last frame running into the first. */
+  loop?: boolean;
 }
 
 export interface Hold {
@@ -296,6 +315,51 @@ export interface RangeDemand {
   limits: [number, number];
 }
 
+/**
+ * A `reach` chain whose aim departs from its pose pair's own picture angle
+ * (rig-c/pose#236), and the two things that make it: the bone's origin sits off
+ * the anchor's (a lever: the target is the pair's end, so a pair turning by θ
+ * about the anchor turns the aim from an origin partway up it by more than θ),
+ * or a bone above it is turned, or translated other than by the anchor's own
+ * travel (which the target carries too, so it cancels). A reading — the keys
+ * are the reach's, unchanged.
+ */
+export interface ReachReading {
+  chain: string;
+  bone: string;
+  /** The pair: the chain's first joint (the translated joint) and its second. */
+  joints: [string, string];
+  /** The anchor (the translated bone), and the setup distance from its origin to the bone's: world units, and as a fraction of the reached length (the pair's median picture length, scaled). */
+  anchor: string;
+  offset: { units: number; ofLength: number };
+  /** The bones above it the animation moves: by a rotate track, or a translate track other than the anchor's. */
+  above: Array<{ bone: string; property: 'rotate' | 'translate'; chain: string | null }>;
+  /** aim − the pair's angle, degrees: the largest |·| over the frames and its frame, and the mean |second difference| of it, °/frame². */
+  departure: { max: number; frame: number; meanD2: number | null };
+  /** Mean |second difference|, °/frame², of the reach's aim and of the pair's own angle, over every frame; and aim ÷ pair (null when the pair is still: its figure rounds to 0). */
+  aimD2: number | null;
+  pairD2: number | null;
+  ratio: number | null;
+}
+
+/**
+ * Mean |second difference| of a series of angles, degrees: |wrap(v[i+1] − v[i])
+ * − wrap(v[i] − v[i−1])| over every i whose three frames `ok` admits (every
+ * frame when it is omitted), and how many triples that was. null on none.
+ */
+export function meanSecondDiff(series: ReadonlyArray<readonly number[]>, ok?: (i: number) => boolean): { value: number | null; triples: number } {
+  let sum = 0;
+  let triples = 0;
+  for (const v of series) {
+    for (let i = 1; i + 1 < v.length; i++) {
+      if (ok !== undefined && !(ok(i - 1) && ok(i) && ok(i + 1))) continue;
+      sum += Math.abs(wrap(v[i + 1]! - v[i]!) - wrap(v[i]! - v[i - 1]!));
+      triples++;
+    }
+  }
+  return { value: triples === 0 ? null : sum / triples, triples };
+}
+
 /** The lines across the body a `TURN` is read on: the subject's right joint, then its left twin. */
 export const TURN_LINES: ReadonlyArray<[string, string, string]> = [['hip', 'r_hip', 'l_hip'], ['shoulder', 'r_shoulder', 'l_shoulder'], ['eye', 'r_eye', 'l_eye']];
 /** A line shorter in the picture than this fraction of its median is turned (rig-c/pose#6: between the front-facing dance's floor, 0.81, and a side-on body's 0.17–0.49). */
@@ -324,6 +388,8 @@ export interface Retarget {
   flips: Flip[];
   /** The figure scale, rig units per picture pixel, and the lengths it came from. */
   scale: { factor: number; pose: number; rig: number } | null;
+  /** rig-c/pose#240: what the figure scale is read against — its segment's foreshortening, the legs' and hips' ratios, the hip's travel; null without a scale. */
+  scaleFit: ScaleFit | null;
   /** The spans each alternate set shows, with their art turn. */
   switches: Switch[];
   /** Per switched or hidden slot, what it shows on each frame (null: nothing). */
@@ -340,6 +406,12 @@ export interface Retarget {
   artRange: ArtRange[];
   /** With --leg-scale: each leg segment's scale, straight length and clamped runs. */
   legScale: LegScale[];
+  /** rig-c/pose#237: every mapped leg segment's picture length ÷ straight (min, median, max), with or without --leg-scale. */
+  segments: LegSegmentRatio[];
+  /** rig-c/pose#237: each side's straight leg, the 95th percentile of its picture length hip → ankle, px (LEG-SCALE's percentile, against FEET's median); null without both legs read. */
+  legStraight: Record<Side, number> | null;
+  /** rig-c/pose#237: each side's rig leg at setup, thigh origin → ankle, world units — the leg length a clamp's shift of the ankle is read in; null without both legs. */
+  rigLeg: Record<Side, number> | null;
   /** Per scaled bone, the scale its x axis must reach on each frame (relative to setup); the scalex key of a bone under a scaled bone differs from it. */
   scales: Map<string, number[]>;
   /** The supports and jumps read off the reference ankles, when the map has both legs (whether or not --plant-feet used them). */
@@ -354,6 +426,8 @@ export interface Retarget {
   blendHold: BlendHold | null;
   /** With --plant-feet on an in-place sequence: the hip's x drift closed over the loop (#92). */
   closure: Closure | null;
+  /** On an in-place sequence without --plant-feet (#242): the translated bone's world x on the last frame less its x on the first, which nothing closes; null otherwise, and when no bone is translated. */
+  openDrift: number | null;
   /** Each ankle's world position on every frame, as the keys put it, when legs are scaled or feet planted. */
   ankles: { bones: Record<Side, string>; at: Record<Side, Pt[]> } | null;
   /** The translated bone's origin against its thigh roots' midpoint, at setup. */
@@ -370,6 +444,10 @@ export interface Retarget {
   figureScale: FigureScaleReading;
   /** Per-frame vertical head nod reading (`rawY`, `clampedY`, and clamped `residual`, `#111`, `#181`, `#190`). */
   headNod: HeadNodReading | null;
+  /** The eye-line chain keys no nod, and why (rig-c/pose#241); null when it does or when no chain carries the eye line. */
+  nodSkipped: NodSkipped | null;
+  /** Each `reach` chain hanging below a bone the animation turns or translates (#236): its aim's departure from the pose pair's angle. */
+  reach: ReachReading[];
 }
 
 export interface FigureScaleFrame {
@@ -403,6 +481,46 @@ export interface Pivot {
 
 type Pt = [number, number];
 
+/** A ratio band, rig units per picture px: the rig's length over the picture's straight (95th percentile) length, to over its median. */
+export interface ScaleBand {
+  /** rig / picture 95th percentile — the factor that matches the length where the picture shows it longest. */
+  lo: number;
+  /** rig / picture median — the factor that matches it on the median frame. */
+  hi: number;
+}
+
+/** rig-c/pose#240: the figure scale beside what it could have been read off instead. */
+export interface ScaleFit {
+  /** The `translate.scale.pose` segment: its median picture length (what the factor divides by) against its 95th percentile. */
+  segment: { joints: [string, string]; median: number; straight: number; ratio: number };
+  /** Each side's leg, hip → ankle: the rig's at setup (thigh origin → ankle, units), the picture's median and 95th percentile (px), and the band rig ÷ those; null without both legs. */
+  leg: { rig: Record<Side, number>; median: Record<Side, number>; straight: Record<Side, number>; band: ScaleBand; within: boolean } | null;
+  /** The hips' width: the rig's thigh roots apart at setup (units), the picture's r_hip → l_hip median and 95th percentile (px), and the band; null without both legs and both hips read. */
+  hip: { rig: number; median: number; straight: number; band: ScaleBand; within: boolean } | null;
+  /** Whether `scale.factor` lies outside the leg band and outside the hip band (`withinPx`); null unless both are read. */
+  outside: boolean | null;
+  /** The translated joint's range over the frames, x and y: the pose's in px, the keyed bone's world origin in units — each also in leg lengths (the pose's straight leg, the rig's at setup, the two sides' mean) and hip widths (the pose's 95th percentile, the rig's at setup); null where the unit is not read. */
+  travel: {
+    joint: string;
+    bone: string;
+    pose: { x: number; y: number; legs: [number, number] | null; hips: [number, number] | null };
+    rig: { x: number; y: number; legs: [number, number] | null; hips: [number, number] | null };
+  };
+}
+
+/**
+ * Whether `scale.factor` sizes a length as the picture shows it: the rig's
+ * length carried into the picture by the factor (rig ÷ factor, px) lies between
+ * the picture's median and 95th percentile, give or take one picture px — the
+ * picture's own unit, so a band the picture never widened (a length it shows the
+ * same on every frame) is not missed by a rounding the picture cannot show.
+ */
+export function withinPx(factor: number, rig: number, median: number, straight: number): boolean {
+  const px = rig / factor;
+  return px >= Math.min(median, straight) - 1 && px <= Math.max(median, straight) + 1;
+}
+
+
 /** The value of a point on one frame, or why it is not good. */
 export function pointOn(joints: Partial<Record<Body18, Joint>>, name: string, minScore: number): Pt | string {
   if (isBody18(name)) {
@@ -467,6 +585,57 @@ function pivotOf(rest: Rest, bone: string | null, legs: ReturnType<typeof legsOf
   return { bone, roots, offset, distance, hipWidths: width > 1e-9 ? distance / width : NaN };
 }
 
+/** Two bones' setup origins apart, world units: the rig's hip width when they are the thigh roots. */
+function rootsApart(rest: Rest, a: string, b: string): number {
+  const x = rest.get(a)!;
+  const y = rest.get(b)!;
+  return Math.hypot(y.worldX - x.worldX, y.worldY - x.worldY);
+}
+
+const rangeOf = (xs: readonly number[]): number => (xs.length === 0 ? 0 : Math.max(...xs) - Math.min(...xs));
+
+/** rig-c/pose#240: the SCALE reading, from fields the retarget already read — nothing here changes a key. */
+function scaleFitOf(o: {
+  joints: [string, string]; joint: string; bone: string; lengths: number[]; factor: number;
+  series: ReadonlyMap<string, Pt[]>; good: ReadonlyMap<string, boolean[]>;
+  legLength: Record<Side, number> | null; legStraight: Record<Side, number> | null; rigLeg: Record<Side, number> | null;
+  rigHip: number | null; origin: readonly Pt[];
+}): ScaleFit {
+  const segMedian = median(o.lengths);
+  const segStraight = percentile(o.lengths, STRAIGHT_PERCENTILE);
+  const leg = o.legLength === null || o.legStraight === null || o.rigLeg === null ? null : (() => {
+    const rig = o.rigLeg!, med = o.legLength!, str = o.legStraight!;
+    const at = (q: Record<Side, number>) => SIDES.map((s) => rig[s] / q[s]);
+    return { rig, median: med, straight: str, band: { lo: Math.min(...at(str)), hi: Math.max(...at(med)) }, within: SIDES.some((s) => withinPx(o.factor, rig[s], med[s], str[s])) };
+  })();
+  const hipWidths: number[] = [];
+  const R = o.series.get('r_hip'), L = o.series.get('l_hip'), gr = o.good.get('r_hip'), gl = o.good.get('l_hip');
+  if (R !== undefined && L !== undefined && gr !== undefined && gl !== undefined) {
+    for (let i = 0; i < R.length; i++) if (gr[i] && gl[i]) hipWidths.push(Math.hypot(L[i]![0] - R[i]![0], L[i]![1] - R[i]![1]));
+  }
+  const hipMedian = hipWidths.length === 0 ? NaN : median(hipWidths);
+  const hipStraight = percentile(hipWidths, STRAIGHT_PERCENTILE);
+  const hip = o.rigHip === null || !(hipMedian > 1e-6) || !(hipStraight > 1e-6) || !(o.rigHip > 1e-6) ? null
+    : { rig: o.rigHip, median: hipMedian, straight: hipStraight, band: { lo: o.rigHip / hipStraight, hi: o.rigHip / hipMedian }, within: withinPx(o.factor, o.rigHip, hipMedian, hipStraight) };
+  const P = o.series.get(o.joint)!;
+  const px = rangeOf(P.map((p) => p[0])), py = rangeOf(P.map((p) => p[1]));
+  const ux = rangeOf(o.origin.map((p) => p[0])), uy = rangeOf(o.origin.map((p) => p[1]));
+  const mean = (q: Record<Side, number>) => (q.r + q.l) / 2;
+  const per = (x: number, y: number, unit: number | null): [number, number] | null => (unit === null || !(unit > 1e-6) ? null : [x / unit, y / unit]);
+  return {
+    segment: { joints: o.joints, median: segMedian, straight: segStraight, ratio: segMedian / segStraight },
+    leg,
+    hip,
+    outside: leg === null || hip === null ? null : !leg.within && !hip.within,
+    travel: {
+      joint: o.joint,
+      bone: o.bone,
+      pose: { x: px, y: py, legs: per(px, py, o.legStraight === null ? null : mean(o.legStraight)), hips: per(px, py, hip === null ? null : hip.straight) },
+      rig: { x: ux, y: uy, legs: per(ux, uy, o.rigLeg === null ? null : mean(o.rigLeg)), hips: per(ux, uy, hip === null ? null : hip.rig) },
+    },
+  };
+}
+
 /**
  * Retarget. Refuses (every reason at once) when a point the map needs is never
  * good, when a hinge's side cannot be read off a straight rest, and — with
@@ -600,6 +769,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // first, because a reach is aimed from where the hip has put its bone.
   let origin: Retarget['origin'] = null;
   let scale: Retarget['scale'] = null;
+  /** The scale segment's picture length on every frame both its points are good (#240's SCALE reading). */
+  let scaleLengths: number[] = [];
   let translateTrack: MotionTrack | null = null;
   /** The translated bone's world travel from its setup origin, per frame. */
   const travel: Pt[] = [];
@@ -621,6 +792,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       else {
         const s = rigLen / poseLen;
         scale = { factor: s, pose: poseLen, rig: rigLen };
+        scaleLengths = lengths;
         const P = series.get(t.joint)!;
         for (let i = 0; i < n; i++) {
           const wx = (P[i]![0] - P[0]![0]) * s;
@@ -720,7 +892,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     for (let k = 1; k < c.bones.length; k++) checkHinge(c, k, targets, restOf, keyTimes, opts, bends, p);
   }
   if (opts.bends === 'refuse' && bends.length > 0) {
-    for (const e of bends) p.add('POSE_BEND_ONE_WAY', bendLine(e));
+    // #238: one line per hinge — its count, worst angle, frame range and the remedy; the per-frame lines are its detail (--verbose).
+    for (const g of bendGroups(bends)) p.add('POSE_BEND_ONE_WAY', bendGroupLine(g, 'refuse'), g.events.map((e) => ({ code: 'POSE_BEND_ONE_WAY', text: bendLine(e) })));
   }
   p.throwIfAny();
 
@@ -729,9 +902,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // which are aimed from where the hip is.
   const legScaleOn = opts.legScale !== undefined && opts.legScale !== 'off';
   const plantOn = opts.plantFeet === true;
-  /** #92: an in-place sequence under --plant-feet — the supporting foot follows its own track, no step releases, the loop closed. */
-  const inPlace = plantOn && opts.travel === TRAVEL_IN_PLACE;
+  /**
+   * #92, #242: the sequence declares itself in place. A property of the sequence, not of --plant-feet: every reading
+   * below takes it with or without the flag — the supports (no step releases a foot), the camera-zoom normalisations
+   * (#159, #163, #173: a loop has no zoom, and their rolling windows do not wrap), the trunk scale (#172) and the head
+   * nod (no detrend window, no clamp). What only planting can do — the supporting foot following its own track and the
+   * loop closed on the planted hip — stays under `plantOn`, and without it `openDrift` says what was not closed.
+   */
+  const inPlace = opts.travel === TRAVEL_IN_PLACE;
   let closure: Closure | null = null;
+  let openDrift: number | null = null;
   const legScale: LegScale[] = [];
   const scales = new Map<string, number[]>();
   let stance: Stance | null = null;
@@ -903,8 +1083,12 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const poseScale: number[] | null = t !== null && scale !== null && n > 25 && !inPlace ? continuousScale : null;
   let trunkScaleBone: string | null = null;
   let trunkScale: number[] | null = null;
-  if (legScaleOn) {
-    const limits = opts.legScale as [number, number];
+  // #237: every mapped leg segment's picture length ÷ straight, with or without --leg-scale: the
+  // straight lengths --leg-scale scales against, so the minimum read here is the one it would clamp.
+  const segments: LegSegmentRatio[] = [];
+  {
+    /** Without --leg-scale nothing is keyed: [1, 1] only lets `legScaleOf` read the ratio. */
+    const limits: [number, number] = legScaleOn ? (opts.legScale as [number, number]) : [1, 1];
     const rawSegments: Array<{ chain: string; bone: string; joints: [string, string]; kind: string; lengths: number[]; ownStraight: number }> = [];
     for (const c of map.chains) {
       if (c.reach) continue;
@@ -912,7 +1096,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const joints: [string, string] = [c.joints[k]!, c.joints[k + 1]!];
         if (!isLegSegment(joints[0], joints[1])) return;
         if (c.aim[k] !== 'x') {
-          p.add('LEGS_MAP', `--leg-scale scales chain "${c.name}" bone "${b}" (${joints[0]} → ${joints[1]}) along its own x axis, and the map aims it ${JSON.stringify(c.aim[k])}; a leg segment it scales must be aimed "x"`);
+          if (legScaleOn) p.add('LEGS_MAP', `--leg-scale scales chain "${c.name}" bone "${b}" (${joints[0]} → ${joints[1]}) along its own x axis, and the map aims it ${JSON.stringify(c.aim[k])}; a leg segment it scales must be aimed "x"`);
+          segments.push({ chain: c.name, bone: b, joints, straight: null, ratio: null, why: `aimed ${JSON.stringify(c.aim[k])}, and --leg-scale scales a segment aimed "x"` });
           return;
         }
         const from = series.get(joints[0])!;
@@ -920,10 +1105,12 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const lengths = from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1]));
         const ownStraight = percentile(lengths, STRAIGHT_PERCENTILE);
         if (!(ownStraight > 1e-6)) {
-          p.add('LEGS_MAP', `--leg-scale: chain "${c.name}" bone "${b}"'s segment ${joints[0]} → ${joints[1]} has a straight length (95th percentile) of ${ownStraight}px; there is nothing to scale against`);
+          if (legScaleOn) p.add('LEGS_MAP', `--leg-scale: chain "${c.name}" bone "${b}"'s segment ${joints[0]} → ${joints[1]} has a straight length (95th percentile) of ${ownStraight}px; there is nothing to scale against`);
+          segments.push({ chain: c.name, bone: b, joints, straight: null, ratio: null, why: `its straight length (95th percentile) is ${ownStraight}px` });
           return;
         }
         rawSegments.push({ chain: c.name, bone: b, joints, kind: `${joints[0].slice(2)}:${joints[1].slice(2)}`, lengths, ownStraight });
+        segments.push({ chain: c.name, bone: b, joints, straight: null, ratio: null });
       });
     }
     const straightByKind = new Map<string, number>();
@@ -971,9 +1158,17 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     };
     for (const seg of rawSegments) {
       const ls = legScaleOf(seg.lengths, limits, straightByKind.get(seg.kind)! * rigShareOf(seg));
-      legScale.push({ chain: seg.chain, bone: seg.bone, joints: seg.joints, ...ls });
-      scales.set(seg.bone, ls.scale);
+      const row = segments.find((x) => x.bone === seg.bone)!;
+      row.straight = ls.straight;
+      row.ratio = ls.ratio;
+      if (legScaleOn) {
+        legScale.push({ chain: seg.chain, bone: seg.bone, joints: seg.joints, ...ls });
+        scales.set(seg.bone, ls.scale);
+      }
     }
+  }
+  if (legScaleOn) {
+    const limits = opts.legScale as [number, number];
     if (legScale.length === 0 && !p.any) p.add('LEGS_MAP', '--leg-scale scales the leg segments (two of one side\'s hip, knee and ankle), and the map aims none');
     const isTrunkPair = (a: string, b: string): boolean => (a === 'mid_hip' && (b === 'neck' || b === 'mid_shoulder')) || (b === 'mid_hip' && (a === 'neck' || a === 'mid_shoulder'));
     const trunkChain = map.chains.find((c) => c.bones.length === 1 && isTrunkPair(c.joints[0]!, c.joints[1]!));
@@ -1107,6 +1302,57 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       stretchChain(stance.stretch);
     }
   }
+  // #237: what the clamps did to a free ankle's height — read, nothing keyed changes. Each side's rig
+  // leg at setup is the unit; the clamped frames of a free leg go on LEG-SCALE, and a lifted or below
+  // STANCE run says the pose's height was kept only where no clamp moved it.
+  let rigLeg: Record<Side, number> | null = null;
+  if (legs !== null && 'legs' in legs) {
+    const L = legs.legs;
+    const of = (s: Side): number => {
+      const o = rest.get(L[s].chain.bones[0]!)!;
+      const e = rest.get(L[s].ankleBone)!;
+      return Math.hypot(e.worldX + e.a * e.length - o.worldX, e.worldY + e.c * e.length - o.worldY);
+    };
+    rigLeg = { r: of('r'), l: of('l') };
+  }
+  if (legScaleOn && feet !== null && legPath !== null && rigLeg !== null && legs !== null && 'legs' in legs) {
+    const L = legs.legs;
+    const F = feet;
+    const legUnit = rigLeg;
+    const trackedSide = new Array<Side | null>(n).fill(null);
+    for (const tr of F.tracked ?? []) for (let i = tr.frames[0]; i <= tr.frames[1]; i++) trackedSide[i] = tr.side;
+    const freeOf = (i: number): Side | null => {
+      const s = F.support[i] ?? trackedSide[i] ?? null;
+      return s === null ? null : s === 'r' ? 'l' : 'r';
+    };
+    const tipY = (i: number, side: Side, scaleOf: (b: string) => number | null): number => {
+      const r = posePath(rest, legPath!, (b): Posing | null => (targets.has(b) ? { turn: restTurn(b, i), target: targets.get(b)![i]!, aimX: aimX.get(b)! } : null), scaleOf);
+      if (typeof r === 'string') throw new Refusal([{ code: 'LEGS_MAP', text: r }]);
+      return tipOf(rest, r, L[side].ankleBone)[1];
+    };
+    const shift = freeAnkleShiftOf(n, legScale, freeOf, tipY);
+    for (const ls of legScale) {
+      const side: Side = ls.joints[0].startsWith('r_') ? 'r' : 'l';
+      const frames: number[] = [];
+      for (let i = 0; i < n; i++) if (ls.scale[i] !== ls.picture[i] && freeOf(i) === side) frames.push(i);
+      const free = shiftOver(side, frames, shift, legUnit[side]);
+      if (free !== null) ls.free = free;
+    }
+    for (const run of stance?.runs ?? []) {
+      if (run.state === 'both' || run.absorbed === true) continue;
+      const frames = Array.from({ length: run.frames[1] - run.frames[0] + 1 }, (_, k) => run.frames[0] + k);
+      const moved = shiftOver(run.side, frames, shift, legUnit[run.side]);
+      if (moved !== null) run.moved = moved;
+    }
+  }
+  const legStraight: Record<Side, number> | null = feet === null ? null : (() => {
+    const out = {} as Record<Side, number>;
+    for (const s of SIDES) {
+      const h = series.get(`${s}_hip`)!;
+      out[s] = percentile(series.get(`${s}_ankle`)!.map((a, i) => Math.hypot(a[0] - h[i]![0], a[1] - h[i]![1])), STRAIGHT_PERCENTILE);
+    }
+    return out;
+  })();
   if (t !== null && scale !== null) {
     const bone = rest.get(t.bone)!;
     const parent = bone.parent === null ? null : rest.get(bone.parent)!;
@@ -1126,6 +1372,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
     translateTrack = { bone: t.bone, property: 'translate', keys };
     origin = { bone: t.bone, at };
+    if (inPlace && !plantOn && n > 0) openDrift = r6(travel[n - 1]![0] - travel[0]![0]);
   }
 
   // Reaches: from the bone's posed origin at the pose's end point, anchored at
@@ -1153,6 +1400,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   let headNod: Pt[] | null = null;
   let headNodTrack: MotionTrack | null = null;
   let headNodReading: HeadNodReading | null = null;
+  let nodSkipped: NodSkipped | null = null;
   const posedOrigin = (b: string, i: number): Pt => {
     const own = rest.get(b)!;
     if (t !== null && b === t.bone) return [own.worldX + (travel[i]?.[0] ?? 0), own.worldY + (travel[i]?.[1] ?? 0)];
@@ -1183,6 +1431,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   };
   const reaches = map.chains.filter((c) => c.reach).sort((x, y) => depth(x.bones[0]!) - depth(y.bones[0]!));
   let aimReach: ((c: Chain) => void) | null = null;
+  const reachAims = new Map<string, { aim: number[]; pair: number[]; length: number }>();
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
@@ -1200,6 +1449,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
       fillLeading(angles, () => p.add('POSE_SEGMENT_ZERO', `chain "${c.name}" — bone "${b}" reaches for ${c.joints[1]}, which the pose puts on the bone's posed origin on every frame; it has no direction`));
       targets.set(b, angles);
+      // #236: the aim as reached, before its own range clamp, beside the pair's own angle (a reading).
+      reachAims.set(c.name, { aim: [...angles], pair: Array.from({ length: n }, (_, i) => pictureAngle(anchor[i]!, end[i]!)), length: median(Array.from({ length: n }, (_, i) => Math.hypot(end[i]![0] - anchor[i]![0], end[i]![1] - anchor[i]![1]) * s)) });
     };
     for (const c of reaches) aimReach(c);
   }
@@ -1286,10 +1537,27 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       if (!((ja === 'r_eye' && jb === 'l_eye') || (ja === 'l_eye' && jb === 'r_eye'))) continue;
       const hb = c.bones[k]!;
       const ha = c.aim[k]!;
-      if (t?.bone === hb || sw.offsetTracks.some((tr) => tr.bone === hb)) break;
-      let underScaled = false;
-      for (let a = rest.get(hb)!.parent; a !== null; a = rest.get(a)!.parent) if (scales.has(a)) underScaled = true;
-      if (underScaled) break;
+      const skip = (why: string): void => {
+        nodSkipped = { bone: hb, chain: c.name, why };
+      };
+      if (c.nod === false) {
+        skip(`the chain declares "nod": false`);
+        break;
+      }
+      if (t?.bone === hb) {
+        skip(`the map's translate moves bone "${hb}"`);
+        break;
+      }
+      if (sw.offsetTracks.some((tr) => tr.bone === hb)) {
+        skip(`a set's offsets translate bone "${hb}"`);
+        break;
+      }
+      let underScaled: string | null = null;
+      for (let a = rest.get(hb)!.parent; a !== null; a = rest.get(a)!.parent) if (scales.has(a) && underScaled === null) underScaled = a;
+      if (underScaled !== null) {
+        skip(`bone "${hb}" hangs below the scaled bone "${underScaled}"`);
+        break;
+      }
       const rEye = series.get('r_eye')!;
       const lEye = series.get('l_eye')!;
       const neckSeries = series.get('neck') ?? (() => {
@@ -1305,6 +1573,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const refEye = median(rEye.map((re, i) => Math.hypot(lEye[i]![0] - re[0], lEye[i]![1] - re[1])));
         if (refEye > 1e-6 && rigEye > 1e-6) nodScale = rigEye / refEye;
       }
+      if (neckSeries === undefined) skip('neck is good on no frame');
+      else if (nodScale === null) skip(`no scale: the map translates no bone and aim ${JSON.stringify(ha)} names no two points to measure the eye distance on`);
       if (neckSeries !== undefined && nodScale !== null) {
         const bone = rest.get(hb)!;
         const parent = bone.parent === null ? null : rest.get(bone.parent)!;
@@ -1325,12 +1595,20 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const maxNod = !inPlace && neckRestLen > 1e-6 ? 0.02 * neckRestLen : Infinity;
         const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
         const halfWin = Math.max(1, Math.round(0.5 / Math.max(1e-6, (keyTimes[n - 1]! - keyTimes[0]!) / Math.max(1, n - 1))));
-        const nodMed = maxNod < Infinity && n > 2 * halfWin
-          ? refEN.map((_, i) => median(refEN.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1))))
-          : refEN.map(() => refEN[0]!);
-        const nodBase = maxNod < Infinity && n > 2 * halfWin
+        const windowed = maxNod < Infinity && n > 2 * halfWin;
+        // #241: on a `clean --loop` sequence the window wraps (the last frame runs into the first), as clean's own
+        // windows do; cut at the ends instead, the two ends of the loop are read against different baselines.
+        const nodWindow: NodWindow = !windowed ? 'in-place' : opts.loop === true ? 'wrapped' : 'cut';
+        const around = (xs: readonly number[], i: number): number[] => {
+          if (nodWindow !== 'wrapped') return xs.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1));
+          const out: number[] = [];
+          for (let j = i - halfWin; j <= i + halfWin; j++) out.push(xs[((j % n) + n) % n]!);
+          return out;
+        };
+        const nodMed = windowed ? refEN.map((_, i) => median(around(refEN, i))) : refEN.map(() => refEN[0]!);
+        const nodBase = windowed
           ? nodMed.map((_, i) => {
-              const sl = nodMed.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1));
+              const sl = around(nodMed, i);
               return sl.reduce((a, b) => a + b, 0) / sl.length;
             })
           : nodMed;
@@ -1345,8 +1623,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           return Math.max(-maxNod, Math.min(maxNod, v));
         });
         const residual = rawNod.map((v, i) => v - dy[i]!);
-        headNodReading = { bone: hb, maxNod, rawY: rawNod, clampedY: dy, residual };
-        if (dy.some((v) => Math.abs(r3(v)) > 0)) {
+        const keyed = dy.some((v) => Math.abs(r3(v)) > 0);
+        headNodReading = { bone: hb, chain: c.name, maxNod, rawY: rawNod, clampedY: dy, residual, window: nodWindow, halfWin: windowed ? halfWin : 0, keyed };
+        if (keyed) {
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
           const ref0 = refEN[0]! / (poseScale?.[0] ?? 1);
@@ -2753,15 +3032,95 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   if (translateTrack !== null) tracks.push(translateTrack);
   if (headNodTrack !== null) tracks.push(headNodTrack);
   tracks.push(...sw.offsetTracks, ...sw.slotTracks);
-
+  const reach = reachReadings(rest, map, tracks, reachAims, t?.bone ?? null);
+
+  const pivot = pivotOf(rest, t?.bone ?? null, legs);
+  const scaleFit = t === null || scale === null || origin === null ? null : scaleFitOf({
+    joints: t.scale.pose, joint: t.joint, bone: t.bone, lengths: scaleLengths, factor: scale.factor,
+    series, good, legLength: feet?.legLength ?? null, legStraight, rigLeg,
+    rigHip: legs !== null && 'legs' in legs ? rootsApart(rest, legs.legs.r.chain.bones[0]!, legs.legs.l.chain.bones[0]!) : null,
+    origin: origin.at,
+  });
   return {
     animation: { duration: keyTimes[n - 1]!, tracks },
-    times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
+    times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale, scaleFit,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face, body, figureScale, headNod: headNodReading,
+    legScale, segments, legStraight, rigLeg, scales, feet, planted: plantOn, stance, floor, blendHold, closure, openDrift, ankles, pivot, raised, byHip, face, body, figureScale, headNod: headNodReading, nodSkipped, reach,
   };
 }
 
+/** A reach bone's origin within this many world units of the anchor's, with nothing above it moved, is aimed along the pair: no REACH line. */
+export const REACH_OFFSET = 1e-6;
+
+/** Round a second-difference figure, °/frame², to 1e-4. */
+const r4 = (v: number) => {
+  const r = Math.round(v * 10000) / 10000;
+  return Object.is(r, -0) ? 0 : r;
+};
+
+/**
+ * #236: for each reach chain, the bones above it the animation moves — a rotate
+ * track, or a translate track other than the anchor's (its travel is in the
+ * target too) — and, when there are any, its aim's departure from the pair.
+ */
+function reachReadings(rest: Rest, map: JointMap, tracks: ReadonlyArray<MotionTrack | SlotTrack>, aims: ReadonlyMap<string, { aim: number[]; pair: number[]; length: number }>, anchor: string | null): ReachReading[] {
+  const out: ReachReading[] = [];
+  if (anchor === null) return out;
+  const a0 = rest.get(anchor)!;
+  const moved = new Map<string, Set<'rotate' | 'translate'>>();
+  for (const tr of tracks) {
+    if (!('bone' in tr) || (tr.property !== 'rotate' && tr.property !== 'translate')) continue;
+    if (tr.property === 'translate' && tr.bone === anchor) continue;
+    const s = moved.get(tr.bone) ?? new Set();
+    s.add(tr.property);
+    moved.set(tr.bone, s);
+  }
+  for (const c of map.chains) {
+    const got = aims.get(c.name);
+    if (!c.reach || got === undefined) continue;
+    const b = c.bones[0]!;
+    const above: ReachReading['above'] = [];
+    for (let a = rest.get(b)?.parent ?? null; a !== null; a = rest.get(a)?.parent ?? null) {
+      for (const property of ['rotate', 'translate'] as const) {
+        if (moved.get(a)?.has(property) !== true) continue;
+        above.push({ bone: a, property, chain: property === 'rotate' ? (map.chains.find((x) => x.bones.includes(a))?.name ?? null) : null });
+      }
+    }
+    const bo = rest.get(b)!;
+    const units = Math.hypot(bo.worldX - a0.worldX, bo.worldY - a0.worldY);
+    if (above.length === 0 && units <= REACH_OFFSET) continue;
+    const dep = got.aim.map((v, i) => wrap(v - got.pair[i]!));
+    let frame = 0;
+    for (let i = 1; i < dep.length; i++) if (Math.abs(dep[i]!) > Math.abs(dep[frame]!)) frame = i;
+    const d2 = meanSecondDiff([dep]).value;
+    const aimD2 = meanSecondDiff([got.aim]).value;
+    const pairD2 = meanSecondDiff([got.pair]).value;
+    out.push({
+      chain: c.name,
+      bone: b,
+      joints: [c.joints[0]!, c.joints[1]!],
+      anchor,
+      offset: { units: r3(units), ofLength: got.length > 0 ? r3(units / got.length) : 0 },
+      above,
+      departure: { max: r3(Math.abs(dep[frame] ?? 0)), frame, meanD2: d2 === null ? null : r4(d2) },
+      aimD2: aimD2 === null ? null : r4(aimD2),
+      pairD2: pairD2 === null ? null : r4(pairD2),
+      ratio: aimD2 === null || pairD2 === null || r4(pairD2) === 0 ? null : Number((aimD2 / pairD2).toFixed(3)),
+    });
+  }
+  return out;
+}
+
+/** The `REACH` line of a reach chain whose aim departs from its pair (#236). */
+export function reachCostLine(e: ReachReading, times: readonly number[]): string {
+  const f = (v: number | null) => (v === null ? 'not measured' : `${v.toFixed(4)}°/f²`);
+  const why: string[] = [];
+  if (e.offset.units > REACH_OFFSET) why.push(`its origin sits ${e.offset.units.toFixed(2)} units from the anchor "${e.anchor}"'s at setup (${e.offset.ofLength.toFixed(3)} of the reached length)`);
+  if (e.above.length > 0) why.push(`it hangs below ${e.above.map((x) => `"${x.bone}" (${x.property === 'rotate' ? (x.chain === null ? 'rotate keys' : `turned by chain "${x.chain}"`) : 'translate keys'})`).join(', ')}`);
+  const ratio = e.ratio === null ? (e.pairD2 === 0 ? ' — the pair is still' : '') : ` (${e.ratio.toFixed(2)}×)`;
+  return `chain "${e.chain}" bone "${e.bone}" (${e.joints[0]} → ${e.joints[1]}) is aimed from its posed origin at the pair's end — ${why.join(', and ')}: the aim departs from the pair's own angle by up to ${e.departure.max.toFixed(3)}° (frame ${e.departure.frame}, t=${times[e.departure.frame]!.toFixed(3)}s), mean |Δ²| of the departure ${f(e.departure.meanD2)}; mean |Δ²| aim ${f(e.aimD2)} against the pair's ${f(e.pairD2)}${ratio} — rotation the pose pair does not have, the cost of "reach"; a reading`;
+}
+
 /** What a placed wrist is measured against: the head (#62, the eyes) or the hip (#93, the hips) — two pose joints and the rig's two points. */
 interface Anchor {
   kind: 'head' | 'hip';
@@ -3192,7 +3551,7 @@ function checkHinge(c: Chain, k: number, targets: Map<string, number[]>, restOf:
   else if (c.bend === 'cw') side = -1;
   else {
     if (Math.abs(restInner) < 0.5) {
-      p.add('MAP_BEND_SIDE', `chain "${c.name}" — the hinge at ${joint} is straight at rest (inner angle ${restInner.toFixed(3)}°), so the rest pose does not say which way it bends; state "bend": "ccw", "cw" or "free"`);
+      p.add('MAP_BEND_SIDE', `chain "${c.name}" — the hinge at ${joint} is straight at rest (inner angle ${restInner.toFixed(3)}°), so the rest pose does not say which way it bends; state "bend": "ccw", "cw" or "free" — ${bendFreeRemedy(c.name)}`);
       return;
     }
     side = restInner > 0 ? 1 : -1;
@@ -3213,8 +3572,83 @@ export function bendLine(e: BendEvent): string {
   return `chain "${e.chain}" hinge ${e.joint}, frame ${e.frame} (t=${e.t.toFixed(3)}s) — inner angle ${e.angle.toFixed(1)}°; it bends ${sense} at rest (${e.rest.toFixed(1)}°), so the angle must stay ${e.side > 0 ? '≥' : '≤'} 0`;
 }
 
+/**
+ * The remedy both bend refusals name (rig-c/pose#238), as the README's map
+ * section ("bend") gives it: front-facing material goes "free", a side view
+ * keeps a side.
+ */
+export function bendFreeRemedy(chain: string): string {
+  return `seen from the front, the side a hinge's picture falls on is not its limit, so for front-facing material state "bend": "free" on chain "${chain}"; keep a side ("rest", "ccw", "cw") only for a side view, where the picture's side is the joint's own`;
+}
+
+/** One hinge's wrong-way frames (#238): what its collapsed line says. */
+export interface BendGroup {
+  chain: string;
+  joint: string;
+  side: 1 | -1;
+  rest: number;
+  /** Every frame it bent the wrong way, in frame order — the per-frame lines. */
+  events: BendEvent[];
+  /** The event furthest on the wrong side. */
+  worst: BendEvent;
+  /** Runs of consecutive frames. */
+  runs: number;
+}
+
+/** The bend events grouped per hinge, in the order the hinges were first met (#238). */
+export function bendGroups(events: readonly BendEvent[]): BendGroup[] {
+  const out = new Map<string, BendGroup>();
+  for (const e of events) {
+    const k = `${e.chain}\u0000${e.joint}`;
+    const g = out.get(k);
+    if (g === undefined) {
+      out.set(k, { chain: e.chain, joint: e.joint, side: e.side, rest: e.rest, events: [e], worst: e, runs: 1 });
+      continue;
+    }
+    if (e.frame !== g.events[g.events.length - 1]!.frame + 1) g.runs++;
+    g.events.push(e);
+    if (-e.side * e.angle > -g.worst.side * g.worst.angle) g.worst = e;
+  }
+  return [...out.values()];
+}
+
+/** One hinge's collapsed line (#238): a refusal names the remedy; a clamp, that every frame was straightened. */
+export function bendGroupLine(g: BendGroup, mode: 'refuse' | 'clamp'): string {
+  const sense = g.side > 0 ? 'counter-clockwise (+)' : 'clockwise (−)';
+  const first = g.events[0]!, last = g.events[g.events.length - 1]!;
+  const range = first.frame === last.frame ? `frame ${first.frame} (t=${first.t.toFixed(3)}s)` : `frames ${first.frame}–${last.frame} (t=${first.t.toFixed(3)}–${last.t.toFixed(3)}s)`;
+  const head = `chain "${g.chain}" hinge ${g.joint}, ${g.events.length} frame(s) in ${g.runs} run(s), ${range} — worst inner angle ${g.worst.angle.toFixed(1)}° at frame ${g.worst.frame} (t=${g.worst.t.toFixed(3)}s); it bends ${sense} at rest (${g.rest.toFixed(1)}°), so the angle must stay ${g.side > 0 ? '≥' : '≤'} 0`;
+  return mode === 'refuse'
+    ? `${head}; ${bendFreeRemedy(g.chain)}; a near-straight knee's noise takes --bends clamp or --bend-tolerance <deg> (each frame: --verbose)`
+    : `${head} — clamped straight on each (each frame: --verbose; --report's "bends")`;
+}
+
 /** Holds grouped per point, one line each span. */
 export function holdLine(h: Hold, times: readonly number[]): string {
   const span = h.from === h.to ? `frame ${h.from} (t=${times[h.from]!.toFixed(3)}s)` : `frames ${h.from}–${h.to} (t=${times[h.from]!.toFixed(3)}–${times[h.to]!.toFixed(3)}s)`;
   return `point "${h.point}" ${span}: ${h.why}; held frame ${h.source}'s value`;
 }
+
+/**
+ * The `NOD` line (rig-c/pose#241): what the eye-line chain did to the head — the keyed range, the window its baseline
+ * was read over, whether the neck clamp acted and so coupled the nod into the head's rotate (and the face pitch). Or,
+ * when no nod is keyed, why. `pitch`: the map keys a face pitch dial.
+ */
+export function nodLine(h: HeadNodReading | null, skipped: NodSkipped | null, pitch: boolean): string | null {
+  if (h === null) return skipped === null ? null : `none on bone "${skipped.bone}" (chain "${skipped.chain}", r_eye → l_eye): ${skipped.why} — no translate keyed, nothing coupled into its rotate${pitch ? ' or the face pitch' : ''}`;
+  const head = `bone "${h.bone}" (chain "${h.chain}", r_eye → l_eye)`;
+  if (!h.keyed) return `${head}: the eyes do not move against the neck past the writer's 0.001 units — no translate keyed, nothing coupled`;
+  const lo = Math.min(...h.clampedY);
+  const hi = Math.max(...h.clampedY);
+  const sign = (v: number): string => `${v >= 0 ? '+' : ''}${v.toFixed(3)}`;
+  const window = h.window === 'in-place'
+    ? 'window none (in-place): the baseline is frame 0, no clamp, nothing coupled'
+    : `window ±${h.halfWin} frame(s) (0.5 s) running median, detrended, ${h.window === 'wrapped' ? 'wrapped on the loop' : 'cut at the clip\'s ends'}`;
+  const clamped = h.residual.filter((r) => r !== 0).length;
+  const clamp = h.window === 'in-place'
+    ? ''
+    : clamped === 0
+      ? `; clamp ±${h.maxNod.toFixed(3)} units (2% of the neck's setup length) never acted, so nothing is coupled`
+      : `; clamp ±${h.maxNod.toFixed(3)} units (2% of the neck's setup length) acted on ${clamped} frame(s), so the clamped nod is coupled in phase into bone "${h.bone}"'s rotate (+${NOD_RESIDUAL_HEAD_GAIN}°/unit)${pitch ? ` and the face pitch (+${NOD_RESIDUAL_PITCH_GAIN}°/unit)` : ''} on every frame`;
+  return `${head}: translate y ${sign(lo)} … ${sign(hi)} units over ${h.clampedY.length} frame(s); ${window}${clamp}`;
+}