@rig-c/pose 0.38.0 → 0.40.0

package/src/pose.ts

@@ -26,14 +26,57 @@
  * the version the file records of what wrote it: a file of a minor newer than
  * this reader's is read, and each key it does not know is refused naming the
  * minor the file says it was written as.
+ *
+ * `rig-pose-sequence/1.2` (rig-c/pose#281) adds derived depth: a per-frame
+ * `depth`, one `{ ratio, sign, source }` per limb segment, written by `clean
+ * --depth walk|run` (`source: "derived"`) or by a 3D detector (`"measured"`,
+ * read and never written here). A minor includes the keys of the minors before
+ * it, so a sequence with depth is "/1.2" whether or not it also carries the
+ * pelvis track; one with the track and no depth stays "/1.1".
  */
 import { BODY18, COCO17, COCO17_TO_BODY18, isBody18, type Body18 } from './joints.ts';
 import { isObject, parseJson, Problems, refuseUnknownKeys, refuseUnknownKeys as refuseKeys, typeName } from './problems.ts';
 
 export const POSE_SPEC = 'rig-pose-sequence/1';
-/** The minor with the pelvis track (rig-c/pose#288), and the newest minor this reader reads. */
+/** The minor with the pelvis track (rig-c/pose#288). */
 export const POSE_SPEC_PELVIS = 'rig-pose-sequence/1.1';
-const POSE_MINOR = 1;
+/** The minor with derived depth (rig-c/pose#281), and the newest minor this reader reads. */
+export const POSE_SPEC_DEPTH = 'rig-pose-sequence/1.2';
+const POSE_MINOR = 2;
+/**
+ * The limb segments a frame's `depth` names (rig-c/pose#281), each from its
+ * proximal joint to its distal one: the sign is + when the distal joint is
+ * nearer the camera than the proximal one.
+ */
+export const DEPTH_SEGMENTS = {
+  r_upper_arm: ['r_shoulder', 'r_elbow'],
+  r_forearm: ['r_elbow', 'r_wrist'],
+  r_thigh: ['r_hip', 'r_knee'],
+  r_shin: ['r_knee', 'r_ankle'],
+  l_upper_arm: ['l_shoulder', 'l_elbow'],
+  l_forearm: ['l_elbow', 'l_wrist'],
+  l_thigh: ['l_hip', 'l_knee'],
+  l_shin: ['l_knee', 'l_ankle'],
+} as const satisfies Record<string, readonly [Body18, Body18]>;
+export type DepthSegment = keyof typeof DEPTH_SEGMENTS;
+export const DEPTH_SEGMENT_NAMES = Object.keys(DEPTH_SEGMENTS) as DepthSegment[];
+/** Where a segment's depth came from: read off the picture's 2D lengths (`clean --depth`), or a 3D detector's. */
+export const DEPTH_SOURCES = ['derived', 'measured'] as const;
+export type DepthSource = (typeof DEPTH_SOURCES)[number];
+/**
+ * One segment's depth on one frame (rig-c/pose#281): `ratio` its drawn length ÷
+ * its rest length; `sign` +1 when its distal joint is nearer the camera than its
+ * proximal one, −1 farther, 0 flat (or not decided); `source` as above.
+ */
+export interface SegmentDepth {
+  ratio: number;
+  sign: -1 | 0 | 1;
+  source: DepthSource;
+}
+export type FrameDepth = Partial<Record<DepthSegment, SegmentDepth>>;
+/** The gait `clean --depth` was told the clip is: it decides the sign of a foreshortened shin. */
+export const DEPTH_GAITS = ['walk', 'run'] as const;
+export type DepthGait = (typeof DEPTH_GAITS)[number];
 /**
  * Where a sequence's `pelvisTilt` came from (rig-c/pose#288): `silhouette` — the
  * straight edge of the drawn figure across the hips; `waistband` — the top edge
@@ -72,6 +115,12 @@ export interface PoseFrame {
    * a sequence with a `pelvisSource`, on none of one without.
    */
   pelvisTilt?: number | null;
+  /**
+   * rig-c/pose#281, minor 1.2: each limb segment's depth on this frame (a segment
+   * whose joints are not both placed on the frame is not named). Present on every
+   * frame of a sequence with depth, on none of one without.
+   */
+  depth?: FrameDepth;
 }
 /**
  * The picture's camera on one frame against frame 0's (rig-c/pose#63), as
@@ -207,6 +256,10 @@ export interface CleanUnheld {
 export interface PelvisParams {
   window: number;
 }
+/** rig-c/pose#281: clean derived each frame's `depth` (`source: "derived"`) for this gait. */
+export interface DepthParams {
+  gait: DepthGait;
+}
 export interface CleanRecord {
   spec: typeof CLEAN_SPEC;
   /**
@@ -214,7 +267,7 @@ export interface CleanRecord {
    * `hold` (#91): the stillness hold's figures, or "off"; absent in a record
    * written before #91.
    */
-  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off'; pelvis?: PelvisParams };
+  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off'; pelvis?: PelvisParams; depth?: DepthParams };
   /**
    * `found`: every joint the spike step replaced, by frame (index into `frames`)
    * and joint. `untested`: the frames the spike step did not test, because a
@@ -282,15 +335,20 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
   const frames0 = doc.spec === POSE_SPEC_FRAMES0;
   // rig-c/pose#288: the minor the file says it was written as; a newer one is read, and what it adds is refused naming it.
   const minor = frames0 ? 0 : minorOf(doc.spec);
-  const note = minor !== null && minor > POSE_MINOR ? `; the file says it was written as ${JSON.stringify(doc.spec)}, a newer minor than this reader's "${POSE_SPEC_PELVIS}" — read it with a rig-pose that reads that minor` : '';
+  const note = minor !== null && minor > POSE_MINOR ? `; the file says it was written as ${JSON.stringify(doc.spec)}, a newer minor than this reader's "${POSE_SPEC_DEPTH}" — read it with a rig-pose that reads that minor` : '';
   const pelvisKnown = minor !== null && minor >= 1;
-  /** A 1.1 key in a file that says /1 (or the older name): one line naming the minor, not an unknown key. */
-  const minorKey = (key: string, on: string) => p.add('POSE_SPEC', `${on} carries ${JSON.stringify(key)}, a key of "${POSE_SPEC_PELVIS}", and the file says ${JSON.stringify(doc.spec)}; a sequence carrying the pelvis track is written as "${POSE_SPEC_PELVIS}" (rig-pose pelvis)`);
+  // rig-c/pose#281: depth is minor 2's.
+  const depthKnown = minor !== null && minor >= 2;
+  /** A key of a later minor in a file that says an earlier one: one line naming the minor, not an unknown key. */
+  const minorKey = (key: string, on: string) => (key === 'depth'
+    ? p.add('POSE_SPEC', `${on} carries "depth", a key of "${POSE_SPEC_DEPTH}", and the file says ${JSON.stringify(doc.spec)}; a sequence carrying depth is written as "${POSE_SPEC_DEPTH}" (rig-pose clean --depth)`)
+    : p.add('POSE_SPEC', `${on} carries ${JSON.stringify(key)}, a key of "${POSE_SPEC_PELVIS}", and the file says ${JSON.stringify(doc.spec)}; a sequence carrying the pelvis track is written as "${POSE_SPEC_PELVIS}" (rig-pose pelvis)`));
   const without = (o: Record<string, unknown>, key: string) => (pelvisKnown || !(key in o) ? o : Object.fromEntries(Object.entries(o).filter(([k]) => k !== key)));
+  const withoutDepth = (o: Record<string, unknown>) => (depthKnown || !('depth' in o) ? o : Object.fromEntries(Object.entries(o).filter(([k]) => k !== 'depth')));
   if (!pelvisKnown && 'pelvisSource' in doc) minorKey('pelvisSource', where);
   refuseUnknownKeys(p, 'POSE_KEYS', where, without(doc, 'pelvisSource'), frames0 ? [...TOP_KEYS, ...OPTIONAL_KEYS, 'fps'] : [...TOP_KEYS, ...OPTIONAL_KEYS, ...(pelvisKnown ? ['pelvisSource'] : [])], note);
   for (const k of TOP_KEYS) if (!(k in doc)) p.add('POSE_KEYS', `${where} has no "${k}"; a ${POSE_SPEC} document carries ${TOP_KEYS.join(', ')}`);
-  if ('spec' in doc && minor === null) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}" and its minors ("${POSE_SPEC_PELVIS}"; a newer minor is read, and a key it adds is refused naming it), and the older name "${POSE_SPEC_FRAMES0}"`);
+  if ('spec' in doc && minor === null) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}" and its minors ("${POSE_SPEC_PELVIS}", "${POSE_SPEC_DEPTH}"; a newer minor is read, and a key it adds is refused naming it), and the older name "${POSE_SPEC_FRAMES0}"`);
   const space = frames0 ? FRAMES0_SPACE : POSE_SPACE;
   if ('space' in doc && JSON.stringify(doc.space) !== JSON.stringify(space)) {
     p.add('POSE_SPACE', `${where} "space" is ${JSON.stringify(doc.space)}; for "${frames0 ? POSE_SPEC_FRAMES0 : POSE_SPEC}" it must be exactly ${JSON.stringify(space)}`);
@@ -307,6 +365,7 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
     } else {
       let lastT = -Infinity;
       const minorFrames: number[] = [];
+      const depthFrames: number[] = [];
       doc.frames.forEach((f: unknown, i: number) => {
         const fw = `${where} frames[${i}]`;
         if (!isObject(f)) {
@@ -314,7 +373,9 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
           return;
         }
         if (!pelvisKnown && 'pelvisTilt' in f) minorFrames.push(i);
-        refuseUnknownKeys(p, 'POSE_KEYS', fw, without(f, 'pelvisTilt'), pelvisKnown ? ['t', 'people', 'pelvisTilt'] : ['t', 'people'], note);
+        if (!depthKnown && 'depth' in f) depthFrames.push(i);
+        refuseUnknownKeys(p, 'POSE_KEYS', fw, withoutDepth(without(f, 'pelvisTilt')), [...(pelvisKnown ? ['t', 'people', 'pelvisTilt'] : ['t', 'people']), ...(depthKnown ? ['depth'] : [])], note);
+        const depth = depthKnown && 'depth' in f ? readDepth(p, fw, f.depth) : undefined;
         let pelvisTilt: number | null | undefined;
         if (pelvisKnown && 'pelvisTilt' in f) {
           const v = f.pelvisTilt;
@@ -349,9 +410,11 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
             people.push({ id: person.id, joints: readJoints(p, pw, person.joints, note) });
           });
         }
-        frames.push({ t: typeof t === 'number' ? t : NaN, people, ...(pelvisTilt !== undefined ? { pelvisTilt } : {}) });
+        frames.push({ t: typeof t === 'number' ? t : NaN, people, ...(pelvisTilt !== undefined ? { pelvisTilt } : {}), ...(depth !== undefined ? { depth } : {}) });
       });
-      if (minorFrames.length > 0) minorKey('pelvisTilt', `${where} ${minorFrames.length === 1 ? `frames[${minorFrames[0]}]` : `${minorFrames.length} frames (${minorFrames[0]}–${minorFrames[minorFrames.length - 1]})`}`);
+      const framesText = (fs: number[]) => `${where} ${fs.length === 1 ? `frames[${fs[0]}]` : `${fs.length} frames (${fs[0]}–${fs[fs.length - 1]})`}`;
+      if (minorFrames.length > 0) minorKey('pelvisTilt', framesText(minorFrames));
+      if (depthFrames.length > 0) minorKey('depth', framesText(depthFrames));
     }
   }
   let pelvisSource: PelvisSource | undefined;
@@ -369,13 +432,30 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
       if (ids.length > 1) p.add('POSE_PELVIS', `${where} carries a pelvis track and ${ids.length} people (${ids.join(', ')}); the track is one figure's, so the sequence holds one person (rig-pose pelvis --person writes only that one)`);
     }
   }
+  if (depthKnown && Array.isArray(doc.frames)) {
+    const carry = doc.frames.map((f: unknown) => isObject(f) && 'depth' in f);
+    const lacking = carry.flatMap((c: boolean, i: number) => (c ? [] : [i]));
+    if (lacking.length > 0 && lacking.length < carry.length) p.add('POSE_DEPTH', `${where} has "depth" on ${carry.length - lacking.length} frame(s) and none on frame(s) ${spansText(lacking)}; a sequence with depth carries it on every frame (an empty object where no segment is placed)`);
+    if (lacking.length < carry.length) {
+      const ids = [...new Set(frames.flatMap((f) => f.people.map((q) => q.id)))].sort();
+      if (ids.length > 1) p.add('POSE_DEPTH', `${where} carries depth and ${ids.length} people (${ids.join(', ')}); the depth is one figure's, so the sequence holds one person (rig-pose clean writes only the one it cleaned)`);
+    }
+  }
   const camera = 'camera' in doc ? readCamera(p, where, doc.camera, Array.isArray(doc.frames) ? doc.frames.length : null, note) : undefined;
   if ('cameraSource' in doc) {
     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, pelvisKnown, note) : undefined;
+  const cleaned = 'cleaned' in doc ? readCleaned(p, where, doc.cleaned, Array.isArray(doc.frames) ? doc.frames.length : null, pelvisKnown, note, depthKnown) : undefined;
+  if (depthKnown) {
+    // rig-c/pose#281: "derived" depth is clean's, and clean records the gait it read it for; "measured" is a 3D detector's.
+    const sources = new Set(frames.flatMap((f) => Object.values(f.depth ?? {}).map((d) => d.source)));
+    const recorded = isObject(doc.cleaned) && isObject(doc.cleaned.params) && 'depth' in doc.cleaned.params;
+    if (sources.size > 1) p.add('POSE_DEPTH', `${where} carries "derived" and "measured" depth together; a sequence's depth comes from one source — clean --depth derives it, a 3D detector measures it`);
+    else if (sources.has('derived') && !recorded) p.add('POSE_DEPTH', `${where} carries "derived" depth and ${'cleaned' in doc ? 'its "cleaned" record has no "params" "depth"' : 'no "cleaned" record'}; derived depth is written by rig-pose clean --depth walk|run, which records the gait it was read for`);
+    if (recorded && cleaned !== undefined && frames.some((f) => f.depth === undefined || Object.values(f.depth).some((d) => d.source !== 'derived'))) p.add('POSE_DEPTH', `${where} "cleaned" "params" has "depth" and the frames do not all carry derived depth; the record says clean derived it on every frame`);
+  }
   if (cleaned !== undefined && pelvisKnown) {
     const hasPelvis = isObject(doc.cleaned) && isObject(doc.cleaned.params) && 'pelvis' in doc.cleaned.params;
     if ('pelvisSource' in doc && !hasPelvis) p.add('POSE_PELVIS', `${where} carries a pelvis track and its "cleaned" record has no "params" "pelvis"; clean smooths the track and records it, so the track was added after clean — run rig-pose pelvis before rig-pose clean`);
@@ -386,6 +466,47 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
   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 } : {}), ...(pelvisSource !== undefined ? { pelvisSource } : {}), frames };
 }
 
+/** rig-c/pose#281: a frame's `depth` — `{ "<segment>": { ratio, sign, source } }`, every part refused by name. */
+function readDepth(p: Problems, fw: string, d: unknown): FrameDepth | undefined {
+  const dw = `${fw} "depth"`;
+  if (!isObject(d)) {
+    p.add('POSE_DEPTH', `${dw} is ${typeName(d)}; it must be an object keyed by limb segment (${DEPTH_SEGMENT_NAMES.join(', ')}), each { ratio, sign, source }`);
+    return undefined;
+  }
+  const out: FrameDepth = {};
+  for (const [name, v] of Object.entries(d)) {
+    const sw = `${dw} "${name}"`;
+    if (!(DEPTH_SEGMENT_NAMES as readonly string[]).includes(name)) {
+      p.add('POSE_DEPTH', `${dw} names ${JSON.stringify(name)}; the segments are ${DEPTH_SEGMENT_NAMES.join(', ')}`);
+      continue;
+    }
+    if (!isObject(v)) {
+      p.add('POSE_DEPTH', `${sw} is ${typeName(v)}; it must be { ratio, sign, source }`);
+      continue;
+    }
+    refuseUnknownKeys(p, 'POSE_DEPTH', sw, v, ['ratio', 'sign', 'source']);
+    let ok = true;
+    for (const k of ['ratio', 'sign', 'source']) if (!(k in v)) {
+      p.add('POSE_DEPTH', `${sw} has no "${k}"; a segment's depth is { ratio, sign, source }`);
+      ok = false;
+    }
+    if ('ratio' in v && !(typeof v.ratio === 'number' && Number.isFinite(v.ratio) && v.ratio >= 0)) {
+      p.add('POSE_DEPTH', `${sw} "ratio" is ${typeName(v.ratio)}; it must be a finite number ≥ 0 (the segment's drawn length ÷ its rest length)`);
+      ok = false;
+    }
+    if ('sign' in v && v.sign !== -1 && v.sign !== 0 && v.sign !== 1) {
+      p.add('POSE_DEPTH', `${sw} "sign" is ${typeName(v.sign)}; it must be 1 (the distal joint nearer the camera), -1 (farther) or 0 (flat, or not decided)`);
+      ok = false;
+    }
+    if ('source' in v && !(typeof v.source === 'string' && (DEPTH_SOURCES as readonly string[]).includes(v.source))) {
+      p.add('POSE_DEPTH', `${sw} "source" is ${typeName(v.source)}; it must be "derived" (clean --depth, from the picture's lengths) or "measured" (a 3D detector)`);
+      ok = false;
+    }
+    if (ok) out[name as DepthSegment] = { ratio: v.ratio as number, sign: v.sign as -1 | 0 | 1, source: v.source as DepthSource };
+  }
+  return out;
+}
+
 /** The minor a sequence's spec names: 0 for "rig-pose-sequence/1", N for "rig-pose-sequence/1.N"; null for anything else. */
 function minorOf(spec: unknown): number | null {
   if (spec === POSE_SPEC) return 0;
@@ -443,7 +564,7 @@ function readCamera(p: Problems, where: string, camera: unknown, frames: number
 }
 
 /** `cleaned`: { spec, params: { loop, legs, rest, hipsInferred?, hold? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after }, holds?, unheld?, seams? }. */
-function readCleaned(p: Problems, where: string, c: unknown, frames: number | null, pelvisKnown: boolean, note: string): CleanRecord | undefined {
+function readCleaned(p: Problems, where: string, c: unknown, frames: number | null, pelvisKnown: boolean, note: string, depthKnown: boolean): CleanRecord | undefined {
   const refuseUnknownKeys = (q: Problems, code: string, w: string, o: Record<string, unknown>, known: readonly string[]) => refuseKeys(q, code, w, o, known, note);
   const cw = `${where} "cleaned"`;
   const shape = '{ spec, params: { loop, legs, rest, hipsInferred?, hold? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after }, holds?, unheld?, seams? }';
@@ -460,7 +581,16 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
     const q = c.params;
     if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest, hipsInferred?, hold? }`);
     else {
-      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest', 'hipsInferred', 'hold', ...(pelvisKnown ? ['pelvis'] : [])]);
+      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest', 'hipsInferred', 'hold', ...(pelvisKnown ? ['pelvis'] : []), ...(depthKnown ? ['depth'] : [])]);
+      if (depthKnown && 'depth' in q) {
+        const v = q.depth;
+        const vw = `${cw} "params" "depth"`;
+        if (!isObject(v)) p.add('POSE_CLEANED', `${vw} is ${typeName(v)}; it must be { gait } (rig-c/pose#281: the gait clean --depth read the depth for)`);
+        else {
+          refuseUnknownKeys(p, 'POSE_CLEANED', vw, v, ['gait']);
+          if (!(typeof v.gait === 'string' && (DEPTH_GAITS as readonly string[]).includes(v.gait))) p.add('POSE_CLEANED', `${vw} "gait" is ${typeName(v.gait)}; it must be ${DEPTH_GAITS.map((g) => `"${g}"`).join(' or ')}`);
+        }
+      }
       if (pelvisKnown && 'pelvis' in q) {
         const v = q.pelvis;
         const vw = `${cw} "params" "pelvis"`;
@@ -589,11 +719,11 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
     });
   }
   if (p.list.length > before) return undefined;
-  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off'; pelvis?: PelvisParams };
+  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off'; pelvis?: PelvisParams; depth?: DepthParams };
   const j = c.jitter as { before: number | null; after: number | null };
   return {
     spec: CLEAN_SPEC,
-    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(q.hipsInferred) } : {}), ...(q.hold !== undefined ? { hold: holdParamsOf(q.hold) } : {}), ...(pelvisKnown && q.pelvis !== undefined ? { pelvis: { window: q.pelvis.window } } : {}) },
+    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(q.hipsInferred) } : {}), ...(q.hold !== undefined ? { hold: holdParamsOf(q.hold) } : {}), ...(pelvisKnown && q.pelvis !== undefined ? { pelvis: { window: q.pelvis.window } } : {}), ...(depthKnown && q.depth !== undefined ? { depth: { gait: q.depth.gait } } : {}) },
     spikes: {
       found: ((c.spikes as { found: Array<{ frame: number; joint: Body18 }> }).found).map((s) => ({ frame: s.frame, joint: s.joint })),
       untested: [...(c.spikes as { untested: number[] }).untested],
@@ -922,6 +1052,8 @@ export function writePoseSequence(seq: PoseSequence): string {
   const frames = seq.frames.map((f) => ({
     t: f.t,
     ...(f.pelvisTilt !== undefined ? { pelvisTilt: f.pelvisTilt === null ? null : round(f.pelvisTilt, 3) } : {}),
+    // rig-c/pose#281: the segments in DEPTH_SEGMENTS' order, each { ratio, sign, source }.
+    ...(f.depth !== undefined ? { depth: Object.fromEntries(DEPTH_SEGMENT_NAMES.filter((k) => f.depth![k] !== undefined).map((k) => [k, { ratio: round(f.depth![k]!.ratio, 3), sign: f.depth![k]!.sign, source: f.depth![k]!.source }])) } : {}),
     people: f.people.map((q) => ({
       id: q.id,
       joints: Object.fromEntries(
@@ -941,14 +1073,14 @@ export function writePoseSequence(seq: PoseSequence): string {
   const jit = (v: number | null) => (v === null ? null : round(v, 4));
   const cleaned = c === undefined ? undefined : {
     spec: c.spec,
-    params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(c.params.hipsInferred) } : {}), ...(c.params.hold !== undefined ? { hold: holdParamsOf(c.params.hold) } : {}), ...(c.params.pelvis !== undefined ? { pelvis: { window: c.params.pelvis.window } } : {}) },
+    params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(c.params.hipsInferred) } : {}), ...(c.params.hold !== undefined ? { hold: holdParamsOf(c.params.hold) } : {}), ...(c.params.pelvis !== undefined ? { pelvis: { window: c.params.pelvis.window } } : {}), ...(c.params.depth !== undefined ? { depth: { gait: c.params.depth.gait } } : {}) },
     spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] },
     jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) },
     ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], ...(h.excursion !== undefined ? { excursion: [h.excursion[0], h.excursion[1]] } : {}), jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
     ...(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) })) } : {}),
   };
-  // rig-c/pose#288: the minor the content needs — /1.1 with a pelvis track, /1 otherwise.
-  const spec = seq.pelvisSource !== undefined ? POSE_SPEC_PELVIS : seq.spec;
+  // rig-c/pose#288, #281: the minor the content needs — /1.2 with depth (it includes 1.1's keys), /1.1 with a pelvis track, /1 otherwise.
+  const spec = seq.frames.some((f) => f.depth !== undefined) ? POSE_SPEC_DEPTH : seq.pelvisSource !== undefined ? POSE_SPEC_PELVIS : seq.spec;
   return `${JSON.stringify({ 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 } : {}), ...(seq.pelvisSource !== undefined ? { pelvisSource: seq.pelvisSource } : {}), frames }, null, 2)}\n`;
 }

package/src/reduce.ts

@@ -48,6 +48,8 @@ export interface ReduceBone {
   dense: number[];
   /** Frame indices that must keep a key regardless (the first and last always do). */
   keep: ReadonlySet<number>;
+  /** Its own world-aim tolerance in degrees, in place of the call's (rig-c/pose#283: its chain's). */
+  tolerance?: number;
 }
 export interface ReduceHip {
   bone: string;
@@ -328,6 +330,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
   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.tolerance !== undefined && !(Number.isFinite(b.tolerance) && b.tolerance > 0)) throw new Error(`reduce: bone "${b.bone}"'s tolerance is ${b.tolerance}°, not a positive number`);
     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);
   }
@@ -349,7 +352,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     const keys = fitTrack(times, samples, {
       targets,
       keep: keptFrames(b.keep, n, `bone "${b.bone}"`),
-      tolerance,
+      tolerance: b.tolerance ?? 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]!);
@@ -617,11 +620,12 @@ export function smoothTrunk(
   if (n < 4 || trunkBones.size === 0) return;
   const samples = samplesOf(times);
   const byName = new Map(bones.map((b) => [b.bone, b]));
+  /** rig-c/pose#283: a bone's own tolerance (its chain's under a per-chain --reduce), else the call's. */
+  const tolOf = (b: string): number => byName.get(b)?.tolerance ?? tolerance;
   const roots = [...trunkBones].filter((b) => {
     const info = byName.get(b);
     return info !== undefined && (info.above === null || !trunkBones.has(info.above));
   });
-  const tolInner = 0.985 * tolerance;
 
   for (const root of roots) {
     const rootKeys = out.rotate.get(root);
@@ -646,8 +650,10 @@ export function smoothTrunk(
     const targetRoot = rootInfo.dense.map((d, i) => d - eAboveRoot[i]!);
     const yRootOld = yOldOf.get(root)!;
 
-    const rootLb = targetRoot.map((t) => t - tolInner);
-    const rootUb = targetRoot.map((t) => t + tolInner);
+    // #283: each bone's own tolerance (its chain's under a per-chain --reduce; the call's otherwise).
+    const rootInner = 0.985 * tolOf(root);
+    const rootLb = targetRoot.map((t) => t - rootInner);
+    const rootUb = targetRoot.map((t) => t + rootInner);
     let smRoot = optimizeBasis(basisOf.get(root)!, rootLb, rootUb);
     let eRoot = smRoot.y.map((v, i) => v - targetRoot[i]!);
 
@@ -667,14 +673,15 @@ export function smoothTrunk(
       for (const h of headBones) {
         const dH = byName.get(h)!.dense;
         const targetH = dH.map((d, i) => d - eRoot[i]!);
-        const smH = optimizeBasis(basisOf.get(h)!, targetH.map((t) => t - tolInner), targetH.map((t) => t + tolInner));
+        const hInner = 0.985 * tolOf(h);
+        const smH = optimizeBasis(basisOf.get(h)!, targetH.map((t) => t - hInner), targetH.map((t) => t + hInner));
         smSub.set(h, smH);
         eSub.set(h, smH.y.map((v, i) => v - targetH[i]!));
       }
       for (const b0 of arm0Bones) {
         const yOld = yOldOf.get(b0)!;
         const wOld = Math.max(...out.errors.get(b0)!.map(Math.abs));
-        const cap = Math.min(0.98 * tolerance, wOld + 0.035 * tolerance);
+        const cap = Math.min(0.98 * tolOf(b0), wOld + 0.035 * tolOf(b0));
         const targetB = byName.get(b0)!.dense.map((d, i) => d - eRoot[i]!);
         const smB = solveLimbPreservingJitter(basisOf.get(b0)!, yOld, targetB.map((t) => t - cap), targetB.map((t) => t + cap));
         smSub.set(b0, smB);
@@ -685,7 +692,7 @@ export function smoothTrunk(
         const eUp = eSub.get(up)!;
         const yOld = yOldOf.get(b1)!;
         const wOld = Math.max(...out.errors.get(b1)!.map(Math.abs));
-        const cap = Math.min(0.98 * tolerance, wOld + 0.035 * tolerance);
+        const cap = Math.min(0.98 * tolOf(b1), wOld + 0.035 * tolOf(b1));
         const targetB = byName.get(b1)!.dense.map((d, i) => d - eUp[i]!);
         const smB = solveLimbPreservingJitter(basisOf.get(b1)!, yOld, targetB.map((t) => t - cap), targetB.map((t) => t + cap));
         smSub.set(b1, smB);
@@ -699,17 +706,17 @@ export function smoothTrunk(
       for (let i = 0; i < n; i++) {
         for (const h of headBones) {
           const eh = eSub.get(h)![i]!;
-          if (Math.abs(eh) > 0.99 * tolerance) {
-            tightenAround(i, Math.abs(eh) - 0.975 * tolerance);
+          if (Math.abs(eh) > 0.99 * tolOf(h)) {
+            tightenAround(i, Math.abs(eh) - 0.975 * tolOf(h));
             anyTightened = true;
           }
         }
         for (const b of [...arm0Bones, ...arm1Bones]) {
           const wOld = Math.max(...out.errors.get(b)!.map(Math.abs));
-          const cap = Math.min(0.985 * tolerance, wOld + 0.04 * tolerance);
+          const cap = Math.min(0.985 * tolOf(b), wOld + 0.04 * tolOf(b));
           const eb = eSub.get(b)![i]!;
           if (Math.abs(eb) > cap) {
-            tightenAround(i, Math.abs(eb) - (cap - 0.01 * tolerance));
+            tightenAround(i, Math.abs(eb) - (cap - 0.01 * tolOf(b)));
             anyTightened = true;
           }
         }
@@ -827,6 +834,8 @@ export interface UnderBone {
   /** The dense rotate keys (unwrapped, as written). */
   dense: readonly number[];
   keep: ReadonlySet<number>;
+  /** Its own world-aim tolerance in degrees, in place of the call's (rig-c/pose#283). */
+  tolerance?: number;
 }
 
 /**
@@ -879,7 +888,7 @@ export function reduceUnderScale(times: readonly number[], bones: readonly Under
       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 rk = fitTrack(times, samples, { targets: solved.map((k) => [k]), keep, tolerance: b.tolerance ?? 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 });

package/src/retarget.ts

@@ -79,7 +79,7 @@ import { aimAngle, aimEnds, bodyYawSets, descends, faceYawSets, knownSetsOf, par
 import type { Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SetRuns, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, phaseGroupProblems, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, LegSegmentRatio, PathPose, Posing, Side, Stance } from './legs.ts';
 import { figureScaleOf, freeAnkleShiftOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, shiftOver, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
@@ -369,6 +369,34 @@ export interface ReachReading {
   ratio: number | null;
 }
 
+/**
+ * rig-c/pose#282: where a `reach` chain's bone starts against the source joint
+ * it re-aims from. The pose's pair starts at the translated joint, which the
+ * rig puts at the translated bone's posed origin; the reach aims from its own
+ * bone's posed origin. The distance between the two, at setup and on the
+ * frames, is the lever #236 names — a reading, with a WARN past
+ * `REACH_ORIGIN_WARN` of the segment. One per reach chain, in map order.
+ */
+export interface ReachOrigin {
+  chain: string;
+  bone: string;
+  /** The pair: the chain's first joint (the translated joint) and its second. */
+  joints: [string, string];
+  /** The translated bone, whose posed origin is where the rig puts the source joint. */
+  anchor: string;
+  /** The distance at setup, world units. */
+  setup: number;
+  /** The largest distance as posed on the frames, world units, and its frame. */
+  posed: { max: number; frame: number };
+  /** The reached length: the pair's median picture length, scaled (world units). */
+  segment: number;
+  /** max(setup, posed.max) ÷ segment. */
+  ofSegment: number;
+  /** ofSegment > threshold. */
+  warn: boolean;
+  threshold: number;
+}
+
 /**
  * Mean |second difference| of a series of angles, degrees: |wrap(v[i+1] − v[i])
  * − wrap(v[i] − v[i−1])| over every i whose three frames `ok` admits (every
@@ -419,6 +447,8 @@ export interface Retarget {
   scaleFit: ScaleFit | null;
   /** The spans each alternate set shows, with their art turn. */
   switches: Switch[];
+  /** rig-c/pose#279: per set without a `phase`, the runs it was nearest on and the runs the minimum span suppressed. */
+  switchRuns: SetRuns[];
   /** Per switched or hidden slot, what it shows on each frame (null: nothing). */
   shown: Map<string, Array<string | null>>;
   /** Per set, its distance to the pose on each frame, degrees. */
@@ -475,6 +505,8 @@ export interface Retarget {
   nodSkipped: NodSkipped | null;
   /** Each `reach` chain hanging below a bone the animation turns or translates (#236): its aim's departure from the pose pair's angle. */
   reach: ReachReading[];
+  /** rig-c/pose#282: each `reach` chain's origin against the source joint it re-aims from; empty when the map has none. */
+  reachOrigin: ReachOrigin[];
   /** rig-c/pose#288: the pelvis bone's source; null when the map has no pelvis chain and the sequence no track. */
   pelvis: PelvisReading | null;
 }
@@ -1486,6 +1518,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const reaches = map.chains.filter((c) => c.reach).sort((x, y) => depth(x.bones[0]!) - depth(y.bones[0]!));
   let aimReach: ((c: Chain) => void) | null = null;
   const reachAims = new Map<string, { aim: number[]; pair: number[]; length: number }>();
+  /** #282: per reach chain, the distance from its bone's posed origin to the anchor's on each frame (the last aim's). */
+  const reachGaps = new Map<string, number[]>();
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
@@ -1494,8 +1528,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const anchor = series.get(c.joints[0]!)!;
       const end = series.get(c.joints[1]!)!;
       const angles: number[] = [];
+      const gaps: number[] = [];
       for (let i = 0; i < n; i++) {
         const o = posedOrigin(b, i);
+        gaps.push(Math.hypot(o[0] - (tb.worldX + travel[i]![0]), o[1] - (tb.worldY + travel[i]![1])));
         const tx = tb.worldX + travel[i]![0] + (end[i]![0] - anchor[i]![0]) * s;
         const ty = tb.worldY + travel[i]![1] - (end[i]![1] - anchor[i]![1]) * s;
         const d = Math.hypot(tx - o[0], ty - o[1]);
@@ -1503,6 +1539,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
       fillLeading(angles, () => p.add('POSE_SEGMENT_ZERO', `chain "${c.name}" — bone "${b}" reaches for ${c.joints[1]}, which the pose puts on the bone's posed origin on every frame; it has no direction`));
       targets.set(b, angles);
+      reachGaps.set(c.name, gaps);
       // #236: the aim as reached, before its own range clamp, beside the pair's own angle (a reading).
       reachAims.set(c.name, { aim: [...angles], pair: Array.from({ length: n }, (_, i) => pictureAngle(anchor[i]!, end[i]!)), length: median(Array.from({ length: n }, (_, i) => Math.hypot(end[i]![0] - anchor[i]![0], end[i]![1] - anchor[i]![1]) * s)) });
     };
@@ -3087,6 +3124,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   if (headNodTrack !== null) tracks.push(headNodTrack);
   tracks.push(...sw.offsetTracks, ...sw.slotTracks);
   const reach = reachReadings(rest, map, tracks, reachAims, t?.bone ?? null);
+  const reachOrigin = reachOrigins(rest, map, reachAims, reachGaps, t?.bone ?? null);
 
   const pivot = pivotOf(rest, t?.bone ?? null, legs);
   const pelvis = pelvisReadingOf(pelvisChain, opts.pelvis, track, fromTrack, tracks);
@@ -3099,8 +3137,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   return {
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale, scaleFit,
-    switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, segments, legStraight, rigLeg, scales, feet, planted: plantOn, stance, floor, blendHold, closure, openDrift, ankles, pivot, raised, byHip, face, body, figureScale, headNod: headNodReading, nodSkipped, reach, pelvis,
+    switches: sw.switches, switchRuns: sw.runs, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
+    legScale, segments, legStraight, rigLeg, scales, feet, planted: plantOn, stance, floor, blendHold, closure, openDrift, ankles, pivot, raised, byHip, face, body, figureScale, headNod: headNodReading, nodSkipped, reach, reachOrigin, pelvis,
   };
 }
 
@@ -3209,6 +3247,47 @@ function reachReadings(rest: Rest, map: JointMap, tracks: ReadonlyArray<MotionTr
   return out;
 }
 
+/**
+ * #282: a reach bone whose origin sits more than this fraction of the segment
+ * from the source joint is warned. The aim from an origin a fraction f up the
+ * pair turns about 1 ÷ (1 − f) times the pair's turn (#236's lever: the example
+ * wave's trunk, f = 0.5, measured 2.00×); 0.2 is 1.25×, a quarter more turn
+ * than the pose has.
+ */
+export const REACH_ORIGIN_WARN = 0.2;
+
+/** #282: each reach chain's origin against the anchor's, at setup and as posed, in map order. */
+function reachOrigins(rest: Rest, map: JointMap, aims: ReadonlyMap<string, { length: number }>, gaps: ReadonlyMap<string, number[]>, anchor: string | null): ReachOrigin[] {
+  const out: ReachOrigin[] = [];
+  if (anchor === null) return out;
+  const a0 = rest.get(anchor)!;
+  for (const c of map.chains) {
+    const got = aims.get(c.name);
+    const g = gaps.get(c.name);
+    if (!c.reach || got === undefined || g === undefined) continue;
+    const b = c.bones[0]!;
+    const bo = rest.get(b)!;
+    const setup = r3(Math.hypot(bo.worldX - a0.worldX, bo.worldY - a0.worldY));
+    let frame = 0;
+    for (let i = 1; i < g.length; i++) if (g[i]! > g[frame]!) frame = i;
+    const max = r3(g[frame] ?? 0);
+    const segment = r3(got.length);
+    const ofSegment = got.length > 0 ? r3(Math.max(setup, max) / got.length) : 0;
+    out.push({ chain: c.name, bone: b, joints: [c.joints[0]!, c.joints[1]!], anchor, setup, posed: { max, frame }, segment, ofSegment, warn: ofSegment > REACH_ORIGIN_WARN, threshold: REACH_ORIGIN_WARN });
+  }
+  return out;
+}
+
+/** #282: the `REACH-ORIGIN` line, one per reach chain. */
+export function reachOriginLine(e: ReachOrigin, times: readonly number[]): string {
+  return `chain "${e.chain}" bone "${e.bone}" (${e.joints[0]} → ${e.joints[1]}): its origin ${e.setup.toFixed(2)} units from the source joint ${e.joints[0]} (bone "${e.anchor}"'s origin) at setup, up to ${e.posed.max.toFixed(2)} on the frames (frame ${e.posed.frame}, t=${times[e.posed.frame]!.toFixed(3)}s): ${e.ofSegment.toFixed(3)} of the ${e.segment.toFixed(2)}-unit segment`;
+}
+
+/** #282: the WARN of a reach chain whose origin sits past REACH_ORIGIN_WARN of the segment. */
+export function reachOriginWarn(e: ReachOrigin): string {
+  return `REACH_ORIGIN: chain "${e.chain}" bone "${e.bone}" starts ${e.ofSegment.toFixed(3)} of the segment from ${e.joints[0]}, past ${e.threshold.toFixed(2)}: re-aimed from there, it turns more than the pair (JITTER bone "${e.bone}"); "reach": false follows the measured angle`;
+}
+
 /** The `REACH` line of a reach chain whose aim departs from its pair (#236). */
 export function reachCostLine(e: ReachReading, times: readonly number[]): string {
   const f = (v: number | null) => (v === null ? 'not measured' : `${v.toFixed(4)}°/f²`);