@rig-c/pose 0.8.0 → 0.9.0

package/src/retarget.ts

@@ -64,11 +64,13 @@ import { screenToSpineDegrees } from 'rig-c/transform';
 import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
 import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
-import { aimAngle, rigPoint } from './map.ts';
+import { aimAngle, descends, rigPoint } from './map.ts';
 import type { Joint } from './pose.ts';
-import { Problems } from './problems.ts';
+import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
+import type { Feet, LegScale, PathPose, Posing, Side } from './legs.ts';
+import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -85,6 +87,10 @@ export interface RetargetOptions extends SwitchOptions {
   flip: number | 'off';
   /** A segment shorter in the picture than this fraction of its median length has its angle held there (`holdShort`); 'off' reads every frame. */
   short: number | 'off';
+  /** Leg segments scaled along their x axis by picture length over straight length, clamped to [min, max] (`legs.ts`); 'off' (the default) scales nothing. */
+  legScale?: [number, number] | 'off';
+  /** The hip derived from the supporting foot (`legs.ts`); false (the default) moves it by the pose's travel. */
+  plantFeet?: boolean;
 }
 
 export interface Hold {
@@ -170,7 +176,7 @@ export interface MotionKey {
 }
 export interface MotionTrack {
   bone: string;
-  property: 'rotate' | 'translate';
+  property: 'rotate' | 'translate' | 'scalex';
   keys: MotionKey[];
 }
 export interface Animation {
@@ -251,6 +257,29 @@ export interface Retarget {
   range: RangeDemand[];
   /** Every run a bone inside a span turned from its drawn angle past its range. */
   artRange: ArtRange[];
+  /** With --leg-scale: each leg segment's scale, straight length and clamped runs. */
+  legScale: LegScale[];
+  /** 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). */
+  feet: Feet | null;
+  /** Whether the hip was derived from the supporting foot. */
+  planted: boolean;
+  /** 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. */
+  pivot: Pivot | null;
+}
+
+/** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
+export interface Pivot {
+  bone: string;
+  roots: [string, string];
+  /** Hip origin − the roots' midpoint, world units. */
+  offset: Pt;
+  distance: number;
+  /** The distance in hip widths (the roots' distance apart). */
+  hipWidths: number;
 }
 
 type Pt = [number, number];
@@ -358,6 +387,24 @@ const r3 = (v: number) => {
   const r = Math.round(v * 1000) / 1000;
   return Object.is(r, -0) ? 0 : r;
 };
+/** A scale key: to 1e-6, so its rounding moves an ankle 500 units out by at most 0.00025. */
+const r6 = (v: number) => {
+  const r = Math.round(v * 1e6) / 1e6;
+  return Object.is(r, -0) ? 0 : r;
+};
+
+/** The translated bone's origin against the midpoint of the two legs' first bones, at setup. */
+function pivotOf(rest: Rest, bone: string | null, legs: ReturnType<typeof legsOf> | null): Pivot | null {
+  if (bone === null || legs === null || !('legs' in legs)) return null;
+  const roots: [string, string] = [legs.legs.r.chain.bones[0]!, legs.legs.l.chain.bones[0]!];
+  const a = rest.get(roots[0])!;
+  const b = rest.get(roots[1])!;
+  const h = rest.get(bone)!;
+  const offset: Pt = [h.worldX - (a.worldX + b.worldX) / 2, h.worldY - (a.worldY + b.worldY) / 2];
+  const width = Math.hypot(b.worldX - a.worldX, b.worldY - a.worldY);
+  const distance = Math.hypot(offset[0], offset[1]);
+  return { bone, roots, offset, distance, hipWidths: width > 1e-9 ? distance / width : NaN };
+}
 
 /**
  * Retarget. Refuses (every reason at once) when a point the map needs is never
@@ -493,30 +540,17 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const s = rigLen / poseLen;
         scale = { factor: s, pose: poseLen, rig: rigLen };
         const P = series.get(t.joint)!;
-        const bone = rest.get(t.bone)!;
-        const parent = bone.parent === null ? null : rest.get(bone.parent)!;
-        const keys: MotionKey[] = [];
-        const at: Pt[] = [];
         for (let i = 0; i < n; i++) {
           const wx = (P[i]![0] - P[0]![0]) * s;
           const wy = -(P[i]![1] - P[0]![1]) * s;
-          let lx = wx;
-          let ly = wy;
-          if (parent !== null) {
-            const det = parent.a * parent.d - parent.b * parent.c;
-            lx = (parent.d * wx - parent.b * wy) / det;
-            ly = (-parent.c * wx + parent.a * wy) / det;
-          }
-          keys.push({ t: keyTimes[i]!, v: [r3(lx), r3(ly)] });
-          at.push([bone.worldX + wx, bone.worldY + wy]);
           travel.push([wx, wy]);
         }
-        translateTrack = { bone: t.bone, property: 'translate', keys };
-        origin = { bone: t.bone, at };
       }
     }
   }
   p.throwIfAny();
+  /** The pose's own travel of the hip, world, before --plant-feet replaces it. */
+  const poseTravel: Pt[] = travel.map((v) => [v[0], v[1]]);
 
   // Each mapped bone's target world angle per frame, reaches last.
   const targets = new Map<string, number[]>();
@@ -595,6 +629,111 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
+  // The legs (#47): each leg segment's scale, the supports and jumps, and with
+  // --plant-feet the hip derived from the supporting foot — before the reaches,
+  // which are aimed from where the hip is.
+  const legScaleOn = opts.legScale !== undefined && opts.legScale !== 'off';
+  const plantOn = opts.plantFeet === true;
+  const legScale: LegScale[] = [];
+  const scales = new Map<string, number[]>();
+  let feet: Feet | null = null;
+  let legs: ReturnType<typeof legsOf> | null = null;
+  let legPath: string[] | null = null;
+  let legTop: string | null = null;
+  const restTurn = (b: string, i: number): number => targets.get(b)![i]! - restOf.get(b)!;
+  const aimX = new Map<string, boolean>();
+  for (const c of map.chains) c.bones.forEach((b, k) => aimX.set(b, c.aim[k] === 'x'));
+  {
+    const why = plantOn ? '--plant-feet' : legScaleOn ? '--leg-scale' : 'reading the feet';
+    legs = legsOf(map, why);
+    if ('problems' in legs) {
+      if (plantOn || legScaleOn) for (const x of legs.problems) p.add('LEGS_MAP', x);
+    } else {
+      const L = legs.legs;
+      const top = t !== null && SIDES.every((s) => L[s].ankleBone === t.bone || descends(rest, L[s].ankleBone, t.bone)) ? t.bone : rootOf(rest, L.r.ankleBone);
+      if (plantOn && (t === null || top !== t.bone)) p.add('LEGS_MAP', t === null ? '--plant-feet places the hip, and the map has no "translate"' : `--plant-feet places the translated bone "${t.bone}", and the legs' last bones (${L.r.ankleBone}, ${L.l.ankleBone}) do not both descend from it`);
+      const path = pathFrom(rest, top, [L.r.ankleBone, L.l.ankleBone]);
+      if (path === null || rootOf(rest, L.l.ankleBone) !== rootOf(rest, L.r.ankleBone)) {
+        if (plantOn || legScaleOn) p.add('LEGS_MAP', `the legs' last bones ${L.r.ankleBone} and ${L.l.ankleBone} do not hang from one bone`);
+      } else {
+        legPath = path;
+        legTop = top;
+      }
+      const hipOf = (s: Side) => series.get(`${s}_hip`);
+      const ankleOf = (s: Side) => series.get(`${s}_ankle`);
+      const hr = hipOf('r'), hl = hipOf('l'), ar = ankleOf('r'), al = ankleOf('l');
+      if (hr !== undefined && hl !== undefined && ar !== undefined && al !== undefined) feet = supportsOf({ r: ar, l: al }, { r: hr, l: hl }, keyTimes, secondsOf);
+      else if (plantOn) p.add('LEGS_MAP', `--plant-feet reads both hips and both ankles from the pose; the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`);
+    }
+  }
+  if (legScaleOn) {
+    const limits = opts.legScale as [number, number];
+    for (const c of map.chains) {
+      if (c.reach) continue;
+      c.bones.forEach((b, k) => {
+        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"`);
+          return;
+        }
+        const from = series.get(joints[0])!;
+        const to = series.get(joints[1])!;
+        const ls = legScaleOf(from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1])), limits);
+        if (!(ls.straight > 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 ${ls.straight}px; there is nothing to scale against`);
+          return;
+        }
+        legScale.push({ chain: c.name, bone: b, joints, ...ls });
+        scales.set(b, ls.scale);
+      });
+    }
+    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');
+  }
+  p.throwIfAny();
+  /** Every bone on the legs' path posed on frame i, by the targets as they stand. */
+  const poseLegs = (i: number): PathPose => {
+    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), (b) => scales.get(b)?.[i] ?? null);
+    if (typeof r === 'string') throw new Refusal([{ code: 'LEGS_MAP', text: r }]);
+    return r;
+  };
+  if (plantOn) {
+    // The plant is derived from the targets before the range clamp, so nothing after may turn a bone on the legs' path.
+    const onPath = new Set(legPath!);
+    for (const c of map.chains) for (const b of Object.keys(c.range)) if (onPath.has(b)) p.add('LEGS_RANGE', `--plant-feet places the hip through chain "${c.name}" bone "${b}", which has a "range"; a clamp after the plant would move the planted foot — drop the range or --plant-feet`);
+    for (const a of map.alternates) {
+      for (const b of [...Object.keys(a.turn), ...Object.keys(a.offsets)]) if (onPath.has(b)) p.add('LEGS_RANGE', `--plant-feet places the hip through bone "${b}", which set "${a.name}" turns or offsets; that would move the planted foot — drop it from the set or --plant-feet`);
+    }
+    p.throwIfAny();
+    const offsets = Array.from({ length: n }, (_, i) => {
+      const lp = poseLegs(i);
+      return { r: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.r.ankleBone : ''), l: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.l.ankleBone : '') };
+    });
+    const tb = rest.get(t!.bone)!;
+    const hip = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY]);
+    for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
+  }
+  if (t !== null && scale !== null) {
+    const bone = rest.get(t.bone)!;
+    const parent = bone.parent === null ? null : rest.get(bone.parent)!;
+    const keys: MotionKey[] = [];
+    const at: Pt[] = [];
+    for (let i = 0; i < n; i++) {
+      const [wx, wy] = travel[i]!;
+      let lx = wx;
+      let ly = wy;
+      if (parent !== null) {
+        const det = parent.a * parent.d - parent.b * parent.c;
+        lx = (parent.d * wx - parent.b * wy) / det;
+        ly = (-parent.c * wx + parent.a * wy) / det;
+      }
+      keys.push({ t: keyTimes[i]!, v: [r3(lx), r3(ly)] });
+      at.push([bone.worldX + wx, bone.worldY + wy]);
+    }
+    translateTrack = { bone: t.bone, property: 'translate', keys };
+    origin = { bone: t.bone, at };
+  }
+
   // Reaches: from the bone's posed origin at the pose's end point, anchored at
   // the translated bone. A reach above another is aimed first.
   const depth = (b: string): number => {
@@ -685,6 +824,25 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const artRange = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
   clampArt(sw.switches, map, targets);
 
+  // The legs on their final targets: a bone under a scaled bone is keyed through
+  // its parent's posed matrix (legs.ts), and each ankle's world position is read.
+  const legPoses: PathPose[] | null = legPath !== null && (legScaleOn || plantOn) ? Array.from({ length: n }, (_, i) => poseLegs(i)) : null;
+  let ankles: Retarget['ankles'] = null;
+  if (legPoses !== null && legs !== null && 'legs' in legs) {
+    const L = legs.legs;
+    const topRest = rest.get(legTop!)!;
+    const at = { r: [] as Pt[], l: [] as Pt[] };
+    legPoses.forEach((lp, i) => {
+      const o: Pt = origin !== null && origin.bone === legTop ? origin.at[i]! : [topRest.worldX, topRest.worldY];
+      for (const sd of SIDES) {
+        const tip = tipOf(rest, lp, L[sd].ankleBone);
+        at[sd].push([o[0] + tip[0], o[1] + tip[1]]);
+      }
+    });
+    ankles = { bones: { r: L.r.ankleBone, l: L.l.ankleBone }, at };
+  }
+  const solvedKey = (b: string, i: number) => legPoses?.[i]!.solved.get(b);
+
   // Keys: the bone's turn less the turn of the nearest mapped bone above it.
   const tracks: Array<MotionTrack | SlotTrack> = [];
   for (const c of map.chains) {
@@ -699,6 +857,22 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         keys.push({ t: keyTimes[i]!, v: [r3(v)] });
       }
       tracks.push({ bone: b, property: 'rotate', keys });
+      // A bone under a scaled bone: the rotate key that lands it through its parent's scale (legs.ts).
+      if (solvedKey(b, 0) !== undefined) {
+        let last = 0;
+        keys.forEach((k, i) => {
+          const raw = solvedKey(b, i)!.rotate;
+          last = i === 0 ? wrap(raw) : last + wrap(raw - last);
+          k.v = [r3(last)];
+        });
+      }
+    }
+  }
+  // Scale keys: a scaled leg segment's own scale, or the scale that lands a bone under one at its asked length.
+  for (const c of map.chains) {
+    for (const b of c.bones) {
+      if (!scales.has(b) && solvedKey(b, 0) === undefined) continue;
+      tracks.push({ bone: b, property: 'scalex', keys: Array.from({ length: n }, (_, i) => ({ t: keyTimes[i]!, v: [r6(solvedKey(b, i)?.scale ?? scales.get(b)?.[i] ?? 1)] })) });
     }
   }
   if (translateTrack !== null) tracks.push(translateTrack);
@@ -708,6 +882,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
+    legScale, scales, feet, planted: plantOn, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs),
   };
 }
 

package/src/rigc.ts

@@ -96,11 +96,11 @@ export interface Gate {
 }
 
 /** Build `rig` with `motion` under rigc's gate into `dir/build`; nothing is read from a red build. */
-export function gate(rig: string, motion: Record<string, unknown>, dir: string, profile: string): Gate {
+export function gate(rig: string, motion: Record<string, unknown>, dir: string, profile: string, images?: string): Gate {
   mkdirSync(dir, { recursive: true });
   const motionPath = join(dir, 'motion.json');
   writeFileSync(motionPath, `${JSON.stringify(motion, null, 2)}\n`);
-  return buildInto(rig, motionPath, join(dir, 'build'), profile, join(dir, 'build-report.json'));
+  return buildInto(rig, motionPath, join(dir, 'build'), profile, join(dir, 'build-report.json'), images);
 }
 
 /**
@@ -112,8 +112,8 @@ export function gate(rig: string, motion: Record<string, unknown>, dir: string,
  * never copied out, which would carry a path climbing from the scratch
  * directory to the filesystem root. --copy-images puts the pages beside it.
  */
-export function buildInto(rig: string, motionPath: string, out: string, profile: string, report?: string): Gate {
-  const run = runRigc(['build', '--rig', rig, '--motion', motionPath, '--out', out, '--profile', profile, '--copy-images', ...(report === undefined ? [] : ['--report', report])]);
+export function buildInto(rig: string, motionPath: string, out: string, profile: string, report?: string, images?: string): Gate {
+  const run = runRigc(['build', '--rig', rig, '--motion', motionPath, '--out', out, '--profile', profile, '--copy-images', ...(images === undefined ? [] : ['--images', images]), ...(report === undefined ? [] : ['--report', report])]);
   const lines = run.out.split('\n');
   return {
     run,
@@ -196,3 +196,12 @@ export function folds(build: string, animation: string, dir: string, fps: number
     frames: setDir,
   };
 }
+
+/** rig-c's version and the entry its launcher picked (`rigc --version`), so a run names the compiler that gated it. */
+export function rigcVersion(): { version: string; entry: string } {
+  const r = runRigc(['--version']);
+  const lines = r.out.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+  const version = lines.find((l) => /^\d+\.\d+\.\d+/.test(l)) ?? lines[0] ?? 'unknown';
+  const entry = lines.find((l) => l.startsWith('entry:'))?.slice('entry:'.length).trim() ?? 'not stated';
+  return { version, entry };
+}

package/src/run.ts

@@ -7,13 +7,15 @@
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { readMap, resolveMap } from './map.ts';
+import { readMap, resolveMap, type JointMap } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.ts';
 import { lineOf, Problems, Refusal, type Problem } from './problems.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type RetargetOptions } from './retarget.ts';
-import { attachmentBones, baseMotionOf, buildInto, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
+import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
 import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
-import { landed, measureLanding, measurePosture, poseFrames, postureLines, ANGLE_TOLERANCE, ORIGIN_TOLERANCE } from './verify.ts';
+import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
+import { legsOf } from './legs.ts';
+import type { LegScale } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -24,6 +26,8 @@ export interface RetargetArgs extends RetargetOptions {
   coco: boolean;
   person?: string;
   baseMotion?: string;
+  /** Passed to rigc build as --images: the directory the rig spec's images resolve in, when rig.json's own `images` does not point there (a copied rig). */
+  images?: string;
   profile: 'spine' | 'spine-html';
   /** Keep the gated build here. */
   build?: string;
@@ -72,17 +76,19 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const scratch = mkdtempSync(join(tmpdir(), 'rig-pose-'));
   try {
     // The rig as it stands, through the gate, so the rest pose is rig-c's reading of a green build.
-    const g0 = gate(input.rig, base, join(scratch, 'base'), a.profile);
+    const g0 = gate(input.rig, base, join(scratch, 'base'), a.profile, a.images);
     if (!g0.green) {
       refuse([{ code: 'RIG_GATE_BASE', text: `${input.rig} with ${input.motion ?? 'no motion spec'} is red under rigc build --profile ${a.profile} before any animation is added (exit ${g0.run.status})` }, ...g0.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
     const doc0 = readBuild(g0.build);
+    const rigc = rigcVersion();
     const rest = restOf(doc0);
     const slots = slotsOf(doc0);
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)`);
+    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}`);
+    say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
     if (a.short !== 'off') {
@@ -96,12 +102,23 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (map.alternates.length > 0) {
       if (r.switches.length === 0) say(`  SWITCH none — no set within ${a.switchTolerance}° of the pose for ${a.switchMin}s`);
       for (const s of r.switches) say(`  SWITCH ${switchLine(s, r.times)}`);
+      for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
+    for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times)}`);
+    if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
+    if (r.feet !== null) {
+      const f = r.feet;
+      const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+      say(`  FEET   ${r.planted ? 'planted' : 'read, not planted (no --plant-feet)'}: leg length (median hip → ankle) r ${f.legLength.r.toFixed(1)}px, l ${f.legLength.l.toFixed(1)}px; ${f.supports.length} support span(s), ${f.changes.filter((c) => c.from !== null).length} change(s) of support, ${f.jumps.length} jump(s), ${f.steps.length} step(s)`);
+      say(`  FEET   supports: ${f.supports.map((x) => `${x.side} ${span(x.frames)}`).join(', ') || 'none'}`);
+      say(`  FEET   jumps (both ankles and mid_hip > 0.05 leg lengths above their rolling floor, ≥ 2 frames): ${f.jumps.map(span).join(', ') || 'none'}`);
+      say(`  FEET   steps (the supporting ankle > 0.03 leg lengths a frame; re-planted after 2 frames < 0.01): ${f.steps.map((x) => `${x.side} ${span(x.frames)} → ${x.to === null ? 'the pose\'s travel' : `${x.to} supports`}, ${x.replant === null ? 'never re-planted' : `re-planted at ${x.replant}`}`).join('; ') || 'none'}`);
+    }
 
     const motion = { ...base, animations: { ...animations, [a.name]: r.animation } };
-    const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile);
+    const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile, a.images);
     if (!g1.green) {
       refuse([{ code: 'RIG_GATE', text: `rigc build --profile ${a.profile} is red with "${a.name}" in (exit ${g1.run.status}); nothing written` }, ...g1.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
@@ -112,16 +129,30 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const landings = measureLanding(doc, a.name, map, r, posed);
     const p = new Problems();
     for (const l of landings) {
-      const unit = l.kind === 'angle' ? '°' : ' units';
-      const tol = l.kind === 'angle' ? ANGLE_TOLERANCE : ORIGIN_TOLERANCE;
-      const line = `bone "${l.bone}" ${l.kind === 'angle' ? 'aim' : 'origin'} — worst |reached − asked| ${l.worst.toPrecision(3)}${unit} at frame ${l.frame} (t=${r.times[l.frame]!.toFixed(3)}s); the tolerance is ${tol}${unit}`;
+      const unit = l.kind === 'angle' ? '°' : l.kind === 'scale' ? ' of its setup length' : ' units';
+      const what = l.kind === 'angle' ? 'aim' : l.kind === 'scale' ? 'scale' : l.kind === 'foot' ? 'ankle' : 'origin';
+      const tol = l.kind === 'foot' ? Number(l.tolerance.toPrecision(3)) : l.tolerance;
+      const line = `bone "${l.bone}" ${what} — worst |reached − asked| ${l.worst.toPrecision(3)}${unit} at frame ${l.frame} (t=${r.times[l.frame]!.toFixed(3)}s); the tolerance is ${tol}${unit}`;
       if (landed(l)) say(`  LAND   ${line}`);
       else p.add('POSE_LANDS', `${line} — the rig does not turn the way the key formula assumes (a constraint, a scaled or sheared parent, a non-normal inherit mode)`);
     }
     p.throwIfAny();
 
-    const posture = measurePosture(posed, new Map(doc.bones.map((b) => [b.name, b.length ?? 0])), map, r, frames, a.minScore);
+    const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore);
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
+    const legBones = legBonesOf(map);
+    const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
+    if (feetReading !== null) {
+      const f = feetReading;
+      say(`  FEET   the posed build, outside jumps: the lowest ankle's vertical range ${f.lowest.range.toFixed(2)} units = ${f.lowest.legs.toFixed(4)} leg lengths (rig leg r ${f.legLength.r.toFixed(1)}, l ${f.legLength.l.toFixed(1)} units) over ${f.lowest.frames} frames`);
+      const worst = (k: 'verticalLegs' | 'horizontalLegs') => f.plants.reduce<(typeof f.plants)[number] | null>((m, x) => (m === null || x[k] > m[k] ? x : m), null);
+      const wv = worst('verticalLegs');
+      const wh = worst('horizontalLegs');
+      if (wv !== null && wh !== null) say(`  FEET   the supporting ankle over each support span: worst vertical range ${wv.vertical.toFixed(2)} units = ${wv.verticalLegs.toFixed(4)} leg lengths (${wv.side} ${wv.frames[0]}–${wv.frames[1]}), worst horizontal drift ${wh.horizontal.toFixed(2)} units = ${wh.horizontalLegs.toFixed(4)} leg lengths (${wh.side} ${wh.frames[0]}–${wh.frames[1]})`);
+    }
+    const shear = r.scales.size === 0 ? [] : measureShear(doc, posed, r.scales.keys());
+    for (const x of shear) say(`  SHEAR  bone "${x.bone}": art sheared up to ${x.shear.toFixed(2)}° (frame ${x.frame}); world x axis ${x.x[0].toFixed(3)} … ${x.x[1].toFixed(3)}, y axis ${x.y[0].toFixed(3)} … ${x.y[1].toFixed(3)} of setup — a scaled bone, or one under it; a reading`);
 
     const dts = r.times.slice(1).map((t, i) => t - r.times[i]!).sort((x, y) => x - y);
     const fps = dts.length === 0 ? 12 : Math.max(1, Math.min(60, Math.round(1 / dts[dts.length >> 1]!)));
@@ -139,7 +170,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
       rmSync(a.build, { recursive: true, force: true });
-      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile);
+      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
       if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
     }
     writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
@@ -150,11 +181,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (a.report !== undefined) {
       writeFileSync(a.report, `${JSON.stringify({
         spec: 'rig-pose-report/1',
+        rigc,
         rig: input.name,
         animation: a.name,
         frames: seq.frames.length,
         duration: r.animation.duration,
-        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile },
+        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -170,6 +202,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         turns: r.turns,
         range: r.range,
         artRange: r.artRange,
+        legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
+        pivot: r.pivot,
+        feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, reading: feetReading },
+        shear,
       }, null, 2)}\n`);
     }
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
@@ -195,3 +231,52 @@ function spans(ts: number[], step: number): string {
 }
 
 export { lineOf };
+
+/**
+ * For each set with `frames` windows: every stretch of a window the set did not
+ * show on, and why — the pose there was past the tolerance (with the largest
+ * distance), or within it but the run was dropped (shorter than --switch-min, or
+ * taken by another set's span). A window never forces a set; this says so.
+ */
+function windowLines(map: JointMap, switches: ReadonlyArray<{ set: string; frames: [number, number] }>, distances: ReadonlyMap<string, readonly number[]>, times: readonly number[], tolerance: number): string[] {
+  const out: string[] = [];
+  for (const set of map.alternates) {
+    if (set.frames === null) continue;
+    const shown = new Set<number>();
+    for (const sw of switches) if (sw.set === set.name) for (let i = sw.frames[0]; i <= sw.frames[1]; i++) shown.add(i);
+    const d = distances.get(set.name)!;
+    for (const [first, last] of set.frames) {
+      const lastIn = Math.min(last, times.length - 1);
+      const parts: string[] = [];
+      for (let i = first; i <= lastIn;) {
+        if (shown.has(i)) { i++; continue; }
+        let j = i;
+        while (j + 1 <= lastIn && !shown.has(j + 1)) j++;
+        const ds = d.slice(i, j + 1);
+        const worst = Math.max(...ds);
+        const over = ds.filter((x) => x > tolerance).length;
+        const span = i === j ? `frame ${i}` : `frames ${i}–${j}`;
+        parts.push(over === ds.length ? `${span} outside the tolerance (up to ${worst.toFixed(1)}° > ${tolerance}°)` : over === 0 ? `${span} within the tolerance but not shown (a run shorter than --switch-min, or another set's span)` : `${span} partly outside the tolerance (up to ${worst.toFixed(1)}°)`);
+        i = j + 1;
+      }
+      const head = `set "${set.name}" window ${first}–${last}`;
+      out.push(parts.length === 0 ? `${head}: shown on every frame` : `${head}: ${parts.join('; ')} — a window restricts a set, it never forces one`);
+    }
+  }
+  return out;
+}
+
+/** Each leg's first bone (its root, the thigh) and last bone (whose tip is the ankle), when the map has both. */
+function legBonesOf(map: JointMap): { r: { root: string; ankle: string }; l: { root: string; ankle: string } } | null {
+  const l = legsOf(map, 'reading the feet');
+  if ('problems' in l) return null;
+  return { r: { root: l.legs.r.chain.bones[0]!, ankle: l.legs.r.ankleBone }, l: { root: l.legs.l.chain.bones[0]!, ankle: l.legs.l.ankleBone } };
+}
+
+/** A LEG-SCALE line: the segment, its straight length, its ratio's spread, and the frames clamped. */
+function legScaleLine(l: LegScale, times: readonly number[]): string {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+  const count = (rs: Array<[number, number]>) => rs.reduce((k, x) => k + x[1] - x[0] + 1, 0);
+  const clamp = (rs: Array<[number, number]>, at: number, how: string) => (rs.length === 0 ? `none ${how} ${at}` : `${count(rs)} frame(s) ${how} ${at}, clamped (frames ${rs.map(span).join(', ')})`);
+  return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (95th percentile of ${times.length} frames); picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}]: ${clamp(l.low, l.limits[0], 'under')}; ${clamp(l.high, l.limits[1], 'over')}`;
+}