@rig-c/pose 0.16.0 → 0.18.0

package/src/map.ts

@@ -50,6 +50,9 @@
  * directions are read), holding every joint its `chains` use; `drawn` is each
  * bone's world angle as painted (a reading: `artTurn`); `offsets` is a
  * translate per bone, in its parent's axes, held while the set shows.
+ * `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).
  * `switch.ts` decides when each one shows.
  */
 import type { RawBone } from 'rig-c/core';
@@ -95,6 +98,8 @@ export interface AlternateSet {
   turn: Record<string, [number, number]>;
   /** A stopgap: the only frames the set may show on, a list of [first, last] windows; on them it is chosen over any set without windows. Null: any frame. */
   frames: Array<[number, number]> | null;
+  /** `place: "by-hip"` (rig-c/pose#93): the chains whose wrist `pose` puts within one hip width of the mid-hip, their wrists placed by the offset from the hip while the set shows. Absent or null: the pose's angles. */
+  place?: { by: 'hip'; chains: string[] } | null;
 }
 export interface JointMap {
   chains: Chain[];
@@ -228,7 +233,39 @@ export function readMap(text: string, where: string): JointMap {
   return { chains, translate, alternates };
 }
 
-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], …] }';
+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" }';
+
+/** 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'];
+
+/**
+ * `place: "by-hip"` (rig-c/pose#93): the set's chains that carry a wrist (their
+ * last joint) which its key skeleton puts within one hip width of the mid-hip —
+ * |wrist − (r_hip + l_hip) / 2| ≤ |r_hip − l_hip| — and each wrist chain's
+ * distance in hip widths; or why the key skeleton cannot be read so.
+ */
+export function byHipChains(pose: Readonly<Record<string, readonly [number, number]>>, chains: readonly Chain[]): { chains: string[]; distances: Array<{ chain: string; wrist: string; hipWidths: number }> } | { problem: string } {
+  const r = pose.r_hip;
+  const l = pose.l_hip;
+  if (r === undefined || l === undefined) return { problem: `its "pose" has no ${[r === undefined ? '"r_hip"' : '', l === undefined ? '"l_hip"' : ''].filter((x) => x !== '').join(' or ')}; "by-hip" reads the hip width and the mid-hip off the key skeleton's two hips, which the map's author supplies` };
+  const noWrist = chains.filter((c) => WRISTS.includes(c.joints[c.joints.length - 1]!) && pose[c.joints[c.joints.length - 1]!] === undefined);
+  if (noWrist.length > 0) return { problem: noWrist.map((c) => `its "pose" has no "${c.joints[c.joints.length - 1]}", the wrist of chain "${c.name}"`).join('; ') + '; "by-hip" reads each wrist\'s distance from the mid-hip off the key skeleton' };
+  const width = Math.hypot(l[0] - r[0], l[1] - r[1]);
+  if (!(width > 1e-9)) return { problem: `its "pose" puts r_hip and l_hip at the same point; a hip width of 0 is no unit` };
+  const mid: [number, number] = [(r[0] + l[0]) / 2, (r[1] + l[1]) / 2];
+  const distances: Array<{ chain: string; wrist: string; hipWidths: number }> = [];
+  for (const c of chains) {
+    const wrist = c.joints[c.joints.length - 1]!;
+    if (!WRISTS.includes(wrist)) continue;
+    const w = pose[wrist];
+    if (w === undefined) continue;
+    distances.push({ chain: c.name, wrist, hipWidths: Math.hypot(w[0] - mid[0], w[1] - mid[1]) / width });
+  }
+  if (distances.length === 0) return { problem: `none of its chains (${chains.map((c) => c.name).join(', ')}) ends at a wrist (${WRISTS.join(', ')}); "by-hip" places a wrist` };
+  const near = distances.filter((d) => d.hipWidths <= 1);
+  if (near.length === 0) return { problem: `its "pose" puts no wrist within one hip width of the mid-hip (${distances.map((d) => `chain "${d.chain}" ${d.wrist} ${d.hipWidths.toFixed(2)} hip widths`).join(', ')}); "by-hip" places a hand that meets the body` };
+  return { chains: near.map((d) => d.chain), distances };
+}
 
 /** `alternates`: each set's shape, its chains against the map's, its key skeleton against those chains' joints, and its bones against those chains' bones. */
 function readAlternates(p: Problems, where: string, raw: unknown, chains: readonly Chain[], translate: Translate | null): AlternateSet[] {
@@ -245,7 +282,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']);
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, a, ['name', 'note', 'slots', 'hides', 'chains', 'pose', 'drawn', 'offsets', 'turn', 'frames', 'place']);
     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`);
@@ -354,7 +391,16 @@ function readAlternates(p: Problems, where: string, raw: unknown, chains: readon
         p.add('MAP_ALT_FRAMES', `${label} "frames" is ${JSON.stringify(f)}; it must be a non-empty list of windows [[first, last], …], whole frame numbers ≥ 0 with first ≤ last`);
       } else frames = (f as Array<[number, number]>).map((w) => [w[0], w[1]]);
     }
-    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames });
+    let place: AlternateSet['place'] = null;
+    if ('place' in a) {
+      if (a.place !== 'by-hip') p.add('MAP_ALT_PLACE', `${label} "place" is ${JSON.stringify(a.place)}; the one placement a set may ask for is "by-hip"`);
+      else if (isObject(a.pose) && own.length > 0) {
+        const by = byHipChains(pose, own);
+        if ('problem' in by) p.add('MAP_ALT_PLACE', `${label} "place" is "by-hip", and ${by.problem}`);
+        else place = { by: 'hip', chains: by.chains };
+      }
+    }
+    if (ok && name !== null && cs !== null) out.push({ name, slots, hides, chains: cs, pose, drawn, offsets, turn, frames, ...(place === null ? {} : { place }) });
   });
   return out;
 }

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 interface HipsInferred {
-  by: 'declared';
+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 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,17 +174,28 @@ 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[];
   /** Present once `rig-pose clean` has run on the sequence (#67). */
   cleaned?: CleanRecord;
+  /**
+   * Optional (rig-c/pose#92): the clip's frame of reference. "in-place" — a
+   * gait filmed without the figure travelling (a treadmill or reel walk, a
+   * loop) — is the one value; `clean --loop` writes it, and it may be written
+   * by hand. Absent: the figure's travel in the picture is its travel.
+   */
+  travel?: Travel;
   frames: PoseFrame[];
 }
 
+/** The one value of a sequence's `travel` (rig-c/pose#92). */
+export const TRAVEL_IN_PLACE = 'in-place';
+export type Travel = typeof TRAVEL_IN_PLACE;
+
 const TOP_KEYS = ['spec', 'space', 'width', 'height', 'source', 'frames'];
-const OPTIONAL_KEYS = ['cameraSource', 'camera', 'cleaned'];
+const OPTIONAL_KEYS = ['cameraSource', 'camera', 'cleaned', 'travel'];
 const CAMERA_KEYS = ['s', 'tx', 'ty', 'inliers'];
 
 /**
@@ -190,10 +280,11 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
     if (typeof doc.cameraSource !== 'string' || doc.cameraSource.trim() === '') p.add('POSE_CAMERA_SOURCE', `${where} "cameraSource" is ${typeName(doc.cameraSource)}; it must be a non-empty string saying where the camera came from ("tracked", "hand-labelled, N keys")`);
     else if (!('camera' in doc)) p.add('POSE_CAMERA_SOURCE', `${where} has "cameraSource" ${JSON.stringify(doc.cameraSource)} and no "camera"; it states where a camera came from, so it needs one`);
   }
+  if ('travel' in doc && doc.travel !== TRAVEL_IN_PLACE) p.add('POSE_TRAVEL', `${where} "travel" is ${typeName(doc.travel)}; the one value is "${TRAVEL_IN_PLACE}" (a gait filmed without the figure travelling), and without the key the picture's travel is the figure's`);
   const cleaned = 'cleaned' in doc ? readCleaned(p, where, doc.cleaned, Array.isArray(doc.frames) ? doc.frames.length : null) : undefined;
   p.throwIfAny();
   const cameraSource = typeof doc.cameraSource === 'string' ? doc.cameraSource : undefined;
-  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, ...(cameraSource !== undefined ? { cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), frames };
+  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, ...(cameraSource !== undefined ? { cameraSource } : {}), ...(camera !== undefined ? { camera } : {}), ...(cleaned !== undefined ? { cleaned } : {}), ...(doc.travel === TRAVEL_IN_PLACE ? { travel: TRAVEL_IN_PLACE } : {}), frames };
 }
 
 /** `camera`: one `{ s > 0, tx, ty, inliers ≥ 0 }` per frame, as many as `frames`. */
@@ -234,32 +325,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 +396,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 +789,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) } };
-  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`;
+  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 } : {}), ...(seq.travel !== undefined ? { travel: seq.travel } : {}), frames }, null, 2)}\n`;
 }