@rig-c/pose 0.37.1 → 0.39.0

package/src/retarget.ts

@@ -80,7 +80,7 @@ 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 { clampArt, coveredChains, isRaised, measureArt, overflow, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } 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';
 import type { BodyReading, FaceReading, YawSetSwitch } from './face.ts';
@@ -174,6 +174,33 @@ export interface RetargetOptions extends SwitchOptions {
   travel?: Travel;
   /** The sequence was cleaned with `--loop` (its `cleaned.params.loop`, rig-c/pose#241): the head nod's detrend window wraps, the last frame running into the first. */
   loop?: boolean;
+  /**
+   * rig-c/pose#288: the sequence's pelvis track (`pelvisTilt` per frame, null where
+   * declined, and its `pelvisSource`). The pelvis chain's bone (a chain whose
+   * joints are r_hip → l_hip) is keyed from it on every frame it reads, and from
+   * the hip line on the frames it does not; absent, from the hip line.
+   */
+  pelvis?: { source: string; tilt: ReadonlyArray<number | null> };
+}
+
+/**
+ * rig-c/pose#288: where the pelvis bone's rotation came from. `source` is the
+ * track's (`silhouette`, `waistband`, `keys`) or "hip line"; `bone`/`chain` the
+ * map's pelvis chain (null without one, when nothing is keyed); `swing` the
+ * peak-to-peak of its rotate keys, degrees (null when not keyed); `track` and
+ * `hipLine` how many frames each keyed; `trackSource` the track's source when the
+ * sequence carries one (also when it read no frame and the hip line was keyed).
+ */
+export interface PelvisReading {
+  source: string;
+  trackSource: string | null;
+  bone: string | null;
+  chain: string | null;
+  swing: number | null;
+  track: number;
+  hipLine: number;
+  /** The frames keyed from the hip line on a sequence that carries a track: the frames its reading declined. */
+  declined: Array<[number, number]>;
 }
 
 export interface Hold {
@@ -448,6 +475,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#288: the pelvis bone's source; null when the map has no pelvis chain and the sequence no track. */
+  pelvis: PelvisReading | null;
 }
 
 export interface FigureScaleFrame {
@@ -809,6 +838,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // Each mapped bone's target world angle per frame, reaches last.
   const targets = new Map<string, number[]>();
   const restOf = new Map<string, number>();
+  // rig-c/pose#288: the pelvis chain (one bone, joints r_hip → l_hip either way) keyed from the track where it reads.
+  const pelvisChain = map.chains.find((c) => !c.reach && c.bones.length === 1 && ((c.joints[0] === 'r_hip' && c.joints[1] === 'l_hip') || (c.joints[0] === 'l_hip' && c.joints[1] === 'r_hip'))) ?? null;
+  const track = opts.pelvis !== undefined && opts.pelvis.tilt.length === n ? opts.pelvis.tilt : null;
+  const fromTrack = pelvisChain !== null && track !== null && track.some((v) => v !== null) ? pelvisChain.bones[0]! : null;
   for (const c of map.chains) {
     c.bones.forEach((b, k) => {
       restOf.set(b, restAngle(rest, b, c.aim[k]!));
@@ -817,6 +850,12 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const to = series.get(c.joints[k + 1]!)!;
       const angles: number[] = [];
       for (let i = 0; i < n; i++) {
+        const v = b === fromTrack ? track![i] : null;
+        if (v !== null && v !== undefined) {
+          // The track is the r_hip → l_hip direction; a chain written l_hip → r_hip aims the other way.
+          angles.push(c.joints[0] === 'r_hip' ? v : wrap(v + 180));
+          continue;
+        }
         const d = Math.hypot(to[i]![0] - from[i]![0], to[i]![1] - from[i]![1]);
         angles.push(d > 1e-9 ? pictureAngle(from[i]!, to[i]!) : (angles[i - 1] ?? NaN));
       }
@@ -842,6 +881,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const joints: [string, string] = [c.joints[k]!, c.joints[k + 1]!];
         const across = isAcross(joints[0], joints[1]);
         if (!across && opts.short === 'off') return;
+        // rig-c/pose#288: a pelvis keyed from its track is not read off the hip pair's length, so it is not held across it.
+        if (b === fromTrack) return;
         const from = series.get(joints[0])!;
         const to = series.get(joints[1])!;
         const lengths = from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1]));
@@ -1211,6 +1252,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   if (opts.stance !== undefined && opts.stance !== 'off' && !plantOn) p.add('STANCE', `--stance ${opts.stance} plants the free foot beside the supporting one that --plant-feet holds, and --plant-feet is not given`);
   if (opts.floor !== undefined && !plantOn) p.add('FLOOR', `--floor ${opts.floor} is the floor --plant-feet plants every support span on, and --plant-feet is not given`);
   if (opts.floor !== undefined && !Number.isFinite(opts.floor)) p.add('FLOOR', `--floor is ${opts.floor}; it must be a finite world y`);
+  // rig-c/pose#286: a set with a `phase` shows on the report's support spans, read with or without --plant-feet; a run that
+  // reads no feet has none to show it on, and a group of competing sets mixing phase and angle sets has no rule.
+  const phased = map.alternates.filter((a) => a.phase !== undefined);
+  if (phased.length > 0) {
+    if (feet === null) {
+      const why = legs !== null && 'problems' in legs ? legs.problems.join('; ') : `the feet are read from both hips and both ankles, and the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`;
+      p.add('PHASE_FEET', `set(s) ${phased.map((a) => `"${a.name}" ("phase": "${a.phase}")`).join(', ')} show by the supporting foot (left-step while the right foot supports), and this run reads no supports: ${why}`);
+    }
+    for (const x of phaseGroupProblems(map.alternates)) p.add('PHASE_GROUP', x);
+  }
   p.throwIfAny();
   const askedScales = new Map<string, number[]>();
   for (const ls of legScale) askedScales.set(ls.bone, ls.asked);
@@ -1485,7 +1536,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   }
   const rawTargets = new Map<string, number[]>([...targets].map(([b, arr]) => [b, [...arr]]));
-  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, { ...opts, shortInfo, handOffsets });
+  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, { ...opts, shortInfo, handOffsets, ...(phased.length > 0 && feet !== null ? { phaseSupports: feet.supports } : {}) });
 
   // The range clamp, outside the spans of a set depicting the bone's chain. Parents
   // first, so a bone below takes its clamped parent into its key; a reach is aimed
@@ -3038,6 +3089,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const reach = reachReadings(rest, map, tracks, reachAims, t?.bone ?? null);
 
   const pivot = pivotOf(rest, t?.bone ?? null, legs);
+  const pelvis = pelvisReadingOf(pelvisChain, opts.pelvis, track, fromTrack, tracks);
   const scaleFit = t === null || scale === null || origin === null ? null : scaleFitOf({
     joints: t.scale.pose, joint: t.joint, bone: t.bone, lengths: scaleLengths, factor: scale.factor,
     series, good, legLength: feet?.legLength ?? null, legStraight, rigLeg,
@@ -3048,10 +3100,53 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     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,
+    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,
   };
 }
 
+/** rig-c/pose#288: the pelvis bone's source, from the chain, the track and the keys written. */
+function pelvisReadingOf(chain: Chain | null, given: RetargetOptions['pelvis'], track: ReadonlyArray<number | null> | null, fromTrack: string | null, tracks: ReadonlyArray<MotionTrack | SlotTrack>): PelvisReading | null {
+  if (chain === null && given === undefined) return null;
+  const bone = chain?.bones[0] ?? null;
+  const keys = bone === null ? null : tracks.find((tr): tr is MotionTrack => 'bone' in tr && tr.bone === bone && tr.property === 'rotate');
+  const vs = keys === null || keys === undefined ? [] : keys.keys.map((k) => k.v[0]!);
+  const swing = vs.length === 0 ? null : r3(Math.max(...vs) - Math.min(...vs));
+  const n = vs.length;
+  const declined: Array<[number, number]> = [];
+  (track ?? []).forEach((v, i) => {
+    if (v !== null) return;
+    const last = declined[declined.length - 1];
+    if (last !== undefined && last[1] === i - 1) last[1] = i;
+    else declined.push([i, i]);
+  });
+  const onTrack = fromTrack === null ? 0 : (track ?? []).filter((v) => v !== null).length;
+  return {
+    source: fromTrack !== null ? given!.source : 'hip line',
+    trackSource: given?.source ?? null,
+    bone,
+    chain: chain?.name ?? null,
+    swing,
+    track: onTrack,
+    hipLine: bone === null ? 0 : n - onTrack,
+    declined: given === undefined ? [] : declined,
+  };
+}
+
+/**
+ * The PELVIS line (rig-c/pose#288): where the pelvis bone's rotation came from and
+ * its swing — "from <source>, swing N°", or "from hip line (no track)".
+ */
+export function pelvisLine(r: PelvisReading, frames: number): string {
+  const spans = (rs: Array<[number, number]>) => rs.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
+  const where = r.bone === null ? '' : `bone "${r.bone}", chain "${r.chain}"`;
+  if (r.bone === null) return `PELVIS: not keyed — the sequence carries a ${r.trackSource} track (${frames - r.declined.reduce((s, [a, b]) => s + b - a + 1, 0)} of ${frames} frames read) and the map has no pelvis chain (one bone, joints r_hip → l_hip); no bone turns with the pelvis`;
+  const swing = r.swing === null ? '' : `, swing ${r.swing.toFixed(2)}°`;
+  if (r.trackSource === null) return `PELVIS: from hip line (no track)${swing} (${where}; every frame from r_hip → l_hip)`;
+  if (r.track === 0) return `PELVIS: from hip line (the ${r.trackSource} track read none of the ${frames} frames)${swing} (${where}; every frame from r_hip → l_hip)`;
+  const rest = r.hipLine === 0 ? `all ${frames} frames from the track` : `${r.track} of ${frames} frames from the track, the hip line on the ${r.hipLine} it declined (frames ${spans(r.declined)})`;
+  return `PELVIS: from ${r.source}${swing} (${where}; ${rest})`;
+}
+
 /** A reach bone's origin within this many world units of the anchor's, with nothing above it moved, is aimed along the pair: no REACH line. */
 export const REACH_OFFSET = 1e-6;
 

package/src/run.ts

@@ -10,19 +10,21 @@ 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';
-import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, rangeLine, reachCostLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
+import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, pelvisLine, rangeLine, reachCostLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, seamRender, slotsOf } from './rigc.ts';
 import { partsPath, projectSeams, readSeamDoc, readSeamPairs, seamLines, type SeamPair } from './seams.ts';
-import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.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);
@@ -151,7 +147,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const slots = slotsOf(doc0);
     resolveMap(map, rest, a.map, slots, input.sets);
 
-    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}) }, slots, input.sets);
+    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}), ...(seq.cleaned!.params.loop ? { loop: true } : {}), ...(seq.pelvisSource !== undefined ? { pelvis: { source: seq.pelvisSource, tilt: seq.frames.map((f) => f.pelvisTilt ?? null) } } : {}) }, slots, input.sets);
     if (fragment.length > 0 && ((r.face?.sets?.length ?? 0) > 0 || (r.body?.sets?.length ?? 0) > 0)) {
       const known = knownSetsOf(map, input.sets);
       for (const s of [...(r.face?.sets ?? []), ...(r.body?.sets ?? [])]) {
@@ -196,6 +192,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       if (r.switches.length === 0) say(`  SWITCH none — no set within ${a.switchTolerance}° of the pose for ${a.switchMin}s`);
       for (const s of r.switches) say(`  SWITCH ${switchLine(s, r.times)}`);
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
+      for (const l of phaseLines(map, r.switches)) say(`  PHASE  ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
     if (a.raisedByHead === true && r.raised.length === 0) say(`  RAISED none — no set drawing an arm within ${RAISED_WITHIN}° of straight up showed; no key moved`);
@@ -206,8 +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;
@@ -215,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(', ')}`);
@@ -353,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);
@@ -441,6 +445,9 @@ 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,
@@ -913,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
@@ -1049,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)`);
@@ -1133,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}`);
     }

package/src/switch.ts

@@ -12,6 +12,11 @@
  * span is dropped, and the base art shows there; a gap shorter than the minimum
  * span between two runs of one set is bridged by that set. No other hysteresis.
  *
+ * A set with a `phase` (rig-c/pose#286) is not selected by distance: it shows
+ * exactly on its supporting foot's spans (`phaseSupports`, the
+ * report's `feet.supports`) and switches on the hand-over, with none of the
+ * rules here or below applied to it.
+ *
  * Sets compete only with the sets they share a slot with (shown or hidden,
  * transitively), or a bone they offset: two that touch nothing in common — a
  * drawing of each arm — can show at once, and two that do never overlap, so
@@ -52,8 +57,9 @@
  * selection put it; it is the CLI's default, because on HQ's dancer the bounded
  * peak still raised the sets' ART-RANGE runs from 24 to 31 (#31, round 2).
  */
-import type { AlternateSet, JointMap, Rest, RigSlots } from './map.ts';
-import { descends } from './map.ts';
+import type { Side } from './legs.ts';
+import type { AlternateSet, JointMap, Phase, Rest, RigSlots } from './map.ts';
+import { descends, PHASE_SIDE } from './map.ts';
 import type { MotionKey, MotionTrack } from './retarget.ts';
 import { pictureAngle, wrap } from './retarget.ts';
 import type { MeshFolds } from './rigc.ts';
@@ -80,6 +86,19 @@ export interface SwitchOptions {
   shortInfo?: ShortSwitchInfo;
   /** Per chain, the reference pose's normalised wrist-from-shoulder offset on each frame, `(wrist - shoulder) / scale`, y down (#180). */
   handOffsets?: ReadonlyMap<string, ReadonlyArray<readonly [number, number]>>;
+  /** The report's `feet.supports` (rig-c/pose#286): the spans a set with a `phase` shows on. Given only when a set declares one. */
+  phaseSupports?: ReadonlyArray<{ side: Side; frames: [number, number] }>;
+}
+
+/** A phase set's span (rig-c/pose#286): its step side, and the support hand-overs it was switched on and off at. */
+export interface PhaseSpan {
+  step: Phase;
+  /** The supporting foot it shows on (left-step: the left foot is stepping, so the right foot supports). */
+  side: Side;
+  /** The hand-over it starts on: the frame, and the side that supported on the frame before (null: no foot). Null from the first frame. */
+  on: { frame: number; from: Side | null } | null;
+  /** The hand-over it ends on: the first frame after it, and the side that supports there (null: no foot). Null to the end. */
+  off: { frame: number; to: Side | null } | null;
 }
 
 /** One boundary of a span: where the selection put it, where it is keyed, and how fast the chains it changes move on each. */
@@ -115,6 +134,8 @@ export interface Switch {
   artTurn: Record<string, { max: number; median: number }>;
   /** The boundary it starts on (null from the first frame) and the one it ends on (null to the end); a boundary between two sets is in both. */
   moved: { on: Move | null; off: Move | null };
+  /** Only on a set with a `phase` (rig-c/pose#286): the step side and the hand-overs the span was switched on. */
+  phase?: PhaseSpan;
 }
 
 export interface AttachmentKey {
@@ -245,6 +266,28 @@ function touches(a: AlternateSet): string[] {
   return [...Object.keys(a.slots), ...a.hides].map((s) => `slot:${s}`).concat(Object.keys(a.offsets).map((b) => `bone:${b}`));
 }
 
+/**
+ * rig-c/pose#286: what the retarget refuses about the map's phase sets, one text each. A group of competing sets (a
+ * common slot or offset bone, transitively) that holds a phase set must hold only phase sets, and at most one of each
+ * side: the hand-over decides which of them shows, and nothing would decide between two of one side, or between a phase
+ * set and an angle set over the frames they share.
+ */
+export function phaseGroupProblems(sets: readonly AlternateSet[]): string[] {
+  const out: string[] = [];
+  for (const group of competing(sets)) {
+    const phased = group.filter((a) => a.phase !== undefined);
+    if (phased.length === 0) continue;
+    const angle = group.filter((a) => a.phase === undefined);
+    const named = (xs: readonly AlternateSet[]) => xs.map((a) => `"${a.name}"`).join(', ');
+    if (angle.length > 0) out.push(`set(s) ${named(phased)} declare "phase" and compete with set(s) ${named(angle)}, which declare none (they switch a common slot or offset bone); a phase set shows on its supporting foot's spans and an angle set on its distance, and nothing decides between them — give every set of the group a "phase", or none`);
+    for (const step of Object.keys(PHASE_SIDE) as Phase[]) {
+      const same = phased.filter((a) => a.phase === step);
+      if (same.length > 1) out.push(`set(s) ${named(same)} all declare "phase": "${step}" and compete (they switch a common slot or offset bone); one drawing shows per support span — keep one "${step}" set per group`);
+    }
+  }
+  return out;
+}
+
 /** Groups of sets that switch a common slot or offset a common bone, transitively; each in map order. */
 function competing(sets: readonly AlternateSet[]): AlternateSet[][] {
   const parent = sets.map((_, i) => i);
@@ -447,8 +490,41 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   const distances = setDistances(map, targets, n, opts.shortInfo);
   const hyst = opts.switchHysteresis ?? SWITCH_LEAVE_HYSTERESIS;
   const switches: Switch[] = [];
+  // rig-c/pose#286: the supporting side on each frame, from the report's support spans (null: no foot, or no set declares a phase).
+  const supportAt: Array<Side | null> = Array.from({ length: n }, () => null);
+  for (const sp of opts.phaseSupports ?? []) for (let i = sp.frames[0]; i <= Math.min(sp.frames[1], n - 1); i++) supportAt[i] = sp.side;
+  /** One group's pick, as segments between boundaries, then each boundary moved (#31), pushed as switches. */
+  const spans = (pick: ReadonlyArray<AlternateSet | null>, moveOpts: SwitchOptions): void => {
+    const vals: Array<AlternateSet | null> = [pick[0] ?? null];
+    const pos: number[] = [];
+    for (let i = 1; i < n; i++) {
+      if (pick[i] === pick[i - 1]) continue;
+      pos.push(i);
+      vals.push(pick[i] ?? null);
+    }
+    const moves = moveBoundaries(vals, pos, map, targets, distances, times, duration, moveOpts);
+    for (let s = 0; s < vals.length; s++) {
+      const a = vals[s];
+      if (a === null || a === undefined) continue;
+      const i = s === 0 ? 0 : moves[s - 1]!.frame[1];
+      const j = s < pos.length ? moves[s]!.frame[1] - 1 : n - 1;
+      const from = times[i]!;
+      const to = j + 1 < n ? times[j + 1]! : duration;
+      const ds = distances.get(a.name)!.slice(i, j + 1);
+      const phase: PhaseSpan | undefined = a.phase === undefined ? undefined : { step: a.phase, side: PHASE_SIDE[a.phase], on: i === 0 ? null : { frame: i, from: supportAt[i - 1] ?? null }, off: j + 1 < n ? { frame: j + 1, to: supportAt[j + 1] ?? null } : null };
+      switches.push({ set: a.name, chains: a.chains, slots: a.slots, hides: a.hides, offsets: a.offsets, from, to, frames: [i, j], distance: { max: r3(Math.max(...ds)), median: r3(median(ds)) }, artTurn: {}, moved: { on: s === 0 ? null : moves[s - 1]!, off: s < pos.length ? moves[s]! : null }, ...(phase === undefined ? {} : { phase }) });
+    }
+  };
   const groups = competing(map.alternates);
   for (const group of groups) {
+    // rig-c/pose#286: a group of phase sets shows each exactly on its supporting foot's spans — no tolerance, no minimum run,
+    // no hysteresis, no bridging, and its boundaries stay on the hand-overs (no --switch-at peak move). The retarget refuses
+    // a group mixing phase and angle sets, or two sets of one side (`phaseGroupProblems`), before it gets here.
+    if (group.some((a) => a.phase !== undefined)) {
+      const pick = supportAt.map((side) => (side === null ? null : group.find((a) => a.phase !== undefined && PHASE_SIDE[a.phase] === side) ?? null));
+      spans(pick, { ...opts, switchAt: 'first' });
+      continue;
+    }
     const layer = groupLayering(group, map, slots);
     const pick: Array<AlternateSet | null> = [];
     for (let i = 0; i < n; i++) {
@@ -582,25 +658,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       if (dropped) bridgeSame(pick);
     }
-    // The segments between boundaries, then each boundary moved (#31).
-    const vals: Array<AlternateSet | null> = [pick[0] ?? null];
-    const pos: number[] = [];
-    for (let i = 1; i < n; i++) {
-      if (pick[i] === pick[i - 1]) continue;
-      pos.push(i);
-      vals.push(pick[i] ?? null);
-    }
-    const moves = moveBoundaries(vals, pos, map, targets, distances, times, duration, opts);
-    for (let s = 0; s < vals.length; s++) {
-      const a = vals[s];
-      if (a === null || a === undefined) continue;
-      const i = s === 0 ? 0 : moves[s - 1]!.frame[1];
-      const j = s < pos.length ? moves[s]!.frame[1] - 1 : n - 1;
-      const from = times[i]!;
-      const to = j + 1 < n ? times[j + 1]! : duration;
-      const ds = distances.get(a.name)!.slice(i, j + 1);
-      switches.push({ set: a.name, chains: a.chains, slots: a.slots, hides: a.hides, offsets: a.offsets, from, to, frames: [i, j], distance: { max: r3(Math.max(...ds)), median: r3(median(ds)) }, artTurn: {}, moved: { on: s === 0 ? null : moves[s - 1]!, off: s < pos.length ? moves[s]! : null } });
-    }
+    spans(pick, opts);
   }
   const order = (name: string) => map.alternates.findIndex((a) => a.name === name);
   switches.sort((x, y) => x.frames[0] - y.frames[0] || order(x.set) - order(y.set));
@@ -632,6 +690,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   // and in a one-sided gesture set keep an arm whose wrist stays behind the torso on its previous behind set.
   const chainHolds: Array<{ set: string; chain: string; frames: [number, number] }> = [];
   for (const group of groups) {
+    if (group.some((a) => a.phase !== undefined)) continue; // #286: a phase group shows exactly its support spans
     const layer = groupLayering(group, map, slots);
     if (!layer.baseInFront) continue;
     const names = new Set(group.map((a) => a.name));
@@ -1193,6 +1252,35 @@ export function switchLine(s: Switch, times: readonly number[]): string {
   return parts.join('; ');
 }
 
+/**
+ * rig-c/pose#286: one `PHASE` line per set with a `phase` — the support side it shows on, every span it showed, and the
+ * hand-over each span was switched on and off at (the side before → the side after; "none" where no foot supports).
+ */
+export function phaseLines(map: JointMap, switches: readonly Switch[]): string[] {
+  const out: string[] = [];
+  const sideText = (x: Side | null) => x ?? 'none';
+  for (const set of map.alternates) {
+    if (set.phase === undefined) continue;
+    const side = PHASE_SIDE[set.phase];
+    const foot = (x: Side) => (x === 'l' ? 'left' : 'right');
+    const head = `set "${set.name}" "${set.phase}" — the ${foot(side === 'l' ? 'r' : 'l')} foot is stepping; shown while the ${foot(side)} foot supports (feet.supports)`;
+    const own = switches.filter((s) => s.set === set.name && s.phase !== undefined);
+    if (own.length === 0) {
+      out.push(`${head}: on no frame — no ${side} support span`);
+      continue;
+    }
+    const count = own.reduce((t, s) => t + s.frames[1] - s.frames[0] + 1, 0);
+    const spansText = own.map((s) => {
+      const ph = s.phase!;
+      const on = ph.on === null ? 'on the first frame' : `on frame ${ph.on.frame} ${sideText(ph.on.from)} → ${side}`;
+      const off = ph.off === null ? 'off at the end' : `off frame ${ph.off.frame} ${side} → ${sideText(ph.off.to)}`;
+      return `${s.frames[0]}–${s.frames[1]} (${on}, ${off})`;
+    });
+    out.push(`${head}: ${own.length} span(s), ${count} frame(s): ${spansText.join(', ')}`);
+  }
+  return out;
+}
+
 const spd = (v: number) => `${v.toFixed(1)}°/frame`;
 const win = (w: [number, number]) => (w[0] === w[1] ? `window frame ${w[0]}` : `window frames ${w[0]}–${w[1]}`);
 function moveText(m: Move): string {