@rig-c/pose 0.31.1 → 0.32.0

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;