@rig-c/pose 0.8.1 → 0.10.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/run.ts

@@ -9,11 +9,14 @@ import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 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 { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
+import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type RetargetOptions } from './retarget.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;
@@ -33,6 +36,12 @@ export interface RetargetArgs extends RetargetOptions {
   render?: string;
   /** Write the run's measurements as JSON here. */
   report?: string;
+  /** The rig's animation read as its idle (default: idle); naming one the motion spec lacks is refused. */
+  idle?: string;
+  /** Loop the idle's dropped tracks into the new animation (#43 item 2). */
+  carryIdle?: boolean;
+  /** A rig-pose-tracks/1 fragment merged into the new animation. */
+  merge?: string;
 }
 
 export interface RunResult {
@@ -50,8 +59,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     throw new Refusal(problems);
   };
   const args = new Problems();
-  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose]] as const) {
-    if (!existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
+  for (const [flag, path] of [['--map', a.map], ['--pose', a.pose], ['--merge', a.merge]] as const) {
+    if (path !== undefined && !existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
   }
   // A file this run writes goes into a directory that is there already; --build and --render make theirs.
   for (const [flag, path] of [['--out', a.out], ['--report', a.report]] as const) {
@@ -65,6 +74,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const base = baseMotionOf(input);
   const animations = base.animations as Record<string, unknown>;
   if (a.name in animations) refuse([{ code: 'MOTION_NAME_FREE', text: `the rig's motion spec already has an animation "${a.name}" (it has ${Object.keys(animations).join(', ')}); name this one with --name` }]);
+  const idleName = a.idle ?? 'idle';
+  if (!(idleName in animations) && (a.idle !== undefined || a.carryIdle === true)) {
+    refuse([{ code: 'IDLE_NAME', text: `${a.idle !== undefined ? `--idle "${idleName}"` : '--carry-idle reads the animation "idle", and'} the rig's motion spec ${input.motion === null ? '— there is none, so it has no animations' : `${input.motion} has no animation "${idleName}" (it has ${Object.keys(animations).join(', ') || 'none'})`}; name the rig's idle with --idle` }]);
+  }
+  const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
   const map = readMap(readFileSync(a.map, 'utf8'), a.map);
   const poseText = readFileSync(a.pose, 'utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
@@ -85,7 +99,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     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' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}`);
     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)}`);
@@ -104,8 +118,59 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     }
     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 } };
+    // The idle against the new animation (#43 item 2): what it drops, and with --carry-idle, looped back in.
+    const groups = (isObject(base.groups) ? base.groups : {}) as Record<string, string[]>;
+    const easings = (isObject(base.easings) ? base.easings : {}) as Record<string, number[]>;
+    const own = r.animation.tracks as unknown as RigcTrack[];
+    const T = r.animation.duration;
+    let idle: IdleReading | null = null;
+    if (!(idleName in animations)) say(`  IDLE   ${input.motion === null ? 'the rig has no motion spec' : `the rig's motion spec has no animation "idle" (it has ${Object.keys(animations).join(', ') || 'none'})`}; no idle read (--idle names another)`);
+    else {
+      const setupOf = (t: Target, property: string, sample: unknown): unknown => {
+        if (t.kind === 'slot' && property === 'attachment') return slots.get(t.name)?.setup;
+        if ((t.kind === 'bone' || t.kind === 'group') && Array.isArray(sample)) return boneIdentity(property, sample.length);
+        return undefined;
+      };
+      const mapped = [...map.chains.flatMap((c) => c.bones), ...(map.translate === null ? [] : [map.translate.bone])];
+      const below = new Map<string, string[]>();
+      for (const m of new Set(mapped)) {
+        for (let b = rest.get(m)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) {
+          const list = below.get(b) ?? [];
+          if (!list.includes(m)) list.push(m);
+          below.set(b, list);
+        }
+      }
+      idle = readIdle(idleName, a.name, animations[idleName] as Record<string, unknown>, own, T, { groups, easings }, setupOf, a.carryIdle === true, (bone) => below.get(bone) ?? [], (bone) => {
+        const hip = map.translate?.bone;
+        if (hip === undefined) return null;
+        for (let b = rest.get(hip)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) if (b === bone) return hip;
+        return null;
+      });
+      say(`  IDLE   animation "${idleName}" (${idle.duration.toFixed(3)}s, ${idle.tracks} track(s)) against "${a.name}": ${idle.dropped.length} dropped (${a.carryIdle === true ? `${idle.carriedTracks.length} carried, looped to ${T.toFixed(3)}s` : 'not carried; --carry-idle loops them in'}), ${idle.keptOut.length} kept out`);
+      for (const d of idle.dropped) say(`  IDLE-DROPPED ${droppedLine(d, a.name, a.carryIdle === true, T)}`);
+      for (const k of idle.keptOut) say(`  IDLE-KEPT-OUT ${keptOutLine(k)}`);
+      for (const n of idle.notTracks) say(`  IDLE-KEPT-OUT "${idleName}"'s ${n} timeline(s): not a track; neither compared nor carried`);
+    }
+    const carried = idle?.carriedTracks ?? [];
+    if (fragment.length > 0) {
+      const problems = mergeProblems(fragment, a.merge!, a.name, [...own, ...carried], T, groups);
+      if (problems.length > 0) refuse(problems);
+      for (const tr of fragment) say(`  MERGE  ${a.merge}: ${trackLabel(tr, groups)}, ${tr.keys.length} key(s) at t=${tr.keys[0]!.t}${tr.keys.length > 1 ? `–${tr.keys[tr.keys.length - 1]!.t}` : ''}s`);
+    }
+    const added = [...carried, ...fragment];
+    const animation = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    const motion = { ...base, animations: { ...animations, [a.name]: animation } };
     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 }))]);
@@ -116,17 +181,41 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const posed = poseFrames(doc, a.name, r.times);
     const landings = measureLanding(doc, a.name, map, r, posed);
     const p = new Problems();
+    // A carried idle track on a bone above a mapped one moves it where the keys did not ask (the key formula holds unmapped bones at setup).
+    const carriedAbove = (bone: string): string => {
+      const above = new Set<string>();
+      for (let b = rest.get(bone)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) above.add(b);
+      const hits = carried.filter((tr) => {
+        const t = targetOf(tr);
+        return t !== null && (t.kind === 'bone' ? above.has(t.name) : t.kind === 'group' && (groups[t.name] ?? []).some((m) => above.has(m)));
+      });
+      return hits.length === 0 ? '' : `; --carry-idle carried ${hits.map((tr) => trackLabel(tr, groups)).join(', ')} onto bones above it`;
+    };
     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)`);
+      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)${carriedAbove(l.bone)}`);
     }
     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]!)));
@@ -160,7 +249,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         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, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -176,6 +265,13 @@ 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,
+        idleDropped: idle === null ? null : idle.dropped,
+        idleKeptOut: idle === null ? null : idle.keptOut,
+        merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
       }, null, 2)}\n`);
     }
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
@@ -235,3 +331,18 @@ function windowLines(map: JointMap, switches: ReadonlyArray<{ set: string; frame
   }
   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')}`;
+}