@rig-c/pose 0.10.0 → 0.11.0

package/README.md

@@ -55,9 +55,10 @@ and what the run cannot decide for you it lists:
 - `FEET` — when the map has both legs: the supports and jumps read off the reference ankles (planted or not), and on the posed build, outside the jumps, the lowest ankle's vertical range and each support span's worst vertical range and horizontal drift of the supporting ankle, in leg lengths.
 - `SHEAR` — with `--leg-scale`: every scaled bone and every bone under one, how far its art is sheared and how long its world axes are against setup. A reading.
 - `IDLE`, `IDLE-DROPPED`, `IDLE-KEPT-OUT`, `MERGE` — the rig's idle against the new animation, and what `--carry-idle` and `--merge` put back ([below](#the-idle-what-the-retarget-drops)).
+- `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale` and `plantFeet` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), and the demand lists:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale` and `plantFeet` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists:
 
 - `switches: [{ set, chains, slots, hides, offsets, from, to, frames: [first, last], distance: { max, median }, artTurn: { <bone>: { max, median } }, moved: { on, off } }]` — one per span shown; `from` is the first frame's time, `to` the time the base art comes back (the animation's end when the span runs to it), `distance` in degrees over the frames shown, `artTurn` |wrap(target − drawn)| in degrees per bone the set has a `drawn` angle for. `moved.on` is the boundary the span starts on (null from the first frame), `moved.off` the one the base art or the next set comes back on (null to the end), each `{ frame: [selected, keyed], frames, seconds, window: [first, last], speed: { old, new } }`: signed frames and seconds, the frames it could move to, and the speed in degrees per frame on the old and the new frame. A boundary between two sets is the same entry in both.
 - `uncovered: [{ slot, attachment, chains, times }]` — every entry of `folds` on the times its slot still shows that mesh, with the map's chains that move it (the deepest: the arm, not the trunk it hangs from). `rigc render --folds` reads only what the pose shows, so a mesh swapped out or hidden by a switch is not read on those frames at all; `uncovered` is the fold times less the switched ones.
@@ -135,6 +136,17 @@ On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle ha
 
 Each track is a rigc-motion track. One posing a channel the new animation (or a carried idle track, or an earlier fragment track) already keys is refused by name (`MERGE_CONFLICT`): a fragment adds a track, it never replaces one. So is a key before 0 or past the animation's duration (`MERGE_TIME`), and a file of any other shape (`MERGE_SPEC`). What the track means — its target, property and values — is rigc's to judge: its gate checks every merged track like any other (`RIG_GATE`). `MERGE` lists each track merged; the report lists them under `merged`.
 
+### Few keys: `--reduce`
+
+The retarget writes one key per pose frame on every mapped bone. That is faithful, but nobody can edit it by hand. **`--reduce <deg>`** (off by default) thins each mapped bone's `rotate` track to a few keys with curves, so that every bone's **world** aim stays within `deg` of the dense keys on every pose frame. **`--reduce-hip <units>`** does the same for the hip's `translate`, holding its world origin within `units`; without it, the hip stays dense.
+
+- **Keys stay on the pose's own frame times.** Between two kept keys, the span is linear if a straight line is within the tolerance. Otherwise it gets one raw Bézier `curve`, with its handles at the span's thirds and its values fitted by least squares. The error is measured the way rig-c's poser evaluates a curve (its 10-piece polyline). A span still over the tolerance gets a key at its worst frame, and both halves are fitted again.
+- **Errors do not pile up down a chain.** Bones are fitted top-down, and each bone is fitted against its dense key less the error its nearest mapped parent already carries. So a bone's world error is its own fit error.
+- **Kept regardless:** the first and last frame; the frames either side of a switch boundary, on the chains the switch changes; and the first and last frame of every `FLIP` spread, `SHORT` span and `RANGE` run, on that bone.
+- **The landing check holds the dense targets** with the tolerance added (0.01° + `deg`; 0.01 + `units`), and it is posed by rig-c as always.
+- **On HQ's dancer** (`--smooth 7 --flip 90 --short 0.35 --bends clamp`; 313 frames, 11 mapped bones): `--reduce 1 --reduce-hip 1` takes the rotate keys from 3443 to 588 (5.86×), 296 of the spans curved, and the hip's translate keys from 313 to 96. The gate is green. rig-c's poser lands every bone within 0.9998° of the dense target (head) and the hip within 0.901 units. At 0.5° the keys drop 3.92×; at 2°, 8.38×.
+- **Not combined with `--leg-scale` or `--plant-feet`.** Their keys land a bone through a scaled parent or an ankle's lever, which this tolerance does not bound (rig-c/pose#32).
+
 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

@@ -75,6 +75,15 @@ retarget
                         "tracks": [ <rigc-motion track> … ] } at absolute times from its start (blinks read
                         off the video); a track on a target and property it already keys is refused
                         (MERGE_CONFLICT), and so is a key past its duration (MERGE_TIME)
+  --reduce <deg>        thin each mapped bone's rotate keys to few keys with curves (linear, or one raw
+                        Bezier per span with handles at its thirds), on the pose's own frame times, so every
+                        bone's world aim stays within deg of the dense keys on every frame; fitted top-down,
+                        each bone against its parent's reduced error, so errors do not pile up down a chain.
+                        Kept regardless: the first and last frame, the frames either side of a switch boundary
+                        on the chains it changes, and the edges of every FLIP spread, SHORT span and RANGE run
+                        (REDUCE lines; default: off). Not with --leg-scale or --plant-feet (rig-c/pose#32)
+  --reduce-hip <units>  with --reduce, thin the hip's translate keys too, its world origin within units
+                        of the dense keys (default: the hip stays dense)
   --switch-tolerance <d>  a set of alternate drawings (the map's "alternates") may show on a frame where
                         every segment of its chains is within d degrees of its key skeleton (default: 25)
   --switch-min <s>      a run of one set shorter than s seconds is dropped (default: 0.25)
@@ -87,7 +96,7 @@ retarget
   --render <dir>        keep rigc's render of the animation (frames, contact.png, folds.json) here
   --report <file>       write the run's measurements (holds, short, endOn, flips, bends, landings, folds,
                         switches, uncovered, turns, range, artRange,
-                        idleDropped, idleKeptOut, merged) as JSON
+                        idleDropped, idleKeptOut, merged, reduce) 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.
@@ -191,7 +200,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge'], ['coco', 'plant-feet', 'carry-idle']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip'], ['coco', 'plant-feet', 'carry-idle']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -228,9 +237,23 @@ function retargetArgs(argv: string[]): RetargetArgs {
     idle: f.get('idle'),
     carryIdle: f.has('carry-idle'),
     merge: f.get('merge'),
+    ...reduceOf(f),
   };
 }
 
+/** --reduce and --reduce-hip (rig-c/pose#32): off unless given; the hip only with the bones. */
+function reduceOf(f: Map<string, string>): { reduce?: number; reduceHip?: number } {
+  if (!f.has('reduce')) {
+    if (f.has('reduce-hip')) throw new Usage('--reduce-hip is given without --reduce; the hip is thinned with the bones, not alone');
+    return {};
+  }
+  const reduce = num(f, 'reduce', 0, (n) => n > 0 && n < 180, 'degrees in (0, 180)');
+  for (const other of ['leg-scale', 'plant-feet'] as const) {
+    if (f.has(other) && f.get(other) !== 'off') throw new Usage(`--reduce is given with --${other}; their keys land a bone through a scaled parent or an ankle's lever, which the reduction's tolerance does not bound (rig-c/pose#32 round 1)`);
+  }
+  return f.has('reduce-hip') ? { reduce, reduceHip: num(f, 'reduce-hip', 0, (n) => n > 0, 'rig units > 0') } : { reduce };
+}
+
 function compareArgs(argv: string[]): CompareArgs {
   const f = parseFlags(argv, ['reference', 'render', 'map', 'retarget-report', 'reference-hands', 'render-hands', 'cloth-reference', 'cloth-render', 'cloth-windows', 'report', 'sheet'], []);
   const pair = (x: string, y: string) => {

package/package.json

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

@@ -0,0 +1,361 @@
+/**
+ * The dense keys thinned to few keys with curves, within a stated tolerance
+ * (rig-c/pose#32, `--reduce`): one key per pose frame on every mapped bone's
+ * `rotate` track and on the hip's `translate`, in; the keys a curve needs to
+ * stay within the tolerance on every frame, out.
+ *
+ * Pure: numbers in, keys out. The method was fixed on the issue before any
+ * measurement. Keys sit on the pose's own frame times; between two kept keys a
+ * span is linear when every frame inside is within the tolerance, else it
+ * carries one raw Bézier `curve` whose handle times sit at the span's thirds and
+ * whose handle values are a least-squares fit; a span still over the tolerance
+ * takes a key at its worst frame and both halves are fitted again.
+ *
+ * Top-down along the tree. A child's `rotate` key adds to the turn of the
+ * mapped bone above it, so the reduced above's error turns the child's world
+ * aim too. A bone is fitted against its dense key minus the error its above
+ * carries (`target = dense − e_above`), and its own residual against that
+ * target is its world error: errors do not pile up down a chain. A knot's value
+ * is the target's, not the dense key's.
+ *
+ * Every error is read after the numbers are rounded as written and evaluated as
+ * rig-c's poser evaluates them (`curveAt`): the curve is the poser's ten-piece
+ * polyline, not the cubic. The poser is the judge — run.ts measures the landing
+ * of the gated build against the dense targets with the tolerance added.
+ */
+import { f32 } from 'rig-c/compile';
+
+/** A key as the reducer writes it: a time, its values, and a raw curve on the segment to the next key. */
+export interface ReducedKey {
+  t: number;
+  v: number[];
+  curve?: number[];
+}
+
+export interface ReduceBone {
+  bone: string;
+  /** The nearest mapped bone above it (whose rotate track it adds to), or null. Always one of the other bones given, or null. */
+  above: string | null;
+  /** The dense key value on every frame (degrees, unwrapped, already rounded to 0.001). */
+  dense: number[];
+  /** Frame indices that must keep a key regardless (the first and last always do). */
+  keep: ReadonlySet<number>;
+}
+export interface ReduceHip {
+  bone: string;
+  /** Dense translate key on every frame, parent-local units, rounded to 0.001. */
+  dense: Array<[number, number]>;
+  keep: ReadonlySet<number>;
+  /** The hip's parent world matrix [a, b, c, d] at setup (wx = a·lx + b·ly, wy = c·lx + d·ly); null when it has none (identity). The tolerance is a world distance. */
+  parent: [number, number, number, number] | null;
+  tolerance: number;
+}
+export interface ReduceRow {
+  bone: string;
+  kind: 'angle' | 'origin';
+  /** Dense key count. */
+  before: number;
+  /** Reduced key count. */
+  after: number;
+  /** The largest error over all frames: degrees of world aim for a bone, world units for the hip. */
+  worst: number;
+  /** The first frame where it is. */
+  frame: number;
+}
+export interface Reduced {
+  rotate: Map<string, ReducedKey[]>;
+  hip: ReducedKey[] | null;
+  /** The bones in the order given, then the hip. */
+  rows: ReduceRow[];
+}
+
+// ---------------------------------------------------------------------------
+// rig-c's evaluation
+// ---------------------------------------------------------------------------
+
+/** rig-c's `BEZIER_SIXTH` (node_modules/rig-c/src/core/animation.ts). */
+const BEZIER_SIXTH = 0.16666667;
+/** Pieces of the poser's polyline per Bézier segment — rig-c's `BEZIER_PIECES`. */
+export const REDUCE_PIECES = 10;
+
+/**
+ * Copied verbatim from rig-c `src/core/animation.ts` (`bezierPolyline`, not
+ * exported by `rig-c/core`): the nine interior points of one channel's Bézier
+ * segment, `[t1, v1, …, t9, v9]`, each float32, by forward differences. The
+ * poser is the judge; this copy only lets the fit see what it will see.
+ */
+export function bezierPolyline(t0: number, v0: number, cx1: number, cy1: number, cx2: number, cy2: number, t3: number, v3: number): number[] {
+  const walk = (p0: number, p1: number, p2: number, p3: number): number[] => {
+    const second = (p0 - 2 * p1 + p2) * 0.03;
+    const third = ((p1 - p2) * 3 - p0 + p3) * 0.006;
+    let first = (p1 - p0) * 0.3 + second + third * BEZIER_SIXTH;
+    let d2 = second * 2 + third;
+    let at = p0;
+    const out: number[] = [];
+    for (let i = 1; i < REDUCE_PIECES; i++) {
+      at += first;
+      first += d2;
+      d2 += third;
+      out.push(Math.fround(at));
+    }
+    return out;
+  };
+  const ts = walk(t0, cx1, cx2, t3);
+  const vs = walk(v0, cy1, cy2, v3);
+  const out: number[] = [];
+  for (let i = 0; i < ts.length; i++) out.push(ts[i]!, vs[i]!);
+  return out;
+}
+
+const F32 = new Float32Array(1);
+const F32_BITS = new Uint32Array(F32.buffer);
+
+/** A key time as the built model states it — rig-c's `keyTime`: its own float32 name, else the float32 at or below it, named. */
+function statedTime(t: number): number {
+  const named = f32(t);
+  if (named === t) return named;
+  let f = Math.fround(t);
+  if (f > t) {
+    F32[0] = f;
+    if (f > 0) F32_BITS[0]! -= 1;
+    else if (f < 0) F32_BITS[0]! += 1;
+    else F32_BITS[0] = 0x80000001;
+    f = F32[0]!;
+  }
+  return f32(f);
+}
+/** A key time as the poser compares it: the float32 of the stated time. */
+const storedTime = (t: number): number => Math.fround(statedTime(t));
+
+/**
+ * One channel of one segment, as the poser holds it: null for a linear
+ * segment, else the polyline `[t0, v0, …nine points…, t3, v3]`. The recurrence
+ * runs on the numbers the built model states (rig-c's `f32` of each, a key
+ * time by `keyTime`); the two ends are the keys as stored, float32.
+ */
+function segmentPoints(a: ReducedKey, b: ReducedKey, channel: number): number[] | null {
+  if (a.curve === undefined) return null;
+  const c = a.curve.slice(channel * 4, channel * 4 + 4).map(f32);
+  const ta = statedTime(a.t);
+  const tb = statedTime(b.t);
+  const va = f32(a.v[channel]!);
+  const vb = f32(b.v[channel]!);
+  const inner = bezierPolyline(ta, va, c[0]!, c[1]!, c[2]!, c[3]!, tb, vb);
+  return [Math.fround(ta), Math.fround(va), ...inner, Math.fround(tb), Math.fround(vb)];
+}
+
+/** `segmentPoints`' segment at `t` — rig-c's `channelAt` past the key search. */
+function pointsAt(a: ReducedKey, b: ReducedKey, channel: number, points: readonly number[] | null, t: number): number {
+  if (points === null) {
+    const ta = storedTime(a.t);
+    const va = Math.fround(a.v[channel]!);
+    return va + ((t - ta) / (storedTime(b.t) - ta)) * (Math.fround(b.v[channel]!) - va);
+  }
+  let i = 2;
+  while (i < points.length - 2 && points[i]! < t) i += 2;
+  const x0 = points[i - 2]!;
+  const y0 = points[i - 1]!;
+  return y0 + ((t - x0) / (points[i]! - x0)) * (points[i + 1]! - y0);
+}
+
+/** Channel `channel` of the segment from key `a` to key `b` (`a.curve` shapes it) at `t`, as rig-c's poser evaluates it. */
+export function curveAt(a: ReducedKey, b: ReducedKey, channel: number, t: number): number {
+  return pointsAt(a, b, channel, segmentPoints(a, b, channel), t);
+}
+
+/** Every channel of a whole track at each sample time: the key search (last key stored at or before `t`), then the segment. */
+function trackAt(keys: readonly ReducedKey[], samples: readonly number[], channels: number): number[][] {
+  const stored = keys.map((k) => storedTime(k.t));
+  const points = keys.map((k, j) => (j + 1 < keys.length ? Array.from({ length: channels }, (_, c) => segmentPoints(k, keys[j + 1]!, c)) : []));
+  let j = 0;
+  return samples.map((t) => {
+    while (j + 1 < keys.length && stored[j + 1]! <= t) j++;
+    const a = keys[j]!;
+    const b = keys[j + 1];
+    // Before the first key the track does not pose; the first key is on frame 0, stored at or below it.
+    if (b === undefined || t < stored[j]!) return a.v.map((v) => Math.fround(v));
+    return Array.from({ length: channels }, (_, c) => pointsAt(a, b, c, points[j]![c]!, t));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// the fit
+// ---------------------------------------------------------------------------
+
+const r3 = (v: number): number => {
+  const r = Math.round(v * 1000) / 1000;
+  return Object.is(r, -0) ? 0 : r;
+};
+
+/** One track to reduce: its targets per frame (one array per frame, a value per channel) and how a frame's error is read. */
+interface Fit {
+  targets: readonly (readonly number[])[];
+  keep: ReadonlySet<number>;
+  tolerance: number;
+  /** The error at frame `i` of `values` against the target. */
+  error: (i: number, values: readonly number[]) => number;
+}
+
+/** The frame with the largest error over `frames` (the first, on a tie), or null when there is none. */
+function worstOf(frames: readonly number[], errorAt: (i: number) => number): { worst: number; frame: number } | null {
+  let best: { worst: number; frame: number } | null = null;
+  for (const i of frames) {
+    const e = errorAt(i);
+    if (best === null || e > best.worst) best = { worst: e, frame: i };
+  }
+  return best;
+}
+
+/** The least-squares handle values of one channel, or null when the normal equations are singular. */
+function solveHandles(a: ReducedKey, b: ReducedKey, channel: number, hx1: number, hx2: number, interior: readonly number[], samples: readonly number[], target: (i: number) => number): [number, number] | null {
+  const model = (cy1: number, cy2: number): number[] => {
+    const c = new Array<number>(a.v.length * 4).fill(0);
+    c.splice(channel * 4, 4, hx1, cy1, hx2, cy2);
+    const k: ReducedKey = { t: a.t, v: a.v, curve: c };
+    const points = segmentPoints(k, b, channel);
+    return interior.map((i) => pointsAt(k, b, channel, points, samples[i]!));
+  };
+  const f00 = model(0, 0);
+  const f10 = model(1, 0);
+  const f01 = model(0, 1);
+  let s11 = 0;
+  let s12 = 0;
+  let s22 = 0;
+  let r1 = 0;
+  let r2 = 0;
+  interior.forEach((i, j) => {
+    const g1 = f10[j]! - f00[j]!;
+    const g2 = f01[j]! - f00[j]!;
+    const r = target(i) - f00[j]!;
+    s11 += g1 * g1;
+    s12 += g1 * g2;
+    s22 += g2 * g2;
+    r1 += g1 * r;
+    r2 += g2 * r;
+  });
+  const det = s11 * s22 - s12 * s12;
+  if (!(s11 > 0 && s22 > 0) || !(det > 1e-12 * s11 * s22)) return null;
+  return [(r1 * s22 - r2 * s12) / det, (r2 * s11 - r1 * s12) / det];
+}
+
+/** A track's keys: the kept frames, then a knot at the worst frame of every span over the tolerance, until none is. */
+function fitTrack(times: readonly number[], samples: readonly number[], fit: Fit): ReducedKey[] {
+  const n = times.length;
+  const channels = fit.targets[0]!.length;
+  const keyOn = (i: number): ReducedKey => ({ t: times[i]!, v: fit.targets[i]!.map(r3) });
+  const knots = [...new Set([0, n - 1, ...fit.keep])].sort((x, y) => x - y);
+  const curves = new Map<number, number[]>();
+  const done: number[] = [];
+  const spans: Array<[number, number]> = [];
+  for (let j = knots.length - 1; j > 0; j--) spans.push([knots[j - 1]!, knots[j]!]);
+  done.push(...knots);
+  while (spans.length > 0) {
+    const [k0, k1] = spans.pop()!;
+    if (k1 - k0 <= 1) continue;
+    const a = keyOn(k0);
+    const b = keyOn(k1);
+    const interior = Array.from({ length: k1 - k0 - 1 }, (_, j) => k0 + 1 + j);
+    const errorWith = (k: ReducedKey) => {
+      const points = Array.from({ length: channels }, (_, c) => segmentPoints(k, b, c));
+      return worstOf(interior, (i) => fit.error(i, points.map((p, c) => pointsAt(k, b, c, p, samples[i]!))))!;
+    };
+    const linear = errorWith(a);
+    if (linear.worst <= fit.tolerance) continue;
+    let split = linear.frame;
+    const hx1 = times[k0]! + (times[k1]! - times[k0]!) / 3;
+    const hx2 = times[k0]! + (2 * (times[k1]! - times[k0]!)) / 3;
+    const handles = Array.from({ length: channels }, (_, c) => solveHandles(a, b, c, hx1, hx2, interior, samples, (i) => fit.targets[i]![c]!));
+    if (handles.every((h) => h !== null)) {
+      const curve = handles.flatMap(([cy1, cy2]) => [hx1, r3(cy1), hx2, r3(cy2)]);
+      const bent = errorWith({ ...a, curve });
+      if (bent.worst <= fit.tolerance) {
+        curves.set(k0, curve);
+        continue;
+      }
+      split = bent.frame;
+    }
+    done.push(split);
+    spans.push([split, k1], [k0, split]);
+  }
+  return [...new Set(done)].sort((x, y) => x - y).map((i) => {
+    const k = keyOn(i);
+    const curve = curves.get(i);
+    return curve === undefined ? k : { ...k, curve };
+  });
+}
+
+/** The frame indices `keep` names, each checked against the frame count. */
+function keptFrames(keep: ReadonlySet<number>, n: number, label: string): Set<number> {
+  for (const i of keep) {
+    if (!Number.isInteger(i) || i < 0 || i >= n) throw new Error(`reduce: ${label} keeps frame ${i}, outside the ${n} frame(s) 0–${n - 1}`);
+  }
+  return new Set(keep);
+}
+
+/**
+ * Every bone's rotate track (and the hip's translate) reduced within the
+ * tolerance, top-down along `above`; the rows say each track's key counts and
+ * its worst world error, measured on the reduced keys as the poser evaluates
+ * them.
+ */
+export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[], tolerance: number, hip: ReduceHip | null): Reduced {
+  const n = times.length;
+  if (n === 0) throw new Error('reduce: no frames to reduce');
+  if (!(Number.isFinite(tolerance) && tolerance > 0)) throw new Error(`reduce: the tolerance is ${tolerance}°, not a positive number`);
+  if (hip !== null && !(Number.isFinite(hip.tolerance) && hip.tolerance > 0)) throw new Error(`reduce: the hip's tolerance is ${hip.tolerance} units, not a positive number`);
+  // The poser samples at the running sum of the frame steps (verify.ts `poseFrames`).
+  const samples: number[] = [times[0]!];
+  for (let i = 1; i < n; i++) samples.push(samples[i - 1]! + (times[i]! - times[i - 1]!));
+
+  const byName = new Map<string, ReduceBone>();
+  for (const b of bones) {
+    if (byName.has(b.bone)) throw new Error(`reduce: bone "${b.bone}" is given twice`);
+    if (b.dense.length !== n) throw new Error(`reduce: bone "${b.bone}" has ${b.dense.length} dense key(s) for ${n} frame(s)`);
+    byName.set(b.bone, b);
+  }
+  for (const b of bones) {
+    if (b.above !== null && !byName.has(b.above)) throw new Error(`reduce: bone "${b.bone}" adds to bone "${b.above}", which is not among the bones reduced`);
+  }
+
+  // Top-down: a bone once its above is done, in the order given otherwise.
+  const errors = new Map<string, number[]>();
+  const rotate = new Map<string, ReducedKey[]>();
+  const rowOf = new Map<string, ReduceRow>();
+  const pending = [...bones];
+  while (pending.length > 0) {
+    const at = pending.findIndex((b) => b.above === null || errors.has(b.above));
+    if (at < 0) throw new Error(`reduce: bones ${pending.map((b) => `"${b.bone}"`).join(', ')} each add to another of them — a loop, not a tree`);
+    const b = pending.splice(at, 1)[0]!;
+    const eAbove = b.above === null ? null : errors.get(b.above)!;
+    const targets = b.dense.map((d, i) => [eAbove === null ? d : d - eAbove[i]!]);
+    const keys = fitTrack(times, samples, {
+      targets,
+      keep: keptFrames(b.keep, n, `bone "${b.bone}"`),
+      tolerance,
+      error: (i, v) => Math.abs(v[0]! - targets[i]![0]!),
+    });
+    const e = trackAt(keys, samples, 1).map((v, i) => v[0]! - targets[i]![0]!);
+    errors.set(b.bone, e);
+    rotate.set(b.bone, keys);
+    const worst = worstOf(e.map((_, i) => i), (i) => Math.abs(e[i]!))!;
+    rowOf.set(b.bone, { bone: b.bone, kind: 'angle', before: n, after: keys.length, worst: worst.worst, frame: worst.frame });
+  }
+  const rows = bones.map((b) => rowOf.get(b.bone)!);
+  const ordered = new Map(bones.map((b) => [b.bone, rotate.get(b.bone)!]));
+
+  let hipKeys: ReducedKey[] | null = null;
+  if (hip !== null) {
+    if (hip.dense.length !== n) throw new Error(`reduce: hip "${hip.bone}" has ${hip.dense.length} dense key(s) for ${n} frame(s)`);
+    const [ma, mb, mc, md] = hip.parent ?? [1, 0, 0, 1];
+    const world = (i: number, v: readonly number[]): number => {
+      const dx = v[0]! - hip.dense[i]![0];
+      const dy = v[1]! - hip.dense[i]![1];
+      return Math.hypot(ma * dx + mb * dy, mc * dx + md * dy);
+    };
+    hipKeys = fitTrack(times, samples, { targets: hip.dense, keep: keptFrames(hip.keep, n, `hip "${hip.bone}"`), tolerance: hip.tolerance, error: world });
+    const at = trackAt(hipKeys, samples, 2);
+    const worst = worstOf(at.map((_, i) => i), (i) => world(i, at[i]!))!;
+    rows.push({ bone: hip.bone, kind: 'origin', before: n, after: hipKeys.length, worst: worst.worst, frame: worst.frame });
+  }
+  return { rotate: ordered, hip: hipKeys, rows };
+}

package/src/retarget.ts

@@ -173,6 +173,8 @@ export interface MotionKey {
   v: number[];
   /** `stepped`: the value holds until the next key (the offsets' translate keys). */
   ease?: 'stepped';
+  /** A raw Bézier to the next key: four absolute (time, value) numbers per channel (`--reduce`, #32). */
+  curve?: number[];
 }
 export interface MotionTrack {
   bone: string;

package/src/run.ts

@@ -7,15 +7,16 @@
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { readMap, resolveMap, type JointMap } from './map.ts';
+import { readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.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 { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, 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, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf } from './legs.ts';
+import { reduceKeys, type ReduceBone, type Reduced } from './reduce.ts';
 import type { LegScale } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -42,6 +43,10 @@ export interface RetargetArgs extends RetargetOptions {
   carryIdle?: boolean;
   /** A rig-pose-tracks/1 fragment merged into the new animation. */
   merge?: string;
+  /** Thin the mapped bones' rotate keys within this many degrees (#32). */
+  reduce?: number;
+  /** With reduce: thin the hip's translate keys within this many rig units. */
+  reduceHip?: number;
 }
 
 export interface RunResult {
@@ -99,7 +104,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}°)${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(`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}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
     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)}`);
@@ -129,6 +134,14 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       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'}`);
     }
 
+    // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
+    const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip);
+    if (reduced !== null) {
+      for (const row of reduced.rows) say(`  REDUCE ${row.kind === 'angle' ? 'bone' : 'hip'} "${row.bone}" ${row.kind === 'angle' ? 'rotate' : 'translate'}: ${row.before} → ${row.after} key(s); worst ${row.kind === 'angle' ? 'aim' : 'origin'} error ${row.worst.toPrecision(3)}${row.kind === 'angle' ? '°' : ' units'} at frame ${row.frame} (t=${r.times[row.frame]!.toFixed(3)}s)`);
+      const sum = (k: 'before' | 'after') => reduced.rows.filter((x) => x.kind === 'angle').reduce((t, x) => t + x[k], 0);
+      say(`  REDUCE rotate keys ${sum('before')} → ${sum('after')} (${(sum('before') / sum('after')).toFixed(2)}×) within ${a.reduce}°${a.reduceHip === undefined ? '; the hip stays dense (no --reduce-hip)' : ''}`);
+    }
+
     // 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[]>;
@@ -179,7 +192,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
 
     const doc = readBuild(g1.build);
     const posed = poseFrames(doc, a.name, r.times);
-    const landings = measureLanding(doc, a.name, map, r, posed);
+    // A reduced track is held to the dense target plus its tolerance (#32).
+    const landings = measureLanding(doc, a.name, map, r, posed).map((l) => (l.kind === 'angle' && a.reduce !== undefined ? { ...l, tolerance: l.tolerance + a.reduce } : l.kind === 'origin' && a.reduceHip !== undefined ? { ...l, tolerance: l.tolerance + a.reduceHip } : l));
     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 => {
@@ -249,7 +263,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, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null },
+        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, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -272,6 +286,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         idleDropped: idle === null ? null : idle.dropped,
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
+        reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows },
       }, null, 2)}\n`);
     }
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
@@ -281,6 +296,47 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   }
 }
 
+/**
+ * The retarget's rotate tracks (and with a hip tolerance, its translate) thinned
+ * in place (#32). Kept regardless, per bone: the frames either side of each
+ * switch boundary on the chains it changes, and the edges of every FLIP spread,
+ * SHORT span and RANGE run on it (the first and last frame the reducer keeps).
+ */
+function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined): Reduced {
+  const n = r.times.length;
+  const keep = new Map<string, Set<number>>();
+  const add = (bone: string, ...frames: number[]) => {
+    const s = keep.get(bone) ?? new Set<number>();
+    for (const f of frames) if (f >= 0 && f < n) s.add(f);
+    keep.set(bone, s);
+  };
+  for (const sw of r.switches) {
+    for (const c of map.chains.filter((x) => sw.chains.includes(x.name))) for (const b of c.bones) add(b, sw.frames[0] - 1, sw.frames[0], sw.frames[1], sw.frames[1] + 1);
+  }
+  for (const x of [...r.flips, ...r.short, ...r.range]) add(x.bone, x.frames[0], x.frames[1]);
+  const mapped = new Set(r.targets.keys());
+  const above = (b: string): string | null => {
+    for (let p = rest.get(b)!.parent; p !== null; p = rest.get(p)!.parent) if (mapped.has(p)) return p;
+    return null;
+  };
+  const rotate = new Map<string, MotionTrack>();
+  for (const tr of r.animation.tracks) if ('bone' in tr && tr.property === 'rotate') rotate.set(tr.bone, tr);
+  const bones: ReduceBone[] = [...rotate.values()].map((tr) => ({ bone: tr.bone, above: above(tr.bone), dense: tr.keys.map((k) => k.v[0]!), keep: keep.get(tr.bone) ?? new Set<number>() }));
+  const hipTrack = r.origin === null || hipTolerance === undefined ? undefined : r.animation.tracks.find((tr): tr is MotionTrack => 'bone' in tr && tr.property === 'translate' && tr.bone === r.origin!.bone && tr.keys.every((k) => k.ease === undefined));
+  const parent = hipTrack === undefined ? null : rest.get(hipTrack.bone)!.parent;
+  const pm = parent === null ? null : rest.get(parent)!;
+  const out = reduceKeys(r.times, bones, tolerance, hipTrack === undefined ? null : {
+    bone: hipTrack.bone,
+    dense: hipTrack.keys.map((k) => [k.v[0]!, k.v[1]!]),
+    keep: new Set<number>(),
+    parent: pm === null ? null : [pm.a, pm.b, pm.c, pm.d],
+    tolerance: hipTolerance!,
+  });
+  for (const [bone, keys] of out.rotate) rotate.get(bone)!.keys = keys;
+  if (hipTrack !== undefined && out.hip !== null) hipTrack.keys = out.hip;
+  return out;
+}
+
 function spans(ts: number[], step: number): string {
   const out: string[] = [];
   let s = ts[0]!;