@rig-c/pose 0.16.0 → 0.18.0

package/src/clean.ts

@@ -4,7 +4,7 @@
  * hanging wrist moves ±20 px a frame and a cloak-hidden leg jumps 100+ px; this
  * removes that once, at the sequence, where others can inspect the result.
  *
- * Four steps, in this order, each on one person's joints:
+ * Five steps, in this order, each on one person's joints:
  *
  * 1. **Spikes.** A joint more than `SPIKE_TRUNKS` (0.2) trunk lengths from its
  *    `SPIKE_WINDOW`-frame (5) median takes the median. The trunk is neck →
@@ -23,7 +23,13 @@
  *    `rest`. A window of 1 is none.
  * 4. **Floor.** With `loop` only: the whole figure is moved in y by one
  *    constant, so the lowest ankle over the cycle (the largest y of either
- *    ankle on any frame) is at its height before smoothing.
+ *    ankle on any frame) is at its height before smoothing. A loop is also
+ *    written with `travel: "in-place"` (rig-c/pose#92): one cycle of a gait,
+ *    repeated, does not travel, whatever its supporting foot does in the
+ *    picture.
+ * 5. **Hold** (#91, unless `hold` is "off"). A joint that has stopped is
+ *    written at one position: detector noise on a still joint is not motion.
+ *    `holdStill` below states the test and the write.
  *
  * What a median is here: per coordinate (x and y apart), over the frames of the
  * window on which the joint has a position — its own frame included, any state.
@@ -39,7 +45,7 @@
  * score are the detector's and are written as they were read: this step moves
  * positions only — with one stated exception, `hipsInferred` below.
  *
- * `hipsInferred` (rig-c/pose#63, `--hips-inferred`): after the four steps, r_hip
+ * `hipsInferred` (rig-c/pose#63, `--hips-inferred`): after the steps, r_hip
  * and l_hip are marked `inferred` on every frame where they have a position,
  * and the record says who said so (`{ by: 'declared' }`, the person running
  * clean). Positions and scores are not touched by it, so retarget's keys are
@@ -59,8 +65,13 @@
  * Pure: no clock, no randomness, no disk.
  */
 import { BODY18, type Body18 } from './joints.ts';
-import type { CleanRecord, CleanSpike, Joint, PoseSequence } from './pose.ts';
-import { CLEAN_SPEC, personTrack, sortedJoints } from './pose.ts';
+import type { CleanRecord, CleanSeam, CleanSpike, CleanUnheld, Joint, PoseSequence } from './pose.ts';
+
+/** A joint not held inside a region where others are (#91): the test it fails there and its figure. */
+export type Unheld = CleanUnheld;
+/** Two holds of one joint back to back (#91): the second's first frame, and the step between their medians. */
+export type Seam = CleanSeam;
+import { CLEAN_SPEC, personTrack, sortedJoints, TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems } from './problems.ts';
 
 /** A spike is a joint this many trunk lengths or more from its median. */
@@ -75,6 +86,16 @@ export const OCCLUSION_SCORE = 0.3;
 export const LEGS: readonly Body18[] = ['r_hip', 'r_knee', 'r_ankle', 'l_hip', 'l_knee', 'l_ankle'];
 /** The polynomial's degree. */
 const ORDER = 2;
+/** The stillness hold (#91): a joint's speed, trunk lengths per frame, under which a frame can be still (`--hold-speed`). */
+export const HOLD_SPEED = 0.015;
+/** The stillness hold: how far, in trunk lengths, a joint may lie from its span median (`--hold-reach`). */
+export const HOLD_REACH = 0.03;
+/** The shortest hold, seconds: the first frame's time to the end of the last. */
+export const HOLD_MIN_SECONDS = 0.5;
+/** The frames before a hold over which the positions blend into it. */
+export const HOLD_BLEND = 6;
+/** The speed's median window, frames. */
+export const HOLD_SPEED_WINDOW = 5;
 
 export interface CleanParams {
   /** The sequence is one cycle: every window wraps, and the floor is re-pinned. */
@@ -85,6 +106,12 @@ export interface CleanParams {
   rest: number;
   /** Mark r_hip and l_hip `inferred` wherever they have a position (#63): the person running clean declares it. */
   hipsInferred?: boolean;
+  /**
+   * The stillness hold (#91): its thresholds, or "off". Absent, the step is not
+   * run and the record does not name it (a caller written before #91); the CLI
+   * always passes one.
+   */
+  hold?: { speed: number; reach: number } | 'off';
 }
 
 /** The joints `--hips-inferred` marks. */
@@ -113,6 +140,23 @@ export interface Floor {
   shift: number;
 }
 
+export interface HoldFound {
+  joint: Body18;
+  /** The span, inclusive. */
+  frames: [number, number];
+  /** First frame's time to the end of the last, seconds. */
+  seconds: number;
+  /** The joint's largest 5-frame median speed on the span, trunk lengths per frame. */
+  speed: number;
+  /** Its largest distance from its span median, trunk lengths. */
+  reach: number;
+  /** The frames blended in before it and out after it, inclusive; null where there are none. */
+  blendIn: [number, number] | null;
+  blendOut: [number, number] | null;
+  /** The joint's jitter over the triples inside the span, px/f²: cleaned, and held. */
+  jitter: { before: number | null; after: number | null };
+}
+
 export interface Cleaned {
   seq: PoseSequence;
   record: CleanRecord;
@@ -131,6 +175,12 @@ export interface Cleaned {
   triples: number;
   /** With `hipsInferred`: how many joint-frames were marked `inferred`, per hip. */
   inferred: { r_hip: number; l_hip: number } | null;
+  /** The stillness holds (#91), one per joint and span, in frame then body-18 order; empty when none was found or the step is off or not run. */
+  holds: HoldFound[];
+  /** The joints not held inside a region where others are, with the test each fails there. */
+  unheld: Unheld[];
+  /** Back-to-back holds of one joint, cross-faded, in frame then body-18 order. */
+  seams: Seam[];
 }
 
 /**
@@ -278,6 +328,225 @@ export function jitterOf(all: readonly Series[], loop: boolean): { value: number
   return { value: count === 0 ? null : sum / count, triples: count };
 }
 
+/**
+ * The stillness hold (#91), on the cleaned positions (after the smoothing and
+ * the floor), joint by joint: stillness is a property of a joint, so a joint
+ * that has stopped is held while one beside it still moves.
+ *
+ * A joint's speed on frame i is its movement from frame i − 1 in trunk lengths
+ * (wrapping with `loop`; none where either frame has no position), taken as a
+ * `HOLD_SPEED_WINDOW`-frame (5) median. The joint is still on a frame where it
+ * has a position and a median speed under `speed` (no speed in its window is
+ * not still: its speed is not known).
+ *
+ * A hold of a joint is a span of its still frames lasting at least
+ * `HOLD_MIN_SECONDS` (first frame's time to the end of the last) over which it
+ * stays within `reach` trunk lengths of its own per-coordinate span median. The
+ * span is chosen greedily, left to right, inside each run of still frames:
+ * from a start it grows one frame at a time while the reach holds on the grown
+ * span (its median re-read each time) and stops at the first frame that breaks
+ * it; if what it reached lasts long enough it is a hold and the next start is
+ * the frame after it, else the start moves one frame on. A span never crosses
+ * the loop's seam.
+ *
+ * On every frame of a hold the joint takes its span median. It blends in over
+ * the `HOLD_BLEND` (6) frames before (p + w (held − p), w = (6 − k)/6 on the
+ * k-th frame before: the 6th stays as cleaned, the frame before is 5/6 of the
+ * way) and out over the 6 frames after, mirrored (the frame after is 5/6 of the
+ * way, the 6th after stays as cleaned). A blend frame outside the clip, or
+ * inside another hold of the same joint, is not touched; where two blends of
+ * the same joint meet, the frame takes the one with the larger weight (the
+ * earlier hold on a tie). No position is invented: a joint without one on a
+ * frame stays without one.
+ *
+ * A seam is two holds of a joint meeting: the first ending on frame k and the
+ * next starting on k + 1 + g, with a gap of g < `HOLD_BLEND` frames between
+ * them (0 when they are back to back). Their medians differ, and stepping from
+ * one to the other across a frame or a short gap would be a jump. The seam
+ * cross-fades over `HOLD_BLEND` + g frames, symmetric about the gap's centre:
+ * frames k − 2 … k + 3 + g take m₁ + w (m₂ − m₁) with w = (2j + 1)/(2(6 + g))
+ * on the j-th of them (for g = 0: 1/12, 3/12, … 11/12, the blend's 1/6 steps
+ * placed symmetric about the seam), so no frame moves more than 1/(6 + g) of the
+ * step. The cross-fade is written after the blends, so it replaces them on the
+ * gap's frames; a frame outside the two holds and the gap is not touched, nor a
+ * frame without a position; where two seams' frames meet (a hold of under 6
+ * frames between them), the later seam is written last. Each seam is recorded
+ * with the joint, the second hold's first frame, the step |m₂ − m₁| in trunk
+ * lengths and the gap.
+ *
+ * A hold that carries a cross-fade's frames has a non-zero jitter after: the
+ * ramp's own curvature, not noise. The lines say "ramp" beside it.
+ *
+ * Where joints are held, the others are read too, so the lines can say why
+ * they were not: the frames any held span covers are joined into regions
+ * (overlapping or touching spans), and every run of a region's frames on which
+ * a joint has a position and no hold of its own is named with the test it
+ * fails over that run — `speed` (its largest median speed there, null where
+ * its speed is not known on some frame), else `reach` (its largest distance
+ * from its median over the run), else `short` (it passes both, and the run
+ * lasts under `HOLD_MIN_SECONDS`; the figure is its seconds), else `span` (it
+ * passes all three over the run, and its greedy spans broke elsewhere; the
+ * figure is its reach).
+ */
+export function holdStill(series: ReadonlyMap<Body18, Series>, times: readonly number[], trunk: number, speed: number, reach: number, loop: boolean, minSeconds = HOLD_MIN_SECONDS): { held: Map<Body18, Series>; holds: HoldFound[]; unheld: Unheld[]; seams: Seam[] } {
+  const n = times.length;
+  const names = BODY18.filter((name) => series.has(name));
+  const endOf = (i: number): number => (i + 1 < n ? times[i + 1]! : n > 1 ? 2 * times[i]! - times[i - 1]! : times[i]!);
+  const secondsOf = (a: number, b: number): number => Math.round((endOf(b) - times[a]!) * 1e6) / 1e6;
+  const med = new Map<Body18, Array<number | null>>();
+  for (const name of names) {
+    const xs = series.get(name)!;
+    const v: Array<number | null> = xs.map((p, i) => {
+      if (p === null || n < 2) return null;
+      if (!loop && i === 0) return null;
+      const q = xs[(i - 1 + n) % n];
+      if (q === null || q === undefined) return null;
+      return Math.hypot(p[0] - q[0], p[1] - q[1]) / trunk;
+    });
+    med.set(name, v.map((_, i) => {
+      const w = windowAt(i, n, HOLD_SPEED_WINDOW, loop).map((j) => v[j]).filter((x): x is number => x !== null && x !== undefined);
+      return w.length === 0 ? null : median1(w);
+    }));
+  }
+  /** One joint's distance (largest) from its per-coordinate median over a..b, trunk lengths, and that median; null where it has no position there. */
+  const spanOf = (name: Body18, a: number, b: number): { reach: number; at: Pt } | null => {
+    const pts = series.get(name)!.slice(a, b + 1).filter((p): p is Pt => p !== null);
+    if (pts.length === 0) return null;
+    const m: Pt = [median1(pts.map((p) => p[0])), median1(pts.map((p) => p[1]))];
+    let worst = 0;
+    for (const p of pts) worst = Math.max(worst, Math.hypot(p[0] - m[0], p[1] - m[1]) / trunk);
+    return { reach: worst, at: m };
+  };
+  const held = new Map<Body18, Series>();
+  const holds: HoldFound[] = [];
+  const seams: Seam[] = [];
+  for (const name of names) {
+    const xs = series.get(name)!;
+    const sp = med.get(name)!;
+    const still = xs.map((p, i) => p !== null && sp[i] !== null && sp[i] !== undefined && sp[i]! < speed);
+    const spans: Array<[number, number]> = [];
+    let s = 0;
+    while (s < n) {
+      if (!still[s]) {
+        s++;
+        continue;
+      }
+      let e = s;
+      while (e + 1 < n && still[e + 1] && spanOf(name, s, e + 1)!.reach <= reach) e++;
+      if (secondsOf(s, e) >= minSeconds - 1e-9) {
+        spans.push([s, e]);
+        s = e + 1;
+      } else s++;
+    }
+    const out: Series = xs.map((p) => (p === null ? null : [p[0], p[1]] as Pt));
+    const inHold = (i: number) => spans.some(([a, b]) => i >= a && i <= b);
+    // The blends: on each frame outside a hold, the largest weight any hold of this joint gives it (the earlier hold on a tie).
+    const blend = new Map<number, { w: number; at: Pt }>();
+    const found: Array<{ a: number; b: number; at: Pt; in: number[]; out: number[] }> = [];
+    for (const [a, b] of spans) {
+      const { at } = spanOf(name, a, b)!;
+      const ins: number[] = [];
+      const outs: number[] = [];
+      for (let k = 1; k < HOLD_BLEND; k++) {
+        const w = (HOLD_BLEND - k) / HOLD_BLEND;
+        for (const [i, list] of [[a - k, ins], [b + k, outs]] as const) {
+          if (i < 0 || i >= n || inHold(i)) continue;
+          list.push(i);
+          const was = blend.get(i);
+          if (was === undefined || w > was.w) blend.set(i, { w, at });
+        }
+      }
+      found.push({ a, b, at, in: ins, out: outs });
+    }
+    for (const { a, b, at } of found) for (let i = a; i <= b; i++) if (out[i] !== null) out[i] = [at[0], at[1]];
+    for (const [i, { w, at }] of blend) {
+      const p = xs[i];
+      if (p === null || p === undefined) continue;
+      out[i] = [p[0] + w * (at[0] - p[0]), p[1] + w * (at[1] - p[1])];
+    }
+    // The seams: two holds back to back, or with a gap of under HOLD_BLEND frames, cross-fade over the
+    // HOLD_BLEND + gap frames centred on the gap's centre (one.b − 2 … two.a + 2), after the blends.
+    for (let q = 0; q + 1 < found.length; q++) {
+      const one = found[q]!;
+      const two = found[q + 1]!;
+      const gap = two.a - one.b - 1;
+      if (gap < 0 || gap >= HOLD_BLEND) continue;
+      seams.push({ joint: name, frame: two.a, step: Math.hypot(two.at[0] - one.at[0], two.at[1] - one.at[1]) / trunk, gap });
+      const width = HOLD_BLEND + gap;
+      for (let j = 0; j < width; j++) {
+        const i = one.b - (HOLD_BLEND / 2 - 1) + j;
+        if (i < one.a || i > two.b || out[i] === null) continue;
+        const w = (2 * j + 1) / (2 * width);
+        out[i] = [one.at[0] + w * (two.at[0] - one.at[0]), one.at[1] + w * (two.at[1] - one.at[1])];
+      }
+    }
+    held.set(name, out);
+    for (const f of found) {
+      let fastest = 0;
+      for (let i = f.a; i <= f.b; i++) if (xs[i] !== null && sp[i] !== null && sp[i] !== undefined) fastest = Math.max(fastest, sp[i]!);
+      const range = (xs2: number[]): [number, number] | null => (xs2.length === 0 ? null : [Math.min(...xs2), Math.max(...xs2)]);
+      holds.push({
+        joint: name,
+        frames: [f.a, f.b],
+        seconds: secondsOf(f.a, f.b),
+        speed: fastest,
+        reach: spanOf(name, f.a, f.b)!.reach,
+        blendIn: range(f.in),
+        blendOut: range(f.out),
+        jitter: { before: jitterOf([xs.slice(f.a, f.b + 1)], false).value, after: jitterOf([out.slice(f.a, f.b + 1)], false).value },
+      });
+    }
+  }
+  holds.sort((x, y) => x.frames[0] - y.frames[0] || BODY18.indexOf(x.joint) - BODY18.indexOf(y.joint));
+  const unheld: Unheld[] = [];
+  for (const [a, b] of holdRegions(holds)) {
+    for (const name of names) {
+      const xs = series.get(name)!;
+      const sp = med.get(name)!;
+      const covered = (i: number) => holds.some((h) => h.joint === name && i >= h.frames[0] && i <= h.frames[1]);
+      const runs: Array<[number, number]> = [];
+      for (let i = a; i <= b; i++) {
+        if (xs[i] === null || covered(i)) continue;
+        const last = runs[runs.length - 1];
+        if (last !== undefined && last[1] === i - 1) last[1] = i;
+        else runs.push([i, i]);
+      }
+      for (const [s0, s1] of runs) {
+        let fastest: number | null = 0;
+        for (let i = s0; i <= s1; i++) {
+          const v = sp[i];
+          if (v === null || v === undefined) {
+            fastest = null;
+            break;
+          }
+          fastest = Math.max(fastest, v);
+        }
+        const r = spanOf(name, s0, s1)!;
+        const seconds = secondsOf(s0, s1);
+        if (fastest === null || fastest >= speed) unheld.push({ joint: name, frames: [s0, s1], test: 'speed', value: fastest });
+        else if (r.reach > reach) unheld.push({ joint: name, frames: [s0, s1], test: 'reach', value: r.reach });
+        else if (seconds < minSeconds - 1e-9) unheld.push({ joint: name, frames: [s0, s1], test: 'short', value: seconds });
+        else unheld.push({ joint: name, frames: [s0, s1], test: 'span', value: r.reach });
+      }
+    }
+  }
+  unheld.sort((x, y) => x.frames[0] - y.frames[0] || BODY18.indexOf(x.joint) - BODY18.indexOf(y.joint));
+  seams.sort((x, y) => x.frame - y.frame || BODY18.indexOf(x.joint) - BODY18.indexOf(y.joint));
+  return { held, holds, unheld, seams };
+}
+
+/** The regions the holds cover: their spans joined where they overlap or touch, in frame order. */
+export function holdRegions(holds: ReadonlyArray<{ frames: readonly [number, number] }>): Array<[number, number]> {
+  const spans = holds.map((h) => [h.frames[0], h.frames[1]] as [number, number]).sort((x, y) => x[0] - y[0] || x[1] - y[1]);
+  const out: Array<[number, number]> = [];
+  for (const [a, b] of spans) {
+    const last = out[out.length - 1];
+    if (last !== undefined && a <= last[1] + 1) last[1] = Math.max(last[1], b);
+    else out.push([a, b]);
+  }
+  return out;
+}
+
 /**
  * Clean one person's track. Refuses (every reason at once) a window that is
  * not 1 or odd ≥ 5, a loop shorter than the widest window it reads, and a
@@ -376,14 +645,38 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
     });
   }
 
+  // 5. The stillness hold (#91).
+  const hold = params.hold;
+  let holds: HoldFound[] = [];
+  let unheld: Unheld[] = [];
+  let seams: Seam[] = [];
+  if (hold !== undefined && hold !== 'off') {
+    const r = holdStill(smoothed, seq.frames.map((f) => f.t), trunk, hold.speed, hold.reach, params.loop);
+    holds = r.holds;
+    unheld = r.unheld;
+    seams = r.seams;
+    for (const name of names) smoothed.set(name, r.held.get(name)!);
+  }
+
   const untested = Array.from({ length: n }, (_, i) => i).filter((i) => !testedAt(i, n, params.loop));
   const before = jitterOf([...raw.values()], params.loop);
   const after = jitterOf([...smoothed.values()], params.loop);
   const record: CleanRecord = {
     spec: CLEAN_SPEC,
-    params: { loop: params.loop, legs: params.legs, rest: params.rest, ...(params.hipsInferred === true ? { hipsInferred: { by: 'declared' as const } } : {}) },
+    params: {
+      loop: params.loop,
+      legs: params.legs,
+      rest: params.rest,
+      ...(params.hipsInferred === true ? { hipsInferred: { by: 'declared' as const } } : {}),
+      ...(hold === undefined ? {} : { hold: hold === 'off' ? ('off' as const) : { speed: hold.speed, reach: hold.reach, minSeconds: HOLD_MIN_SECONDS, blend: HOLD_BLEND } }),
+    },
     spikes: { found: spikes.map((s) => ({ frame: s.frame, joint: s.joint })), untested },
     jitter: { before: before.value, after: after.value },
+    ...(hold === undefined || hold === 'off' ? {} : {
+      holds: holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]] as [number, number], jitter: { before: h.jitter.before, after: h.jitter.after } })),
+      unheld: unheld.map((u) => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]] as [number, number], test: u.test, value: u.value })),
+      seams: seams.map((x) => ({ joint: x.joint, frame: x.frame, step: x.step, gap: x.gap })),
+    }),
   };
   const inferred = params.hipsInferred === true ? { r_hip: 0, l_hip: 0 } : null;
   const frames = seq.frames.map((f, i) => {
@@ -403,7 +696,8 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
   });
   const { cleaned: _was, ...rest } = seq;
   return {
-    seq: { ...rest, cleaned: record, frames },
+    // #92: a loop is one cycle of a gait repeated in place, so it carries no travel of its own.
+    seq: { ...rest, ...(params.loop ? { travel: TRAVEL_IN_PLACE } : {}), cleaned: record, frames },
     record,
     person,
     trunk: { length: trunk, frames: lengths.length },
@@ -414,6 +708,9 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
     floor,
     triples: before.triples,
     inferred,
+    holds,
+    unheld,
+    seams,
   };
 }
 
@@ -432,17 +729,56 @@ export function cleanLine(r: CleanRecord): string {
   const spikes = `${found.length === 0 ? 'no spike' : `${found.length} spike(s) replaced (${shown}${found.length > 8 ? `, … ${found.length - 8} more` : ''})`}, ${untestedText(r.spikes.untested)}`;
   const jit = (v: number | null) => (v === null ? 'not measured' : v.toFixed(2));
   const hips = r.params.hipsInferred === undefined ? '' : `; hips inferred (${inferredSource(r)})`;
-  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²${hips}`;
+  return `${r.spec}: ${windows}, ${loop ? 'loop' : 'no loop'}; ${spikes}; jitter (mean |second difference| of y) ${jit(r.jitter.before)} → ${jit(r.jitter.after)} px/f²${holdText(r)}${hips}`;
+}
+
+/**
+ * The stillness hold on the CLEAN line (#91): "; hold off"; "; no HOLD (…)";
+ * or, per region the holds cover, the joints held over which frames and the
+ * joints not held with the test each fails and its figure. Nothing for a
+ * record written before #91.
+ */
+function holdText(r: CleanRecord): string {
+  const h = r.params.hold;
+  if (h === undefined) return '';
+  if (h === 'off') return '; hold off';
+  const holds = r.holds ?? [];
+  if (holds.length === 0) return `; no HOLD (speed < ${h.speed} trunk/frame, within ${h.reach} trunk, ≥ ${h.minSeconds} s)`;
+  return holdRegions(holds).map(([a, b]) => {
+    const groups = new Map<string, string[]>();
+    for (const x of holds) {
+      if (x.frames[0] > b || x.frames[1] < a) continue;
+      const k = `${x.frames[0]}–${x.frames[1]}`;
+      groups.set(k, [...(groups.get(k) ?? []), x.joint]);
+    }
+    const held = [...groups].map(([k, js]) => `${js.join(', ')} ${k}`).join('; ');
+    const not = (r.unheld ?? []).filter((u) => u.frames[0] >= a && u.frames[1] <= b).map(unheldText(h));
+    const sm = (r.seams ?? []).filter((x) => x.frame >= a && x.frame <= b).map((x) => `${x.joint} ${x.frame} (step ${x.step.toFixed(4)}${x.gap > 0 ? `, gap ${x.gap}` : ''})`);
+    const ramps = holds.filter((x) => x.frames[0] <= b && x.frames[1] >= a && x.jitter.after !== null && x.jitter.after > 0).map((x) => `${x.joint} ${x.frames[0]}–${x.frames[1]} ${x.jitter.after!.toFixed(4)} px/f² (ramp)`);
+    return `; HOLD frames ${a}–${b}: held ${held}${sm.length === 0 ? '' : `; seams cross-faded: ${sm.join(', ')}`}${ramps.length === 0 ? '' : `; jitter after ${ramps.join(', ')}`}${not.length === 0 ? '; every joint held' : `; not held: ${not.join(', ')}`}`;
+  }).join('');
+}
+
+/** One joint's frames not held, as the lines say it: `r_wrist 21–59 (reach 0.1375 > 0.03)` (the drifting wrist of the tests). */
+export function unheldText(h: { speed: number; reach: number; minSeconds?: number }): (u: CleanUnheld) => string {
+  return (u) => {
+    const at = `${u.joint} ${u.frames[0] === u.frames[1] ? `${u.frames[0]}` : `${u.frames[0]}–${u.frames[1]}`}`;
+    if (u.test === 'speed') return `${at} (speed ${u.value === null ? 'not known on some frame' : `${u.value.toFixed(4)} ≥ ${h.speed}`})`;
+    if (u.test === 'reach') return `${at} (reach ${u.value!.toFixed(4)} > ${h.reach})`;
+    if (u.test === 'short') return `${at} (still, ${u.value!.toFixed(3)} s < ${h.minSeconds ?? HOLD_MIN_SECONDS} s)`;
+    return `${at} (passes all three, reach ${u.value!.toFixed(4)}; its spans broke elsewhere)`;
+  };
 }
 
 /**
  * Where a sequence's `inferred` hips come from, as the lines say it: "declared
- * at clean" when the record says `--hips-inferred` marked them; "source not
+ * at clean" when the record says `--hips-inferred` marked them; "measured by
+ * <method>" when a tool read the pelvis line off the picture (#86); "source not
  * stated" when the joints carry the state and the record does not say why
  * (a file whose states were written by hand or by another tool).
  */
 export function inferredSource(r: CleanRecord | undefined): string {
   const h = r?.params.hipsInferred;
   if (h === undefined) return 'source not stated';
-  return h.by === 'declared' ? 'declared at clean' : h.by;
+  return h.by === 'declared' ? 'declared at clean' : `measured by ${h.method}`;
 }