@rig-c/pose 0.13.0 → 0.15.0

package/src/retarget.ts

@@ -19,9 +19,8 @@
  * pose puts the segment's end, relative to the translated joint and scaled. So
  * the hip and its travel are computed before any bone's target.
  *
- * Smoothing is Savitzky–Golay: a centred least-squares cubic over the window,
- * 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.
+ * Smoothing is not done here: the sequence comes cleaned (`clean.ts`, #67 —
+ * spikes, occlusion, a per-joint Savitzky–Golay), and its record says how.
  *
  * The short hold (rig-c/pose#22) comes next: a segment whose picture length on
  * a frame is under `short` of its own median length over the sequence is seen
@@ -35,7 +34,7 @@
  * 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, smoothing and the short hold, and before the hinge check. A reach's
+ * holds and the short hold, and before the hinge check. A reach's
  * target is aimed later, from posed positions, and is neither held short nor
  * guarded.
  *
@@ -52,7 +51,7 @@
  * against it (`artTurn`, and `artRange` where it leaves its range).
  *
  * The lines across the body — hips, shoulders, eyes — are read from the pose
- * after holds and smoothing, whether the map uses them or not: a line under
+ * after holds, whether the map uses them or not: a line under
  * `TURN_FRACTION` of its median picture length, or reversed (pointing more
  * than 90° from the subject's right to left), for ≥ `TURN_SECONDS`, is a `TURN`:
  * the body or head turned, a pose a flat rig cannot draw. It changes no key.
@@ -77,8 +76,6 @@ const DEG = 180 / Math.PI;
 export interface RetargetOptions extends SwitchOptions {
   /** A joint with a score below this is not good on that frame (a joint with no score is). */
   minScore: number;
-  /** Savitzky–Golay window over joint positions, in frames: 1 = none, else odd and ≥ 5. */
-  smooth: number;
   /** What a hinge bent the wrong way does: refuse the run, or straighten that hinge on that frame. */
   bends: 'refuse' | 'clamp';
   /** Degrees past straight a hinge may bend the wrong way before it counts. */
@@ -331,64 +328,6 @@ function median(xs: number[]): number {
   return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
 }
 
-/**
- * Savitzky–Golay, centred: at each frame, the least-squares polynomial of
- * `order` over the frames of the window that exist (clipped at the ends), read
- * at that frame. With fewer points than order + 1 the order drops to fit them
- * exactly, so a window clipped to 4 frames or fewer returns the input there.
- * A polynomial of degree ≤ `order` passes through unchanged.
- */
-export function savitzkyGolay(xs: readonly Pt[], window: number, order = 3): Pt[] {
-  if (window <= 1) return xs.map((x) => [x[0], x[1]]);
-  const h = window >> 1;
-  const n = xs.length;
-  const cache = new Map<string, number[]>();
-  return xs.map((_, i) => {
-    const lo = Math.max(0, i - h) - i;
-    const hi = Math.min(n - 1, i + h) - i;
-    const key = `${lo},${hi}`;
-    let w = cache.get(key);
-    if (w === undefined) {
-      w = sgWeights(lo, hi, Math.min(order, hi - lo));
-      cache.set(key, w);
-    }
-    let x = 0;
-    let y = 0;
-    for (let u = lo; u <= hi; u++) {
-      const c = w[u - lo]!;
-      x += c * xs[i + u]![0];
-      y += c * xs[i + u]![1];
-    }
-    return [x, y];
-  });
-}
-
-/** The weights that read a least-squares polynomial of degree q over u = lo..hi at u = 0. */
-function sgWeights(lo: number, hi: number, q: number): number[] {
-  const m = q + 1;
-  // Normal equations: A[j][l] = Σ u^(j+l); solve A z = e0, then w(u) = Σ z_j u^j.
-  const A = Array.from({ length: m }, (_, j) => Array.from({ length: m + 1 }, (_, l) => {
-    if (l === m) return j === 0 ? 1 : 0;
-    let s = 0;
-    for (let u = lo; u <= hi; u++) s += u ** (j + l);
-    return s;
-  }));
-  for (let c = 0; c < m; c++) {
-    let piv = c;
-    for (let r = c + 1; r < m; r++) if (Math.abs(A[r]![c]!) > Math.abs(A[piv]![c]!)) piv = r;
-    [A[c], A[piv]] = [A[piv]!, A[c]!];
-    for (let r = 0; r < m; r++) {
-      if (r === c) continue;
-      const f = A[r]![c]! / A[c]![c]!;
-      for (let l = c; l <= m; l++) A[r]![l]! -= f * A[c]![l]!;
-    }
-  }
-  const z = A.map((row, j) => row[m]! / row[j]!);
-  const w: number[] = [];
-  for (let u = lo; u <= hi; u++) w.push(z.reduce((s, zj, j) => s + zj * u ** j, 0));
-  return w;
-}
-
 const r3 = (v: number) => {
   const r = Math.round(v * 1000) / 1000;
   return Object.is(r, -0) ? 0 : r;
@@ -439,7 +378,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const series = new Map<string, Pt[]>();
   const good = new Map<string, boolean[]>();
   const holds: Hold[] = [];
-  /** A point held where it is not good, then smoothed; or why it is good on no frame. */
+  /** A point held where it is not good; or why it is good on no frame. */
   const heldOf = (name: string): { at: Pt[]; good: boolean[]; holds: Hold[] } | { never: string } => {
     const raw = frames.map((f) => pointOn(f, name, opts.minScore));
     const firstGood = raw.findIndex((v) => typeof v !== 'string');
@@ -463,7 +402,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         spans.push(span);
       }
     }
-    return { at: savitzkyGolay(out, opts.smooth), good: raw.map((v) => typeof v !== 'string'), holds: spans };
+    return { at: out, good: raw.map((v) => typeof v !== 'string'), holds: spans };
   };
   for (const name of [...needed].sort()) {
     const h = heldOf(name);
@@ -477,7 +416,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
-  // TURN: the lines across the body, read from the pose (held and smoothed as the
+  // TURN: the lines across the body, read from the pose (held as the
   // map's points are, whether or not the map uses them). A reading; no key moves.
   const turns: Turn[] = [];
   const turnsUnread: Retarget['turnsUnread'] = [];

package/src/run.ts

@@ -8,6 +8,7 @@ import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeF
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { readMap, resolveMap, type JointMap, type Rest } from './map.ts';
+import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, type CameraFrame } 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';
@@ -26,6 +27,8 @@ export interface RetargetArgs extends RetargetOptions {
   out: string;
   name: string;
   coco: boolean;
+  /** `--smooth`'s value when given: an alias since #67 — the cleaning carries the smoothing; it prints so and changes nothing. */
+  smoothAlias?: string;
   person?: string;
   baseMotion?: string;
   /** Passed to rigc build as --images: the directory the rig spec's images resolve in, when rig.json's own `images` does not point there (a copied rig). */
@@ -87,6 +90,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const map = readMap(readFileSync(a.map, 'utf8'), a.map);
   const poseText = readFileSync(a.pose, 'utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
+  if (seq.cleaned === undefined) refuse([{ code: 'POSE_NOT_CLEANED', text: notCleaned(a.pose, a.coco) }]);
   const frames = personTrack(seq, a.person, a.pose);
   const times = seq.frames.map((f) => f.t);
 
@@ -104,8 +108,10 @@ 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.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${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(`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}, 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.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${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`);
+    say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
+    if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
     if (seq.camera !== undefined) say(`  CAMERA ${cameraLine(seq.camera, times, seq.cameraSource)}`);
     else if (a.plantFeet === true) say('  CAMERA none in the sequence: --plant-feet reads the picture as a fixed camera, so a zoom or a pan in the video moves the floor with it and the floor may step with the picture (tools/scan.py reads the camera, rig-c/pose#63)');
     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)})`);
@@ -219,7 +225,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     p.throwIfAny();
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore);
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned));
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
@@ -266,7 +272,8 @@ 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, stance: a.stance ?? 'off', idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        cleaned: seq.cleaned,
+        options: { minScore: a.minScore, 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, stance: a.stance ?? 'off', 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,
@@ -436,3 +443,14 @@ function legScaleLine(l: LegScale, times: readonly number[]): string {
   const clamp = (rs: Array<[number, number]>, at: number, how: string) => (rs.length === 0 ? `none ${how} ${at}` : `${count(rs)} frame(s) ${how} ${at}, clamped (frames ${rs.map(span).join(', ')})`);
   return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (95th percentile of ${times.length} frames); picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}]: ${clamp(l.low, l.limits[0], 'under')}; ${clamp(l.high, l.limits[1], 'over')}`;
 }
+
+/**
+ * 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
+ * suggestion beside it (`<name>.clean.json`).
+ */
+export function notCleaned(pose: string, coco: boolean): string {
+  const out = pose.endsWith('.json') ? `${pose.slice(0, -'.json'.length)}.clean.json` : `${pose}.clean.json`;
+  const what = coco ? `${pose} is COCO-17 (--coco), which carries no "cleaned" record` : `${pose} has no "cleaned" record`;
+  return `${what}; retarget reads a sequence rig-pose clean wrote (spikes, occlusion, smoothing; there is no flag to skip it). Run \`rig-pose clean ${coco ? '--coco ' : ''}--pose ${pose} --out ${out}\` (add --loop for one cycle of a gait) and retarget --pose ${out}`;
+}

package/src/switch.ts

@@ -4,7 +4,7 @@
  *
  * The metric, per frame and per set: the largest |wrap(pose − key)| over every
  * segment of the set's chains, where "pose" is the segment's angle exactly as
- * the retarget asked the bone for it (after holds, smoothing, the short hold,
+ * the retarget asked the bone for it (after holds, the short hold,
  * the flip guard and the hinge check; before any range clamp) and "key" is the
  * same segment's angle in the set's key skeleton, both by `pictureAngle`. Per
  * frame the candidate is the set with the smallest distance within the

package/src/verify.ts

@@ -246,8 +246,19 @@ export interface Posture {
   rigShoulder: string | null;
   /** Reference frames on which the hips (tilt) and the hips and shoulders (sway) are all good. */
   frames: { tilt: number; sway: number; of: number };
-  /** Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's aim). */
-  tilt: { reference: Range; rig: Range; ratio: number };
+  /**
+   * Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's
+   * aim). Null when every frame with both hips good has an `inferred` hip
+   * (#63): the tilt is not read, and `tiltWhy` says why.
+   */
+  tilt: { reference: Range; rig: Range; ratio: number } | null;
+  /** Present only when `tilt` is null: why it was not read. */
+  tiltWhy?: string;
+  /**
+   * Present only when some frame with both hips good has an `inferred` hip:
+   * how many such frames the tilt left out, and where the state came from.
+   */
+  hipsInferred?: { frames: number; source: string };
   /**
    * Sway: the x-range of mid_hip − mid_shoulder, in rig units (the reference's
    * picture px × the figure scale) and in each body's own shoulder widths.
@@ -282,8 +293,17 @@ const medianOf = (xs: number[]): number => {
  * the joints it needs are good), the rig is the gated build posed by rig-c.
  * Null when the map has no pelvis chain (joints exactly r_hip, l_hip) or no
  * translate.
+ *
+ * Inferred hips (#63): a frame on which either hip is `inferred` is left out of
+ * the tilt — its hip line is a position the detector supplied but did not see,
+ * and a tilt read off it would be the detector's guess reported as the dancer's.
+ * When that is every frame (`clean --hips-inferred` marks them all), the tilt
+ * is null and `tiltWhy` names the reason and its source (`inferredSource`, read
+ * from the clean record). On some frames only, the tilt is read over the rest
+ * and the line counts the frames left out. Sway is read as before, inferred
+ * hips included: it is a different measure, and the card leaves it as it is.
  */
-export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number): Posture | null {
+export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number, inferredSource = 'source not stated'): Posture | null {
   const pelvis = map.chains.find((c) => c.joints.length === 2 && c.joints[0] === 'r_hip' && c.joints[1] === 'l_hip');
   if (pelvis === undefined || map.translate === null || r.origin === null || r.scale === null) return null;
   const s = r.scale.factor;
@@ -294,11 +314,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const refTilt: number[] = [];
   const refSway: number[] = [];
   const refSw: number[] = [];
-  frames.forEach((_, i) => {
+  let inferred = 0;
+  frames.forEach((f, i) => {
     const rh = at(i, 'r_hip');
     const lh = at(i, 'l_hip');
     if (rh === null || lh === null) return;
-    refTilt.push(pictureAngle(rh, lh));
+    if (f.r_hip?.state === 'inferred' || f.l_hip?.state === 'inferred') inferred++;
+    else refTilt.push(pictureAngle(rh, lh));
     const rs = at(i, 'r_shoulder');
     const ls = at(i, 'l_shoulder');
     if (rs === null || ls === null) return;
@@ -307,9 +329,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   });
   const bone = pelvis.bones[0]!;
   const aim = pelvis.aim[0]!;
-  const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
-  const tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
-  tilt.ratio = tilt.rig.range / tilt.reference.range;
+  let tilt: Posture['tilt'] = null;
+  const why = `hips inferred (${inferredSource})`;
+  if (inferred === 0 || refTilt.length > 0) {
+    const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
+    tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
+    tilt.ratio = tilt.rig.range / tilt.reference.range;
+  }
 
   // The rig's mid-shoulder: the point a reach aims at, else the midpoint of the arms' first bones.
   const reach = map.chains.find((c) => c.reach);
@@ -340,7 +366,16 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       ratioSw: rig === null || rig.rangeSw === null ? null : rig.rangeSw / reference.rangeSw,
     };
   }
-  return { pelvis: pelvis.name, rigHip: r.origin.bone, rigShoulder, frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length }, tilt, sway };
+  return {
+    pelvis: pelvis.name,
+    rigHip: r.origin.bone,
+    rigShoulder,
+    frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length },
+    tilt,
+    ...(tilt === null ? { tiltWhy: why } : {}),
+    ...(inferred > 0 ? { hipsInferred: { frames: inferred, source: inferredSource } } : {}),
+    sway,
+  };
 }
 
 const f1 = (x: number) => x.toFixed(1);
@@ -350,8 +385,12 @@ const sg = (x: number) => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
 /** The POSTURE lines. */
 export function postureLines(q: Posture): string[] {
   const over = (k: number) => (k === q.frames.of ? '' : ` over ${k} of ${q.frames.of} frames`);
+  const t = q.tilt;
+  const left = q.hipsInferred === undefined ? '' : `; ${q.hipsInferred.frames} frame(s) with an inferred hip not read (${q.hipsInferred.source})`;
   const out = [
-    `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(q.tilt.reference.range)}° (${sg(q.tilt.reference.min)}° … ${sg(q.tilt.reference.max)}°${over(q.frames.tilt)}), rig ${f1(q.tilt.rig.range)}° (${sg(q.tilt.rig.min)}° … ${sg(q.tilt.rig.max)}°) — rig/reference ${f3(q.tilt.ratio)}`,
+    t === null
+      ? `hip tilt not read: ${q.tiltWhy}`
+      : `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(t.reference.range)}° (${sg(t.reference.min)}° … ${sg(t.reference.max)}°${over(q.frames.tilt)}), rig ${f1(t.rig.range)}° (${sg(t.rig.min)}° … ${sg(t.rig.max)}°) — rig/reference ${f3(t.ratio)}${left}`,
   ];
   const w = q.sway;
   if (w === null) out.push('sway: the reference has no frame with both hips and both shoulders good; not measured');