@rig-c/pose 0.31.1 → 0.33.0

package/src/clean.ts

@@ -807,7 +807,7 @@ export function untestedText(frames: readonly number[]): string {
 }
 
 /** The record as one line: retarget's CLEAN line, and clean's own summary. */
-export function cleanLine(r: CleanRecord): string {
+export function cleanLine(r: CleanRecord, hold: (r: CleanRecord) => string = holdText): string {
   const { loop, legs, rest } = r.params;
   const windows = legs === 1 && rest === 1 ? 'legs 1, rest 1 — no smoothing' : `legs ${legs}, rest ${rest}`;
   const found = r.spikes.found;
@@ -815,7 +815,28 @@ export function cleanLine(r: CleanRecord): string {
   const spikes = `${found.length === 0 ? 'no spike' : `${found.length} spike(s) replaced (${shown}${found.length > 8 ? `, … ${found.length - 8} more` : ''})`}, ${untestedText(r.spikes.untested)}`;
   const jit = (v: number | null) => (v === null ? 'not measured' : v.toFixed(2));
   const hips = r.params.hipsInferred === undefined ? '' : `; hips inferred (${inferredSource(r)})`;
-  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²${holdText(r)}${hips}`;
+  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²${hold(r)}${hips}`;
+}
+
+/**
+ * The CLEAN line as retarget prints it by default (rig-c/pose#238): `cleanLine`
+ * with the stillness hold's per-joint record replaced by its count — holds,
+ * joints, regions and the frames they span. The record itself is in the
+ * sequence's `cleaned` (`holds`, `unheld`, `seams`), which `--report` writes
+ * whole as its `cleaned`; `--verbose` prints `cleanLine`.
+ */
+export function cleanSummaryLine(r: CleanRecord): string {
+  return cleanLine(r, holdCount);
+}
+
+function holdCount(r: CleanRecord): string {
+  const h = r.params.hold;
+  const holds = r.holds ?? [];
+  if (h === undefined || h === 'off' || holds.length === 0) return holdText(r);
+  const regions = holdRegions(holds);
+  const span = `${regions[0]![0]}–${regions[regions.length - 1]![1]}`;
+  const unheld = (r.unheld ?? []).length, seams = (r.seams ?? []).length;
+  return `; ${holds.length} HOLD(s) over ${new Set(holds.map((x) => x.joint)).size} joint(s) in ${regions.length} region(s), frames ${span}, ${unheld} joint span(s) not held, ${seams} seam(s) (per joint: --report's cleaned.holds, cleaned.unheld, cleaned.seams; --verbose)`;
 }
 
 /**

package/src/legs.ts

@@ -321,6 +321,16 @@ export interface LegScale {
   scale: number[];
   /** The scale the pose asked for on each frame before the clamp floor (`min(ratio, limits[1])`, rig-c/pose#107). */
   asked: number[];
+  /** The picture's scale on each frame, before either limit: picture length ÷ straight (rig-c/pose#237). */
+  picture: number[];
+  /**
+   * rig-c/pose#237: on the frames this segment was clamped (`scale ≠ picture`)
+   * while its side was free (the other foot supporting, or tracked), what the
+   * clamps on that leg did to the free ankle: its height keyed against its
+   * height with every segment of that side at the picture's scale, the other
+   * leg as keyed on both. Absent with no supports read, or no clamped frame.
+   */
+  free?: FreeAnkleShift;
   /**
    * rig-c/pose#133: under `--plant-feet`, runs of supporting frames on this
    * segment where the asked scale went under `limits[0]` and followed `asked`
@@ -357,9 +367,90 @@ export function legScaleOf(lengths: readonly number[], limits: [number, number],
     ...(clamped.length > 0 ? { clamped } : {}),
     scale,
     asked,
+    picture: ratio,
   };
 }
 
+/** rig-c/pose#237: one mapped leg segment's picture length ÷ its straight length (the one `--leg-scale` scales against), read with or without the flag. */
+export interface LegSegmentRatio {
+  chain: string;
+  bone: string;
+  joints: [string, string];
+  /** px; null where it was not measured (`why`). */
+  straight: number | null;
+  /** Before any clamp: lowest, median, highest; null where it was not measured. */
+  ratio: { min: number; median: number; max: number } | null;
+  why?: string;
+}
+
+/** A free ankle's height moved by the leg-scale clamps (rig-c/pose#237): world units, and in that side's rig leg at setup (thigh origin → ankle). */
+export interface AnkleShift {
+  units: number;
+  legLengths: number;
+}
+
+/** What the clamps on a free leg did to its ankle's height over a set of frames (rig-c/pose#237). */
+export interface FreeAnkleShift {
+  side: Side;
+  /** Runs of the frames counted. */
+  frames: Array<[number, number]>;
+  /** How many frames. */
+  count: number;
+  /** The largest height above the picture's, and the largest below it (both ≥ 0); null where no frame was that way. */
+  above: AnkleShift | null;
+  below: AnkleShift | null;
+}
+
+/**
+ * rig-c/pose#237: per side and frame, the free ankle's world y as keyed less
+ * its world y with that side's leg segments at the picture's scale — on a frame
+ * the side is free (`freeOf`) and at least one of its segments' keyed scale is
+ * not the picture's; null on every other frame. `tipY` poses the legs by a
+ * scale lookup and returns that side's ankle world y; both poses share every
+ * other bone's scale, so the supporting leg cancels.
+ */
+export function freeAnkleShiftOf(n: number, legScale: readonly LegScale[], freeOf: (i: number) => Side | null, tipY: (i: number, side: Side, scaleOf: (bone: string) => number | null) => number): Record<Side, Array<number | null>> {
+  const out: Record<Side, Array<number | null>> = { r: new Array<number | null>(n).fill(null), l: new Array<number | null>(n).fill(null) };
+  const sideOf = (ls: LegScale): Side => (ls.joints[0].startsWith('r_') ? 'r' : 'l');
+  const byBone = new Map(legScale.map((ls) => [ls.bone, ls]));
+  for (let i = 0; i < n; i++) {
+    const f = freeOf(i);
+    if (f === null) continue;
+    const own = legScale.filter((ls) => sideOf(ls) === f);
+    if (!own.some((ls) => ls.scale[i] !== ls.picture[i])) continue;
+    const keyed = (b: string): number | null => byBone.get(b)?.scale[i] ?? null;
+    const picture = (b: string): number | null => {
+      const ls = byBone.get(b);
+      if (ls === undefined) return null;
+      return sideOf(ls) === f ? ls.picture[i]! : ls.scale[i]!;
+    };
+    out[f][i] = tipY(i, f, keyed) - tipY(i, f, picture);
+  }
+  return out;
+}
+
+/** The frames of `frames` with a shift on `side`, as a `FreeAnkleShift` in that side's rig leg `leg` (world units); null when none has one. */
+export function shiftOver(side: Side, frames: readonly number[], shift: Record<Side, ReadonlyArray<number | null>>, leg: number): FreeAnkleShift | null {
+  const hit = frames.filter((i) => shift[side][i] !== null && shift[side][i] !== undefined);
+  if (hit.length === 0) return null;
+  const vs = hit.map((i) => shift[side][i]!);
+  const up = Math.max(0, ...vs);
+  const down = Math.max(0, ...vs.map((v) => -v));
+  const of = (u: number): AnkleShift => ({ units: u, legLengths: u / leg });
+  return { side, frames: runsOf(hit), count: hit.length, above: vs.some((v) => v > 0) ? of(up) : null, below: vs.some((v) => v < 0) ? of(down) : null };
+}
+
+/** Consecutive runs of a sorted list of frames. */
+function runsOf(xs: readonly number[]): Array<[number, number]> {
+  const out: Array<[number, number]> = [];
+  for (const x of xs) {
+    const last = out[out.length - 1];
+    if (last !== undefined && last[1] === x - 1) last[1] = x;
+    else out.push([x, x]);
+  }
+  return out;
+}
+
 function runs(flags: readonly boolean[]): Array<[number, number]> {
   const out: Array<[number, number]> = [];
   for (let i = 0; i < flags.length; i++) {
@@ -1129,6 +1220,8 @@ export interface StanceRun {
   k: { min: number; max: number } | null;
   /** #87: a run read in `state`, shorter than `STANCE_MIN_SECONDS` between two runs of the other state, which took their state; its frames are in their run too, and `k` is null. */
   absorbed?: true;
+  /** rig-c/pose#237, on a `lifted` or `below` run under `--leg-scale`: the frames whose free ankle the clamps moved off the pose's height, and by how much. Absent when the pose's height was kept on every frame. */
+  moved?: FreeAnkleShift;
 }
 
 /** A run of planted-both frames whose stretch needed a factor past the bounds (or could not reach: `needed` null). */

package/src/map.ts

@@ -43,6 +43,11 @@
  * well. Outside a set's span the retarget clamps the key there, and lists the
  * overflow as demand (`RANGE`).
  *
+ * The chain whose joints carry the eye line (`r_eye → l_eye`) keys the head's
+ * nod; `"nod": false` on it keys none and couples none (rig-c/pose#241). "nod"
+ * on any other chain is refused (`MAP_NOD`): a switch with nothing to turn off
+ * would be read as having turned something off.
+ *
  * `alternates` lists the rig's alternate drawings as sets: `{ name, slots,
  * hides, chains, pose, drawn?, offsets? }`. While a set shows, every slot in
  * `slots` shows its attachment and every slot in `hides` is empty; `pose` is the
@@ -73,6 +78,8 @@ export interface Chain {
   reach: boolean;
   /** Per bone of the chain: the rotate key's range, degrees relative to setup, [min, max]. */
   range: Record<string, [number, number]>;
+  /** On the chain carrying the eye line (`r_eye → l_eye`): false keys no head nod and couples none (rig-c/pose#241); absent or true, the nod is read. */
+  nod?: boolean;
 }
 export interface Translate {
   bone: string;
@@ -160,6 +167,23 @@ export interface RestBone extends RawBone {
 }
 export type Rest = ReadonlyMap<string, RestBone>;
 
+/** The body-18 points past which nothing is read: no toe past an ankle, no hand point past a wrist. */
+const LIMB_ENDS: Readonly<Record<string, string>> = { r_ankle: 'toe', l_ankle: 'toe', r_wrist: 'hand point', l_wrist: 'hand point' };
+
+/**
+ * MAP_CHAIN_JOINTS's remedy (rig-c/pose#240): a chain one joint short whose last
+ * joint ends a limb — a three-bone leg on hip, knee, ankle — has a bone body-18
+ * gives no segment to, so the remedy is to leave it out, not to find a joint.
+ */
+function endOfLimb(bones: readonly string[], joints: readonly string[]): string {
+  const last = joints[joints.length - 1];
+  if (joints.length !== bones.length || last === undefined) return '';
+  const what = LIMB_ENDS[last];
+  if (what === undefined) return '';
+  const bone = bones[bones.length - 1]!;
+  return ` — body-18 has no ${what} past "${last}", so nothing aims bone "${bone}": list the chain's bones up to the one ending at "${last}" (${bones.slice(0, -1).map((b) => `"${b}"`).join(', ')}) and leave "${bone}" out of "bones"; it stays unkeyed and turns with its parent`;
+}
+
 export function readMap(text: string, where: string): JointMap {
   const doc = parseJson(text, where, 'MAP_JSON');
   const p = new Problems();
@@ -178,10 +202,10 @@ export function readMap(text: string, where: string): JointMap {
     doc.chains.forEach((c: unknown, i: number) => {
       const cw = `${where} chains[${i}]`;
       if (!isObject(c)) {
-        p.add('MAP_CHAIN_SHAPE', `${cw} is ${typeName(c)}; a chain is { name, bones, joints, aim?, bend?, reach?, range? }`);
+        p.add('MAP_CHAIN_SHAPE', `${cw} is ${typeName(c)}; a chain is { name, bones, joints, aim?, bend?, reach?, range?, nod? }`);
         return;
       }
-      refuseUnknownKeys(p, 'MAP_KEYS', cw, c, ['name', 'bones', 'joints', 'aim', 'bend', 'reach', 'range']);
+      refuseUnknownKeys(p, 'MAP_KEYS', cw, c, ['name', 'bones', 'joints', 'aim', 'bend', 'reach', 'range', 'nod']);
       const name = typeof c.name === 'string' && c.name !== '' ? c.name : null;
       if (name === null) p.add('MAP_CHAIN_NAME', `${cw} "name" is ${typeName(c.name)}; it must be a non-empty string`);
       else if (names.has(name)) p.add('MAP_CHAIN_NAME', `${cw} "name" "${name}" names two chains`);
@@ -192,7 +216,7 @@ export function readMap(text: string, where: string): JointMap {
       if (bones === null || bones.length === 0) p.add('MAP_CHAIN_BONES', `${label} "bones" is ${typeName(c.bones)}; it must be a non-empty array of bone names`);
       if (joints === null || joints.length < 2) p.add('MAP_CHAIN_JOINTS', `${label} "joints" is ${typeName(c.joints)}; it must be an array of at least two joint names`);
       if (bones !== null && joints !== null && bones.length > 0 && joints.length !== bones.length + 1) {
-        p.add('MAP_CHAIN_JOINTS', `${label} has ${bones.length} bone(s) and ${joints.length} joint(s); bone k carries the segment from joint k to joint k+1, so it needs ${bones.length + 1}`);
+        p.add('MAP_CHAIN_JOINTS', `${label} has ${bones.length} bone(s) and ${joints.length} joint(s); bone k carries the segment from joint k to joint k+1, so it needs ${bones.length + 1}${endOfLimb(bones, joints)}`);
       }
       for (const j of joints ?? []) {
         if (!POINT_NAMES.includes(j)) p.add('MAP_JOINT_NAME', `${label} names joint "${j}", which is not a point this package reads; they are ${POINT_NAMES.join(', ')}`);
@@ -228,7 +252,14 @@ export function readMap(text: string, where: string): JointMap {
           }
         }
       }
-      chains.push({ name: name ?? cw, bones: bones ?? [], joints: joints ?? [], aim, bend, reach, range });
+      let nod: boolean | undefined;
+      if ('nod' in c) {
+        const eyeLine = (joints ?? []).some((j, k, js) => (j === 'r_eye' && js[k + 1] === 'l_eye') || (j === 'l_eye' && js[k + 1] === 'r_eye'));
+        if (typeof c.nod !== 'boolean') p.add('MAP_NOD', `${label} "nod" is ${typeName(c.nod)}; it must be true or false (false keys no head nod and couples none into the head's rotate or the face pitch)`);
+        else if (!eyeLine) p.add('MAP_NOD', `${label} has "nod" but its joints (${(joints ?? []).join(' → ')}) carry no eye line; the nod is read on the chain whose joints run r_eye → l_eye (or l_eye → r_eye), so "nod" belongs there or nowhere`);
+        else nod = c.nod;
+      }
+      chains.push({ name: name ?? cw, bones: bones ?? [], joints: joints ?? [], aim, bend, reach, range, ...(nod !== undefined ? { nod } : {}) });
     });
   }
   let translate: Translate | null = null;

package/src/problems.ts

@@ -10,6 +10,13 @@ export interface Problem {
   code: string;
   /** The object, the value found, the value required. */
   text: string;
+  /**
+   * The per-frame problems this one collapses (rig-c/pose#238): a refusal of one
+   * kind that fires on every frame prints one line with its count, worst value
+   * and frame range; these are the lines it stands for, printed under --verbose.
+   * `detail.length` is the count the collapsed line states.
+   */
+  detail?: readonly Problem[];
 }
 
 export class Refusal extends Error {
@@ -28,8 +35,8 @@ export function lineOf(p: Problem): string {
 /** A collector: `add` while reading, `throwIfAny` once at the end. */
 export class Problems {
   readonly list: Problem[] = [];
-  add(code: string, text: string): void {
-    this.list.push({ code, text });
+  add(code: string, text: string, detail?: readonly Problem[]): void {
+    this.list.push(detail === undefined ? { code, text } : { code, text, detail });
   }
   get any(): boolean {
     return this.list.length > 0;

package/src/report.ts

@@ -56,10 +56,12 @@ export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:Rep
     if(Array.isArray(value)){value.forEach((row,i)=>visit(row,`${where}[${i}]`));return;}
     if(!isObject(value))return;
     // Preserve uncovered's discrete renderer times; they do not index the pose.
-    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')){
+    if(where.startsWith('report.uncovered[')||where.startsWith('report.folds[')||where.startsWith('report.seams[')){
       if(!render)fail(where,'render-domain event requires declared renderer metadata');
       add(value,'domain','render',where);return;
     }
+    // seamPairs' frame lists are the seam render's indices (#216); they carry no pose coordinate.
+    if(where.startsWith('report.seamPairs['))return;
     let coordinates=false;
     if(poseEvent(where)&&value.frame!==undefined&&typeof value.frame!=='number')fail(where+'.frame','expected nonnegative integer pose frame');
     if(typeof value.frame==='number'){add(value,'t',time(value.frame,where+'.frame'),where);coordinates=true;}
@@ -85,4 +87,26 @@ export function enrichReport(input:Record<string,unknown>,map:JointMap,clock:Rep
   if(inputs!==undefined){if(!isObject(inputs))throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);for(const key of ['rig','map','pose'] as const){const entry=inputs[key];if(!isObject(entry)||typeof entry.path!=='string'||!entry.path||entry.path.startsWith('/')||entry.path.charCodeAt(0)===92||/^[A-Za-z]:/.test(entry.path)||typeof entry.sha256!=='string'||! /^[a-f0-9]{64}$/.test(entry.sha256))throw new Refusal([{code:'REPORT_INPUTS',text:`inputs.${key}: expected invocation-relative consumed file path and exact SHA-256`}]);}add(report,'inputs',clone(inputs),'report');}
   problems.throwIfAny();return report;
 }
-export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}
+/**
+ * rig-c/pose#216: `seams` and `seamPairs` are declared fields, not optional by
+ * accident — a report without them is a run whose seam reading never ran, and
+ * the writer refuses it by name. Each `seams` row is one span of one kind:
+ * `{ pair, kind, frames: [first, last], times: [first, last], maxPx }`.
+ */
+export function checkSeams(input:Record<string,unknown>):void {
+  const p=new Problems();
+  if(!Array.isArray(input.seams))p.add('REPORT_SEAMS',`seams: found ${input.seams===undefined?'no field':JSON.stringify(input.seams)}; the report declares the seam reading's spans (rig-c/pose#216), [] when none opens or no pair is declared, and seamPairs says which`);
+  if(!Array.isArray(input.seamPairs))p.add('REPORT_SEAMS',`seamPairs: found ${input.seamPairs===undefined?'no field':JSON.stringify(input.seamPairs)}; the report declares what the seam reading said of each declared pair (rig-c/pose#216), [] when none is declared`);
+  p.throwIfAny();
+  const int=(v:unknown)=>Number.isSafeInteger(v)&&(v as number)>=0;
+  (input.seams as unknown[]).forEach((row,i)=>{
+    const ok=isObject(row)&&typeof row.pair==='string'&&row.pair.includes('|')&&(row.kind==='gap'||row.kind==='ghost')&&Array.isArray(row.frames)&&row.frames.length===2&&row.frames.every(int)&&(row.frames[1] as number)>=(row.frames[0] as number)&&Array.isArray(row.times)&&row.times.length===2&&row.times.every(t=>typeof t==='number'&&Number.isFinite(t)&&t>=0)&&(row.times[1] as number)>=(row.times[0] as number)&&int(row.maxPx)&&(row.maxPx as number)>0;
+    if(!ok)p.add('REPORT_SEAMS',`seams[${i}]: found ${JSON.stringify(row)}; expected { pair: "<a>|<b>", kind: "gap"|"ghost", frames: [first, last], times: [first, last], maxPx > 0 }`);
+  });
+  (input.seamPairs as unknown[]).forEach((row,i)=>{
+    const ok=isObject(row)&&typeof row.pair==='string'&&(row.status==='read'||row.status==='skip'||row.status==='unread')&&(row.status!=='unread'||typeof row.reason==='string');
+    if(!ok)p.add('REPORT_SEAMS',`seamPairs[${i}]: found ${JSON.stringify(row)}; expected { pair, status: "read"|"skip"|"unread", reason when unread }`);
+  });
+  p.throwIfAny();
+}
+export function writeReport(input:Record<string,unknown>,map:JointMap,clock:ReportClock,render:RenderDomain|null,inputs:ReportInputs):string {checkSeams(input);if(inputs===undefined)throw new Refusal([{code:'REPORT_INPUTS',text:'inputs: expected rig, map and pose file identities'}]);return JSON.stringify(enrichReport(input,map,clock,render,inputs),null,2)+'\n';}