@rig-c/pose 0.38.0 → 0.39.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/run.ts

@@ -10,6 +10,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
 import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, cleanSummaryLine, inferredSource } from './clean.ts';
+import { depthLine, layersOf, type FrameLayers } from './depth.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
@@ -18,11 +19,12 @@ import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, rea
 import { partsPath, projectSeams, readSeamDoc, readSeamPairs, seamLines, type SeamPair } from './seams.ts';
 import { artRangeLine, chainsMoving, phaseLines, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
 import { jitterLine, landed, type FeetReading, type JitterRow, type Landing, measureFeet, measureJitter, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
-import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
+import { FRONTAL_DISAGREE, legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, smoothTrunk, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
-import type { BlendHold, Closure, Floor, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import type { BlendHold, Closure, Feet, Floor, FreeAnkleShift, LegScale, LegSegmentRatio, Lowered, Side, Stance, SupportScaleRun, SupportSignal } from './legs.ts';
 import { reportRenderDomain, writeReport, type ReportInput } from './report.ts';
 import { PROVENANCE_FILE, provenanceText } from './provenance.ts';
+import { madeLine, planOutDirs } from './outdir.ts';
 import { bodyLine, faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -104,15 +106,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const report = a.report ?? defaultReportPath(a.out);
   // A file this run writes goes into a directory the user named: one that is not there yet is made
   // after the run is green (one line says so), as --build and --render make theirs; a file in the way is refused.
-  const makeDirs = new Map<string, string[]>();
-  for (const [flag, path] of [['--out', a.out], ['--report', report], ['--camera', a.camera]] as const) {
-    if (path === undefined) continue;
-    const dir = dirname(path);
-    let up = dir;
-    while (!existsSync(up) && dirname(up) !== up) up = dirname(up);
-    if (!statSync(up).isDirectory()) args.add('ARG_PATH', up === dir ? `${flag} ${path} — ${dir} is not a directory` : `${flag} ${path} — ${up} is a file, so directory ${dir} cannot be made under it`);
-    else if (up !== dir) makeDirs.set(dir, [...(makeDirs.get(dir) ?? []), `${flag} ${path}`]);
-  }
+  const makeDirs = planOutDirs([['--out', a.out], ['--report', report], ['--camera', a.camera]], args);
+  // #284: --build and --render make their own directories (rigc, the copy); a file in the way is refused here, up front.
+  planOutDirs([['--build', a.build], ['--render', a.render]], args);
   if (a.reference !== undefined && a.build === undefined) args.add('ARG_REFERENCE', `--reference ${a.reference} needs --build: the record it goes in is written beside the build (${PROVENANCE_FILE})`);
   args.throwIfAny();
   const input = resolveRig(a.rig, a.baseMotion);
@@ -207,9 +203,14 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const e of r.byHip) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.reach) say(`  REACH  ${reachCostLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
-    for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times, r.feet?.legLength ?? null, r.rigLeg)}`);
+    // #287: a range that clamps no frame says so once, on the last segment's line (the line count stays one per segment).
+    const noClamp = legScaleNoClamp(r.legScale);
+    r.legScale.forEach((l, k) => say(`  LEG-SCALE ${legScaleLine(l, r.times, r.feet?.legLength ?? null, r.rigLeg)}${k === r.legScale.length - 1 && noClamp !== null ? `; ${noClamp}` : ''}`));
     for (const l of r.legScale) for (const s of l.support ?? []) say(`  LEG-SCALE ${supportScaleLine(l, s, r.times)}`);
     if (r.pelvis !== null) say(`  ${pelvisLine(r.pelvis, seq.frames.length)}`);
+    // rig-c/pose#281: the limbs' front-to-back order from the sequence's depth, only when it carries depth.
+    const layers: FrameLayers[] | null = seq.frames.some((x) => x.depth !== undefined) ? frames.map((j, i) => layersOf(j, seq.frames[i]!.depth ?? {})) : null;
+    if (layers !== null) say(`  ${depthLine(layers, seq.frames, seq.cleaned!.params.depth?.gait ?? null)}`);
     if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
     if (r.feet !== null) {
       const f = r.feet;
@@ -217,6 +218,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       say(`  FEET   ${r.planted ? 'planted' : 'read, not planted (no --plant-feet)'}: leg length (median hip → ankle) r ${f.legLength.r.toFixed(1)}px, l ${f.legLength.l.toFixed(1)}px; ${f.supports.length} support span(s), ${f.changes.filter((c) => c.from !== null).length} change(s) of support, ${f.jumps.length} jump(s), ${f.steps.length} step(s)`);
       for (const sg of r.segments) say(`  FEET   ${segmentLine(sg)}`);
       say(`  FEET   supports: ${f.supports.map((x) => `${x.side} ${span(x.frames)}`).join(', ') || 'none'}`);
+      if (f.signal !== undefined) for (const l of signalLines(f.signal, f.supports)) say(`  FEET   ${l}`);
       say(`  FEET   jumps (both ankles and mid_hip > 0.05 leg lengths above their rolling floor, ≥ 2 frames): ${f.jumps.map(span).join(', ') || 'none'}`);
       if (f.lowered !== undefined) say(`  FEET   ${loweredLine(f.lowered)}`);
       if (f.tracked !== undefined) say(`  FEET   tracked (the lower foot supports on the floor, following its scaled ankle track until still, rig-c/pose#119): ${f.tracked.map((x) => `${x.side} ${span(x.frames)}`).join(', ')}`);
@@ -355,7 +357,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
     const hips = seq.cleaned?.params.hipsInferred;
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned), hips?.by === 'measured' ? hips : null);
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned), hips?.by === 'measured' ? hips : null, seq.pelvisSource !== undefined ? { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } : null);
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
@@ -444,6 +446,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         legScale: r.legScale.map(({ scale: _scale, asked: _asked, picture: _picture, ...rest }) => rest),
         pivot: r.pivot,
         pelvis: r.pelvis,
+        // Only when the sequence carries depth (#281): a sequence without it writes the report it always has.
+        ...(layers !== null ? { layers: layers.map((l, frame) => ({ frame, order: l.order, depth: l.depth })) } : {}),
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, ...(r.stance.range === undefined ? {} : { range: r.stance.range }), runs: r.stance.runs, over: r.stance.over },
         feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, straight: r.legStraight, rigLeg: r.rigLeg, segments: r.segments, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, ...(r.feet.lowered === undefined ? {} : { lowered: r.feet.lowered }), ...(r.feet.tracked === undefined ? {} : { tracked: r.feet.tracked }), floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, ...(r.blendHold.range === undefined ? {} : { range: r.blendHold.range }), runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading, closure: r.closure },
         shear,
@@ -916,6 +920,48 @@ function loweredLine(lowered: readonly Lowered[]): string {
   return `${head}: ${frames} frame(s) read differently from before — ${lowered.map((x) => `frames ${span(x.frames)} ${side(x.was)} → ${side(x.now)}${x.cause === undefined ? '' : ` (${CAUSE[x.cause]})`}`).join(', ')}`;
 }
 
+/**
+ * The support-signal lines (rig-c/pose#280). On a clip read as frontal: two
+ * lines — how often the ankle's vertical speed contradicts ankle height against
+ * `FRONTAL_DISAGREE`, and where the stride shows (in depth) — then one line per
+ * support span (a stride) naming the signal that decided its frames and what
+ * ankle height alone would have read. On any other clip ankle height decided as
+ * before and nothing is printed: the output of a clip the second signal does not
+ * decide stays as it was, in every mode (`Feet.signal` still carries the figures).
+ */
+export function signalLines(sig: SupportSignal, supports: Feet['supports']): string[] {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+  const n = Math.round(FRONTAL_DISAGREE * 100);
+  const pct = sig.read === 0 ? 0 : (100 * sig.contradict.length) / sig.read;
+  if (!sig.frontal) return [];
+  const ranges = `x · y against the hips: r ${sig.range.r.x.toFixed(1)} · ${sig.range.r.y.toFixed(1)} px, l ${sig.range.l.x.toFixed(1)} · ${sig.range.l.y.toFixed(1)} px`;
+  const contra = `${sig.contradict.length} of ${sig.read} frame(s) (${pct.toFixed(1)} %`;
+  const out = [
+    `support: ankle vertical speed (rig-c/pose#280) — it contradicts ankle height on ${contra}, past ${n} %): the lower ankle moving while the higher moves with the ground`,
+    `support: read as a frontal view — ankles move more in y than x (${ranges}); ankle height only where neither foot moves with the ground`,
+  ];
+  for (const sp of supports) {
+    let speed = 0;
+    let height = 0;
+    let both = 0;
+    let differ = 0;
+    const was = new Set<string>();
+    for (let i = sp.frames[0]; i <= sp.frames[1]; i++) {
+      if (sig.by[i] === 'speed') speed++;
+      else if (sig.by[i] === 'height') height++;
+      if (sig.contact[i] === 'both') both++;
+      if (sig.height[i] !== sp.side) {
+        differ++;
+        was.add(sig.height[i] ?? 'none');
+      }
+    }
+    const by = speed > 0 ? `ankle vertical speed on ${speed} frame(s)${height > 0 ? `, ankle height on ${height} (neither foot moved with the ground)` : ''}` : `ankle height on ${height} frame(s) (neither foot moved with the ground)`;
+    const alone = differ === 0 ? 'ankle height alone reads the same' : `ankle height alone would read ${[...was].join(' or ')} on ${differ} of them`;
+    out.push(`stride ${sp.side} ${span(sp.frames)}: ${by} (both feet down on ${both}); ${alone}`);
+  }
+  return out;
+}
+
 /**
  * The in-place line without --plant-feet (rig-c/pose#242): what the declaration still changes, and the one thing it
  * cannot without planted feet — the loop closure, which spreads back the planted hip's drift. `drift` is the
@@ -1052,6 +1098,21 @@ export function legScaleLine(l: LegScale, times: readonly number[], legLength: R
   return `chain "${l.chain}" bone "${l.bone}" (${l.joints[0]} → ${l.joints[1]}): straight length ${l.straight.toFixed(1)}px (larger 95th percentile of ${times.length} frames, both legs)${share}; picture length ÷ straight ${l.ratio.min.toFixed(3)} … ${l.ratio.max.toFixed(3)} (median ${l.ratio.median.toFixed(3)}); scalex keyed in [${l.limits[0]}, ${l.limits[1]}] of the straight length (${limitsPx}): ${clamp(l.low, l.limits[0], 'under', 'low')}; ${clamp(l.high, l.limits[1], 'over', 'high')}${free}`;
 }
 
+/**
+ * rig-c/pose#287: when `--leg-scale`'s range clamps no frame on any leg segment
+ * (no run under the floor, none over the ceiling, no supporting frame scaled past
+ * the floor), the clause naming the range and the picture's own spread across
+ * every segment, so a reader learns the range never bound and what floor would.
+ * Null when any frame was clamped, or with no segment scaled.
+ */
+export function legScaleNoClamp(ls: readonly LegScale[]): string | null {
+  if (ls.length === 0 || ls.some((l) => l.low.length > 0 || l.high.length > 0 || (l.support ?? []).length > 0)) return null;
+  const [floor, ceiling] = ls[0]!.limits;
+  const min = Math.min(...ls.map((l) => l.ratio.min));
+  const max = Math.max(...ls.map((l) => l.ratio.max));
+  return `no frame clamped on any leg segment: the range [${floor}, ${ceiling}] holds the picture's whole spread, picture length ÷ straight ${min.toFixed(3)} … ${max.toFixed(3)} over the ${ls.length} segment(s), so each segment is scaled to the picture on every frame; a floor above ${min.toFixed(3)} would clamp`;
+}
+
 /** A LEG-SCALE past the floor (support) line (rig-c/pose#133): the supporting leg segment scaled below `--leg-scale`'s floor down to #95's bound. */
 export function supportScaleLine(l: LegScale, s: SupportScaleRun, times: readonly number[]): string {
   const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
@@ -1136,11 +1197,6 @@ export function defaultReportPath(out: string): string {
   return `${out.endsWith('.json') ? out.slice(0, -'.json'.length) : out}.report.json`;
 }
 
-/** rig-c/pose#239: the line a directory this run made prints — the directory, and the paths that named it. */
-export function madeLine(dir: string, flags: readonly string[]): string {
-  return `  made directory ${dir} — it did not exist; ${flags.join(' and ')} ${flags.length === 1 ? 'is' : 'are'} written into it`;
-}
-
 /** rig-c/pose#239: the report's `wrote` line — whether it was the default, and the mtime of the report it replaced. */
 export function reportLine(report: string, byDefault: boolean, previous: Date | null): string {
   return `  wrote ${report} — the run's report (rig-pose-report/1)${byDefault ? ', beside --out by default; name another path with --report' : ''}${previous === null ? '' : `; it replaced the report there last written ${previous.toISOString()}`}`;

package/src/runcompare.ts

@@ -5,12 +5,12 @@
  * not a failure: the run exits 0 whenever it compared.
  */
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { compare, findingLine, readCloth, readHands, readSpans, summaryLine, writeComparison, type ClothWindow, type CompareInput, type Comparison } from './compare.ts';
 import { readMap } from './map.ts';
 import { personTrack, readPoseSequence, type PoseSequence } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import { drawable, drawSheet } from './sheet.ts';
+import { makeOutDirs, planOutDirs } from './outdir.ts';
 
 export interface CompareArgs {
   reference: string;
@@ -37,12 +37,9 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     if (!existsSync(path)) p.add('ARG_PATH', `${flag} ${path} does not exist`);
     else if (!statSync(path).isFile()) p.add('ARG_PATH', `${flag} ${path} is not a file`);
   }
-  for (const [flag, path] of [['--report', a.report], ['--sheet', a.sheet]] as const) {
-    if (path === undefined) continue;
-    const dir = dirname(path);
-    if (!existsSync(dir)) p.add('ARG_PATH', `${flag} ${path} — directory ${dir} does not exist`);
-    else if (!statSync(dir).isDirectory()) p.add('ARG_PATH', `${flag} ${path} — ${dir} is not a directory`);
-  }
+  // #284: a directory --report or --sheet names that is not there yet is made just before that file is written.
+  const reportDirs = planOutDirs([['--report', a.report]], p);
+  const sheetDirs = planOutDirs([['--sheet', a.sheet]], p);
   p.throwIfAny();
 
   // Every reader runs, and every refusal is reported together.
@@ -98,6 +95,7 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     if (c.cloth.windows.length > 0) log(`  CLOTH  the render's stroke threshold ${c.cloth.stroke.render.toFixed(4)} of its hip widths = ${c.cloth.stroke.carried}`);
   }
   if (a.report !== undefined) {
+    makeOutDirs(reportDirs, log);
     writeFileSync(a.report, writeComparison(c, {
       reference: a.reference, render: a.render, map: a.map, retargetReport: a.retargetReport ?? null,
       referenceHands: a.referenceHands ?? null, renderHands: a.renderHands ?? null, clothReference: a.clothReference ?? null, clothRender: a.clothRender ?? null,
@@ -108,6 +106,7 @@ export function runCompare(a: CompareArgs, log: (line: string) => void): Compari
     const plate = drawSheet({ frames: ref!.frames, width: ref!.seq.width, height: ref!.seq.height }, { frames: ren!.frames, width: ren!.seq.width, height: ren!.seq.height }, c.findings);
     if (plate === null) log(`  SHEET  no finding has a frame to draw (${c.findings.length} finding(s), none outside cloth); ${a.sheet} not written`);
     else {
+      makeOutDirs(sheetDirs, log);
       plate.writePng(a.sheet);
       log(`  SHEET  ${drawable(c.findings).length} finding(s), reference | render at each worst frame: wrote ${a.sheet}`);
     }