@rig-c/pose 0.17.0 → 0.19.0

package/src/map.ts

@@ -50,6 +50,9 @@
  * directions are read), holding every joint its `chains` use; `drawn` is each
  * bone's world angle as painted (a reading: `artTurn`); `offsets` is a
  * translate per bone, in its parent's axes, held while the set shows.
+ * `place: "by-hip"` (rig-c/pose#93) places the wrist of each of its chains that
+ * `pose` puts within one hip width of the mid-hip by its offset from the hip
+ * (`byHipChains`; the retarget solves it).
  * `switch.ts` decides when each one shows.
  */
 import type { RawBone } from 'rig-c/core';
@@ -95,6 +98,8 @@ export interface AlternateSet {
   turn: Record<string, [number, number]>;
   /** A stopgap: the only frames the set may show on, a list of [first, last] windows; on them it is chosen over any set without windows. Null: any frame. */
   frames: Array<[number, number]> | null;
+  /** `place: "by-hip"` (rig-c/pose#93): the chains whose wrist `pose` puts within one hip width of the mid-hip, their wrists placed by the offset from the hip while the set shows. Absent or null: the pose's angles. */
+  place?: { by: 'hip'; chains: string[] } | null;
 }
 export interface JointMap {
   chains: Chain[];
@@ -228,7 +233,39 @@ export function readMap(text: string, where: string): JointMap {
   return { chains, translate, alternates };
 }
 
-const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …] }';
+const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …], place?: "by-hip" }';
+
+/** The joints a wrist is, for `place: "by-hip"`: a chain whose last joint is one of them carries a wrist. */
+export const WRISTS: readonly string[] = ['r_wrist', 'l_wrist'];
+
+/**
+ * `place: "by-hip"` (rig-c/pose#93): the set's chains that carry a wrist (their
+ * last joint) which its key skeleton puts within one hip width of the mid-hip —
+ * |wrist − (r_hip + l_hip) / 2| ≤ |r_hip − l_hip| — and each wrist chain's
+ * distance in hip widths; or why the key skeleton cannot be read so.
+ */
+export function byHipChains(pose: Readonly<Record<string, readonly [number, number]>>, chains: readonly Chain[]): { chains: string[]; distances: Array<{ chain: string; wrist: string; hipWidths: number }> } | { problem: string } {
+  const r = pose.r_hip;
+  const l = pose.l_hip;
+  if (r === undefined || l === undefined) return { problem: `its "pose" has no ${[r === undefined ? '"r_hip"' : '', l === undefined ? '"l_hip"' : ''].filter((x) => x !== '').join(' or ')}; "by-hip" reads the hip width and the mid-hip off the key skeleton's two hips, which the map's author supplies` };
+  const noWrist = chains.filter((c) => WRISTS.includes(c.joints[c.joints.length - 1]!) && pose[c.joints[c.joints.length - 1]!] === undefined);
+  if (noWrist.length > 0) return { problem: noWrist.map((c) => `its "pose" has no "${c.joints[c.joints.length - 1]}", the wrist of chain "${c.name}"`).join('; ') + '; "by-hip" reads each wrist\'s distance from the mid-hip off the key skeleton' };
+  const width = Math.hypot(l[0] - r[0], l[1] - r[1]);
+  if (!(width > 1e-9)) return { problem: `its "pose" puts r_hip and l_hip at the same point; a hip width of 0 is no unit` };
+  const mid: [number, number] = [(r[0] + l[0]) / 2, (r[1] + l[1]) / 2];
+  const distances: Array<{ chain: string; wrist: string; hipWidths: number }> = [];
+  for (const c of chains) {
+    const wrist = c.joints[c.joints.length - 1]!;
+    if (!WRISTS.includes(wrist)) continue;
+    const w = pose[wrist];
+    if (w === undefined) continue;
+    distances.push({ chain: c.name, wrist, hipWidths: Math.hypot(w[0] - mid[0], w[1] - mid[1]) / width });
+  }
+  if (distances.length === 0) return { problem: `none of its chains (${chains.map((c) => c.name).join(', ')}) ends at a wrist (${WRISTS.join(', ')}); "by-hip" places a wrist` };
+  const near = distances.filter((d) => d.hipWidths <= 1);
+  if (near.length === 0) return { problem: `its "pose" puts no wrist within one hip width of the mid-hip (${distances.map((d) => `chain "${d.chain}" ${d.wrist} ${d.hipWidths.toFixed(2)} hip widths`).join(', ')}); "by-hip" places a hand that meets the body` };
+  return { chains: near.map((d) => d.chain), distances };
+}
 
 /** `alternates`: each set's shape, its chains against the map's, its key skeleton against those chains' joints, and its bones against those chains' bones. */
 function readAlternates(p: Problems, where: string, raw: unknown, chains: readonly Chain[], translate: Translate | null): AlternateSet[] {
@@ -245,7 +282,7 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
       p.add('MAP_ALT_SHAPE', `${aw} is ${typeName(a)}; a set is ${SET_SHAPE}`);
       return;
     }
-    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place']);
     const name = typeof a.name === 'string' && a.name !== '' ? a.name : null;
     if (name === null) p.add('MAP_ALT_NAME', `${aw} "name" is ${typeName(a.name)}; it must be a non-empty string`);
     else if (names.has(name)) p.add('MAP_ALT_NAME', `${aw} "name" "${name}" names two sets`);
@@ -354,7 +391,16 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         p.add('MAP_ALT_FRAMES', `${label} "frames" is ${JSON.stringify(f)}; it must be a non-empty list of windows [[first, last], …], whole frame numbers ≥ 0 with first ≤ last`);
       } else frames = (f as Array<[number, number]>).map((w) => [w[0], w[1]]);
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames });
+    let place: AlternateSet['place'] = null;
+    if ('place' in a) {
+      if (a.place !== 'by-hip') p.add('MAP_ALT_PLACE', `${label} "place" is ${JSON.stringify(a.place)}; the one placement a set may ask for is "by-hip"`);
+      else if (isObject(a.pose) && own.length > 0) {
+        const by = byHipChains(pose, own);
+        if ('problem' in by) p.add('MAP_ALT_PLACE', `${label} "place" is "by-hip", and ${by.problem}`);
+        else place = { by: 'hip', chains: by.chains };
+      }
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }) });
   });
   return out;
 }

package/src/pose.ts

@@ -74,36 +74,63 @@ export interface CleanSpike {
  * pelvis line off the picture (`tools/pelvis.py`, after clean) and turned the
  * hip pair to a measured angle on every frame. The exact shape:
  *
- *   { by: "measured", method: string,
- *     read: Run[], interpolated: Run[], held: Run[],
+ *   { by: "measured", method: string, fit?: { frames, gain, corr },
+ *     read: Run[], interpolated: Run[], scaled?: Run[], held: Run[], unmeasured?: Run[],
  *     declined: Array<{ frames: Run, why: string }> }      Run = [first, last]
  *
  * `method` names the reading. Runs are integer frame indices inside the
  * sequence, first ≤ last, increasing and not overlapping within each list.
  * Every frame of the sequence is in exactly one of `read` (the frame's own
  * reading), `interpolated` (a declined frame between two reads close in time,
- * the angle interpolated) and `held` (any other declined frame, the earlier
- * read carried to the end of its run; at the clip's start, the later read). `declined` lists, with the reason, exactly the frames that are
- * interpolated or held. Anything else is refused by name (POSE_CLEANED).
+ * the angle interpolated), `scaled` (#106: a longer declined run taking the
+ * detector hip line scaled by `fit.gain`), `held` (the earlier read carried to
+ * the end of its run; at the clip's start, the later read) and `unmeasured`
+ * (#106: a longer declined run when `fit.corr` < 0.9). `declined` lists, with
+ * the reason, exactly the non-read frames. Anything else is refused by name
+ * (POSE_CLEANED).
  */
 export type Run = [number, number];
+export interface PelvisFit {
+  frames: number;
+  gain: number | null;
+  corr: number | null;
+}
 export type HipsInferred =
   | { by: 'declared' }
-  | { by: 'measured'; method: string; read: Run[]; interpolated: Run[]; held: Run[]; declined: Array<{ frames: Run; why: string }> };
+  | {
+      by: 'measured';
+      method: string;
+      fit?: PelvisFit;
+      read: Run[];
+      interpolated: Run[];
+      scaled?: Run[];
+      held: Run[];
+      unmeasured?: Run[];
+      declined: Array<{ frames: Run; why: string }>;
+    };
 
 /** A copy of the record, in the writer's key order. */
 export function copyHipsInferred(h: HipsInferred): HipsInferred {
   const runs = (rs: Run[]): Run[] => rs.map(([a, b]) => [a, b]);
-  return h.by === 'declared'
-    ? { by: 'declared' }
-    : { by: 'measured', method: h.method, read: runs(h.read), interpolated: runs(h.interpolated), held: runs(h.held), declined: h.declined.map((d) => ({ frames: [d.frames[0], d.frames[1]], why: d.why })) };
+  if (h.by === 'declared') return { by: 'declared' };
+  return {
+    by: 'measured',
+    method: h.method,
+    ...(h.fit !== undefined ? { fit: { frames: h.fit.frames, gain: h.fit.gain, corr: h.fit.corr } } : {}),
+    read: runs(h.read),
+    interpolated: runs(h.interpolated),
+    ...(h.scaled !== undefined ? { scaled: runs(h.scaled) } : {}),
+    held: runs(h.held),
+    ...(h.unmeasured !== undefined ? { unmeasured: runs(h.unmeasured) } : {}),
+    declined: h.declined.map((d) => ({ frames: [d.frames[0], d.frames[1]], why: d.why })),
+  };
 }
 
-/** The frames a `measured` record gives an angle on (read, interpolated, held), as a set; null for any other record or none. */
+/** The frames a `measured` record gives an angle on (read, interpolated, scaled, held), as a set; null for any other record or none. */
 export function measuredFrames(h: HipsInferred | undefined): Set<number> | null {
   if (h === undefined || h.by !== 'measured') return null;
   const out = new Set<number>();
-  for (const rs of [h.read, h.interpolated, h.held]) for (const [a, b] of rs) for (let f = a; f <= b; f++) out.add(f);
+  for (const rs of [h.read, h.interpolated, h.scaled ?? [], h.held]) for (const [a, b] of rs) for (let f = a; f <= b; f++) out.add(f);
   return out;
 }
 
@@ -180,11 +207,22 @@ export interface PoseSequence {
   camera?: CameraFrame[];
   /** Present once `rig-pose clean` has run on the sequence (#67). */
   cleaned?: CleanRecord;
+  /**
+   * Optional (rig-c/pose#92): the clip's frame of reference. "in-place" — a
+   * gait filmed without the figure travelling (a treadmill or reel walk, a
+   * loop) — is the one value; `clean --loop` writes it, and it may be written
+   * by hand. Absent: the figure's travel in the picture is its travel.
+   */
+  travel?: Travel;
   frames: PoseFrame[];
 }
 
+/** The one value of a sequence's `travel` (rig-c/pose#92). */
+export const TRAVEL_IN_PLACE = 'in-place';
+export type Travel = typeof TRAVEL_IN_PLACE;
+
 const TOP_KEYS = ['spec', 'space', 'width', 'height', 'source', 'frames'];
-const OPTIONAL_KEYS = ['cameraSource', 'camera', 'cleaned'];
+const OPTIONAL_KEYS = ['cameraSource', 'camera', 'cleaned', 'travel'];
 const CAMERA_KEYS = ['s', 'tx', 'ty', 'inliers'];
 
 /**
@@ -269,10 +307,11 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
     if (typeof doc.cameraSource !== 'string' || doc.cameraSource.trim() === '') p.add('POSE_CAMERA_SOURCE', `${where} "cameraSource" is ${typeName(doc.cameraSource)}; it must be a non-empty string saying where the camera came from ("tracked", "hand-labelled, N keys")`);
     else if (!('camera' in doc)) p.add('POSE_CAMERA_SOURCE', `${where} has "cameraSource" ${JSON.stringify(doc.cameraSource)} and no "camera"; it states where a camera came from, so it needs one`);
   }
+  if ('travel' in doc && doc.travel !== TRAVEL_IN_PLACE) p.add('POSE_TRAVEL', `${where} "travel" is ${typeName(doc.travel)}; the one value is "${TRAVEL_IN_PLACE}" (a gait filmed without the figure travelling), and without the key the picture's travel is the figure's`);
   const cleaned = 'cleaned' in doc ? readCleaned(p, where, doc.cleaned, Array.isArray(doc.frames) ? doc.frames.length : null) : undefined;
   p.throwIfAny();
   const cameraSource = typeof doc.cameraSource === 'string' ? doc.cameraSource : undefined;
-  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, ...(cameraSource !== undefined ? { cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), frames };
+  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, ...(cameraSource !== undefined ? { cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), ...(doc.travel === TRAVEL_IN_PLACE ? { travel: TRAVEL_IN_PLACE } : {}), frames };
 }
 
 /** `camera`: one `{ s > 0, tx, ty, inliers ≥ 0 }` per frame, as many as `frames`. */
@@ -477,10 +516,22 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     return;
   }
   const before = p.list.length;
-  const CLASSES = ['read', 'interpolated', 'held'] as const;
-  refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by', 'method', ...CLASSES, 'declined']);
-  for (const k of ['method', ...CLASSES, 'declined']) if (!(k in h)) p.add('POSE_CLEANED', `${hw} has no "${k}"; a measured record is ${measuredShape}`);
+  const REQ_CLASSES = ['read', 'interpolated', 'held'] as const;
+  const ALL_CLASSES = ['read', 'interpolated', 'scaled', 'held', 'unmeasured'] as const;
+  refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by', 'method', 'fit', ...ALL_CLASSES, 'declined']);
+  for (const k of ['method', ...REQ_CLASSES, 'declined']) if (!(k in h)) p.add('POSE_CLEANED', `${hw} has no "${k}"; a measured record is ${measuredShape}`);
   if ('method' in h && !(typeof h.method === 'string' && h.method.trim() !== '')) p.add('POSE_CLEANED', `${hw} "method" is ${typeName(h.method)}; it must be a non-empty string naming the reading`);
+  if ('fit' in h) {
+    const f = h.fit;
+    const fw = `${hw} "fit"`;
+    if (!isObject(f)) p.add('POSE_CLEANED', `${fw} is ${typeName(f)}; it must be { frames, gain, corr }`);
+    else {
+      refuseUnknownKeys(p, 'POSE_CLEANED', fw, f, ['frames', 'gain', 'corr']);
+      if (!(Number.isInteger(f.frames) && (f.frames as number) >= 0)) p.add('POSE_CLEANED', `${fw} "frames" is ${typeName(f.frames)}; it must be a whole number of frames ≥ 0`);
+      if (!(f.gain === null || (typeof f.gain === 'number' && Number.isFinite(f.gain)))) p.add('POSE_CLEANED', `${fw} "gain" is ${typeName(f.gain)}; it must be a finite number or null`);
+      if (!(f.corr === null || (typeof f.corr === 'number' && Number.isFinite(f.corr) && f.corr >= -1 && f.corr <= 1))) p.add('POSE_CLEANED', `${fw} "corr" is ${typeName(f.corr)}; it must be a correlation in [-1, 1] or null`);
+    }
+  }
   const range = `[0, ${frames === null ? 'the frame count' : frames - 1}]`;
   /** A run [first, last], or null after naming what is wrong with it. */
   const run = (v: unknown, rw: string): Run | null => {
@@ -512,8 +563,8 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
       if (cur.r[0] <= prev.r[1]) p.add('POSE_CLEANED', `${cur.w} [${cur.r[0]}, ${cur.r[1]}] starts at or before the end of ${prev.w} [${prev.r[0]}, ${prev.r[1]}]; ${what} runs must increase and not overlap`);
     }
   };
-  const classes: Record<(typeof CLASSES)[number], Named[]> = { read: [], interpolated: [], held: [] };
-  for (const c of CLASSES) {
+  const classes: Record<(typeof ALL_CLASSES)[number], Named[]> = { read: [], interpolated: [], scaled: [], held: [], unmeasured: [] };
+  for (const c of ALL_CLASSES) {
     if (!(c in h)) continue;
     const list = h[c];
     if (!Array.isArray(list)) {
@@ -548,12 +599,15 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     });
     ordered(declined, 'declined');
   }
-  // Across lists: the classes are disjoint, they cover every frame, and declined is exactly interpolated ∪ held.
-  for (let x = 0; x < CLASSES.length; x++) {
-    for (let y = x + 1; y < CLASSES.length; y++) {
-      for (const a of classes[CLASSES[x]!]) {
-        for (const b of classes[CLASSES[y]!]) {
-          if (a.r[0] <= b.r[1] && b.r[0] <= a.r[1]) p.add('POSE_CLEANED', `${a.w} [${a.r[0]}, ${a.r[1]}] and ${b.w} [${b.r[0]}, ${b.r[1]}] share frame(s) ${Math.max(a.r[0], b.r[0])}–${Math.min(a.r[1], b.r[1])}; a frame is one of read, interpolated and held`);
+  const has106 = 'scaled' in h || 'unmeasured' in h || 'fit' in h;
+  const classListLabel = has106 ? 'read, interpolated, scaled, held and unmeasured' : 'read, interpolated and held';
+  const filledLabel = has106 ? 'interpolated, scaled, held or unmeasured' : 'interpolated or held';
+  // Across lists: the classes are disjoint, they cover every frame, and declined is exactly the non-read classes.
+  for (let x = 0; x < ALL_CLASSES.length; x++) {
+    for (let y = x + 1; y < ALL_CLASSES.length; y++) {
+      for (const a of classes[ALL_CLASSES[x]!]) {
+        for (const b of classes[ALL_CLASSES[y]!]) {
+          if (a.r[0] <= b.r[1] && b.r[0] <= a.r[1]) p.add('POSE_CLEANED', `${a.w} [${a.r[0]}, ${a.r[1]}] and ${b.w} [${b.r[0]}, ${b.r[1]}] share frame(s) ${Math.max(a.r[0], b.r[0])}–${Math.min(a.r[1], b.r[1])}; a frame is one of ${classListLabel}`);
         }
       }
     }
@@ -574,18 +628,18 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     return out.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
   };
   const read = set(classes.read);
-  const filled = set([...classes.interpolated, ...classes.held]);
+  const nonRead = set([...classes.interpolated, ...classes.scaled, ...classes.held, ...classes.unmeasured]);
   const dec = set(declined);
   if (frames !== null) {
-    const none = Array.from({ length: frames }, (_, f) => f).filter((f) => !read.has(f) && !filled.has(f));
-    if (none.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(none)} are in none of read, interpolated and held; every frame of the sequence is one of them`);
+    const none = Array.from({ length: frames }, (_, f) => f).filter((f) => !read.has(f) && !nonRead.has(f));
+    if (none.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(none)} are in none of ${classListLabel}; every frame of the sequence is one of them`);
   }
   const both = [...dec].filter((f) => read.has(f)).sort((a, b) => a - b);
   if (both.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(both)} are both read and declined; a frame is read or declined, not both`);
-  const unfilled = [...dec].filter((f) => !read.has(f) && !filled.has(f)).sort((a, b) => a - b);
-  if (unfilled.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(unfilled)} are declined but neither interpolated nor held; a declined frame takes one of them`);
-  const undeclared = [...filled].filter((f) => !dec.has(f)).sort((a, b) => a - b);
-  if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are interpolated or held but not declined; only a frame the reading declined is filled, and "declined" says why`);
+  const unfilled = [...dec].filter((f) => !read.has(f) && !nonRead.has(f)).sort((a, b) => a - b);
+  if (unfilled.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(unfilled)} are declined but neither ${filledLabel}; a declined frame takes one of them`);
+  const undeclared = [...nonRead].filter((f) => !dec.has(f)).sort((a, b) => a - b);
+  if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are ${filledLabel} but not declined; only a frame the reading declined is filled, and "declined" says why`);
 }
 const holdParamsOf = (h: HoldParams | 'off'): HoldParams | 'off' => (h === 'off' ? 'off' : { speed: h.speed, reach: h.reach, minSeconds: h.minSeconds, blend: h.blend });
 const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: h.jitter.before, after: h.jitter.after } });
@@ -786,5 +840,5 @@ export function writePoseSequence(seq: PoseSequence): string {
     ...(c.seams !== undefined ? { seams: c.seams.map((x) => ({ joint: x.joint, frame: x.frame, step: round(x.step, 4), gap: x.gap })) } : {}),
     ...(c.unheld !== undefined ? { unheld: c.unheld.map((u) => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value === null ? null : round(u.value, 4) })) } : {}),
   };
-  return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, ...(seq.cameraSource !== undefined ? { cameraSource: seq.cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), frames }, null, 2)}\n`;
+  return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, ...(seq.cameraSource !== undefined ? { cameraSource: seq.cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), ...(seq.travel !== undefined ? { travel: seq.travel } : {}), frames }, null, 2)}\n`;
 }

package/src/reduce.ts

@@ -18,6 +18,13 @@
  * 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.
  *
+ * Scaled bones (rig-c/pose#94). A `scalex` track is thinned in value space
+ * within `SCALE_REDUCE` (`reduceScale`). A bone under a scaled bone is not
+ * keyed by the formula above but through its parent's posed matrix (legs.ts
+ * `posePath`), so `reduceUnderScale` solves its keys again through its parent
+ * as reduced and reads each error as the world aim, and the world length, it
+ * lands on.
+ *
  * 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
@@ -52,12 +59,13 @@ export interface ReduceHip {
 }
 export interface ReduceRow {
   bone: string;
-  kind: 'angle' | 'origin';
+  /** `scale`: a `scalex` track (#94), its error the bone's world x-axis length against its setup length times the scale asked. */
+  kind: 'angle' | 'origin' | 'scale';
   /** 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. */
+  /** The largest error over all frames: degrees of world aim for a bone, world units for the hip, a fraction of the setup length for a scale. */
   worst: number;
   /** The first frame where it is. */
   frame: number;
@@ -67,6 +75,8 @@ export interface Reduced {
   hip: ReducedKey[] | null;
   /** The bones in the order given, then the hip. */
   rows: ReduceRow[];
+  /** Each bone's world-aim error on every frame (reduced less dense, degrees), as the poser evaluates the reduced keys. */
+  errors: Map<string, number[]>;
 }
 
 // ---------------------------------------------------------------------------
@@ -186,6 +196,11 @@ const r3 = (v: number): number => {
   const r = Math.round(v * 1000) / 1000;
   return Object.is(r, -0) ? 0 : r;
 };
+/** A scale as the retarget writes one (retarget.ts `r6`). */
+const r6 = (v: number): number => {
+  const r = Math.round(v * 1e6) / 1e6;
+  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 {
@@ -194,6 +209,8 @@ interface Fit {
   tolerance: number;
   /** The error at frame `i` of `values` against the target. */
   error: (i: number, values: readonly number[]) => number;
+  /** How a written value is rounded: 0.001 (an angle, a translate) unless given. */
+  round?: (v: number) => number;
 }
 
 /** The frame with the largest error over `frames` (the first, on a tie), or null when there is none. */
@@ -242,7 +259,8 @@ function solveHandles(a: ReducedKey, b: ReducedKey, channel: number, hx1: number
 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 round = fit.round ?? r3;
+  const keyOn = (i: number): ReducedKey => ({ t: times[i]!, v: fit.targets[i]!.map(round) });
   const knots = [...new Set([0, n - 1, ...fit.keep])].sort((x, y) => x - y);
   const curves = new Map<number, number[]>();
   const done: number[] = [];
@@ -266,7 +284,7 @@ function fitTrack(times: readonly number[], samples: readonly number[], fit: Fit
     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 curve = handles.flatMap(([cy1, cy2]) => [hx1, round(cy1), hx2, round(cy2)]);
       const bent = errorWith({ ...a, curve });
       if (bent.worst <= fit.tolerance) {
         curves.set(k0, curve);
@@ -304,8 +322,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
   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 samples = samplesOf(times);
 
   const byName = new Map<string, ReduceBone>();
   for (const b of bones) {
@@ -341,6 +358,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     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 errorsOrdered = new Map(bones.map((b) => [b.bone, errors.get(b.bone)!]));
   const ordered = new Map(bones.map((b) => [b.bone, rotate.get(b.bone)!]));
 
   let hipKeys: ReducedKey[] | null = null;
@@ -357,5 +375,147 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     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 };
+  return { rotate: ordered, hip: hipKeys, rows, errors: errorsOrdered };
+}
+
+/** The times the poser samples a track at: the running sum of the frame steps (verify.ts `poseFrames`). */
+export function samplesOf(times: readonly number[]): number[] {
+  const samples: number[] = [times[0]!];
+  for (let i = 1; i < times.length; i++) samples.push(samples[i - 1]! + (times[i]! - times[i - 1]!));
+  return samples;
+}
+
+// ---------------------------------------------------------------------------
+// scales, and bones keyed through a scaled parent (rig-c/pose#94)
+// ---------------------------------------------------------------------------
+
+/**
+ * The tolerance a reduced `scalex` track is held to: half of the landing
+ * check's scale tolerance (verify.ts `SCALE_TOLERANCE`, 1e-4 of the setup
+ * length), so a reduced curve cannot fail the check it is re-run against.
+ */
+export const SCALE_REDUCE = 5e-5;
+
+/**
+ * One `scalex` track of a bone with no scaled bone above it, reduced: its world
+ * x-axis length over setup is its own scale, so the error is the value's
+ * distance from the scale asked.
+ */
+export function reduceScale(times: readonly number[], bone: string, asked: readonly number[], keep: ReadonlySet<number>, tolerance: number): { keys: ReducedKey[]; at: number[]; row: ReduceRow } {
+  const n = times.length;
+  if (asked.length !== n) throw new Error(`reduce: bone "${bone}" asks ${asked.length} scale(s) for ${n} frame(s)`);
+  const samples = samplesOf(times);
+  const keys = fitTrack(times, samples, { targets: asked.map((v) => [v]), keep: keptFrames(keep, n, `bone "${bone}" scalex`), tolerance, error: (i, v) => Math.abs(v[0]! - asked[i]!), round: r6 });
+  const at = trackAt(keys, samples, 1).map((v) => v[0]!);
+  const worst = worstOf(at.map((_, i) => i), (i) => Math.abs(at[i]! - asked[i]!))!;
+  return { keys, at, row: { bone, kind: 'scale', before: n, after: keys.length, worst: worst.worst, frame: worst.frame } };
+}
+
+/** A world 2×2: columns (a, c) — the x axis — and (b, d) — the y axis (legs.ts `M2`). */
+export type M2 = [number, number, number, number];
+const DEG = 180 / Math.PI;
+const mul = (p: M2, q: M2): M2 => [p[0] * q[0] + p[1] * q[2], p[0] * q[1] + p[1] * q[3], p[2] * q[0] + p[3] * q[2], p[2] * q[1] + p[3] * q[3]];
+const inv = (m: M2): M2 => {
+  const det = m[0] * m[3] - m[1] * m[2];
+  return [m[3] / det, -m[1] / det, -m[2] / det, m[0] / det];
+};
+const apply = (m: M2, v: [number, number]): [number, number] => [m[0] * v[0] + m[1] * v[1], m[2] * v[0] + m[3] * v[1]];
+const rot = (deg: number): M2 => {
+  const r = deg / DEG;
+  return [Math.cos(r), -Math.sin(r), Math.sin(r), Math.cos(r)];
+};
+const scaleX = (s: number): M2 => [s, 0, 0, 1];
+/** A bone's setup local 2×2 in its parent's axes: inv(parent's setup world) · its setup world (legs.ts `posePath`'s L0). */
+export const setupLocal = (parentWorld0: M2, world0: M2): M2 => mul(inv(parentWorld0), world0);
+/** `p · q`. */
+export const mulM2 = mul;
+const IDENTITY: M2 = [1, 0, 0, 1];
+export { IDENTITY as M2_IDENTITY };
+const wrap180 = (d: number): number => {
+  const x = ((d + 180) % 360 + 360) % 360 - 180;
+  return x === -180 ? 180 : x;
+};
+
+/**
+ * A mapped bone under a scaled bone (legs.ts `posePath`: keyed through its
+ * parent's posed matrix), reduced once the bones above it are. Its parent's
+ * world 2×2 is posed from keys already reduced — a bone the key formula holds
+ * for (`rigid`: R(turn) · its setup world · diag(scale, 1), its turn and scale
+ * the reduced ones), or another bone of the same call given before it — times
+ * the setup locals of the unmapped bones between (`via`).
+ */
+export interface UnderBone {
+  bone: string;
+  parent: { rigid: { turn: readonly number[]; world0: M2; scale: readonly number[] }; via: M2 } | { under: string; via: M2 };
+  /** Its setup local 2×2 in its parent's axes: inv(parent's setup world) · its setup world, by rig-c's setup. */
+  local: M2;
+  /** Its setup world x-axis length. */
+  len0: number;
+  /** The world angle its x axis is asked on every frame (degrees), and the scale of it asked (1: none). */
+  target: readonly number[];
+  asked: readonly number[];
+  /** The dense rotate keys (unwrapped, as written). */
+  dense: readonly number[];
+  keep: ReadonlySet<number>;
+}
+
+/**
+ * Each bone under a scaled bone, in the order given (parents first): its
+ * rotate and scalex keys re-solved through its parent's reduced posed matrix
+ * (the key that puts its x axis on the target, and the scale that gives it the
+ * length asked), then reduced — the rotate with its error read as the world aim
+ * it lands on through that matrix, the scale with its error read as the world
+ * length over setup against the scale asked, on the rotate as reduced. Its
+ * world error is its own fit error, as down a chain the key formula holds for.
+ */
+export function reduceUnderScale(times: readonly number[], bones: readonly UnderBone[], tolerance: number, scaleTolerance: number): { rotate: Map<string, ReducedKey[]>; scale: Map<string, ReducedKey[]>; rows: ReduceRow[] } {
+  const n = times.length;
+  const samples = samplesOf(times);
+  const world = new Map<string, M2[]>();
+  const rotate = new Map<string, ReducedKey[]>();
+  const scale = new Map<string, ReducedKey[]>();
+  const rows: ReduceRow[] = [];
+  for (const b of bones) {
+    for (const [what, xs] of [['target', b.target], ['asked', b.asked], ['dense', b.dense]] as const) {
+      if (xs.length !== n) throw new Error(`reduce: bone "${b.bone}" has ${xs.length} ${what} value(s) for ${n} frame(s)`);
+    }
+    const p = b.parent;
+    let parent: M2[];
+    if ('under' in p) {
+      const above = world.get(p.under);
+      if (above === undefined) throw new Error(`reduce: bone "${b.bone}" hangs from bone "${p.under}", which is not given before it`);
+      parent = above.map((m) => mul(m, p.via));
+    } else {
+      parent = Array.from({ length: n }, (_, i) => mul(mul(mul(rot(p.rigid.turn[i]!), p.rigid.world0), scaleX(p.rigid.scale[i]!)), p.via));
+    }
+    const l0: [number, number] = [b.local[0], b.local[2]];
+    const a0 = Math.atan2(l0[1], l0[0]) * DEG;
+    /** The x axis's world vector through the parent on frame i, at rotate key k, before its own scale. */
+    const axis = (i: number, k: number) => apply(parent[i]!, apply(rot(k), l0));
+    // The dense keys re-solved through the reduced parent (posePath's solve).
+    const solved = b.target.map((t, i) => {
+      const v = apply(inv(parent[i]!), [b.asked[i]! * b.len0 * Math.cos(t / DEG), b.asked[i]! * b.len0 * Math.sin(t / DEG)]);
+      const k = Math.atan2(v[1], v[0]) * DEG - a0;
+      return b.dense[i]! + wrap180(k - b.dense[i]!);
+    });
+    const aimError = (i: number, k: number) => {
+      const w = axis(i, k);
+      return Math.abs(wrap180(Math.atan2(w[1], w[0]) * DEG - b.target[i]!));
+    };
+    const keep = keptFrames(b.keep, n, `bone "${b.bone}"`);
+    const rk = fitTrack(times, samples, { targets: solved.map((k) => [k]), keep, tolerance, error: (i, v) => aimError(i, v[0]!) });
+    const kAt = trackAt(rk, samples, 1).map((v) => v[0]!);
+    const ae = worstOf(kAt.map((_, i) => i), (i) => aimError(i, kAt[i]!))!;
+    rows.push({ bone: b.bone, kind: 'angle', before: n, after: rk.length, worst: ae.worst, frame: ae.frame });
+    // The scale that gives it the length asked on the rotate as reduced.
+    const reach = kAt.map((k, i) => Math.hypot(...axis(i, k)) / b.len0);
+    const sk = fitTrack(times, samples, { targets: reach.map((r, i) => [b.asked[i]! / r]), keep, tolerance: scaleTolerance, error: (i, v) => Math.abs(v[0]! * reach[i]! - b.asked[i]!), round: r6 });
+    const sAt = trackAt(sk, samples, 1).map((v) => v[0]!);
+    const se = worstOf(sAt.map((_, i) => i), (i) => Math.abs(sAt[i]! * reach[i]! - b.asked[i]!))!;
+    rows.push({ bone: b.bone, kind: 'scale', before: n, after: sk.length, worst: se.worst, frame: se.frame });
+    world.set(b.bone, parent.map((m, i) => mul(mul(mul(m, rot(kAt[i]!)), b.local), scaleX(sAt[i]!))));
+    rotate.set(b.bone, rk);
+    scale.set(b.bone, sk);
+  }
+  return { rotate, scale, rows };
 }