@rig-c/pose 0.1.1 → 0.2.0

package/README.md

@@ -29,6 +29,7 @@ Nothing is written until every check passes:
 and what the run cannot decide for you it lists:
 
 - `HOLD` — a joint missing, or scored under `--min-score`, holds its last good value; one line per span, with the frames and the reason.
+- `FLIP` — a segment that turns more than `--flip` degrees in one frame (with `--flip <deg>`; off by default) is spread over the frames around the jump; one line per spread, with the chain, the segment, the jump, the frames and h. Below.
 - `BEND` — with `--bends clamp`, a hinge bent the wrong way is straightened on that frame instead of refusing.
 - `FOLD` — `rigc render --folds` over the new animation: every mesh that folds, and when. A reading, not a gate.
 - `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate.
@@ -37,6 +38,12 @@ and what the run cannot decide for you it lists:
 
 **Use `--smooth 7` at 24 fps.** It was measured on a 13 s dance on a @rig-c/parts rig, read back from the gated build: the motion's timing did not move (speed cross-correlation lag 0 on the wrists, ankles and hip), the frame-to-frame second difference dropped 2.5× on the wrists, 1.7–2.1× on the ankles and 1.5× on the hip, and the hip's 95th-percentile speed fell to 0.85×. The criterion set beforehand, a 2× drop on every point, was not met on the hip. That criterion was flawed: the hip's second difference is mostly real motion, while the filter cuts white noise 4.6×. A measure that isolates noise is a later card, and the default stays off until it passes.
 
+**The flip guard.** A pose model can put a fast sweep of a limb into one frame — under motion blur it takes the elbow or the wrist for another point — and the rig then whips the limb round between two keys. Position smoothing cannot remove a step like that. So after holds and smoothing, and before the hinge check, every segment the map aims (not a `reach`, which is aimed later from posed positions) is read frame to frame: a turn greater than `--flip <deg>` from frame k−1 to frame k is spread. For the smallest h ≥ 1 that keeps every one-frame turn at or under the threshold, frames k−h … k+h−1 are replaced by the straight line from frame k−h−1 to frame k+h, the turn's own way round. It is centred, so the step happens when the pose put it, over 2h frames, and both ends keep the pose's angles. A window that would cross the first or last frame stops there and the line says so; two windows that overlap become one. `--flip off` keeps every turn. The report lists each spread under `flips`.
+
+The threshold was fixed by measuring first ([#15](https://github.com/rig-c/pose/issues/15)). On the 13 s dance (313 frames, RTMPose), the one-frame turns of the picture angle of 10 segments — both upper arms, forearms, thighs and shins, the eye line and the hip line, 3,120 turns — run p50 1.0°, p90 5.0°, p99 23.1°, p99.5 33.4°, p99.9 78.2°, max 148.6°. 90° is the p99.9 rounded up past a margin, and marks the 3 turns above it (0.1%): both forearms between frames 181 and 182 (148.6° and 114.4°, a motion-blurred stretch) and the left forearm between 53 and 54 (99.2°, the forearm pointing at the camera). None of them is a spike that comes back: each keeps the direction the limb was already turning, and the new angle holds — a real sweep put into one frame. Holding the last angle would be wrong a frame later, so the guard spreads the step instead. With it, on the @rig-c/parts rig #11 measured, the largest one-frame turn of any guarded bone in the gated build, posed by rig-c, is 78.2° (148.6° without it), and every bone still lands.
+
+Re-measured with the guard on, against the guarded unsmoothed run, on #11's criteria (power above 6 Hz down ≥ 2× on every point, timing lag 0, p95 speed ≥ 0.85×): no window passes. `--smooth 7` comes closest — the left wrist's power drops 1.99× and the hip's p95 speed is 0.847× — so `--smooth` stays off by default, and so does the guard: the rule posted before the run made a default for either one depend on a window passing. **Use `--flip 90`**: with it, no bone of the gated build turns more than 90° in one frame (without it, 148.6°), and every bone still lands.
+
 Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2` bad invocation. `rig-pose --help` has every flag.
 
 ## The pose: `rig-pose-sequence/1`

package/cli.ts

@@ -35,13 +35,16 @@ retarget
   --smooth <n>          Savitzky–Golay over n frames of joint positions: a centred least-squares cubic,
                         read at each frame (default: 1, none); n is odd and ≥ 5 — a cubic through 3
                         points passes through all three, so 3 would change nothing
+  --flip <deg>|off      a segment that turns more than <deg> degrees in one frame of the pose is
+                        spread over the frames around the jump, centred on it, and listed as FLIP
+                        (default: off, every turn kept as the pose gives it; 90 is the measured setting)
   --bends refuse|clamp  a hinge (elbow, knee: any joint inside a chain) bent the wrong way refuses
                         the run (default), or is straightened on that frame and listed
   --bend-tolerance <d>  degrees past straight a hinge may bend the wrong way before it counts (default: 0)
   --profile spine|spine-html  rigc's gate profile (default: spine, rigc's own default)
   --build <dir>         keep the gated build (skeleton.json, .atlas, .model.json) here
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
-  --report <file>       write the run's measurements (holds, bends, landings, folds) as JSON
+  --report <file>       write the run's measurements (holds, flips, bends, landings, folds) as JSON
 
   It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
   the angle the pose asks for (posed by rig-c's own poser), and no hinge bends the wrong way.
@@ -96,8 +99,13 @@ function smoothOf(f: Map<string, string>): number {
   return n;
 }
 
+function flipOf(f: Map<string, string>): number | 'off' {
+  if (!f.has('flip') || f.get('flip') === 'off') return 'off';
+  return num(f, 'flip', 90, (v) => v > 0 && v < 180, 'off, or degrees in (0, 180) — a one-frame turn is never more than 180°');
+}
+
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'bends', 'bend-tolerance', 'profile', 'build', 'render', 'report'], ['coco']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'flip', 'bends', 'bend-tolerance', 'profile', 'build', 'render', 'report'], ['coco']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const profile = f.get('profile') ?? 'spine';
@@ -115,6 +123,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     baseMotion: f.get('base-motion'),
     minScore: num(f, 'min-score', 0.3, (n) => n >= 0, 'a number ≥ 0'),
     smooth: smoothOf(f),
+    flip: flipOf(f),
     bends,
     bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     profile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.1.1",
+  "version": "0.2.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/retarget.ts

@@ -23,6 +23,12 @@
  * evaluated at the frame, on each joint's positions after its holds. Centred,
  * it moves no motion in time; a cubic keeps a peak a moving average flattens.
  *
+ * The flip guard (rig-c/pose#15) then spreads a segment's turn greater than
+ * `flip` degrees in one frame over the frames around it, linearly and centred on
+ * the jump (`spreadFlips`). It reads the mapped segments' target angles after
+ * holds and smoothing and before the hinge check. A reach's target is aimed
+ * later, from posed positions, and is not guarded.
+ *
  * What this cannot know is held to account afterwards: `verify.ts` poses the
  * gated build with rig-c's poser and measures where each bone landed.
  */
@@ -45,6 +51,8 @@ export interface RetargetOptions {
   bends: 'refuse' | 'clamp';
   /** Degrees past straight a hinge may bend the wrong way before it counts. */
   bendTolerance: number;
+  /** A segment turning more than this many degrees in one frame is spread (`spreadFlips`); 'off' keeps every turn. */
+  flip: number | 'off';
 }
 
 export interface Hold {
@@ -69,6 +77,26 @@ export interface BendEvent {
   rest: number;
 }
 
+/** One spread: a segment's turn over the threshold, and the frames whose angle was replaced. */
+export interface Flip {
+  chain: string;
+  bone: string;
+  /** The segment the bone carries: from joint, to joint. */
+  joints: [string, string];
+  /** The largest input turn in the spread, degrees, signed (Spine's sense, counter-clockwise +). */
+  jump: number;
+  /** Every input turn over the threshold the spread covers: `frame` is k, the turn is from frame k−1 to k. */
+  turns: Array<{ frame: number; jump: number }>;
+  /** First and last frame whose angle was replaced; the frames either side keep the input's. */
+  frames: [number, number];
+  /** The half-width the spread needed (for spreads merged from neighbouring turns, the widest). */
+  h: number;
+  /** The one-frame turn across the spread, degrees, signed. */
+  step: number;
+  /** Which end of the series cut the window short, if one did. */
+  clipped: 'start' | 'end' | 'both' | null;
+}
+
 export interface MotionKey {
   t: number;
   v: number[];
@@ -93,6 +121,7 @@ export interface Retarget {
   origin: { bone: string; at: Array<[number, number]> } | null;
   holds: Hold[];
   bends: BendEvent[];
+  flips: Flip[];
   /** The figure scale, rig units per picture pixel, and the lengths it came from. */
   scale: { factor: number; pose: number; rig: number } | null;
 }
@@ -329,6 +358,20 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
+  // The flip guard, on every segment the pose aims directly (not a reach).
+  const flips: Flip[] = [];
+  if (opts.flip !== 'off') {
+    const threshold = opts.flip;
+    for (const c of map.chains) {
+      if (c.reach) continue;
+      c.bones.forEach((b, k) => {
+        for (const s of spreadFlips(targets.get(b)!, threshold)) {
+          flips.push({ chain: c.name, bone: b, joints: [c.joints[k]!, c.joints[k + 1]!], ...s });
+        }
+      });
+    }
+  }
+
   // Hinges: each joint strictly inside a chain (a reach has one bone, so none).
   const bends: BendEvent[] = [];
   for (const c of map.chains) {
@@ -409,7 +452,90 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   if (translateTrack !== null) tracks.push(translateTrack);
 
-  return { animation: { duration: keyTimes[n - 1]!, tracks }, times: keyTimes, targets, origin, holds, bends, scale };
+  return { animation: { duration: keyTimes[n - 1]!, tracks }, times: keyTimes, targets, origin, holds, bends, flips, scale };
+}
+
+type Spread = Omit<Flip, 'chain' | 'bone' | 'joints'>;
+
+/**
+ * The flip guard on one angle series (degrees), in place. A turn greater than
+ * `threshold` from frame k−1 to frame k is spread: for the smallest h ≥ 1, the
+ * angles of frames k−h…k+h−1 are replaced by the straight line from frame
+ * k−h−1 to frame k+h, taken through the unwrapped series (each one-frame turn
+ * the short way round, so the jump keeps its own direction), such that every
+ * one-frame turn in frames k−h…k+h is at or under the threshold. It is centred
+ * on the jump, so the step happens when the input put it, spread over 2h frames,
+ * and both ends are the input's own angles. A window that would cross the first
+ * or the last frame stops there (`clipped`). Windows that overlap — one replaces
+ * a frame the other ends on — merge into one line over both, widened again
+ * while that line still turns faster than the threshold. Returns the spreads.
+ */
+export function spreadFlips(angles: number[], threshold: number): Spread[] {
+  const n = angles.length;
+  if (n < 2) return [];
+  const u: number[] = [angles[0]!];
+  for (let i = 1; i < n; i++) u.push(u[i - 1]! + wrap(angles[i]! - angles[i - 1]!));
+  const fits = (lo: number, hi: number) => Math.abs(u[hi]! - u[lo]!) <= threshold * (hi - lo);
+  interface Win { lo: number; hi: number; h: number; start: boolean; end: boolean; turns: Array<{ frame: number; jump: number }> }
+  const wins: Win[] = [];
+  for (let k = 1; k < n; k++) {
+    const jump = u[k]! - u[k - 1]!;
+    if (Math.abs(jump) <= threshold) continue;
+    let h = 1;
+    let lo = Math.max(0, k - h - 1);
+    let hi = Math.min(n - 1, k + h);
+    while (!fits(lo, hi) && (lo > 0 || hi < n - 1)) {
+      h++;
+      lo = Math.max(0, k - h - 1);
+      hi = Math.min(n - 1, k + h);
+    }
+    wins.push({ lo, hi, h, start: k - h - 1 < 0, end: k + h > n - 1, turns: [{ frame: k, jump }] });
+  }
+  // Merge overlapping windows; a merged line that turns too fast widens by one on each side, then merges again.
+  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), h: Math.max(a.h, b.h), start: a.start || b.start, end: a.end || b.end, turns: [...a.turns, ...b.turns].sort((x, y) => x.frame - y.frame) });
+      changed = true;
+      break;
+    }
+    if (changed) continue;
+    for (const w of wins) {
+      if (w.turns.length < 2 || fits(w.lo, w.hi) || (w.lo === 0 && w.hi === n - 1)) continue;
+      if (w.lo === 0) w.start = true;
+      if (w.hi === n - 1) w.end = true;
+      w.lo = Math.max(0, w.lo - 1);
+      w.hi = Math.min(n - 1, w.hi + 1);
+      w.h++;
+      changed = true;
+    }
+  }
+  return wins.map((w) => {
+    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));
+    const top = w.turns.reduce((m, t) => (Math.abs(t.jump) > Math.abs(m.jump) ? t : m));
+    return {
+      jump: top.jump,
+      turns: w.turns,
+      frames: [w.lo + 1, w.hi - 1] as [number, number],
+      h: w.h,
+      step,
+      clipped: w.start && w.end ? 'both' : w.start ? 'start' : w.end ? 'end' : null,
+    };
+  });
+}
+
+export function flipLine(f: Flip, times: readonly number[], threshold: number): string {
+  const sg = (v: number) => `${v >= 0 ? '+' : '−'}${Math.abs(v).toFixed(1)}°`;
+  const turns = f.turns.map((t) => `${sg(t.jump)} from frame ${t.frame - 1} to ${t.frame} (t=${times[t.frame - 1]!.toFixed(3)}–${times[t.frame]!.toFixed(3)}s)`).join(', ');
+  const span = f.frames[0] > f.frames[1] ? 'no frame (the pose has none between the two)' : f.frames[0] === f.frames[1] ? `frame ${f.frames[0]}` : `frames ${f.frames[0]}–${f.frames[1]}`;
+  const clip = f.clipped === null ? '' : f.clipped === 'both' ? '; the window was cut short by both ends of the pose' : `; the window was cut short at the ${f.clipped === 'start' ? 'first' : 'last'} frame of the pose`;
+  const still = Math.abs(f.step) > threshold ? ` — still over ${threshold}°: the pose is too short to spread it` : '';
+  return `chain "${f.chain}" bone "${f.bone}" (${f.joints[0]} → ${f.joints[1]}) turned ${turns}, over ${threshold}° in one frame; spread over ${span} (h=${f.h}), ${sg(f.step)} per frame${clip}${still}`;
 }
 
 /** Frames before the first with a direction take its value; none at all is a problem. */

package/src/run.ts

@@ -9,7 +9,7 @@ import { dirname, join } from 'node:path';
 import { readMap, resolveMap } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.ts';
 import { lineOf, Problems, Refusal, type Problem } from './problems.ts';
-import { bendLine, holdLine, retarget, type RetargetOptions } from './retarget.ts';
+import { bendLine, flipLine, holdLine, retarget, type RetargetOptions } from './retarget.ts';
 import { baseMotionOf, folds, gate, readBuild, resolveRig, restOf } from './rigc.ts';
 import { landed, measureLanding, measurePosture, poseFrames, postureLines, ANGLE_TOLERANCE, ORIGIN_TOLERANCE } from './verify.ts';
 
@@ -78,9 +78,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map);
 
     const r = retarget(rest, map, frames, times, a);
-    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}, 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}°`}, bends ${a.bends} (tolerance ${a.bendTolerance}°)`);
     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.flip !== 'off') for (const fl of r.flips) say(`  FLIP   ${flipLine(fl, r.times, a.flip)}`);
     for (const e of r.bends) say(`  BEND   ${bendLine(e)} — clamped straight`);
 
     const motion = { ...base, animations: { ...animations, [a.name]: r.animation } };
@@ -129,10 +130,11 @@ 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, bends: a.bends, bendTolerance: a.bendTolerance, profile: a.profile },
+        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, bends: a.bends, bendTolerance: a.bendTolerance, profile: a.profile },
         scale: r.scale,
         holds: r.holds,
         bends: r.bends,
+        flips: r.flips,
         gate: g1.summary,
         landings,
         posture,