@rig-c/pose 0.37.1 → 0.39.0

package/src/depth.ts

@@ -0,0 +1,190 @@
+/**
+ * Derived depth (rig-c/pose#281): which way each limb segment leans out of the
+ * picture, read off its 2D length, and the limbs' front-to-back order from it.
+ *
+ * A sequence carries x and y only, so nothing downstream can say which limb is
+ * nearer the camera. A segment drawn shorter than its rest length is tilted out
+ * of the picture plane, and by how much its length says: `ratio` = drawn length
+ * ÷ rest length, the rest length being the larger of the two sides' 95th
+ * percentile picture lengths of that segment over the clip — the straight length
+ * the leg scale reads (`STRAIGHT_PERCENTILE`, #148), per segment. Which way it
+ * tilts the length cannot say; the sign comes from the body:
+ *
+ * | segment   | sense when foreshortened | why |
+ * | --------- | ------------------------ | --- |
+ * | thigh     | forward                  | a hip flexes forward; it extends back too little to foreshorten past the band |
+ * | shin      | walk: forward · run: back | the gait rule (rig-c/pose#281, HQ): a walk's lifted foot comes forward, a run's is kicked back — the knee alone cannot say, since it bends forward in both |
+ * | upper arm | with the opposite leg    | in a gait each arm swings with the opposite leg: forward when the other side's thigh is the more foreshortened of the two, back when its own is; forward (a shoulder flexes forward) when neither thigh is foreshortened |
+ * | forearm   | forward                  | an elbow bends toward the back of the body, so the forearm folds forward |
+ *
+ * "Forward" is the trunk's facing: toward the camera (+1) when the figure faces
+ * it (its left shoulder and hip drawn right of its right ones), away (−1) when
+ * it faces away, and undecided (sign 0) when the trunk is side-on — shoulders
+ * and hips drawn less than `SIDE_ON` trunk lengths wide — since forward is then
+ * across the picture, not into it. A ratio within `FLAT_BAND` is flat, sign 0,
+ * and so is one above it (drawn longer than rest is not a tilt).
+ *
+ * The layers: each joint's depth is its parent's plus its segment's,
+ * sign × rest × √(1 − ratio²) px (rest = drawn ÷ ratio), from the shoulders and
+ * hips at 0; a limb's depth is the mean of its middle and end joints'; the limbs
+ * are ordered nearest first, equal depths (to 0.01 px) sharing a layer. A limb
+ * whose segments are not both named on a frame is not ordered on it.
+ *
+ * Pure: no clock, no randomness, no disk.
+ */
+import type { Body18 } from './joints.ts';
+import { percentile, STRAIGHT_PERCENTILE } from './legs.ts';
+import { DEPTH_SEGMENT_NAMES, DEPTH_SEGMENTS, type DepthGait, type DepthSegment, type DepthSource, type FrameDepth, type Joint, type SegmentDepth } from './pose.ts';
+
+/** A ratio within this band is flat (sign 0): cos 18.2° = 0.95, so a segment within about 18° of the picture plane reads flat. */
+export const FLAT_BAND: readonly [number, number] = [0.95, 1.05];
+/** The trunk is side-on when its shoulders and hips are drawn, on average, less than this many trunk lengths (neck → mid_hip) wide. */
+export const SIDE_ON = 0.1;
+/** The limbs `layers` orders, each by its segments from the trunk out. */
+export const LIMBS = {
+  r_arm: ['r_upper_arm', 'r_forearm'],
+  l_arm: ['l_upper_arm', 'l_forearm'],
+  r_leg: ['r_thigh', 'r_shin'],
+  l_leg: ['l_thigh', 'l_shin'],
+} as const satisfies Record<string, readonly [DepthSegment, DepthSegment]>;
+export type Limb = keyof typeof LIMBS;
+export const LIMB_NAMES = Object.keys(LIMBS) as Limb[];
+
+type Pt = [number, number];
+type Joints = Partial<Record<Body18, Joint>>;
+const at = (j: Joint | undefined): Pt | null => (j === undefined || j.state === 'missing' || j.at === undefined ? null : j.at);
+const kindOf = (s: DepthSegment) => s.slice(2) as 'upper_arm' | 'forearm' | 'thigh' | 'shin';
+const other = (s: DepthSegment): DepthSegment => `${s.startsWith('r_') ? 'l' : 'r'}_${s.slice(2)}` as DepthSegment;
+
+/** A segment's drawn length on a frame; null where a joint is not placed. */
+function drawn(joints: Joints, s: DepthSegment): number | null {
+  const [a, b] = DEPTH_SEGMENTS[s];
+  const pa = at(joints[a]);
+  const pb = at(joints[b]);
+  return pa === null || pb === null ? null : Math.hypot(pb[0] - pa[0], pb[1] - pa[1]);
+}
+
+/** The trunk's facing on a frame: +1 toward the camera, −1 away, 0 side-on or not placed. */
+export function facingOf(joints: Joints): -1 | 0 | 1 {
+  const p = (n: Body18) => at(joints[n]);
+  const [rs, ls, rh, lh, neck] = [p('r_shoulder'), p('l_shoulder'), p('r_hip'), p('l_hip'), p('neck')];
+  if (rs === null || ls === null || rh === null || lh === null || neck === null) return 0;
+  const trunk = Math.hypot(neck[0] - (rh[0] + lh[0]) / 2, neck[1] - (rh[1] + lh[1]) / 2);
+  if (!(trunk > 0)) return 0;
+  const width = (ls[0] - rs[0] + (lh[0] - rh[0])) / 2 / trunk;
+  return width > SIDE_ON ? 1 : width < -SIDE_ON ? -1 : 0;
+}
+
+export interface DerivedDepth {
+  /** Per frame, each segment whose joints are placed. */
+  frames: FrameDepth[];
+  /** Each segment kind's rest length, px (the larger side's 95th percentile); null where neither side is ever placed. */
+  rest: Record<'upper_arm' | 'forearm' | 'thigh' | 'shin', number | null>;
+  /** Frames the trunk faced the camera, faced away, and was side-on (or not placed). */
+  facing: { toward: number; away: number; side: number };
+  /** Segment-frames by sign. */
+  signs: { toward: number; away: number; flat: number };
+}
+
+/** Each frame's depth, derived from the picture's lengths for `gait` (the table above). */
+export function deriveDepth(track: readonly Joints[], gait: DepthGait): DerivedDepth {
+  const lengths = new Map(DEPTH_SEGMENT_NAMES.map((s) => [s, track.map((j) => drawn(j, s))]));
+  const rest = {} as DerivedDepth['rest'];
+  for (const k of ['upper_arm', 'forearm', 'thigh', 'shin'] as const) {
+    const sides = (['r', 'l'] as const).map((side) => percentile(lengths.get(`${side}_${k}`)!.filter((v): v is number => v !== null), STRAIGHT_PERCENTILE)).filter((v) => Number.isFinite(v) && v > 0);
+    rest[k] = sides.length === 0 ? null : Math.max(...sides);
+  }
+  const facing = { toward: 0, away: 0, side: 0 };
+  const signs = { toward: 0, away: 0, flat: 0 };
+  const frames = track.map((joints, i) => {
+    const face = facingOf(joints);
+    if (face === 1) facing.toward++;
+    else if (face === -1) facing.away++;
+    else facing.side++;
+    const ratio = (s: DepthSegment): number | null => {
+      const d = lengths.get(s)![i];
+      const r = rest[kindOf(s)];
+      return d === null || d === undefined || r === null ? null : d / r;
+    };
+    const out: FrameDepth = {};
+    for (const s of DEPTH_SEGMENT_NAMES) {
+      const r = ratio(s);
+      if (r === null) continue;
+      let sense: -1 | 1;
+      const kind = kindOf(s);
+      if (kind === 'shin') sense = gait === 'walk' ? 1 : -1;
+      else if (kind === 'upper_arm') {
+        // The arm swings with the opposite leg: its own thigh and the other side's, by how foreshortened each is.
+        const own = ratio(`${s.slice(0, 2)}thigh` as DepthSegment);
+        const opp = ratio(other(`${s.slice(0, 2)}thigh` as DepthSegment));
+        sense = own === null || opp === null || Math.min(own, opp) >= FLAT_BAND[0] || own === opp ? 1 : opp < own ? 1 : -1;
+      } else sense = 1;
+      const sign = (r < FLAT_BAND[0] ? face * sense : 0) as -1 | 0 | 1;
+      if (sign === 1) signs.toward++;
+      else if (sign === -1) signs.away++;
+      else signs.flat++;
+      out[s] = { ratio: r, sign: sign === 0 ? 0 : sign, source: 'derived' };
+    }
+    return out;
+  });
+  return { frames, rest, facing, signs };
+}
+
+/** One frame's layers: the limbs nearest first, equal depths sharing a layer, and each limb's depth (px, + toward the camera). */
+export interface FrameLayers {
+  order: Limb[][];
+  depth: Partial<Record<Limb, number>>;
+}
+
+/** The depth one segment adds to its distal joint over its proximal one, px: sign × rest × √(1 − ratio²). */
+export function segmentDepth(d: SegmentDepth, length: number): number {
+  if (d.sign === 0 || !(d.ratio > 0)) return 0;
+  const r = Math.min(d.ratio, 1);
+  return d.sign * (length / d.ratio) * Math.sqrt(1 - r * r);
+}
+
+/** The limbs' front-to-back order on one frame, from its depth and its joints' drawn lengths. */
+export function layersOf(joints: Joints, depth: FrameDepth): FrameLayers {
+  const z: Partial<Record<Limb, number>> = {};
+  for (const limb of LIMB_NAMES) {
+    const [upper, lower] = LIMBS[limb];
+    const du = depth[upper];
+    const dl = depth[lower];
+    const lu = drawn(joints, upper);
+    const ll = drawn(joints, lower);
+    if (du === undefined || dl === undefined || lu === null || ll === null) continue;
+    const mid = segmentDepth(du, lu);
+    const end = mid + segmentDepth(dl, ll);
+    z[limb] = Math.round(((mid + end) / 2) * 100) / 100;
+  }
+  const placed = LIMB_NAMES.filter((l) => z[l] !== undefined).sort((a, b) => z[b]! - z[a]! || LIMB_NAMES.indexOf(a) - LIMB_NAMES.indexOf(b));
+  const order: Limb[][] = [];
+  for (const l of placed) {
+    const last = order[order.length - 1];
+    if (last !== undefined && z[last[0]!] === z[l]) last.push(l);
+    else order.push([l]);
+  }
+  return { order, depth: z };
+}
+
+/** A frame's layers as text: "r_arm > l_arm = r_leg > l_leg". */
+export const orderText = (order: Limb[][]): string => order.map((g) => g.join(' = ')).join(' > ');
+
+/** The source a sequence's depth came from, or null when its frames carry none. */
+export function depthSourceOf(frames: ReadonlyArray<{ depth?: FrameDepth }>): DepthSource | null {
+  for (const f of frames) for (const d of Object.values(f.depth ?? {})) return d.source;
+  return null;
+}
+
+/**
+ * retarget's DEPTH line (rig-c/pose#281): where the depth came from, on how many
+ * frames the limbs were ordered, and which limb was in front alone how often.
+ */
+export function depthLine(layers: readonly FrameLayers[], frames: ReadonlyArray<{ depth?: FrameDepth }>, gait: DepthGait | null): string {
+  const source = depthSourceOf(frames);
+  const from = source === null ? 'the sequence\'s depth (no segment named)' : source === 'derived' ? `the sequence's derived depth (clean --depth ${gait ?? '?'})` : 'the sequence\'s measured depth';
+  const ordered = layers.filter((l) => l.order.length > 0).length;
+  const front = LIMB_NAMES.map((limb) => `${limb} ${layers.filter((l) => l.order[0]?.length === 1 && l.order[0][0] === limb).length}`).join(', ');
+  const tied = layers.filter((l) => (l.order[0]?.length ?? 0) > 1).length;
+  return `DEPTH  layers from ${from}: the limbs ordered front to back on ${ordered} of ${layers.length} frame(s); in front alone: ${front}; tied in front on ${tied} (the report's layers)`;
+}

package/src/legs.ts

@@ -516,6 +516,12 @@ export interface Feet {
    * rule does not apply.
    */
   tracked?: Array<{ side: Side; frames: [number, number] }>;
+  /**
+   * rig-c/pose#280: the second support signal (the ankle's vertical speed), how
+   * often it contradicts ankle height, and which one decided each frame. Set by
+   * `supportsOf` on every reading.
+   */
+  signal?: SupportSignal;
 }
 
 /** A run of frames whose support the lower-ankle rule (rig-c/pose#113) reads differently from the reading before it. */
@@ -559,8 +565,17 @@ export function rollingFloor(ys: readonly number[], times: readonly number[]): n
  * The frames whose support this changes are `lowered`. On a frame where no foot
  * is planted because the only foot free is the higher one (rig-c/pose#119), the
  * lower foot is tracked (`tracked`).
+ *
+ * rig-c/pose#280: the ankle's vertical speed is read beside ankle height on
+ * every clip (`speedSignalOf`), and on a frontal view it decides the support
+ * (`frontalOf`); `signal` says which signal decided each frame.
  */
 export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number, inPlace = false, lowerAnkle = false): Feet {
+  return frontalOf(ankle, hip, heightSupportsOf(ankle, hip, times, secondsOf, inPlace, lowerAnkle));
+}
+
+/** The support read from ankle height alone: the rules above, #113's included (the whole reading before rig-c/pose#280). */
+function heightSupportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number, inPlace: boolean, lowerAnkle: boolean): Feet {
   if (inPlace || !lowerAnkle) return readSupports(ankle, hip, times, secondsOf, inPlace, false).feet;
   const { feet, released } = readSupports(ankle, hip, times, secondsOf, false, true);
   const before = readSupports(ankle, hip, times, secondsOf, false, false).feet.support;
@@ -727,6 +742,179 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
   return { feet: { legLength, support, supports, jumps, steps, changes, ...(tracked.length > 0 ? { tracked } : {}) }, released };
 }
 
+// --- the second signal: the ankle's vertical speed against the ground (rig-c/pose#280) ---
+
+/** A foot's contact on one frame, read from the ankles' vertical speed: one side, both, or neither (null). */
+export type Contact = Side | 'both' | null;
+
+export interface SpeedSignal {
+  /** Each side's ground speed: the median of its ankle's vertical step (picture px a frame, y down) over the frames outside every jump. */
+  ground: Record<Side, number>;
+  /** Per frame: the feet that move with the ground, on the step into the frame or the step out of it (null on a jump frame or where neither does). */
+  contact: Contact[];
+  /** The frames the two signals contradict: the lower ankle (by ≥ `PLANT_SWITCH` leg lengths) leaves the ground's speed while the higher moves with it. */
+  contradict: number[];
+  /** The frames both signals read: outside every jump. */
+  read: number;
+}
+
+/**
+ * The ankle's vertical speed as a support signal (rig-c/pose#280). A planted
+ * foot moves with the ground: still under a fixed camera, or sliding at the
+ * ground's speed in a gait drawn in place. Each side's ground speed is the
+ * median of its ankle's vertical step over the frames outside every jump —
+ * a walking foot is down on more than half of them — and a foot moves with it
+ * on a step that departs from it by less than `STILL_SPEED` of that side's leg
+ * length. A frame's foot is down when either the step into the frame or the
+ * step out of it moves with the ground, so a drawing a foot lands or lifts on
+ * reads it down. `contradict` lists the frames where this and ankle height
+ * disagree in the way a frontal view's depth makes them: the lower ankle is
+ * the moving one, the higher the one moving with the ground.
+ */
+export function speedSignalOf(ankle: Record<Side, readonly Pt[]>, feet: Pick<Feet, 'legLength' | 'jumps'>): SpeedSignal {
+  const n = ankle.r.length;
+  const jump = new Array<boolean>(n).fill(false);
+  for (const [a, b] of feet.jumps) for (let i = a; i <= b; i++) jump[i] = true;
+  const step = (s: Side, i: number): number | null => (i < 1 || i >= n || jump[i] || jump[i - 1] ? null : ankle[s][i]![1] - ankle[s][i - 1]![1]);
+  const ground = {} as Record<Side, number>;
+  for (const s of SIDES) {
+    const xs: number[] = [];
+    for (let i = 1; i < n; i++) {
+      const v = step(s, i);
+      if (v !== null) xs.push(v);
+    }
+    ground[s] = xs.length === 0 ? 0 : percentile(xs, 0.5);
+  }
+  const withGround = (s: Side, i: number): boolean => {
+    const v = step(s, i);
+    return v !== null && Math.abs(v - ground[s]) < STILL_SPEED * feet.legLength[s];
+  };
+  const down = (s: Side, i: number) => withGround(s, i) || withGround(s, i + 1);
+  const mean = (feet.legLength.r + feet.legLength.l) / 2;
+  const contact: Contact[] = [];
+  const contradict: number[] = [];
+  let read = 0;
+  for (let i = 0; i < n; i++) {
+    if (jump[i]) {
+      contact.push(null);
+      continue;
+    }
+    read++;
+    const r = down('r', i);
+    const l = down('l', i);
+    contact.push(r && l ? 'both' : r ? 'r' : l ? 'l' : null);
+    const gap = ankle.l[i]![1] - ankle.r[i]![1];
+    const lower: Side | null = Math.abs(gap) < PLANT_SWITCH * mean ? null : gap > 0 ? 'l' : 'r';
+    if (lower !== null && !down(lower, i) && down(lower === 'r' ? 'l' : 'r', i)) contradict.push(i);
+  }
+  return { ground, contact, contradict, read };
+}
+
+/**
+ * A clip whose two support signals contradict on more than this share of the
+ * frames both read is read as a frontal view (rig-c/pose#280), when its stride
+ * also shows in depth (`strideInDepth`). A frontal walk contradicts at every
+ * hand-over, for as long as the nearer foot is in the air below the planted one:
+ * 18 of 96 frames (18.8 %) on the tests' synthetic frontal walk, where ankle
+ * height alone hands support to the nearer foot 1 or 2 frames before it lands
+ * (16 frames in all, declared in place). Every clip the other tests read with
+ * its stride in depth contradicts on none; the shortest contradiction a walk
+ * can make, one frame a step, is 8.3 % of a 1 s cycle at 24 fps (2 of 24).
+ */
+export const FRONTAL_DISAGREE = 0.05;
+
+/** rig-c/pose#280: the two support signals of a clip, and which one decided each frame's support. */
+export interface SupportSignal {
+  /** The frames the signals contradict (`speedSignalOf`), of `read` frames both read. */
+  contradict: number[];
+  read: number;
+  /** Each side's ankle range in the picture, relative to its hip (5th to 95th percentile), px: the stride shows in y on a frontal view and in x on a side view. */
+  range: Record<Side, { x: number; y: number }>;
+  /** The stride shows in depth (y range over x range on both sides) and the signals contradict on more than `FRONTAL_DISAGREE` of the frames: the support comes from the vertical speed. */
+  frontal: boolean;
+  /** Per frame, the vertical speed's reading: the side down, both, or null (a jump, or neither foot moving with the ground). */
+  contact: Contact[];
+  /** Per frame, ankle height's reading (the support before #280). */
+  height: Array<Side | null>;
+  /** Per frame, the signal that decided the support: `speed`, `height`, or null where no foot supports. */
+  by: Array<'speed' | 'height' | null>;
+}
+
+/** Each side's ankle range relative to its hip, px, x and y (5th to 95th percentile). */
+function rangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>): Record<Side, { x: number; y: number }> {
+  const span = (xs: number[]) => percentile(xs, 0.95) - percentile(xs, 0.05);
+  const out = {} as Record<Side, { x: number; y: number }>;
+  for (const s of SIDES) out[s] = { x: span(ankle[s].map((a, i) => a[0] - hip[s][i]![0])), y: span(ankle[s].map((a, i) => a[1] - hip[s][i]![1])) };
+  return out;
+}
+
+/**
+ * rig-c/pose#280: the support from the ankle's vertical speed, on a frontal
+ * view. Seen from the front, a foot's depth is drawn as height, so the lower
+ * ankle is the nearer foot, which may be the one in the air. A clip is read as
+ * frontal when both hold: its stride shows in depth — on each side the ankle's
+ * range relative to its hip is larger in y than in x (a side view's stride is
+ * in x) — and the two signals contradict on more than `FRONTAL_DISAGREE` of the
+ * frames both read. Then each frame's support is the vertical speed's: the one
+ * foot down; on frames both are down, the foot that landed (the other side from
+ * the support before the run, or, at the clip's start, the side that stays down
+ * after it), so support passes on the frame the incoming foot lands (as #102
+ * takes it from the landing frame); and ankle height's reading where neither
+ * foot moves with the ground. A plant ends where the other foot lands, so no
+ * step releases one and none is tracked (#113's `lowered` and #119's `tracked`
+ * are not read). Otherwise the feet are ankle height's, unchanged.
+ */
+function frontalOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, feet: Feet): Feet {
+  const sig = speedSignalOf(ankle, feet);
+  const range = rangeOf(ankle, hip);
+  const strideInDepth = SIDES.every((s) => range[s].y > range[s].x);
+  const frontal = strideInDepth && sig.read > 0 && sig.contradict.length > FRONTAL_DISAGREE * sig.read;
+  const height = feet.support.map((s) => s ?? null);
+  const signal = (by: SupportSignal['by']): SupportSignal => ({ contradict: sig.contradict, read: sig.read, range, frontal, contact: sig.contact, height, by });
+  if (!frontal) return { ...feet, signal: signal(height.map((s) => (s === null ? null : 'height'))) };
+  const n = height.length;
+  const other = (s: Side): Side => (s === 'r' ? 'l' : 'r');
+  const support: Array<Side | null> = new Array<Side | null>(n).fill(null);
+  const by: SupportSignal['by'] = new Array<'speed' | 'height' | null>(n).fill(null);
+  const fromHeight = (i: number) => {
+    support[i] = height[i]!;
+    by[i] = height[i] === null ? null : 'height';
+  };
+  for (let i = 0; i < n; i++) {
+    const c = sig.contact[i] ?? null;
+    if (c === 'r' || c === 'l') {
+      support[i] = c;
+      by[i] = 'speed';
+    } else if (c === 'both') {
+      let b = i;
+      while (b + 1 < n && sig.contact[b + 1] === 'both') b++;
+      const before = i > 0 ? (support[i - 1] ?? null) : null;
+      const after = b + 1 < n ? (sig.contact[b + 1] ?? null) : null;
+      const landed: Side | null = before !== null ? other(before) : after === 'r' || after === 'l' ? after : null;
+      for (let k = i; k <= b; k++) {
+        if (landed === null) fromHeight(k);
+        else {
+          support[k] = landed;
+          by[k] = 'speed';
+        }
+      }
+      i = b;
+    } else fromHeight(i);
+  }
+  const supports: Feet['supports'] = [];
+  const changes: Feet['changes'] = [];
+  for (let i = 0; i < n; i++) {
+    const s = support[i];
+    if (s === null || s === undefined) continue;
+    const prev = i > 0 ? (support[i - 1] ?? null) : null;
+    if (prev !== s) changes.push({ frame: i, from: prev, to: s });
+    const last = supports[supports.length - 1];
+    if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
+    else supports.push({ side: s, frames: [i, i] });
+  }
+  return { legLength: feet.legLength, support, supports, jumps: feet.jumps, steps: [], changes, signal: signal(by) };
+}
+
 /** One support span's shift onto the floor (rig-c/pose#85): its side, its frames, and floor − its planted height, world units. */
 export interface FloorShift {
   side: Side;
@@ -1584,3 +1772,4 @@ export function holdBlend(blends: readonly BlendFrame[], n: number, posed: (i: n
   const range = rangeUsed(lower, held);
   return { bounds: STANCE_BOUNDS, ...(range === null ? {} : { range }), runs, over, stretch };
 }
+

package/src/map.ts

@@ -58,6 +58,11 @@
  * `place: "by-hip"` (rig-c/pose#93) places the wrist of each of its chains that
  * `pose` puts within one hip width of the mid-hip by its offset from the hip
  * (`byHipChains`; the retarget solves it).
+ * `phase: "left-step" | "right-step"` (rig-c/pose#286) declares a gait set drawn
+ * for the foot that is stepping (swinging), named by it — left-step: the left foot is stepping; shown while the right foot supports (right-step
+ * mirrors it). It shows exactly on the report's `feet.supports` spans of the
+ * supporting foot and is switched on the support hand-over, not on angle
+ * distance (`PHASE_SIDE`).
  * `switch.ts` decides when each one shows.
  */
 import type { RawBone } from 'rig-c/core';
@@ -86,6 +91,9 @@ export interface Translate {
   joint: string;
   scale: { pose: [string, string]; rig: [string, string] };
 }
+/** The step sides a set may declare as its `phase` (rig-c/pose#286), and the supporting foot each one shows on: left-step: the left foot is stepping; shown while the right foot supports. */
+export const PHASE_SIDE = { 'left-step': 'r', 'right-step': 'l' } as const;
+export type Phase = keyof typeof PHASE_SIDE;
 /** An alternate drawing: a set of slots switched together, and the key skeleton it is selected by. */
 export interface AlternateSet {
   name: string;
@@ -113,6 +121,8 @@ export interface AlternateSet {
   support?: string[];
   /** `anchor` (rig-c/pose#191): the set's two-bone arm chains whose hand-tip is anchored to the set's `drawn` head-local offset while the set shows. */
   anchor?: string[];
+  /** `phase` (rig-c/pose#286): the stepping foot the set is drawn for (left-step: the left foot is stepping; shown while the right foot supports); it shows exactly on that supporting foot's `feet.supports` spans, switched on the hand-over. Absent: the angle rule. */
+  phase?: Phase;
 }
 export interface YawSet {
   set: string;
@@ -423,7 +433,7 @@ function readBodyMap(p: Problems, where: string, raw: unknown): BodyMap | undefi
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
-const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …], place?: "by-hip" }';
+const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …], place?: "by-hip", phase?: "left-step" | "right-step" }';
 
 /** The joints a wrist is, for `place: "by-hip"`: a chain whose last joint is one of them carries a wrist. */
 export const WRISTS: readonly string[] = ['r_wrist', 'l_wrist'];
@@ -472,7 +482,7 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
       p.add('MAP_ALT_SHAPE', `${aw} is ${typeName(a)}; a set is ${SET_SHAPE}`);
       return;
     }
-    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place', 'symmetric', 'support', 'anchor']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place', 'symmetric', 'support', 'anchor', 'phase']);
     const name = typeof a.name === 'string' && a.name !== '' ? a.name : null;
     if (name === null) p.add('MAP_ALT_NAME', `${aw} "name" is ${typeName(a.name)}; it must be a non-empty string`);
     else if (names.has(name)) p.add('MAP_ALT_NAME', `${aw} "name" "${name}" names two sets`);
@@ -676,7 +686,18 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         if (ok) anchor = anc;
       }
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }), ...(symmetric === undefined ? {} : { symmetric }), ...(support === undefined ? {} : { support }), ...(anchor === undefined ? {} : { anchor }) });
+    let phase: Phase | undefined;
+    if ('phase' in a) {
+      const phases = Object.keys(PHASE_SIDE);
+      if (typeof a.phase !== 'string' || !phases.includes(a.phase)) {
+        p.add('MAP_ALT_PHASE', `${label} "phase" is ${JSON.stringify(a.phase)}; it is the stepping foot the set is drawn for, one of ${phases.map((x) => `"${x}"`).join(', ')} (left-step: the left foot is stepping; shown while the right foot supports)`);
+        ok = false;
+      } else if ('frames' in a) {
+        p.add('MAP_ALT_PHASE', `${label} names both "phase" and "frames"; a phase set shows on its supporting foot's spans, and a window would cut them — drop one`);
+        ok = false;
+      } else phase = a.phase as Phase;
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }), ...(symmetric === undefined ? {} : { symmetric }), ...(support === undefined ? {} : { support }), ...(anchor === undefined ? {} : { anchor }), ...(phase === undefined ? {} : { phase }) });
   });
   return out;
 }

package/src/outdir.ts

@@ -0,0 +1,54 @@
+/**
+ * Where a command's output goes (rig-c/pose#239, #284). A file a command writes goes into a
+ * directory the user named: one that is not there yet is made just before the write (mkdir -p),
+ * and a `made directory` line says so and which paths it holds. A file where a directory has to
+ * be made, or a directory that cannot be written into, is refused by name (`ARG_PATH`) before
+ * anything is read or written.
+ */
+import { accessSync, constants, existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { Problems } from './problems.ts';
+
+/** The directories to make before writing, each with the `<flag> <path>`s written into it, in the order named. */
+export type OutDirs = Map<string, string[]>;
+
+const writable = (dir: string): boolean => {
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Check where each named output lands: its directory is there, or the nearest existing ancestor
+ * is a directory this process can write into. A miss is added to `p`; a directory still to make
+ * is added to `dirs`. A directory a flag names itself (--build, --render) is checked by its parent.
+ */
+export function planOutDirs(outputs: ReadonlyArray<readonly [string, string | undefined]>, p: Problems, dirs: OutDirs = new Map()): OutDirs {
+  for (const [flag, path] of outputs) {
+    if (path === undefined) continue;
+    const dir = dirname(path);
+    let up = dir;
+    while (!existsSync(up) && dirname(up) !== up) up = dirname(up);
+    if (!statSync(up).isDirectory()) p.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 && !writable(up)) p.add('ARG_PATH', `${flag} ${path} — ${up} is not writable, so directory ${dir} cannot be made under it`);
+    else if (up !== dir) dirs.set(dir, [...(dirs.get(dir) ?? []), `${flag} ${path}`]);
+  }
+  return dirs;
+}
+
+/** Make each planned directory (mkdir -p) and print its line; run after the command is green, just before it writes. */
+export function makeOutDirs(dirs: OutDirs, tell: (l: string) => void): void {
+  for (const [dir, flags] of dirs) {
+    if (existsSync(dir)) continue;
+    mkdirSync(dir, { recursive: true });
+    tell(madeLine(dir, flags));
+  }
+}
+
+/** 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`;
+}