@rig-c/pose 0.38.0 → 0.40.0

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/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`;
+}

package/src/pelvis.ts

@@ -22,7 +22,15 @@
  * - `waistband`: the top edge of a garment covering the hips — the colour at the
  *   hips' midpoint, where it is not the background's, and in each column of the
  *   hip span the first row from 1.5 hip widths above the hips where three pixels
- *   in a row carry it; the line fitted through those tops.
+ *   in a row carry it; the line fitted through those tops. The colour must hold
+ *   (rig-c/pose#293): ≥ `HOLD` of the patch's pixels carry its median. A dithered
+ *   or paletted garment does not hold pixel by pixel — its channels alternate
+ *   between palette steps — so it is read through the mean of a 5×5 window,
+ *   which does; hips on the band's top edge give a patch half garment, half
+ *   ground, so the patch is tried below them (up to two patch radii), and the
+ *   scan runs down to where the colour was found. The first patch that holds
+ *   and is not the background is the garment; with none, the midpoint's median
+ *   is read as it is.
  *
  * The forearms are not read: pixels near the segments elbow → wrist (and the
  * hands) are masked, since a hanging arm passes the hips in a walk. A frame
@@ -40,6 +48,7 @@ import type { Body18 } from './joints.ts';
 import { personTrack, readPoseSequence, writePoseSequence, type Joint, type PelvisSource, type PoseSequence } from './pose.ts';
 import { isObject, parseJson, Problems, refuseUnknownKeys, typeName } from './problems.ts';
 import { pictureAngle, wrap } from './retarget.ts';
+import { makeOutDirs, planOutDirs } from './outdir.ts';
 
 type Pt = [number, number];
 type RGB = [number, number, number];
@@ -53,6 +62,10 @@ export const PELVIS_KEYS_SPEC = 'rig-pose-pelvis-keys/1';
 export const FIGURE_DIFF = 64;
 /** A pixel carries the garment's colour when no channel differs from it by more than this. */
 export const GARMENT_DIFF = 40;
+/** A garment's colour holds on a patch when at least this share of its pixels carry it (within `GARMENT_DIFF`). */
+export const HOLD = 0.75;
+/** A garment that does not hold pixel by pixel is read through the mean of the square window this many px either side of a pixel (5×5: a 4×4 ordered dither's period and a pixel more). */
+export const DITHER_RADIUS = 2;
 /** The silhouette reader scores lines within this many degrees of level. */
 export const MAX_TILT = 40;
 /** A line is read when it covers at least this share of the hip span's columns. */
@@ -64,8 +77,12 @@ export const ARM_RADIUS = 0.15;
 /** Hips closer than this in the picture, px, have no span to read across (a figure seen side-on). */
 export const MIN_SPAN = 6;
 
-/** One frame's reading: the tilt (Spine degrees, r_hip → l_hip), or why it was declined. */
-export type Reading = { tilt: number; cover: number; rms: number } | { kind: string; why: string };
+/**
+ * One frame's reading: the tilt (Spine degrees, r_hip → l_hip), or why it was declined. A waistband
+ * read through the window mean says so (`mean`), and one whose colour was found below the hips says
+ * how far (`below`, px).
+ */
+export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number } | { kind: string; why: string };
 
 /** The frame as RGB over white, its background colour, and which pixels are masked (forearms, hands). */
 interface Frame {
@@ -221,22 +238,76 @@ function silhouette(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
   return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms };
 }
 
+/** The mean colour of the unmasked pixels in the window `DITHER_RADIUS` either side of (x, y), or null when all are masked. Cached per frame. */
+function meanOf(f: Frame): (x: number, y: number) => RGB | null {
+  const cache = new Map<number, RGB | null>();
+  return (x, y) => {
+    const key = y * f.w + x;
+    const hit = cache.get(key);
+    if (hit !== undefined) return hit;
+    const s: RGB = [0, 0, 0];
+    let n = 0;
+    for (let v = Math.max(0, y - DITHER_RADIUS); v <= Math.min(f.h - 1, y + DITHER_RADIUS); v++) {
+      for (let u = Math.max(0, x - DITHER_RADIUS); u <= Math.min(f.w - 1, x + DITHER_RADIUS); u++) {
+        if (f.masked(u, v)) continue;
+        const p = f.rgb(u, v);
+        s[0] += p[0];
+        s[1] += p[1];
+        s[2] += p[2];
+        n++;
+      }
+    }
+    const m: RGB | null = n === 0 ? null : [s[0] / n, s[1] / n, s[2] / n];
+    cache.set(key, m);
+    return m;
+  };
+}
+
 function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols: number, rHip: Pt, lHip: Pt): Reading {
-  // The garment's colour: the median over the unmasked pixels near the hips' midpoint.
+  // The garment's colour: the median over the unmasked pixels of a patch at the hips' midpoint (or below it), as they are or through the window mean.
   const r = Math.max(2, 0.3 * span);
-  const patch: RGB[] = [];
-  for (let y = Math.floor(c[1] - r); y <= Math.ceil(c[1] + r); y++) {
-    for (let x = Math.floor(c[0] - r); x <= Math.ceil(c[0] + r); x++) {
-      if (x < 0 || y < 0 || x >= f.w || y >= f.h || Math.hypot(x - c[0], y - c[1]) > r || f.masked(x, y)) continue;
-      patch.push(f.rgb(x, y));
+  const raw = (x: number, y: number): RGB | null => f.rgb(x, y);
+  const mean = meanOf(f);
+  const patchAt = (cy: number, colour: (x: number, y: number) => RGB | null): { g: RGB; holds: boolean } | null => {
+    const patch: RGB[] = [];
+    for (let y = Math.floor(cy - r); y <= Math.ceil(cy + r); y++) {
+      for (let x = Math.floor(c[0] - r); x <= Math.ceil(c[0] + r); x++) {
+        if (x < 0 || y < 0 || x >= f.w || y >= f.h || Math.hypot(x - c[0], y - cy) > r || f.masked(x, y)) continue;
+        const p = colour(x, y);
+        if (p !== null) patch.push(p);
+      }
     }
+    if (patch.length === 0) return null;
+    const g: RGB = [0, 1, 2].map((k) => median(patch.map((p) => p[k]!))) as RGB;
+    return { g, holds: patch.filter((p) => diff(p, g) <= GARMENT_DIFF).length >= HOLD * patch.length };
+  };
+  const mid = patchAt(c[1], raw);
+  if (mid === null) return { kind: 'hips behind a forearm', why: 'the hips\' midpoint is covered by a forearm; no garment colour to read' };
+  // The first patch that holds and is not the background: at the midpoint, then one and two patch radii below; as they are, then through the window mean.
+  let found: { g: RGB; below: number; isMean: boolean } | null = null;
+  for (const below of [0, r, 2 * r]) {
+    for (const isMean of [false, true]) {
+      const pa = below === 0 && !isMean ? mid : patchAt(c[1] + below, isMean ? mean : raw);
+      if (pa !== null && pa.holds && diff(pa.g, f.bg) > FIGURE_DIFF) {
+        found = { g: pa.g, below, isMean };
+        break;
+      }
+    }
+    if (found !== null) break;
   }
-  if (patch.length === 0) return { kind: 'hips behind a forearm', why: 'the hips\' midpoint is covered by a forearm; no garment colour to read' };
-  const g: RGB = [0, 1, 2].map((k) => median(patch.map((p) => p[k]!))) as RGB;
+  // None: the midpoint's median as it is.
+  const g = found?.g ?? mid.g;
+  const isMean = found?.isMean ?? false;
+  const below = found?.below ?? 0;
   if (diff(g, f.bg) <= FIGURE_DIFF) return { kind: 'no garment over the hips', why: `the colour at the hips' midpoint (${g.map((v) => v.toFixed(0)).join(', ')}) is the background's (${f.bg.map((v) => v.toFixed(0)).join(', ')})` };
   const top = Math.max(0, Math.floor(c[1] - 1.5 * span));
-  const bottom = Math.floor(c[1]);
-  const garment = (x: number, y: number) => y < f.h && diff(f.rgb(x, y), g) <= GARMENT_DIFF;
+  const bottom = Math.floor(c[1] + below);
+  const colourAt = isMean ? mean : raw;
+  const garment = (x: number, y: number) => {
+    if (y >= f.h) return false;
+    const p = colourAt(x, y);
+    return p !== null && diff(p, g) <= GARMENT_DIFF;
+  };
   const tops: Pt[] = [];
   let above = 0;
   for (let x = x0; x <= x1; x++) {
@@ -258,7 +329,7 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
   if (fit === null) return { kind: 'no line', why: 'the garment\'s top edge does not fit a line (fewer than three columns)' };
   if (fit.rms > MAX_RMS) return { kind: 'not a straight waistband', why: `the garment's top edge lies ${fit.rms.toFixed(2)} px from its line (root mean square > ${MAX_RMS}); not a straight waistband` };
   if (Math.abs(Math.atan(fit.m)) * (180 / Math.PI) > 45) return { kind: 'waistband too steep', why: `the garment's top edge runs ${(Math.atan(fit.m) * (180 / Math.PI)).toFixed(1)}° from level; a waistband is within 45°` };
-  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms };
+  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}) };
 }
 
 /**
@@ -341,6 +412,17 @@ function declinedRuns(readings: Reading[]): Array<{ from: number; to: number; ki
   return out;
 }
 
+/** How the waistband found its colour where it was not the midpoint's pixels as they are (rig-c/pose#293); empty when every frame read them. */
+function viaNote(readings: Reading[]): string {
+  const ok = readings.flatMap((r) => ('tilt' in r ? [r] : []));
+  const mean = ok.filter((r) => r.mean === true).length;
+  const below = ok.filter((r) => r.below !== undefined).length;
+  const parts: string[] = [];
+  if (mean > 0) parts.push(`${mean} through the ${2 * DITHER_RADIUS + 1}×${2 * DITHER_RADIUS + 1} window mean (the garment's colour does not hold pixel by pixel: a dithered or paletted picture)`);
+  if (below > 0) parts.push(`${below} with the colour found below the hips (up to ${Math.max(...ok.map((r) => r.below ?? 0)).toFixed(1)} px; the hips on the band's edge)`);
+  return parts.length === 0 ? '' : `; of the frames read, ${parts.join(', ')}`;
+}
+
 /** The sequence with the track: the one person, `pelvisTilt` on every frame, `pelvisSource`. */
 export function withPelvis(seq: PoseSequence, person: string, tilt: ReadonlyArray<number | null>, source: PelvisSource): PoseSequence {
   return {
@@ -355,6 +437,7 @@ export function runPelvis(a: PelvisArgs, say: (l: string) => void): void {
   const seq = readPoseSequence(readFileSync(a.pose, 'utf8'), a.pose);
   const p = new Problems();
   if (seq.cleaned !== undefined) p.add('PELVIS_AFTER_CLEAN', `${a.pose} carries a "cleaned" record; rig-pose pelvis reads a sequence before clean, so that clean smooths the track it writes — run it on the sequence clean read`);
+  const outDirs = planOutDirs([['--out', a.out]], p);
   if (seq.pelvisSource !== undefined) p.add('PELVIS_TRACK', `${a.pose} already carries a pelvis track (pelvisSource "${seq.pelvisSource}"); a sequence is read once — run rig-pose pelvis on the sequence without it`);
   p.throwIfAny();
   const track = personTrack(seq, a.person, a.pose);
@@ -370,6 +453,7 @@ export function runPelvis(a: PelvisArgs, say: (l: string) => void): void {
     const tilt = readPelvisKeys(readFileSync(a.keys, 'utf8'), a.keys, n);
     say(`rig-pose pelvis: ${n} frame(s) of person "${person}" from ${a.pose}, from the hand keys in ${a.keys}`);
     say(`  PELVIS keys: linear between the keys (the short way round) and held outside them, on all ${n} frame(s); swing ${swingOf(tilt).toFixed(2)}° (Spine degrees, r_hip → l_hip)`);
+    makeOutDirs(outDirs, say);
     writeFileSync(a.out, writePoseSequence(withPelvis(seq, person, tilt, 'keys')));
     say(`  wrote ${a.out} (pelvisSource "keys", rig-pose-sequence/1.1)`);
     return;
@@ -404,10 +488,11 @@ export function runPelvis(a: PelvisArgs, say: (l: string) => void): void {
   if (read.length > 0) {
     const covers = readings.flatMap((r) => ('tilt' in r ? [r.cover] : []));
     const rms = readings.flatMap((r) => ('tilt' in r ? [r.rms] : []));
-    say(`  PELVIS ${a.mode} read ${read.length} of ${n} frame(s), ${n - read.length} declined (null: marked, not guessed); swing ${swingOf(read).toFixed(2)}° over the frames read (Spine degrees, r_hip → l_hip); cover ${(100 * Math.min(...covers)).toFixed(0)}–${(100 * Math.max(...covers)).toFixed(0)}% of the hip span, fit within ${Math.max(...rms).toFixed(2)} px`);
+    say(`  PELVIS ${a.mode} read ${read.length} of ${n} frame(s), ${n - read.length} declined (null: marked, not guessed); swing ${swingOf(read).toFixed(2)}° over the frames read (Spine degrees, r_hip → l_hip); cover ${(100 * Math.min(...covers)).toFixed(0)}–${(100 * Math.max(...covers)).toFixed(0)}% of the hip span, fit within ${Math.max(...rms).toFixed(2)} px${viaNote(readings)}`);
   } else {
     say(`  PELVIS ${a.mode} read none of the ${n} frame(s) (every frame null: marked, not guessed); retarget keys the hip line and its PELVIS line says so`);
   }
+  makeOutDirs(outDirs, say);
   writeFileSync(a.out, writePoseSequence(withPelvis(seq, person, tilt, a.mode)));
   say(`  wrote ${a.out} (pelvisSource "${a.mode}", rig-pose-sequence/1.1)`);
 }