@rig-c/pose 0.30.1 → 0.31.0

package/README.md

@@ -200,7 +200,7 @@ Re-checked on a @rig-c/parts fixture rig with the short hold, the flip guard and
 
 A knee bending toward the camera is seen from the front only as a shorter leg, and a rig with rigid legs cannot lower its hip without lifting its feet ([#47](https://github.com/rig-c/pose/issues/47)). Two flags, both off by default:
 
-**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the larger of the two sides' 95th-percentile picture lengths for that segment over the sequence ([#148](https://github.com/rig-c/pose/issues/148); on a non-`in-place` sequence longer than 25 frames, each frame's segment length is normalised by a continuous rate-limited figure-scale signal `figureScaleOf` derived from posture-invariant measures — `max(r_thigh + r_shin, l_thigh + l_shin)`, shoulder width and eye width, never the trunk — with frame-to-frame step ≤ 1 % and frozen spans ≥ 5 frames held at their median, so neither camera zoom nor a forward trunk bend reads as the camera moving, and `--camera <file>` writes that track as `rig-pose-camera/1` without changing `motion.json`, [#159](https://github.com/rig-c/pose/issues/159), [#161](https://github.com/rig-c/pose/issues/161), [#163](https://github.com/rig-c/pose/issues/163), [#172](https://github.com/rig-c/pose/issues/172)), clamped to [min, max]. When the camera-normalised trunk (`neck → mid_hip` or `mid_shoulder → mid_hip`) foreshortens or extends by more than 4 % from its standing length, the trunk bone is keyed in `scaley` (for a `+y`-aimed trunk, `scalex` for `+x`) clamped to the same `[min, max]` bounds, carrying the trunk and head's depth bend while keeping the aimed rotation ([#172](https://github.com/rig-c/pose/issues/172)). The bounds are `<min,max>` with `0 < min ≤ 1 ≤ max`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit.
+**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the larger of the two sides' 95th-percentile picture lengths for that segment over the sequence ([#148](https://github.com/rig-c/pose/issues/148), weighted by the segment's share of the two legs' mean setup bone length when the rig's setup legs differ by more than 0.1 % so an asymmetrically drawn rig places both ankles at the sequence's relative height, [#225](https://github.com/rig-c/pose/issues/225); on a non-`in-place` sequence longer than 25 frames, each frame's segment length is normalised by a continuous rate-limited figure-scale signal `figureScaleOf` derived from posture- and crouch-invariant segment measures — `max(r_thigh + r_shin, l_thigh + l_shin)` plus the `mid_hip → mid_shoulder` trunk segment held at each support span's 95th-percentile straight length when the 5-series consensus moves past ±2 %, never vertical `ankle.y − nose.y` — with frame-to-frame step ≤ 1 % and frozen spans ≥ 5 frames held at their median, so neither camera zoom, a forward trunk bend nor a landing crouch reads as the figure changing size, and `--camera <file>` writes that track as `rig-pose-camera/1` without changing `motion.json`, [#159](https://github.com/rig-c/pose/issues/159), [#161](https://github.com/rig-c/pose/issues/161), [#163](https://github.com/rig-c/pose/issues/163), [#172](https://github.com/rig-c/pose/issues/172), [#226](https://github.com/rig-c/pose/issues/226)), clamped to [min, max]. When the camera-normalised trunk (`neck → mid_hip` or `mid_shoulder → mid_hip`) foreshortens or extends by more than 4 % from its standing length, the trunk bone is keyed in `scaley` (for a `+y`-aimed trunk, `scalex` for `+x`) clamped to the same `[min, max]` bounds, carrying the trunk and head's depth bend while keeping the aimed rotation ([#172](https://github.com/rig-c/pose/issues/172)). The bounds are `<min,max>` with `0 < min ≤ 1 ≤ max`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit with the unclamped `asked` scale range on each clamped run (`legScale[].clamped` in `--report`, `{ frames, times, limit, asked: { min, max } }`, [#225](https://github.com/rig-c/pose/issues/225)).
 
 rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inherit mode takes its parent's whole world matrix. So under a thigh scaled by s, a shin at angle φ in the thigh's axes points at atan2(sin φ, s·cos φ), and is itself scaled by |(s·cos φ, sin φ)|. A child (or its intermediate control bone) with `noScale` or `noScaleOrReflection` ([#153](https://github.com/rig-c/pose/issues/153)) still has its direction carried through the parent's scaled matrix, so its angle is skewed the same way, while rig-c normalises that direction to unit length so the parent's scale is not inherited. The rotate key `turn − turn above` assumes unit scale. A mapped bone under a scaled bone is therefore keyed through its parent's posed matrix: a `rotate` key k and a `scalex` key s' put its world x axis on its target at the scale asked (under `noScale`, s' is the bone's own asked scale s directly). On `dance-a` the unit-scale formula missed the shins by up to 2.4°, their length by 0.16 of setup and the ankles by 38 units; solved, every bone lands. A `normal` child's art is still sheared by its parent's scale, and a bone under it (a foot) is squashed along the shin: `SHEAR` reads both.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/legs.ts

@@ -295,11 +295,18 @@ export interface SupportScaleRun {
   clamped?: { bound: number; hipRise: number };
 }
 
+export interface ClampedScaleRun {
+  frames: [number, number];
+  limit: 'low' | 'high';
+  /** The lowest and highest scale asked (`picture length ÷ straight`) on the clamped run's frames (#225). */
+  asked: { min: number; max: number };
+}
+
 export interface LegScale {
   chain: string;
   bone: string;
   joints: [string, string];
-  /** The straight length: the larger of the two sides' 95th-percentile picture lengths for this segment (#148), px. */
+  /** The straight length: the larger of the two sides' 95th-percentile picture lengths for this segment (#148), weighted by the bone's setup length share when the rig's legs differ at setup (#225), px. */
   straight: number;
   /** The picture length over the straight length, before the clamp: lowest, median, highest. */
   ratio: { min: number; median: number; max: number };
@@ -308,6 +315,8 @@ export interface LegScale {
   /** Runs of frames clamped at the low and at the high limit. */
   low: Array<[number, number]>;
   high: Array<[number, number]>;
+  /** Runs of frames clamped at the low or high limit, with the asked scale range on each run (#225). */
+  clamped?: ClampedScaleRun[];
   /** The scale keyed on each frame (clamped). */
   scale: number[];
   /** The scale the pose asked for on each frame before the clamp floor (`min(ratio, limits[1])`, rig-c/pose#107). */
@@ -321,7 +330,7 @@ export interface LegScale {
   support?: SupportScaleRun[];
 }
 
-/** One segment's scale per frame: picture length ÷ straight length (the larger of the two sides' 95th percentiles, #148), clamped; its asked scale without the clamp floor (#107); and the runs clamped. */
+/** One segment's scale per frame: picture length ÷ straight length (the larger of the two sides' 95th percentiles, #148, scaled per leg when setup leg lengths differ, #225), clamped; its asked scale without the clamp floor (#107); and the runs clamped with their asked values (#225). */
 export function legScaleOf(lengths: readonly number[], limits: [number, number], straight = percentile(lengths, STRAIGHT_PERCENTILE)): Omit<LegScale, 'chain' | 'bone' | 'joints'> {
   const ratio = lengths.map((l) => l / straight);
   const scale = ratio.map((r) => Math.min(Math.max(r, limits[0]), limits[1]));
@@ -329,12 +338,23 @@ export function legScaleOf(lengths: readonly number[], limits: [number, number],
   const sorted = [...ratio].sort((a, b) => a - b);
   const mid = sorted.length >> 1;
   const median = sorted.length % 2 === 1 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2;
+  const low = runs(ratio.map((r) => r < limits[0]));
+  const high = runs(ratio.map((r) => r > limits[1]));
+  const spanAsked = ([a, b]: [number, number]): { min: number; max: number } => {
+    const sub = ratio.slice(a, b + 1);
+    return { min: Math.min(...sub), max: Math.max(...sub) };
+  };
+  const clamped: ClampedScaleRun[] = [
+    ...low.map((frames) => ({ frames, limit: 'low' as const, asked: spanAsked(frames) })),
+    ...high.map((frames) => ({ frames, limit: 'high' as const, asked: spanAsked(frames) })),
+  ];
   return {
     straight,
     ratio: { min: sorted[0]!, median, max: sorted[sorted.length - 1]! },
     limits,
-    low: runs(ratio.map((r) => r < limits[0])),
-    high: runs(ratio.map((r) => r > limits[1])),
+    low,
+    high,
+    ...(clamped.length > 0 ? { clamped } : {}),
     scale,
     asked,
   };
@@ -671,7 +691,7 @@ export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel:
     const y = floor ?? percentile(heights as number[], 0.5);
     const shifts = feet.supports.map((sp, k) => ({ side: sp.side, frames: [sp.frames[0], sp.frames[1]] as [number, number], shift: y - heights[k]! }));
     const placed = placeHip(feet, offset, travel, start, y, follow);
-    const closure = follow === undefined ? null : closeLoop(placed.hip);
+    const closure = follow === undefined ? null : closeLoop(placed.hip, feet.supports);
     return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
   } finally {
     trackFn = undefined;
@@ -685,15 +705,35 @@ export interface Closure {
 }
 
 /**
- * Close an in-place loop (rig-c/pose#92): the hip's x on frame i moves by
- * −drift · i / (n − 1), drift its x on the last frame less its x on the first,
- * so the last frame's hip x is the first's and the loop carries no net travel.
- * The y is the floor's (#85) and is not touched. In place.
+ * Close an in-place loop (rig-c/pose#92, #224): when support spans repeat across
+ * multiple cycles, measure the per-cycle x drift between matching phase frames
+ * (`cf = 0` of cycle 1 vs cycle `k + 1`) and subtract that linear trend so the
+ * within-cycle offset (`cf 0 → last frame of cycle`) is preserved; on a single
+ * cycle (or when no repeating support spans are given), subtract the whole-clip
+ * displacement `hip[n - 1].x - hip[0].x`. The y is the floor's (#85) and is not
+ * touched. In place.
  */
-export function closeLoop(hip: Pt[]): Closure {
+export function closeLoop(hip: Pt[], supports?: Feet['supports']): Closure {
   const n = hip.length;
-  const drift = n > 1 ? hip[n - 1]![0] - hip[0]![0] : 0;
-  if (n > 1) for (let i = 0; i < n; i++) hip[i]![0] -= (drift * i) / (n - 1);
+  if (n <= 1) return { drift: 0, frames: n };
+  let perFrame = (hip[n - 1]![0] - hip[0]![0]) / (n - 1);
+  if (supports !== undefined && supports.length > 0) {
+    const bySide: Record<Side, number[]> = { r: [], l: [] };
+    for (const sp of supports) {
+      if (sp.frames[0] > 0) bySide[sp.side].push(sp.frames[0]);
+    }
+    const starts = bySide.r.length >= bySide.l.length ? bySide.r : bySide.l;
+    if (starts.length >= 2) {
+      const period = Math.round((starts[starts.length - 1]! - starts[0]!) / (starts.length - 1));
+      const cycles = period > 0 ? Math.floor((n - 1) / period) : 0;
+      if (cycles >= 1 && cycles * period < n) {
+        const span = cycles * period;
+        perFrame = (hip[span]![0] - hip[0]![0]) / span;
+      }
+    }
+  }
+  const drift = perFrame * (n - 1);
+  for (let i = 0; i < n; i++) hip[i]![0] -= perFrame * i;
   return { drift, frames: n };
 }
 
@@ -739,7 +779,7 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     const b = travel(mode.from);
     let y = mode.at[1] + a[1] - b[1];
     if (mode.carry !== undefined && mode.land !== undefined && mode.end !== undefined && floorY !== null) {
-      if (mode.land < n && mode.land > mode.from) {
+      if ((mode.land < n || follow !== undefined) && mode.land > mode.from) {
         y += mode.carry * ((Math.min(i, mode.land) - mode.from) / (mode.land - mode.from));
       }
       if (i <= mode.end) {
@@ -748,7 +788,7 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     }
     return [mode.at[0] + a[0] - b[0], y];
   };
-  /** A travel span from `startFrame` off frame `from`'s hip `at`: carried to meet `floorY` at landing when it contains a jump (#103). */
+  /** A travel span from `startFrame` off frame `from`'s hip `at`: carried to meet `floorY` at landing when it contains a jump (#103, and wrapped to frame 0 on an in-place loop, #224). */
   const makeTravel = (startFrame: number, from: number, at: Pt): Mode => {
     let end = startFrame;
     while (end + 1 < n && (feet.support[end + 1] ?? null) === null && (tracked[end + 1] ?? null) === null) end++;
@@ -756,10 +796,11 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     if (!isJump) return { kind: 'travel', from, at };
     const land = end + 1;
     let carry = 0;
-    if (land < n) {
-      const landSide = (feet.support[land] ?? tracked[land] ?? null)!;
-      const rawLandY = at[1] + travel(land)[1] - travel(from)[1];
-      const targetLandY = floorY - offset(land, landSide)[1];
+    const landIdx = land < n ? land : follow !== undefined ? 0 : -1;
+    const landSide = landIdx >= 0 ? (feet.support[landIdx] ?? tracked[landIdx] ?? null) : null;
+    if (landSide !== null) {
+      const rawLandY = at[1] + travel(landIdx)[1] - travel(from)[1];
+      const targetLandY = floorY - offset(landIdx, landSide)[1];
       carry = targetLandY - rawLandY;
     }
     return { kind: 'travel', from, at, end, land, carry };
@@ -780,7 +821,17 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
     if (i === 0) {
       if (s !== null) {
         const o = offset(0, s);
+        const anchorY = floorY ?? (start[1] + o[1]);
         mode = plant(0, s, [start[0] + o[0], start[1] + o[1]]);
+        // #224: in a periodic in-place loop whose last frame is in flight, the first cycle's plant blends from that flight just like cycles 2..N.
+        if (follow !== undefined && n > 1 && (feet.support[n - 1] ?? null) === null && (tracked[n - 1] ?? null) === null) {
+          from = { kind: 'travel', from: 0, at: [start[0], anchorY - o[1]] };
+          blendAt = 0;
+          blendEnd = 0;
+          while (blendEnd + 1 < n && (feet.support[blendEnd + 1] ?? null) === s) blendEnd++;
+          blendToFlight =
+            blendEnd + 1 < n && (feet.support[blendEnd + 1] ?? null) === null && (tracked[blendEnd + 1] ?? null) === null;
+        }
       } else if (tr !== null) {
         const o = offset(0, tr);
         mode = { kind: 'track', side: tr, anchor: [start[0] + o[0], floorY ?? (start[1] + o[1])], from: 0, at: start };

package/src/retarget.ts

@@ -839,13 +839,17 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               return cons.map((c) => c * legSum[0]!);
             }
           }
-          const top = heldPt('nose') ?? heldPt('neck');
-          if (top !== null) {
-            const h = ar.map((r, i) => Math.max(r[1], al[i]![1]) - top[i]![1]);
-            if (h.every((v) => v > 1e-6)) return h;
+          const segH =
+            rs !== null && ls !== null
+              ? legSum.map((l, i) => l + dist2([(hr[i]![0] + hl[i]![0]) / 2, (hr[i]![1] + hl[i]![1]) / 2], [(rs[i]![0] + ls[i]![0]) / 2, (rs[i]![1] + ls[i]![1]) / 2]))
+              : legSum;
+          const out = winPercentile(segH, 15, STRAIGHT_PERCENTILE);
+          if (feet !== null) {
+            for (const sp of feet.supports) {
+              const m = percentile(segH.slice(sp.frames[0], sp.frames[1] + 1), STRAIGHT_PERCENTILE);
+              for (let i = sp.frames[0]; i <= sp.frames[1]; i++) out[i] = m;
+            }
           }
-          const out = winPercentile(legSum, 1, STRAIGHT_PERCENTILE);
-          out[0] = legSum[0]!;
           return out;
         }
         return legSum;
@@ -937,8 +941,24 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         }
       }
     }
+    const rigLenByKind = new Map<string, number[]>();
+    for (const seg of rawSegments) {
+      const len = rest.get(seg.bone)?.length ?? 0;
+      if (len > 1e-6) {
+        const list = rigLenByKind.get(seg.kind) ?? [];
+        list.push(len);
+        rigLenByKind.set(seg.kind, list);
+      }
+    }
+    const rigShareOf = (seg: (typeof rawSegments)[number]): number => {
+      const lens = rigLenByKind.get(seg.kind);
+      const rigLen = rest.get(seg.bone)?.length ?? 0;
+      if (lens === undefined || lens.length < 2 || !(rigLen > 1e-6)) return 1;
+      const meanRigLen = lens.reduce((a, b) => a + b, 0) / lens.length;
+      return Math.abs(rigLen - meanRigLen) > 1e-3 * meanRigLen ? rigLen / meanRigLen : 1;
+    };
     for (const seg of rawSegments) {
-      const ls = legScaleOf(seg.lengths, limits, straightByKind.get(seg.kind)!);
+      const ls = legScaleOf(seg.lengths, limits, straightByKind.get(seg.kind)! * rigShareOf(seg));
       legScale.push({ chain: seg.chain, bone: seg.bone, joints: seg.joints, ...ls });
       scales.set(seg.bone, ls.scale);
     }

package/src/run.ts

@@ -773,12 +773,23 @@ function legRangeLine(which: 'free' | 'supporting', range: Partial<Record<'r' |
   return `bound from the leg's own range: on a frame where the picture folds the ${which} leg below ${bounds[0]} of its straight length (hip → ankle, its 95th percentile), the lower bound is that fold — lowest ${sides.join(', ')}; the upper stays ${bounds[1]}`;
 }
 
-/** A LEG-SCALE line: the segment, its straight length, its ratio's spread, and the frames clamped. */
+/** A LEG-SCALE line: the segment, its straight length, its ratio's spread, and the frames clamped (with the asked value, #225). */
 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 (larger 95th percentile of ${times.length} frames, both legs); 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')}`;
+  const val = (r: { min: number; max: number }) => (r.min.toFixed(3) === r.max.toFixed(3) ? r.min.toFixed(3) : `${r.min.toFixed(3)}–${r.max.toFixed(3)}`);
+  const askedOf = (x: [number, number], kind: 'low' | 'high'): string => {
+    const c = l.clamped?.find((r) => r.limit === kind && r.frames[0] === x[0] && r.frames[1] === x[1]);
+    if (c !== undefined) return `asked ${val(c.asked)}`;
+    const sub = l.asked.slice(x[0], x[1] + 1);
+    return sub.length === 0 ? '' : `asked ${val({ min: Math.min(...sub), max: Math.max(...sub) })}`;
+  };
+  const clamp = (rs: Array<[number, number]>, at: number, how: string, kind: 'low' | 'high') => {
+    if (rs.length === 0) return `none ${how} ${at}`;
+    const detail = rs.length === 1 ? ` (${askedOf(rs[0]!, kind)})` : ` (${rs.map((x) => `${span(x)}: ${askedOf(x, kind)}`).join(', ')})`;
+    return `${count(rs)} frame(s) ${how} ${at}, clamped (frames ${rs.map(span).join(', ')})${detail}`;
+  };
+  return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (larger 95th percentile of ${times.length} frames, both legs); 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', 'low')}; ${clamp(l.high, l.limits[1], 'over', 'high')}`;
 }
 
 /** 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. */