@rig-c/pose 0.19.0 → 0.20.1

package/src/retarget.ts

@@ -82,7 +82,7 @@ import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf } from './legs.ts';
+import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -163,18 +163,29 @@ export interface Flip {
   clipped: 'start' | 'end' | 'both' | null;
 }
 
-/** One span of frames under the short cutoff: the segment's angle there was interpolated, not read (`holdShort`). */
+/**
+ * One span of frames under `--short` (angle interpolated, `holdShort`) or under
+ * `SHORT_STEP_FRACTION` with a one-frame step over `SHORT_STEP_CAP` (step
+ * capped, `capShortSteps`, #110).
+ */
 export interface Short {
   chain: string;
   bone: string;
   /** The segment the bone carries: from joint, to joint. */
   joints: [string, string];
-  /** First and last frame under the cutoff; every one of them had its angle replaced, and the frames either side keep the input's. */
+  /** First and last frame whose angle was replaced; the frames either side keep the input's. */
   frames: [number, number];
   /** The lowest picture length on those frames, as a fraction of the segment's median picture length. */
   minFraction: number;
+  /** Present when a foreshortened segment (< `SHORT_STEP_FRACTION`) had its per-frame step capped (#110): the one-frame step after capping and the largest step asked, degrees, signed. */
+  step?: number;
+  asked?: number;
 }
 
+/** A limb segment shorter than this fraction of its median picture length has its per-frame angle step capped at `SHORT_STEP_CAP` degrees (rig-c/pose#110). */
+export const SHORT_STEP_FRACTION = 0.6;
+export const SHORT_STEP_CAP = 30;
+
 /**
  * A segment under the short cutoff long enough to be a pose (the limb pointing
  * at the camera), not a blur: short spans merged across a gap of `END_ON_GAP`
@@ -571,6 +582,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // against its own median, on the points the angle was read from.
   const short: Short[] = [];
   const endOn: EndOn[] = [];
+  const fractions = new Map<string, { chain: string; joints: [string, string]; fraction: number[] }>();
   if (opts.short !== 'off') {
     const cutoff = opts.short;
     for (const c of map.chains) {
@@ -586,7 +598,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           p.add('POSE_SHORT_MEDIAN', `chain "${c.name}" — bone "${b}"'s segment ${joints[0]} → ${joints[1]} has median picture length ${med}px over the ${n} frames; --short measures a frame's length against that median, and there is none to measure against`);
           return;
         }
-        const spans = holdShort(targets.get(b)!, lengths.map((l) => l / med), cutoff);
+        const fraction = lengths.map((l) => l / med);
+        fractions.set(b, { chain: c.name, joints, fraction });
+        const spans = holdShort(targets.get(b)!, fraction, cutoff);
         for (const s of spans) short.push({ chain: c.name, bone: b, joints, ...s });
         for (const run of mergeRuns(spans, END_ON_GAP)) {
           const seconds = Math.round((endOf(run.frames[1]) - keyTimes[run.frames[0]]!) * 1e6) / 1e6;
@@ -692,12 +706,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   if (opts.floor !== undefined && !plantOn) p.add('FLOOR', `--floor ${opts.floor} is the floor --plant-feet plants every support span on, and --plant-feet is not given`);
   if (opts.floor !== undefined && !Number.isFinite(opts.floor)) p.add('FLOOR', `--floor is ${opts.floor}; it must be a finite world y`);
   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);
+  const askedScales = new Map<string, number[]>();
+  for (const ls of legScale) askedScales.set(ls.bone, ls.asked);
+  /** Every bone on the legs' path posed on frame i, by the targets and the given scale series. */
+  const poseLegsWith = (i: number, sc: ReadonlyMap<string, 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) => sc.get(b)?.[i] ?? null);
     if (typeof r === 'string') throw new Refusal([{ code: 'LEGS_MAP', text: r }]);
     return r;
   };
+  /** Every bone on the legs' path posed on frame i, by the targets as they stand. */
+  const poseLegs = (i: number): PathPose => poseLegsWith(i, scales);
   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!);
@@ -706,20 +724,28 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       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();
+    // #107: the clamp floor holds the bone, not the hip; the plant places the hip from the scale the pose asked for.
     const offsets = Array.from({ length: n }, (_, i) => {
-      const lp = poseLegs(i);
+      const lp = poseLegsWith(i, askedScales);
       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)!;
     // #85: every support span on one floor — the median of their planted heights, or --floor.
     // #92: in place, the supporting ankle's own picture x, scaled, is the track its anchor follows.
-    const follow = inPlace ? (i: number, s: Side) => series.get(`${s}_ankle`)![i]![0] * scale!.factor : undefined;
-    const planted = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY], opts.floor, follow);
+    // #119: a tracked support follows the lower ankle's own picture x, scaled, on the floor until it is still.
+    const track = (i: number, s: Side) => series.get(`${s}_ankle`)![i]![0] * scale!.factor;
+    const follow = inPlace ? track : undefined;
+    const planted = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY], opts.floor, follow, track);
     const hip = planted.hip;
     floor = planted.floor;
     closure = planted.closure;
-    for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
     const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
+    // #133: on a frame where the supporting leg asks under --leg-scale's floor, its scalex follows the asked
+    // value down to #95's bound so the ankle stays on #85's floor; the free leg keeps the configured clamp.
+    if (legScaleOn && feet !== null) {
+      scaleSupport(legScale, scales, feet, L, hip, (i, s) => offsets[i]![s], (i, s) => tipOf(rest, poseLegs(i), L[s].ankleBone));
+    }
+    for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
     const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
     /** Both legs posed on frame i by the scales as they stand, world (y up): each chain's root and ankle. */
     const posedFeet = (i: number) => {
@@ -805,16 +831,20 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
    * offset turned by the nearest mapped bone above — the key formula's own
    * assumption (unit scale, no shear), which the landing check holds to account.
    */
+  let headNodBone: string | null = null;
+  let headNod: Pt[] | null = null;
+  let headNodTrack: MotionTrack | 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)];
-    if (own.parent === null) return [own.worldX, own.worldY];
+    const nod = b === headNodBone ? (headNod?.[i] ?? [0, 0]) : [0, 0];
+    if (own.parent === null) return [own.worldX + nod[0], own.worldY + nod[1]];
     const parent = own.parent;
     const po = posedOrigin(parent, i);
     const r = turnAbove(parent, i) / DEG;
     const ox = own.worldX - rest.get(parent)!.worldX;
     const oy = own.worldY - rest.get(parent)!.worldY;
-    return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
+    return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy + nod[0], po[1] + Math.sin(r) * ox + Math.cos(r) * oy + nod[1]];
   };
   /** A rig point (a bone, `name:tip`, `a+b`) posed on frame i the same way. */
   const posedPoint = (spec: string, i: number): Pt => {
@@ -868,6 +898,13 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   };
   const turn = (bone: string, i: number) => targets.get(bone)![i]! - restOf.get(bone)!;
   const covered = coveredChains(sw.switches, n);
+  if (opts.short !== 'off') {
+    for (const [b, info] of fractions) {
+      for (const s of capShortSteps(targets.get(b)!, info.fraction, covered.get(info.chain))) {
+        short.push({ chain: info.chain, bone: b, joints: info.joints, ...s });
+      }
+    }
+  }
   const range: RangeDemand[] = [];
   const order = map.chains.flatMap((c) => c.bones.map((b) => ({ c, b }))).filter(({ c, b }) => c.reach || b in c.range);
   order.sort((x, y) => depth(x.b) - depth(y.b));
@@ -895,6 +932,74 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
+  // #111: the head chain's nod channel — the eyes' vertical travel against the
+  // neck, measured in the rig's own units, keyed as a translate on the head bone
+  // (whose rotate track carries roll only).
+  for (const c of map.chains) {
+    for (let k = 0; k + 1 < c.joints.length; k++) {
+      const ja = c.joints[k]!;
+      const jb = c.joints[k + 1]!;
+      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 rEye = series.get('r_eye')!;
+      const lEye = series.get('l_eye')!;
+      const neckSeries = series.get('neck') ?? (() => {
+        const h = heldOf('neck');
+        return 'never' in h ? undefined : h.at;
+      })();
+      let nodScale: number | null = scale?.factor ?? null;
+      if (nodScale === null && ha.includes('>')) {
+        const [pa, pb] = aimEnds(hb, ha);
+        const a0 = rigPoint(rest, pa)!;
+        const b0 = rigPoint(rest, pb)!;
+        const rigEye = Math.hypot(b0[0] - a0[0], b0[1] - a0[1]);
+        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 && nodScale !== null) {
+        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
+        const dy = refEN.map((v) => (v - refEN[0]!) * nodScale);
+        if (dy.some((v) => Math.abs(r3(v)) > 0)) {
+          const bone = rest.get(hb)!;
+          const parent = bone.parent === null ? null : rest.get(bone.parent)!;
+          const keys: MotionKey[] = [];
+          const nod: Pt[] = [];
+          for (let i = 0; i < n; i++) {
+            const wy = dy[i]!;
+            let lx = 0;
+            let ly = r3(wy);
+            let awx = 0;
+            let awy = ly;
+            if (parent !== null) {
+              const r = turnAbove(parent.name, i) / DEG;
+              const pa = Math.cos(r) * parent.a - Math.sin(r) * parent.c;
+              const pb = Math.cos(r) * parent.b - Math.sin(r) * parent.d;
+              const pc = Math.sin(r) * parent.a + Math.cos(r) * parent.c;
+              const pd = Math.sin(r) * parent.b + Math.cos(r) * parent.d;
+              const det = pa * pd - pb * pc;
+              lx = r3((-pb * wy) / det);
+              ly = r3((pa * wy) / det);
+              awx = pa * lx + pb * ly;
+              awy = pc * lx + pd * ly;
+            }
+            keys.push({ t: keyTimes[i]!, v: [lx, ly] });
+            nod.push([awx, awy]);
+          }
+          headNodBone = hb;
+          headNod = nod;
+          headNodTrack = { bone: hb, property: 'translate', keys };
+        }
+      }
+      break;
+    }
+    if (headNodTrack !== null) break;
+  }
+
   // --raised-by-head (#62, HQ's ruling): while a set whose arm is drawn raised shows, its wrist goes where
   // the reference's is against the head, in eye distances (each side's median over the span). Solved last
   // of the bones: every bone above the arm, the head and the trunk's reach included, has its final target
@@ -1176,6 +1281,7 @@ 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);
 
   return {
@@ -1302,10 +1408,97 @@ export function mergeRuns(spans: readonly ShortSpan[], gap: number): ShortSpan[]
   return out;
 }
 
+/**
+ * Cap one-frame steps on a foreshortened segment (#110), in place. Where a
+ * segment's picture length is under `SHORT_STEP_FRACTION` (0.60) of its median
+ * on either side of a frame step (above `--short`'s hold cutoff, where two end-on
+ * pixels still swing the angle faster than the limb moved) and the one-frame turn
+ * exceeds `SHORT_STEP_CAP` (30°), spread the turn across a symmetric window of
+ * frames the same way `spreadFlips` does (`lo = k - h - 1`, `hi = k + h`), bounded
+ * by the ends of the pose and by any active alternate set on the chain (`covered`).
+ */
+export function capShortSteps(
+  angles: number[],
+  fraction: readonly number[],
+  covered?: readonly boolean[],
+  fractionCutoff: number = SHORT_STEP_FRACTION,
+  stepCap: number = SHORT_STEP_CAP,
+): ShortSpan[] {
+  const n = angles.length;
+  if (n < 2) return [];
+  const out: ShortSpan[] = [];
+  for (let segStart = 0; segStart < n;) {
+    if (covered?.[segStart] === true) {
+      segStart++;
+      continue;
+    }
+    let segEnd = segStart;
+    while (segEnd + 1 < n && covered?.[segEnd + 1] !== true) segEnd++;
+    if (segEnd - segStart >= 1) {
+      const u: number[] = new Array<number>(n).fill(0);
+      u[segStart] = angles[segStart]!;
+      for (let i = segStart + 1; i <= segEnd; i++) u[i] = u[i - 1]! + wrap(angles[i]! - angles[i - 1]!);
+      const fits = (lo: number, hi: number) => Math.abs(u[hi]! - u[lo]!) <= stepCap * (hi - lo);
+      interface Win { lo: number; hi: number; asked: number }
+      const wins: Win[] = [];
+      for (let k = segStart + 1; k <= segEnd; k++) {
+        if (!(Math.min(fraction[k - 1]!, fraction[k]!) < fractionCutoff)) continue;
+        const jump = u[k]! - u[k - 1]!;
+        if (Math.abs(jump) <= stepCap) continue;
+        let h = 1;
+        let lo = Math.max(segStart, k - h - 1);
+        let hi = Math.min(segEnd, k + h);
+        while (!fits(lo, hi) && (lo > segStart || hi < segEnd)) {
+          h++;
+          lo = Math.max(segStart, k - h - 1);
+          hi = Math.min(segEnd, k + h);
+        }
+        wins.push({ lo, hi, asked: jump });
+      }
+      for (let changed = true; changed;) {
+        changed = false;
+        wins.sort((a, b) => a.lo - b.lo);
+        for (let i = 0; i + 1 < wins.length; i++) {
+          const a = wins[i]!;
+          const b = wins[i + 1]!;
+          if (b.lo >= a.hi) continue;
+          wins.splice(i, 2, { lo: a.lo, hi: Math.max(a.hi, b.hi), asked: Math.abs(b.asked) > Math.abs(a.asked) ? b.asked : a.asked });
+          changed = true;
+          break;
+        }
+        if (changed) continue;
+        for (const w of wins) {
+          if (fits(w.lo, w.hi) || (w.lo === segStart && w.hi === segEnd)) continue;
+          w.lo = Math.max(segStart, w.lo - 1);
+          w.hi = Math.min(segEnd, w.hi + 1);
+          changed = true;
+        }
+      }
+      for (const w of wins) {
+        if (w.lo + 1 > w.hi - 1) continue;
+        const step = (u[w.hi]! - u[w.lo]!) / (w.hi - w.lo);
+        for (let i = w.lo + 1; i < w.hi; i++) angles[i] = wrap(u[w.lo]! + step * (i - w.lo));
+        let minFraction = Infinity;
+        for (let i = w.lo + 1; i <= w.hi - 1; i++) minFraction = Math.min(minFraction, fraction[i]!);
+        if (!(minFraction < fractionCutoff)) {
+          minFraction = Math.min(minFraction, fraction[w.lo]!, fraction[w.hi]!);
+        }
+        out.push({ frames: [w.lo + 1, w.hi - 1], minFraction, step: r3(step), asked: r3(w.asked) });
+      }
+    }
+    segStart = segEnd + 1;
+  }
+  return out;
+}
+
 const spanOf = (frames: [number, number], times: readonly number[]): string =>
   frames[0] === frames[1] ? `frame ${frames[0]} (t=${times[frames[0]]!.toFixed(3)}s)` : `frames ${frames[0]}–${frames[1]} (t=${times[frames[0]]!.toFixed(3)}–${times[frames[1]]!.toFixed(3)}s)`;
 
 export function shortLine(s: Short, times: readonly number[], cutoff: number): string {
+  if (s.step !== undefined && s.asked !== undefined) {
+    const sg = (v: number) => `${v >= 0 ? '+' : '−'}${Math.abs(v).toFixed(1)}°`;
+    return `chain "${s.chain}" bone "${s.bone}" (${s.joints[0]} → ${s.joints[1]}) ${spanOf(s.frames, times)}: picture length down to ${s.minFraction.toFixed(2)} of its median, under ${SHORT_STEP_FRACTION.toFixed(2)}, turned ${sg(s.asked)} in one frame (over ${SHORT_STEP_CAP}°); spread to ${sg(s.step)} per frame`;
+  }
   const lo = s.frames[0] - 1;
   const hi = s.frames[1] + 1;
   const held = lo < 0 && hi >= times.length

package/src/run.ts

@@ -18,7 +18,7 @@ import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switc
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
-import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance } from './legs.ts';
+import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -138,6 +138,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const e of r.byHip) if (e.short.length > 0) say(`  REACH  ${reachLine(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)}`);
+    for (const l of r.legScale) for (const s of l.support ?? []) say(`  LEG-SCALE ${supportScaleLine(l, s, 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;
@@ -146,6 +147,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       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'}`);
       if (f.lowered !== undefined) say(`  FEET   ${loweredLine(f.lowered)}`);
+      if (f.tracked !== undefined) say(`  FEET   tracked (the lower foot supports on the floor, following its scaled ankle track until still, rig-c/pose#119): ${f.tracked.map((x) => `${x.side} ${span(x.frames)}`).join(', ')}`);
       if (r.closure !== null) say(`  FEET   ${travelLine(r.closure)}`);
       else 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'}`);
       if (r.floor !== null) {
@@ -315,10 +317,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         raised: r.raised,
         // Only when a set declares `place` (#93): a map without one writes the report it always has.
         ...(map.alternates.some((x) => x.place !== undefined && x.place !== null) ? { byHip: r.byHip } : {}),
-        legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
+        legScale: r.legScale.map(({ scale: _scale, asked: _asked, ...rest }) => rest),
         pivot: r.pivot,
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, ...(r.stance.range === undefined ? {} : { range: r.stance.range }), runs: r.stance.runs, over: r.stance.over },
-        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, ...(r.feet.lowered === undefined ? {} : { lowered: r.feet.lowered }), floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, ...(r.blendHold.range === undefined ? {} : { range: r.blendHold.range }), runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading, closure: r.closure },
+        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, ...(r.feet.lowered === undefined ? {} : { lowered: r.feet.lowered }), ...(r.feet.tracked === undefined ? {} : { tracked: r.feet.tracked }), floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, ...(r.blendHold.range === undefined ? {} : { range: r.blendHold.range }), runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading, closure: r.closure },
         shear,
         idleDropped: idle === null ? null : idle.dropped,
         idleKeptOut: idle === null ? null : idle.keptOut,
@@ -672,6 +674,16 @@ function legScaleLine(l: LegScale, times: readonly number[]): string {
   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')}`;
 }
 
+/** A LEG-SCALE past the floor (support) line (rig-c/pose#133): the supporting leg segment scaled below `--leg-scale`'s floor down to #95's bound. */
+export function supportScaleLine(l: LegScale, s: SupportScaleRun, times: readonly number[]): string {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
+  const val = (r: { min: number; max: number }) => (r.min === r.max ? r.min.toFixed(4) : `${r.min.toFixed(4)}–${r.max.toFixed(4)}`);
+  if (s.clamped !== undefined) {
+    return `past the floor (support): chain "${l.chain}" bone "${l.bone}" (supporting foot ${s.side}) ${span(s.frames)} — asked ${val(s.asked)} under ${l.limits[0]}, clamped at the leg's own range ${s.clamped.bound.toFixed(4)} (#95), used ${val(s.used)}; hip rose by up to +${s.clamped.hipRise.toFixed(2)} units (never sinks)`;
+  }
+  return `past the floor (support): chain "${l.chain}" bone "${l.bone}" (supporting foot ${s.side}) ${span(s.frames)} — asked ${val(s.asked)} under ${l.limits[0]}, used ${val(s.used)} (within the leg's own range, #95; ankle stays on the floor)`;
+}
+
 /**
  * POSE_NOT_CLEANED (#67): retarget reads only a sequence `rig-pose clean` wrote.
  * The message is the command to run on this file; the output name is a

package/src/switch.ts

@@ -590,22 +590,50 @@ export function artRangeLine(e: ArtRange, times: readonly number[]): string {
   return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it; ${e.clamped ? 'held at the limit' : 'the bone follows the pose'} — demand for another drawing of the set`;
 }
 
+/**
+ * The art-range clamp eases in and out at a span's edges over at least
+ * `ART_EASE_FRAMES` frames, or enough frames to keep the clamp's step at the
+ * boundary within `ART_EASE_STEP` degrees per frame (#110).
+ */
+export const ART_EASE_FRAMES = 3;
+export const ART_EASE_STEP = 3;
+
 /**
  * Inside each span, a bone with a `turn` in the set is held within it: its
- * target world angle is drawn + clamp(wrap(target − drawn), min, max). Each
- * bone is clamped on its own world angle, and keys are differences of world
- * angles, so a forearm under a clamped upper arm keeps its own target.
+ * target world angle is drawn + clamp(wrap(target − drawn), min, max), eased
+ * in and out over at least `ART_EASE_FRAMES` frames at an edge where the clamp
+ * switches on or off across the boundary (#110). Each bone is clamped on its
+ * own world angle, and keys are differences of world angles, so a forearm
+ * under a clamped upper arm keeps its own target.
  */
 export function clampArt(switches: readonly Switch[], map: JointMap, targets: Map<string, number[]>): void {
   for (const sw of switches) {
     const set = map.alternates.find((a) => a.name === sw.set)!;
+    const [a, b] = sw.frames;
     for (const [bone, limits] of Object.entries(set.turn)) {
       const drawn = set.drawn[bone]!;
       const target = targets.get(bone)!;
-      for (let i = sw.frames[0]; i <= sw.frames[1]; i++) {
+      const n = target.length;
+      const delta = (i: number): number => {
         const t = wrap(target[i]! - drawn);
         const c = Math.min(Math.max(t, limits[0]), limits[1]);
-        if (Math.abs(c - t) > RANGE_SLACK) target[i] = wrap(drawn + c);
+        return Math.abs(c - t) > RANGE_SLACK ? c - t : 0;
+      };
+      const da = delta(a);
+      const db = delta(b);
+      const easeIn = a > 0 && da !== 0 && Math.sign(delta(a - 1)) === Math.sign(da)
+        ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(da) / ART_EASE_STEP) - 1)
+        : 0;
+      const easeOut = b + 1 < n && db !== 0 && Math.sign(delta(b + 1)) === Math.sign(db)
+        ? Math.max(ART_EASE_FRAMES, Math.ceil(Math.abs(db) / ART_EASE_STEP) - 1)
+        : 0;
+      for (let i = a; i <= b; i++) {
+        const d = delta(i);
+        if (d === 0) continue;
+        const wIn = i - a < easeIn ? (i - a + 1) / (easeIn + 1) : 1;
+        const wOut = b - i < easeOut ? (b - i + 1) / (easeOut + 1) : 1;
+        const w = Math.min(wIn, wOut);
+        target[i] = wrap(target[i]! + w * d);
       }
     }
   }

package/src/verify.ts

@@ -10,7 +10,7 @@
  */
 import { poseRawAnimation, poseRawSetup, type CompiledDocument, type RawBone } from 'rig-c/core';
 import type { Body18 } from './joints.ts';
-import { aimAngle, pointAt, type JointMap } from './map.ts';
+import { aimAngle, aimEnds, pointAt, type JointMap } from './map.ts';
 import type { HipsInferred, Joint, PelvisFit, Run } from './pose.ts';
 import type { Retarget } from './retarget.ts';
 import { pictureAngle, pointOn, wrap } from './retarget.ts';
@@ -289,6 +289,81 @@ export interface Posture {
     ratio: number | null;
     ratioSw: number | null;
   } | null;
+  /**
+   * Present with `--plant-feet` when there is at least one support span (#107):
+   * per support span, the detrended (centred ±12-frame moving mean removed)
+   * vertical sd, rig/reference ratio and correlation for the hip, the neck, and
+   * eyes − neck.
+   */
+  bounce?: BounceSpan[];
+}
+
+export interface BounceMetric {
+  reference: number;
+  rig: number;
+  ratio: number | null;
+  corr: number | null;
+}
+
+export interface BounceSpan {
+  side: 'r' | 'l';
+  frames: [number, number];
+  hip: BounceMetric;
+  neck: BounceMetric;
+  eyesNeck: BounceMetric;
+}
+
+/** Half-window (frames each side; 25-frame centred window at 24 fps ≈ 1 s) for detrending a support span's bounce (#107). */
+export const POSTURE_DETREND_HALF_WINDOW = 12;
+
+function detrend(xs: readonly number[], w = POSTURE_DETREND_HALF_WINDOW): number[] {
+  const n = xs.length;
+  return xs.map((x, i) => {
+    const lo = Math.max(0, i - w);
+    const hi = Math.min(n - 1, i + w);
+    let sum = 0;
+    for (let k = lo; k <= hi; k++) sum += xs[k]!;
+    return x - sum / (hi - lo + 1);
+  });
+}
+
+function sdOf(xs: readonly number[]): number {
+  if (xs.length === 0) return 0;
+  const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+  let s2 = 0;
+  for (const x of xs) s2 += (x - mean) * (x - mean);
+  return Math.sqrt(s2 / xs.length);
+}
+
+function corrOf(a: readonly number[], b: readonly number[]): number | null {
+  if (a.length < 2 || a.length !== b.length) return null;
+  const ma = a.reduce((x, y) => x + y, 0) / a.length;
+  const mb = b.reduce((x, y) => x + y, 0) / b.length;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < a.length; i++) {
+    const xa = a[i]! - ma;
+    const xb = b[i]! - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  const den = Math.sqrt(da * db);
+  return den > 1e-9 ? num / den : null;
+}
+
+function bounceMetric(ref: readonly number[], rig: readonly number[]): BounceMetric {
+  const dr = detrend(ref);
+  const dg = detrend(rig);
+  const sr = sdOf(dr);
+  const sg = sdOf(dg);
+  return {
+    reference: sr,
+    rig: sg,
+    ratio: sr > 1e-9 ? sg / sr : null,
+    corr: corrOf(dr, dg),
+  };
 }
 
 function rangeOf(xs: number[]): Range {
@@ -407,6 +482,78 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       ratioSw: rig === null || rig.rangeSw === null ? null : rig.rangeSw / reference.rangeSw,
     };
   }
+  const bounce: BounceSpan[] = [];
+  if (r.planted && r.feet !== null && r.feet.supports.length > 0) {
+    const scaleNeckIdx = map.translate.scale.pose.indexOf('neck');
+    const neckChain = map.chains.find((c) => c.joints.includes('neck'));
+    const neckJointIdx = neckChain === undefined ? -1 : neckChain.joints.indexOf('neck');
+    const rigNeck = posed[0]?.has('neck')
+      ? 'neck'
+      : scaleNeckIdx >= 0
+        ? map.translate.scale.rig[scaleNeckIdx]!
+        : neckChain !== undefined && neckJointIdx > 0
+          ? (neckChain.aim[neckJointIdx - 1] === 'x' ? `${neckChain.bones[neckJointIdx - 1]}:tip` : neckChain.aim[neckJointIdx - 1]!)
+          : rigShoulder;
+    const headChain = map.chains.find((c) => c.joints.includes('r_eye') && c.joints.includes('l_eye'));
+    const rigNeckY = (b: Map<string, RawBone>): number | null => (rigNeck === null ? null : (pointAt(b, lengths, rigNeck)?.[1] ?? null));
+    const rigEyesY = (b: Map<string, RawBone>): number | null => {
+      if (headChain !== undefined) {
+        const k = headChain.joints.findIndex((j, idx) => idx + 1 < headChain.joints.length && ((j === 'r_eye' && headChain.joints[idx + 1] === 'l_eye') || (j === 'l_eye' && headChain.joints[idx + 1] === 'r_eye')));
+        if (k >= 0) {
+          const ha = headChain.aim[k]!;
+          const hb = headChain.bones[k]!;
+          if (ha.includes('>')) {
+            const [pa, pb] = aimEnds(hb, ha);
+            const ya = pointAt(b, lengths, pa);
+            const yb = pointAt(b, lengths, pb);
+            if (ya !== null && yb !== null) return (ya[1] + yb[1]) / 2;
+          }
+          const p = pointAt(b, lengths, ha === 'x' ? hb : ha);
+          if (p !== null) return p[1];
+        }
+      }
+      if (b.has('eye_r') && b.has('eye_l')) return (b.get('eye_r')!.worldY + b.get('eye_l')!.worldY) / 2;
+      if (b.has('head')) return b.get('head')!.worldY;
+      return rigNeckY(b);
+    };
+    for (const sp of r.feet.supports) {
+      const refHip: number[] = [];
+      const rigHipY: number[] = [];
+      const refNeck: number[] = [];
+      const rigNeckS: number[] = [];
+      const refEyesNeck: number[] = [];
+      const rigEyesNeck: number[] = [];
+      for (let i = sp.frames[0]; i <= sp.frames[1]; i++) {
+        const b = posed[i]!;
+        const rh = at(i, 'r_hip');
+        const lh = at(i, 'l_hip');
+        if (rh !== null && lh !== null) {
+          refHip.push(-((rh[1] + lh[1]) / 2) * s);
+          rigHipY.push(b.get(r.origin.bone)!.worldY);
+        }
+        const nk = at(i, 'neck');
+        const ny = rigNeckY(b);
+        if (nk !== null && ny !== null) {
+          refNeck.push(-nk[1] * s);
+          rigNeckS.push(ny);
+          const re = at(i, 'r_eye');
+          const le = at(i, 'l_eye');
+          const ey = rigEyesY(b);
+          if (re !== null && le !== null && ey !== null) {
+            refEyesNeck.push(-((re[1] + le[1]) / 2 - nk[1]) * s);
+            rigEyesNeck.push(ey - ny);
+          }
+        }
+      }
+      bounce.push({
+        side: sp.side,
+        frames: [sp.frames[0], sp.frames[1]],
+        hip: bounceMetric(refHip, rigHipY),
+        neck: bounceMetric(refNeck, rigNeckS),
+        eyesNeck: bounceMetric(refEyesNeck, rigEyesNeck),
+      });
+    }
+  }
   const has106 = measured !== null && (measured.scaled !== undefined || measured.unmeasured !== undefined || measured.fit !== undefined);
   return {
     pelvis: pelvis.name,
@@ -438,6 +585,7 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
         }
       : {}),
     sway,
+    ...(bounce.length > 0 ? { bounce } : {}),
   };
 }
 
@@ -478,5 +626,11 @@ export function postureLines(q: Posture): string[] {
       out.push(`sway, x-range of mid_hip − mid_shoulder: ${ref}, rig ${f1(w.rig.range)} units (${sw}; mid_hip = "${q.rigHip}", mid_shoulder = "${q.rigShoulder}") — rig/reference ${f3(w.ratio!)} in units${ratioSw}`);
     }
   }
+  if (q.bounce !== undefined) {
+    const fmt = (bm: BounceMetric) => `${bm.ratio === null ? 'n/a' : f3(bm.ratio)} (${f1(bm.rig)}/${f1(bm.reference)}u, r=${bm.corr === null ? 'none' : f3(bm.corr)})`;
+    for (const b of q.bounce) {
+      out.push(`bounce ${b.side} ${b.frames[0]}–${b.frames[1]} (detrended y sd, rig/reference): hip ${fmt(b.hip)}, neck ${fmt(b.neck)}, eyes − neck ${fmt(b.eyesNeck)}`);
+    }
+  }
   return out;
 }