@rig-c/pose 0.16.0 → 0.17.0

package/src/pose.ts

@@ -70,16 +70,91 @@ export interface CleanSpike {
 }
 /**
  * Who said the hips are `inferred` (#63): `declared` — the person running
- * `rig-pose clean --hips-inferred` said so. A measured producer would record
- * itself under another `by`; this reader reads only `declared` today.
+ * `rig-pose clean --hips-inferred` said so; `measured` (#86) — a tool read the
+ * pelvis line off the picture (`tools/pelvis.py`, after clean) and turned the
+ * hip pair to a measured angle on every frame. The exact shape:
+ *
+ *   { by: "measured", method: string,
+ *     read: Run[], interpolated: Run[], held: Run[],
+ *     declined: Array<{ frames: Run, why: string }> }      Run = [first, last]
+ *
+ * `method` names the reading. Runs are integer frame indices inside the
+ * sequence, first ≤ last, increasing and not overlapping within each list.
+ * Every frame of the sequence is in exactly one of `read` (the frame's own
+ * reading), `interpolated` (a declined frame between two reads close in time,
+ * the angle interpolated) and `held` (any other declined frame, the earlier
+ * read carried to the end of its run; at the clip's start, the later read). `declined` lists, with the reason, exactly the frames that are
+ * interpolated or held. Anything else is refused by name (POSE_CLEANED).
+ */
+export type Run = [number, number];
+export type HipsInferred =
+  | { by: 'declared' }
+  | { by: 'measured'; method: string; read: Run[]; interpolated: Run[]; held: Run[]; declined: Array<{ frames: Run; why: string }> };
+
+/** A copy of the record, in the writer's key order. */
+export function copyHipsInferred(h: HipsInferred): HipsInferred {
+  const runs = (rs: Run[]): Run[] => rs.map(([a, b]) => [a, b]);
+  return h.by === 'declared'
+    ? { by: 'declared' }
+    : { by: 'measured', method: h.method, read: runs(h.read), interpolated: runs(h.interpolated), held: runs(h.held), declined: h.declined.map((d) => ({ frames: [d.frames[0], d.frames[1]], why: d.why })) };
+}
+
+/** The frames a `measured` record gives an angle on (read, interpolated, held), as a set; null for any other record or none. */
+export function measuredFrames(h: HipsInferred | undefined): Set<number> | null {
+  if (h === undefined || h.by !== 'measured') return null;
+  const out = new Set<number>();
+  for (const rs of [h.read, h.interpolated, h.held]) for (const [a, b] of rs) for (let f = a; f <= b; f++) out.add(f);
+  return out;
+}
+
+/** The stillness hold's figures (#91): speed in trunk lengths per frame, reach in trunk lengths, the shortest hold in seconds, the blend in frames. */
+export interface HoldParams {
+  speed: number;
+  reach: number;
+  minSeconds: number;
+  blend: number;
+}
+/**
+ * One stillness hold of one joint: its frames (inclusive), and the joint's
+ * jitter inside them before and after, px/f². `after` is 0 on a hold held at
+ * its median throughout; on a hold that carries a seam's cross-fade it is the
+ * ramp's own curvature, expected and not noise (the lines print "ramp").
  */
-export interface HipsInferred {
-  by: 'declared';
+export interface CleanHold {
+  joint: Body18;
+  frames: [number, number];
+  jitter: { before: number | null; after: number | null };
+}
+/**
+ * A run of frames (`frames`, inside a region the holds cover) on which a joint
+ * has a position and no hold, with the test it fails there: `speed` (its
+ * largest median speed, trunk lengths a frame; null where its speed is not
+ * known on some frame), `reach` (its largest distance from its median over the
+ * run, trunk lengths), `short` (it passes both and the run lasts under the
+ * minimum; the figure is its seconds), or `span` (it passes all three and its
+ * spans broke elsewhere; the figure is its reach).
+ */
+/** Two holds of one joint meeting (back to back, or a gap of under 6 frames): the second's first frame, the step between their medians in trunk lengths, and the gap in frames (cross-faded). */
+export interface CleanSeam {
+  joint: Body18;
+  frame: number;
+  step: number;
+  gap: number;
+}
+export interface CleanUnheld {
+  joint: Body18;
+  frames: [number, number];
+  test: 'speed' | 'reach' | 'short' | 'span';
+  value: number | null;
 }
 export interface CleanRecord {
   spec: typeof CLEAN_SPEC;
-  /** `hipsInferred` is present only when clean marked the hips (`--hips-inferred`). */
-  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
+  /**
+   * `hipsInferred` is present only when clean marked the hips (`--hips-inferred`).
+   * `hold` (#91): the stillness hold's figures, or "off"; absent in a record
+   * written before #91.
+   */
+  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off' };
   /**
    * `found`: every joint the spike step replaced, by frame (index into `frames`)
    * and joint. `untested`: the frames the spike step did not test, because a
@@ -88,6 +163,10 @@ export interface CleanRecord {
   spikes: { found: CleanSpike[]; untested: number[] };
   /** Mean |second difference| of y, px/f², before and after; null where no joint has three consecutive positions. */
   jitter: { before: number | null; after: number | null };
+  /** The stillness holds (#91), per joint; present, with `unheld`, exactly when `params.hold` is an object. */
+  holds?: CleanHold[];
+  unheld?: CleanUnheld[];
+  seams?: CleanSeam[];
 }
 export interface PoseSequence {
   spec: typeof POSE_SPEC;
@@ -95,7 +174,7 @@ export interface PoseSequence {
   width: number;
   height: number;
   source: string;
-  /** Optional, only with `camera`: where it came from — "tracked", or "hand-labelled, N keys" (#63). */
+  /** Optional, only with `camera`: where it came from — "tracked", "hand-labelled, N keys" (#63), or "hand windows, floor-snapped: …" (#82). */
   cameraSource?: string;
   /** Optional: one per frame, when a scan read the camera (#63). */
   camera?: CameraFrame[];
@@ -234,32 +313,38 @@ function readCamera(p: Problems, where: string, camera: unknown, frames: number
   return out;
 }
 
-/** `cleaned`: { spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }. */
+/** `cleaned`: { spec, params: { loop, legs, rest, hipsInferred?, hold? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after }, holds?, unheld?, seams? }. */
 function readCleaned(p: Problems, where: string, c: unknown, frames: number | null): CleanRecord | undefined {
   const cw = `${where} "cleaned"`;
-  const shape = '{ spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }';
+  const shape = '{ spec, params: { loop, legs, rest, hipsInferred?, hold? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after }, holds?, unheld?, seams? }';
   if (!isObject(c)) {
     p.add('POSE_CLEANED', `${cw} is ${typeName(c)}; it is the record rig-pose clean writes, ${shape}`);
     return undefined;
   }
   const before = p.list.length;
-  refuseUnknownKeys(p, 'POSE_CLEANED', cw, c, ['spec', 'params', 'spikes', 'jitter']);
+  refuseUnknownKeys(p, 'POSE_CLEANED', cw, c, ['spec', 'params', 'spikes', 'jitter', 'holds', 'unheld', 'seams']);
   for (const k of ['spec', 'params', 'spikes', 'jitter']) if (!(k in c)) p.add('POSE_CLEANED', `${cw} has no "${k}"; the record is ${shape}`);
   if ('spec' in c && c.spec !== CLEAN_SPEC) p.add('POSE_CLEANED', `${cw} "spec" is ${typeName(c.spec)}; this reader reads "${CLEAN_SPEC}"`);
   const window = (v: unknown) => Number.isInteger(v) && (v === 1 || ((v as number) >= 5 && (v as number) % 2 === 1));
   if ('params' in c) {
     const q = c.params;
-    if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest, hipsInferred? }`);
+    if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest, hipsInferred?, hold? }`);
     else {
-      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest', 'hipsInferred']);
-      if ('hipsInferred' in q) {
-        const h = q.hipsInferred;
-        if (!isObject(h)) p.add('POSE_CLEANED', `${cw} "params" "hipsInferred" is ${typeName(h)}; it must be { by: "declared" }`);
+      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest', 'hipsInferred', 'hold']);
+      if ('hold' in q) {
+        const h = q.hold;
+        const hw = `${cw} "params" "hold"`;
+        if (h === 'off') {
+          for (const k of ['holds', 'unheld', 'seams']) if (k in c) p.add('POSE_CLEANED', `${cw} has "${k}" with "params" "hold" "off"; a record lists holds only when the hold ran`);
+        } else if (!isObject(h)) p.add('POSE_CLEANED', `${hw} is ${typeName(h)}; it must be "off" or { speed, reach, minSeconds, blend }`);
         else {
-          refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params" "hipsInferred"`, h, ['by']);
-          if (h.by !== 'declared') p.add('POSE_CLEANED', `${cw} "params" "hipsInferred" "by" is ${typeName(h.by)}; this reader reads "declared" (the person running rig-pose clean --hips-inferred said so)`);
+          refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['speed', 'reach', 'minSeconds', 'blend']);
+          for (const k of ['speed', 'reach', 'minSeconds'] as const) if (!(typeof h[k] === 'number' && Number.isFinite(h[k]) && h[k] > 0)) p.add('POSE_CLEANED', `${hw} "${k}" is ${typeName(h[k])}; it must be a number > 0 (${k === 'minSeconds' ? 'seconds' : k === 'speed' ? 'trunk lengths per frame' : 'trunk lengths'})`);
+          if (!(Number.isInteger(h.blend) && (h.blend as number) >= 0)) p.add('POSE_CLEANED', `${hw} "blend" is ${typeName(h.blend)}; it must be a whole number of frames ≥ 0`);
+          for (const k of ['holds', 'unheld', 'seams']) if (!(k in c)) p.add('POSE_CLEANED', `${cw} has "params" "hold" and no "${k}"; a record whose hold ran lists its holds, the joints it did not hold and its seams (an empty array when none)`);
         }
-      }
+      } else for (const k of ['holds', 'unheld', 'seams']) if (k in c) p.add('POSE_CLEANED', `${cw} has "${k}" and no "params" "hold"; the holds' figures are recorded in "params" "hold"`);
+      if ('hipsInferred' in q) readHipsInferred(p, `${cw} "params" "hipsInferred"`, q.hipsInferred, frames);
       if (typeof q.loop !== 'boolean') p.add('POSE_CLEANED', `${cw} "params" "loop" is ${typeName(q.loop)}; it must be true or false`);
       for (const k of ['legs', 'rest'] as const) if (!window(q[k])) p.add('POSE_CLEANED', `${cw} "params" "${k}" is ${typeName(q[k])}; it must be 1 (none) or an odd whole number ≥ 5`);
     }
@@ -299,20 +384,213 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
       }
     }
   }
+  if ('holds' in c) {
+    const hs = c.holds;
+    if (!Array.isArray(hs)) p.add('POSE_CLEANED', `${cw} "holds" is ${typeName(hs)}; it must be an array of { joint, frames: [first, last], jitter: { before, after } }`);
+    else hs.forEach((h: unknown, i: number) => {
+      const hw = `${cw} holds[${i}]`;
+      if (!isObject(h)) {
+        p.add('POSE_CLEANED', `${hw} is ${typeName(h)}; a hold is { joint, frames: [first, last], jitter: { before, after } }`);
+        return;
+      }
+      refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['joint', 'frames', 'jitter']);
+      if (typeof h.joint !== 'string' || !isBody18(h.joint)) p.add('POSE_CLEANED', `${hw} "joint" is ${typeName(h.joint)}; it must be a body-18 joint: ${BODY18.join(', ')}`);
+      const f = h.frames;
+      if (!(Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number))) p.add('POSE_CLEANED', `${hw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      const j = h.jitter;
+      if (!isObject(j)) p.add('POSE_CLEANED', `${hw} "jitter" is ${typeName(j)}; it must be { before, after }`);
+      else {
+        refuseUnknownKeys(p, 'POSE_CLEANED', `${hw} "jitter"`, j, ['before', 'after']);
+        for (const k of ['before', 'after'] as const) {
+          const v = j[k];
+          if (!(v === null || (typeof v === 'number' && Number.isFinite(v) && v >= 0))) p.add('POSE_CLEANED', `${hw} "jitter" "${k}" is ${typeName(v)}; it must be px/f² ≥ 0, or null (not measured)`);
+        }
+      }
+    });
+  }
+  if ('unheld' in c) {
+    const us = c.unheld;
+    if (!Array.isArray(us)) p.add('POSE_CLEANED', `${cw} "unheld" is ${typeName(us)}; it must be an array of { joint, frames: [first, last], test, value }`);
+    else us.forEach((u: unknown, i: number) => {
+      const uw = `${cw} unheld[${i}]`;
+      if (!isObject(u)) {
+        p.add('POSE_CLEANED', `${uw} is ${typeName(u)}; an unheld joint is { joint, frames: [first, last], test, value }`);
+        return;
+      }
+      refuseUnknownKeys(p, 'POSE_CLEANED', uw, u, ['joint', 'frames', 'test', 'value']);
+      if (typeof u.joint !== 'string' || !isBody18(u.joint)) p.add('POSE_CLEANED', `${uw} "joint" is ${typeName(u.joint)}; it must be a body-18 joint: ${BODY18.join(', ')}`);
+      const f = u.frames;
+      if (!(Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number))) p.add('POSE_CLEANED', `${uw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      if (u.test !== 'speed' && u.test !== 'reach' && u.test !== 'short' && u.test !== 'span') p.add('POSE_CLEANED', `${uw} "test" is ${typeName(u.test)}; it must be "speed", "reach", "short" or "span"`);
+      const v = u.value;
+      const ok = typeof v === 'number' && Number.isFinite(v) && v >= 0;
+      if (!(ok || (v === null && u.test === 'speed'))) p.add('POSE_CLEANED', `${uw} "value" is ${typeName(v)}; it must be a figure ≥ 0 (trunk lengths, or seconds for "short"), or null for a speed not known`);
+    });
+  }
+  if ('seams' in c) {
+    const ss = c.seams;
+    if (!Array.isArray(ss)) p.add('POSE_CLEANED', `${cw} "seams" is ${typeName(ss)}; it must be an array of { joint, frame, step, gap }`);
+    else ss.forEach((x: unknown, i: number) => {
+      const sw = `${cw} seams[${i}]`;
+      if (!isObject(x)) {
+        p.add('POSE_CLEANED', `${sw} is ${typeName(x)}; a seam is { joint, frame, step, gap }`);
+        return;
+      }
+      refuseUnknownKeys(p, 'POSE_CLEANED', sw, x, ['joint', 'frame', 'step', 'gap']);
+      if (!(Number.isInteger(x.gap) && (x.gap as number) >= 0)) p.add('POSE_CLEANED', `${sw} "gap" is ${typeName(x.gap)}; it must be a whole number of frames ≥ 0`);
+      if (typeof x.joint !== 'string' || !isBody18(x.joint)) p.add('POSE_CLEANED', `${sw} "joint" is ${typeName(x.joint)}; it must be a body-18 joint: ${BODY18.join(', ')}`);
+      if (!frameOk(x.frame)) p.add('POSE_CLEANED', `${sw} "frame" is ${typeName(x.frame)}; it must be a frame index in ${frameRange}`);
+      if (!(typeof x.step === 'number' && Number.isFinite(x.step) && x.step >= 0)) p.add('POSE_CLEANED', `${sw} "step" is ${typeName(x.step)}; it must be trunk lengths ≥ 0`);
+    });
+  }
   if (p.list.length > before) return undefined;
-  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
+  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred; hold?: HoldParams | 'off' };
   const j = c.jitter as { before: number | null; after: number | null };
   return {
     spec: CLEAN_SPEC,
-    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: { by: q.hipsInferred.by } } : {}) },
+    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(q.hipsInferred) } : {}), ...(q.hold !== undefined ? { hold: holdParamsOf(q.hold) } : {}) },
     spikes: {
       found: ((c.spikes as { found: Array<{ frame: number; joint: Body18 }> }).found).map((s) => ({ frame: s.frame, joint: s.joint })),
       untested: [...(c.spikes as { untested: number[] }).untested],
     },
     jitter: { before: j.before, after: j.after },
+    ...('holds' in c ? { holds: (c.holds as CleanHold[]).map(copyHold) } : {}),
+    ...('unheld' in c ? { unheld: (c.unheld as CleanUnheld[]).map(copyUnheld) } : {}),
+    ...('seams' in c ? { seams: (c.seams as CleanSeam[]).map((x) => ({ joint: x.joint, frame: x.frame, step: x.step, gap: x.gap })) } : {}),
   };
 }
 
+/** `hipsInferred`: { by: "declared" } or the measured record (the shape at `HipsInferred`), refused by name otherwise. */
+function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number | null): void {
+  const measuredShape = '{ by: "measured", method, read, interpolated, held: [[first, last]], declined: [{ frames: [first, last], why }] }';
+  if (!isObject(h)) {
+    p.add('POSE_CLEANED', `${hw} is ${typeName(h)}; it must be { by: "declared" } or ${measuredShape}`);
+    return;
+  }
+  if (h.by === 'declared') {
+    refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by']);
+    return;
+  }
+  if (h.by !== 'measured') {
+    refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by']);
+    p.add('POSE_CLEANED', `${hw} "by" is ${typeName(h.by)}; this reader reads "declared" (the person running rig-pose clean --hips-inferred said so) or "measured" (a tool read the pelvis line off the picture, tools/pelvis.py)`);
+    return;
+  }
+  const before = p.list.length;
+  const CLASSES = ['read', 'interpolated', 'held'] as const;
+  refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by', 'method', ...CLASSES, 'declined']);
+  for (const k of ['method', ...CLASSES, 'declined']) if (!(k in h)) p.add('POSE_CLEANED', `${hw} has no "${k}"; a measured record is ${measuredShape}`);
+  if ('method' in h && !(typeof h.method === 'string' && h.method.trim() !== '')) p.add('POSE_CLEANED', `${hw} "method" is ${typeName(h.method)}; it must be a non-empty string naming the reading`);
+  const range = `[0, ${frames === null ? 'the frame count' : frames - 1}]`;
+  /** A run [first, last], or null after naming what is wrong with it. */
+  const run = (v: unknown, rw: string): Run | null => {
+    if (!(Array.isArray(v) && v.length === 2)) {
+      p.add('POSE_CLEANED', `${rw} is ${typeName(v)}; a run is [first, last], two frame indices`);
+      return null;
+    }
+    let ok = true;
+    v.forEach((f: unknown, k: number) => {
+      if (!(Number.isInteger(f) && (f as number) >= 0 && (frames === null || (f as number) < frames))) {
+        p.add('POSE_CLEANED', `${rw}[${k}] is ${typeName(f)}; it must be a frame index in ${range}`);
+        ok = false;
+      }
+    });
+    if (!ok) return null;
+    const [a, b] = v as Run;
+    if (a > b) {
+      p.add('POSE_CLEANED', `${rw} is [${a}, ${b}]; a run's first frame must not come after its last`);
+      return null;
+    }
+    return [a, b];
+  };
+  type Named = { r: Run; w: string };
+  /** Runs in order and apart: each starts after the previous one ends. */
+  const ordered = (rs: Named[], what: string) => {
+    for (let k = 1; k < rs.length; k++) {
+      const prev = rs[k - 1]!;
+      const cur = rs[k]!;
+      if (cur.r[0] <= prev.r[1]) p.add('POSE_CLEANED', `${cur.w} [${cur.r[0]}, ${cur.r[1]}] starts at or before the end of ${prev.w} [${prev.r[0]}, ${prev.r[1]}]; ${what} runs must increase and not overlap`);
+    }
+  };
+  const classes: Record<(typeof CLASSES)[number], Named[]> = { read: [], interpolated: [], held: [] };
+  for (const c of CLASSES) {
+    if (!(c in h)) continue;
+    const list = h[c];
+    if (!Array.isArray(list)) {
+      p.add('POSE_CLEANED', `${hw} "${c}" is ${typeName(list)}; it must be an array of runs [first, last]`);
+      continue;
+    }
+    list.forEach((v: unknown, k: number) => {
+      const w = `${hw} ${c}[${k}]`;
+      const r = run(v, w);
+      if (r !== null) classes[c].push({ r, w });
+    });
+    ordered(classes[c], c);
+  }
+  const declined: Named[] = [];
+  if ('declined' in h) {
+    if (!Array.isArray(h.declined)) p.add('POSE_CLEANED', `${hw} "declined" is ${typeName(h.declined)}; it must be an array of { frames: [first, last], why }`);
+    else h.declined.forEach((d: unknown, k: number) => {
+      const w = `${hw} declined[${k}]`;
+      if (!isObject(d)) {
+        p.add('POSE_CLEANED', `${w} is ${typeName(d)}; a declined run is { frames: [first, last], why }`);
+        return;
+      }
+      refuseUnknownKeys(p, 'POSE_CLEANED', w, d, ['frames', 'why']);
+      if (!('why' in d)) p.add('POSE_CLEANED', `${w} has no "why"; a declined run says why, a non-empty string`);
+      else if (!(typeof d.why === 'string' && d.why.trim() !== '')) p.add('POSE_CLEANED', `${w} "why" is ${typeName(d.why)}; a declined run says why, a non-empty string`);
+      if (!('frames' in d)) {
+        p.add('POSE_CLEANED', `${w} has no "frames"; a declined run is { frames: [first, last], why }`);
+        return;
+      }
+      const r = run(d.frames, `${w} "frames"`);
+      if (r !== null) declined.push({ r, w: `${w} "frames"` });
+    });
+    ordered(declined, 'declined');
+  }
+  // Across lists: the classes are disjoint, they cover every frame, and declined is exactly interpolated ∪ held.
+  for (let x = 0; x < CLASSES.length; x++) {
+    for (let y = x + 1; y < CLASSES.length; y++) {
+      for (const a of classes[CLASSES[x]!]) {
+        for (const b of classes[CLASSES[y]!]) {
+          if (a.r[0] <= b.r[1] && b.r[0] <= a.r[1]) p.add('POSE_CLEANED', `${a.w} [${a.r[0]}, ${a.r[1]}] and ${b.w} [${b.r[0]}, ${b.r[1]}] share frame(s) ${Math.max(a.r[0], b.r[0])}–${Math.min(a.r[1], b.r[1])}; a frame is one of read, interpolated and held`);
+        }
+      }
+    }
+  }
+  if (p.list.length > before) return;
+  const set = (rs: Named[]) => {
+    const out = new Set<number>();
+    for (const { r } of rs) for (let f = r[0]; f <= r[1]; f++) out.add(f);
+    return out;
+  };
+  const spans = (fs: number[]) => {
+    const out: Run[] = [];
+    for (const f of fs) {
+      const last = out[out.length - 1];
+      if (last !== undefined && f === last[1] + 1) last[1] = f;
+      else out.push([f, f]);
+    }
+    return out.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
+  };
+  const read = set(classes.read);
+  const filled = set([...classes.interpolated, ...classes.held]);
+  const dec = set(declined);
+  if (frames !== null) {
+    const none = Array.from({ length: frames }, (_, f) => f).filter((f) => !read.has(f) && !filled.has(f));
+    if (none.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(none)} are in none of read, interpolated and held; every frame of the sequence is one of them`);
+  }
+  const both = [...dec].filter((f) => read.has(f)).sort((a, b) => a - b);
+  if (both.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(both)} are both read and declined; a frame is read or declined, not both`);
+  const unfilled = [...dec].filter((f) => !read.has(f) && !filled.has(f)).sort((a, b) => a - b);
+  if (unfilled.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(unfilled)} are declined but neither interpolated nor held; a declined frame takes one of them`);
+  const undeclared = [...filled].filter((f) => !dec.has(f)).sort((a, b) => a - b);
+  if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are interpolated or held but not declined; only a frame the reading declined is filled, and "declined" says why`);
+}
+const holdParamsOf = (h: HoldParams | 'off'): HoldParams | 'off' => (h === 'off' ? 'off' : { speed: h.speed, reach: h.reach, minSeconds: h.minSeconds, blend: h.blend });
+const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: h.jitter.before, after: h.jitter.after } });
+const copyUnheld = (u: CleanUnheld): CleanUnheld => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value });
+
 function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Body18, Joint>> {
   const out: Partial<Record<Body18, Joint>> = {};
   if (!isObject(joints)) {
@@ -499,6 +777,14 @@ export function writePoseSequence(seq: PoseSequence): string {
   const camera = seq.camera?.map((c) => ({ s: round(c.s, 6), tx: round(c.tx, 3), ty: round(c.ty, 3), inliers: c.inliers }));
   const c = seq.cleaned;
   const jit = (v: number | null) => (v === null ? null : round(v, 4));
-  const cleaned = c === undefined ? undefined : { spec: c.spec, params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: { by: c.params.hipsInferred.by } } : {}) }, spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] }, jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) } };
+  const cleaned = c === undefined ? undefined : {
+    spec: c.spec,
+    params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(c.params.hipsInferred) } : {}), ...(c.params.hold !== undefined ? { hold: holdParamsOf(c.params.hold) } : {}) },
+    spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] },
+    jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) },
+    ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
+    ...(c.seams !== undefined ? { seams: c.seams.map((x) => ({ joint: x.joint, frame: x.frame, step: round(x.step, 4), gap: x.gap })) } : {}),
+    ...(c.unheld !== undefined ? { unheld: c.unheld.map((u) => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value === null ? null : round(u.value, 4) })) } : {}),
+  };
   return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, ...(seq.cameraSource !== undefined ? { cameraSource: seq.cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), frames }, null, 2)}\n`;
 }

package/src/retarget.ts

@@ -76,8 +76,8 @@ import type { Joint } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
-import type { Feet, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, supportsOf, tipOf } from './legs.ts';
+import type { BlendHold, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
+import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -108,6 +108,8 @@ export interface RetargetOptions extends SwitchOptions {
   plantFeet?: boolean;
   /** With plantFeet: a free ankle within this many leg lengths of the floor plants both feet, its leg stretched to reach it (`legs.ts` stanceOf, #60); 'off' (the default) plants one. */
   stance?: number | 'off';
+  /** With plantFeet: the floor's world y every support span is planted on (#85); absent, the median of the spans' planted heights. */
+  floor?: number;
   /** While a set whose arm is drawn raised shows, its wrist is placed against the rig's head in eye distances (rig-c/pose#62); false (the default) keeps the pose's angles. */
   raisedByHead?: boolean;
 }
@@ -288,6 +290,10 @@ export interface Retarget {
   planted: boolean;
   /** With --stance: the frames planted both and lifted, and the free leg's stretch (#60). */
   stance: Stance | null;
+  /** With --plant-feet: the one floor every support span was planted on, and each span's shift onto it (#85). */
+  floor: Floor | null;
+  /** With --plant-feet: the supporting leg stretched on the blend frames so its ankle stays on the floor (#85). */
+  blendHold: BlendHold | null;
   /** Each ankle's world position on every frame, as the keys put it, when legs are scaled or feet planted. */
   ankles: { bones: Record<Side, string>; at: Record<Side, Pt[]> } | null;
   /** The translated bone's origin against its thigh roots' midpoint, at setup. */
@@ -609,6 +615,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const legScale: LegScale[] = [];
   const scales = new Map<string, number[]>();
   let stance: Stance | null = null;
+  let floor: Floor | null = null;
+  let blendHold: BlendHold | null = null;
   let feet: Feet | null = null;
   let legs: ReturnType<typeof legsOf> | null = null;
   let legPath: string[] | null = null;
@@ -664,6 +672,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     if (legScale.length === 0 && !p.any) p.add('LEGS_MAP', '--leg-scale scales the leg segments (two of one side\'s hip, knee and ankle), and the map aims none');
   }
   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`);
   p.throwIfAny();
   /** Every bone on the legs' path posed on frame i, by the targets as they stand. */
   const poseLegs = (i: number): PathPose => {
@@ -684,32 +694,52 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       return { r: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.r.ankleBone : ''), l: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.l.ankleBone : '') };
     });
     const tb = rest.get(t!.bone)!;
-    const hip = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY]);
+    // #85: every support span on one floor — the median of their planted heights, or --floor.
+    const planted = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY], opts.floor);
+    const hip = planted.hip;
+    floor = planted.floor;
     for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
-    // --stance (#60): with the hip placed, a free ankle within the tolerance of the floor has its leg
-    // stretched (every bone of its chain's scalex, about the chain's root) until it reaches it.
-    if (opts.stance !== undefined && opts.stance !== 'off') {
-      const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
-      const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
-      const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
-      stance = stanceOf(feet!, ankleSeries, opts.stance, (i) => {
-        const lp = poseLegs(i);
-        return {
-          root: { r: world(i, lp.origin.get(L.r.chain.bones[0]!)!), l: world(i, lp.origin.get(L.l.chain.bones[0]!)!) },
-          ankle: { r: world(i, tipOf(rest, lp, L.r.ankleBone)), l: world(i, tipOf(rest, lp, L.l.ankleBone)) },
-        };
-      });
+    const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
+    const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
+    /** Both legs posed on frame i by the scales as they stand, world (y up): each chain's root and ankle. */
+    const posedFeet = (i: number) => {
+      const lp = poseLegs(i);
+      return {
+        root: { r: world(i, lp.origin.get(L.r.chain.bones[0]!)!), l: world(i, lp.origin.get(L.l.chain.bones[0]!)!) },
+        ankle: { r: world(i, tipOf(rest, lp, L.r.ankleBone)), l: world(i, tipOf(rest, lp, L.l.ankleBone)) },
+      };
+    };
+    /** Every bone of a side's chain has its scalex multiplied by the stretch keyed on that side. */
+    const stretchChain = (stretch: ReadonlyArray<{ side: Side; k: number } | null>) => {
       for (const side of SIDES) {
-        if (!stance.stretch.some((x) => x?.side === side)) continue;
+        if (!stretch.some((x) => x?.side === side)) continue;
         for (const b of L[side].chain.bones) {
           const own = scales.get(b);
           const s = own === undefined ? new Array<number>(n).fill(1) : [...own];
-          stance.stretch.forEach((x, i) => {
+          stretch.forEach((x, i) => {
             if (x?.side === side) s[i] = s[i]! * x.k;
           });
           scales.set(b, s);
         }
       }
+    };
+    // #85: on a blend frame the hip is between two derivations; the supporting leg is stretched
+    // (stanceOf's mechanism, its bounds) so its ankle stays on the floor. Before --stance, whose
+    // floor is that supporting ankle.
+    blendHold = holdBlend(planted.blends, n, posedFeet);
+    stretchChain(blendHold.stretch);
+    // --stance (#60): with the hip placed, a free ankle within the tolerance of the floor has its leg
+    // stretched (every bone of its chain's scalex, about the chain's root) until it reaches it.
+    if (opts.stance !== undefined && opts.stance !== 'off') {
+      const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
+      stance = stanceOf(feet!, ankleSeries, opts.stance, posedFeet, secondsOf);
+      // The supporting leg (the blend's) and the free leg (the stance's) are different chains on a frame.
+      for (let i = 0; i < n; i++) {
+        const b = blendHold.stretch[i];
+        if (b !== null && b !== undefined && stance.stretch[i]?.side === b.side) p.add('LEGS_STRETCH', `frame ${i}: chain "${L[b.side].chain.name}" is stretched both as the supporting leg of a blend (k ${b.k}) and as the free leg of --stance (k ${stance.stretch[i]!.k}); one chain takes one stretch`);
+      }
+      p.throwIfAny();
+      stretchChain(stance.stretch);
     }
   }
   if (t !== null && scale !== null) {
@@ -1110,7 +1140,7 @@ 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,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised,
   };
 }