@rig-c/pose 0.14.0 → 0.15.0

package/README.md

@@ -25,7 +25,7 @@ The map names **chains**: each limb as bones that descend from one another, pare
 ## Clean first: `rig-pose clean`
 
 ```sh
-rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5] [--rest 7]
+rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5] [--rest 7] [--hips-inferred]
 ```
 
 `retarget` reads only a sequence that `clean` wrote ([#67](https://github.com/rig-c/pose/issues/67)). A pose model reads each frame alone, so a hanging wrist moves ±20 px a frame and a cloak-hidden leg jumps 100+ px, and every key carries that shake. `clean` takes it out once, at the sequence, where it can be inspected. A sequence without the record is refused by name (`POSE_NOT_CLEANED`), and the message is the `clean` command to run on that file. There is no flag to skip the step. Windows of 1 (`--legs 1 --rest 1`) are a legitimate run that smooths nothing, and they are recorded as such.
@@ -33,7 +33,7 @@ rig-pose clean --pose dance.scan.json --out dance.pose.json [--loop] [--legs 5]
 The steps, in this order, each printed with its figures:
 
 1. **Spikes.** A joint more than 0.2 trunk lengths from its 5-frame median takes the median. The trunk is neck → mid-hip, the median over the clip. Each replacement is listed by frame and joint (`SPIKE`). Without `--loop`, a clip end cuts the window of the first and last two frames. There the median is a neighbour's value, and a joint moving steadily would read as a spike. Those frames are **not tested**, and the `SPIKES` line and the record name them. Reflecting the window does not help: the median of `[x2, x1, x0, x1, x2]` is still `x1`.
-2. **Occlusion.** A joint whose state is not `observed`, or whose score is under 0.3, takes its 3-frame median (`OCCLUDED`).
+2. **Occlusion.** A joint whose state is not `observed` (or `inferred`), or whose score is under 0.3, takes its 3-frame median (`OCCLUDED`).
 3. **Smoothing.** A quadratic Savitzky–Golay per joint: the legs (both hips, knees and ankles) over `--legs` frames (default 5), every other joint over `--rest` (default 7). A window is 1 (none) or odd and at least 5. 3 is refused because a quadratic through 3 points passes through all three. Without `--loop`, the window is cut at the ends. Where fewer than three frames have a position, the degree drops to fit the ones that do.
 4. **Floor.** Only with `--loop`: the whole figure moves in y by one constant, so that the lowest ankle over the cycle is where it was before smoothing.
 
@@ -50,6 +50,8 @@ The output carries the record, here the dancer's from the table below:
 
 `jitter` is the mean |second difference| of y, in px/f², over every joint and every three consecutive frames that have a position, wrapping with `--loop`. It is measured on the sequence as read and on the cleaned positions. `retarget` prints the record as its `CLEAN` line and copies it into `--report`.
 
+**`--hips-inferred`** ([#63](https://github.com/rig-c/pose/issues/63)) declares that the hips are not seen: under a skirt or a cloak the pose model still places them, but where it puts them is its guess. After the four steps, `r_hip` and `l_hip` are marked `inferred` on every frame where they have a position (`INFERRED`), and the record's params carry `"hipsInferred": { "by": "declared" }` — the person running `clean` said so. Positions and scores are unchanged, so `retarget`'s keys are the same with the flag and without it. What changes is the `POSTURE` line, which does not read a hip tilt off inferred hips (below), and the `CLEAN` line, which ends `hips inferred (declared at clean)`.
+
 **Measured** on HQ's references ([#67](https://github.com/rig-c/pose/issues/67)'s bars):
 
 | Clip | Run | Jitter, px/f² | Against |
@@ -89,7 +91,7 @@ and what the run cannot decide for you it lists:
 - `FLIP` — a segment that turns more than `--flip` degrees in one frame (with `--flip <deg>`; off by default) is spread over the frames around the jump; one line per spread, with the chain, the segment, the jump, the frames and h. Below.
 - `BEND` — with `--bends clamp`, a hinge bent the wrong way is straightened on that frame instead of refusing.
 - `FOLD` — `rigc render --folds` over the new animation: every mesh that folds, and when. A reading, not a gate.
-- `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate.
+- `POSTURE` — when the map has a pelvis chain (joints `r_hip`, `l_hip`) and a `translate`: the hip line's tilt range, and the sway — the x-range of mid_hip − mid_shoulder — in rig units and in shoulder widths, the pose's beside the posed rig's. A reading, not a gate. A frame on which either hip is `inferred` is left out of the tilt. When that is every frame, as after `clean --hips-inferred`, the line is `hip tilt not read: hips inferred (declared at clean)` and the report's `posture` has `"tilt": null` with `"tiltWhy"`; on some frames only, the tilt is read over the others and the line counts the frames left out (`posture.hipsInferred`). The source is read from the clean record, or is `source not stated` when the joints carry the state and the record does not. The sway reads the hips as before.
 - `SWITCH` — with `alternates` in the map ([below](#alternate-drawings-alternates)): each span on which a set of alternate drawings shows, its slots, its frames, how far the pose was from the set's key skeleton, how far each bone with a `drawn` angle was turned from it, and where each of its boundaries was moved to (`moved`, [below](#alternate-drawings-alternates)).
 - `UNCOVERED` — with `alternates` in the map: every fold on a frame where no switch took the folding mesh off screen. This is the list of poses still to paint.
 - `RANGE` — a chain's `range` ([below](#a-joints-range-range)): a bone whose rotate key the pose asks past its range, outside every span of a set depicting its chain, is clamped at the limit; one line per run, with the frames, the seconds and the largest overflow. The demand for an alternate.
@@ -182,7 +184,7 @@ A rig's motion spec usually has an `idle` — a blink, a breath, hair and hem sw
 
 Every bone still has to land with the carried tracks in. A carried translate above the translated bone moves its origin off the pose's travel, and the run refuses with `POSE_LANDS`, naming the carried tracks above the bone that missed.
 
-On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle has 26 tracks. Kept out: the four arm rotates, which the dance keys, and `chest_ctl` scalex, `neck` rotate and `head_ctl` rotate, which sit above the mapped chest, head and arms — carried, they missed the chest, the head and the arms by 0.16°–1.37°. Carried: the other 19, the blink (`group "eyes"` scaley) and the breath (`bone "chest_ctl"` translatey) among them. The gate is green, every bone lands (worst 0.00167°), and rig-c's poser shows the blink at every cycle (scaleY 0.12 at 2.37 s, 5.70 s, 9.08 s and 12.41 s, against the idle's at t mod 3.333 s within 8.9e-6) and the breath's chest_ctl offset (5.02 at 0.833, 4.167, 7.5, 10.833 s; 0 at 2.5, 5.833, 9.167, 12.5 s; 1.035 at the cut, 13 s).
+On HQ's dancer (`--flip 90 --short 0.35 --bends clamp --carry-idle`) the idle has 26 tracks. Kept out: the four arm rotates, which the dance keys, and a control bone's scalex above the chest, the neck's rotate and a head control's rotate, which sit above the mapped chest, head and arms — carried, they missed the chest, the head and the arms by 0.16°–1.37°. Carried: the other 19, the blink (an eyes group's scaley) and the breath (the chest control's translatey) among them. The gate is green, every bone lands (worst 0.00167°), and rig-c's poser shows the blink at every cycle (scaleY 0.12 at 2.37 s, 5.70 s, 9.08 s and 12.41 s, against the idle's at t mod 3.333 s within 8.9e-6) and the breath's offset (5.02 at 0.833, 4.167, 7.5, 10.833 s; 0 at 2.5, 5.833, 9.167, 12.5 s; 1.035 at the cut, 13 s).
 
 **`--merge <file>`** merges a timed track fragment into the new animation, at absolute times from its start — blinks read off the video, for example:
 
@@ -222,7 +224,7 @@ Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2
 ```
 
 - `t` is seconds and strictly increases; the animation's keys are at `t − t₀`.
-- Joints are body-18 (`nose neck r_shoulder r_elbow r_wrist l_shoulder l_elbow l_wrist r_hip r_knee r_ankle l_hip l_knee l_ankle r_eye l_eye r_ear l_ear`); `r`/`l` are the **subject's** sides. `state` is `observed`, `occluded` or `missing`, as in the keypoints file. An unlisted joint is missing.
+- Joints are body-18 (`nose neck r_shoulder r_elbow r_wrist l_shoulder l_elbow l_wrist r_hip r_knee r_ankle l_hip l_knee l_ankle r_eye l_eye r_ear l_ear`); `r`/`l` are the **subject's** sides. `state` is `observed`, `occluded` or `missing`, as in the keypoints file, or `inferred` ([#63](https://github.com/rig-c/pose/issues/63)): a position the detector supplied but did not see. An `inferred` joint carries `at` (one without it is refused, `POSE_JOINT_AT`), and `retarget` keys it as it keys `observed`. An unlisted joint is missing.
 - Two differences from the keypoints file: the unit is `picture-px`, and `at` may lie outside the picture (a hand leaves the frame; the score says how much to believe it).
 - More than one person: `--person <id>`.
 - `score` is whatever the pose model gives. RTMPose's goes above 1, so `--min-score` is a cut on that model's scale, not a probability.
@@ -273,16 +275,18 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 
 ```json
 "alternates": [
-  { "name": "K1_hands_behind_head",
-    "slots":   { "upperarm_r_under": "K1_upperarm_r", "forearm_r_back": "K1_forearm_r", "topwear": "K1_topwear" },
+  { "name": "raised_arms",
+    "slots":   { "upperarm_r_raised": "raised/upperarm_r", "forearm_r_raised": "raised/forearm_r", "torso": "raised/torso" },
     "hides":   ["upperarm_r", "forearm_r"],
     "chains":  ["arm_r", "arm_l"],
-    "pose":    { "r_shoulder": [450, 640], "r_elbow": [350, 500], "r_wrist": [510, 480],
-                 "l_shoulder": [610, 640], "l_elbow": [720, 500], "l_wrist": [560, 480] },
-    "drawn":   { "sleeve_r0": 117.8, "sleeve_r1": 30.4 },
+    "pose":    { "r_shoulder": [400, 600], "r_elbow": [300, 450], "r_wrist": [450, 400],
+                 "l_shoulder": [600, 600], "l_elbow": [700, 450], "l_wrist": [550, 400] },
+    "drawn":   { "sleeve_r0": 120, "sleeve_r1": 30 },
     "offsets": { "sleeve_r1": [4, -2] } } ]
 ```
 
+(The names, coordinates and angles above are illustrative.)
+
 - `slots`: what each slot of the set shows while it shows; each attachment must be in that slot under some skin of the rig, as rig-c built it. `hides`: the slots that are empty while it shows. A slot's place in the draw order is the rig's own, so a drawing that must sit in front of the torso is an attachment in a slot that is: a switch is attachment keys only, and no draw-order key is written.
 - `chains`: the map's chains whose pose the set depicts; it is selected by them. `pose`: the key skeleton the art was painted from, body-18 (or `mid_hip`/`mid_shoulder`) in picture px, y down, any scale and place — only its directions are read; every joint the listed chains use must be in it.
 - `drawn` (optional): each bone's world angle (Spine degrees) as painted. It changes no key: while a set shows, a bone is keyed to the pose as always, and the art turns with it. What it gives is a figure: the art turn, how far each bone is from the angle its art was painted at (`artTurn`, and `ART-RANGE` past the bone's range).

package/cli.ts

@@ -34,6 +34,10 @@ clean (required before retarget; rig-c/pose#67)
   --legs <n>            Savitzky–Golay window over the legs — both hips, knees and ankles (default: 5)
   --rest <n>            Savitzky–Golay window over every other joint (default: 7)
                         n is 1 (none), or odd and ≥ 5: a quadratic through 3 points passes through all three
+  --hips-inferred       declare the hips inferred (rig-c/pose#63): r_hip and l_hip are marked "inferred" — a
+                        position the detector supplied but did not see — on every frame where they have one, and
+                        the record says so (hipsInferred: { by: "declared" }). Positions are unchanged, so retarget's
+                        keys are too; its POSTURE line does not read the hip tilt ("hip tilt not read: hips inferred")
 
   In order, each step printed with its figures: (1) spikes — a joint more than 0.2 trunk lengths
   (neck → mid_hip, the median over the clip) from its 5-frame median takes the median, each listed by
@@ -346,10 +350,10 @@ function runsOf(frames: number[]): string {
 
 /** `rig-pose clean` (#67): read, clean, print each step's figures, write. */
 function runClean(argv: string[], say: (l: string) => void): void {
-  const f = parseFlags(argv, ['pose', 'out', 'legs', 'rest', 'person'], ['loop', 'coco']);
+  const f = parseFlags(argv, ['pose', 'out', 'legs', 'rest', 'person'], ['loop', 'coco', 'hips-inferred']);
   const input = need(f, 'pose');
   const out = need(f, 'out');
-  const params = { loop: f.has('loop'), legs: windowOf(f, 'legs', 5), rest: windowOf(f, 'rest', 7) };
+  const params = { loop: f.has('loop'), legs: windowOf(f, 'legs', 5), rest: windowOf(f, 'rest', 7), hipsInferred: f.has('hips-inferred') };
   const text = readFileSync(input, 'utf8');
   const seq = f.has('coco') ? convertCoco17(text, input) : readPoseSequence(text, input);
   const c = clean(seq, params, f.get('person'), input);
@@ -372,6 +376,7 @@ function runClean(argv: string[], say: (l: string) => void): void {
   }
   const jit = (v: number | null) => (v === null ? 'not measured' : `${fmt(v, 3)}`);
   say(`  JITTER mean |second difference| of y over ${c.triples} joint-frame triple(s): ${jit(c.record.jitter.before)} → ${jit(c.record.jitter.after)} px/f²${c.record.jitter.before !== null && c.record.jitter.after !== null && c.record.jitter.before > 0 ? ` (${fmt(100 * (1 - c.record.jitter.after / c.record.jitter.before), 1)}% lower)` : ''}`);
+  if (c.inferred !== null) say(`  INFERRED r_hip on ${c.inferred.r_hip} frame(s), l_hip on ${c.inferred.l_hip} frame(s) of ${n} marked "inferred" (every frame where it has a position): declared at clean (--hips-inferred); positions and scores unchanged`);
   writeFileSync(out, writePoseSequence(c.seq));
   say(`  CLEAN  ${cleanLine(c.record)}`);
   say(`  wrote ${out}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/clean.ts

@@ -37,7 +37,15 @@
  * median of on its own frame, and a value made from its neighbours would be a
  * guess; `retarget` holds it, and says so with a HOLD line. A joint's state and
  * score are the detector's and are written as they were read: this step moves
- * positions only.
+ * positions only — with one stated exception, `hipsInferred` below.
+ *
+ * `hipsInferred` (rig-c/pose#63, `--hips-inferred`): after the four 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
+ * the same with and without it; what changes is POSTURE, which does not read a
+ * hip tilt off inferred hips. The occlusion step reads `inferred` as it reads
+ * `observed`: a cleaned file cleaned again moves its hips the same way.
  *
  * The smoothing fits the frames of the window where the joint has a position;
  * where fewer than three are there, the polynomial's degree drops to fit the
@@ -75,8 +83,13 @@ export interface CleanParams {
   legs: number;
   /** Savitzky–Golay window over every other joint, frames: 1 (none), or odd and ≥ 5. */
   rest: number;
+  /** Mark r_hip and l_hip `inferred` wherever they have a position (#63): the person running clean declares it. */
+  hipsInferred?: boolean;
 }
 
+/** The joints `--hips-inferred` marks. */
+export const HIPS: readonly Body18[] = ['r_hip', 'l_hip'];
+
 export type Pt = [number, number];
 /** One joint's positions over the frames; null where it has none. */
 export type Series = Array<Pt | null>;
@@ -116,6 +129,8 @@ export interface Cleaned {
   floor: Floor | null;
   /** How many (joint, three-frame) runs the jitter was read over: before, after. */
   triples: number;
+  /** With `hipsInferred`: how many joint-frames were marked `inferred`, per hip. */
+  inferred: { r_hip: number; l_hip: number } | null;
 }
 
 /**
@@ -323,10 +338,10 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
       if (q === null) return;
       const j = track[i]![name]!;
       const low = j.score !== undefined && j.score < OCCLUSION_SCORE;
-      if (j.state === 'observed' && !low) return;
+      if ((j.state === 'observed' || j.state === 'inferred') && !low) return;
       const m = medianAt(xs, i, OCCLUSION_WINDOW, params.loop)!;
       out[i] = m;
-      occluded.push({ joint: name, frame: i, moved: Math.hypot(m[0] - q[0], m[1] - q[1]), why: j.state !== 'observed' ? j.state : `score ${j.score!.toFixed(3)} < ${OCCLUSION_SCORE}` });
+      occluded.push({ joint: name, frame: i, moved: Math.hypot(m[0] - q[0], m[1] - q[1]), why: j.state !== 'observed' && j.state !== 'inferred' ? j.state : `score ${j.score!.toFixed(3)} < ${OCCLUSION_SCORE}` });
     });
     unhidden.set(name, out);
   }
@@ -366,17 +381,23 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
   const after = jitterOf([...smoothed.values()], params.loop);
   const record: CleanRecord = {
     spec: CLEAN_SPEC,
-    params: { loop: params.loop, legs: params.legs, rest: params.rest },
+    params: { loop: params.loop, legs: params.legs, rest: params.rest, ...(params.hipsInferred === true ? { hipsInferred: { by: 'declared' as const } } : {}) },
     spikes: { found: spikes.map((s) => ({ frame: s.frame, joint: s.joint })), untested },
     jitter: { before: before.value, after: after.value },
   };
+  const inferred = params.hipsInferred === true ? { r_hip: 0, l_hip: 0 } : null;
   const frames = seq.frames.map((f, i) => {
     const q = f.people.find((x) => x.id === person);
     if (q === undefined) return { t: f.t, people: [] };
     const joints: Partial<Record<Body18, Joint>> = {};
     for (const [name, j] of Object.entries(q.joints) as Array<[Body18, Joint]>) {
       const moved = smoothed.get(name)?.[i] ?? null;
-      joints[name] = moved === null ? { ...j } : { ...j, at: [moved[0], moved[1]] };
+      const out: Joint = moved === null ? { ...j } : { ...j, at: [moved[0], moved[1]] };
+      if (inferred !== null && (name === 'r_hip' || name === 'l_hip') && out.state !== 'missing' && out.at !== undefined) {
+        out.state = 'inferred';
+        inferred[name]++;
+      }
+      joints[name] = out;
     }
     return { t: f.t, people: [{ id: person, joints: sortedJoints(joints) }] };
   });
@@ -392,6 +413,7 @@ export function clean(seq: PoseSequence, params: CleanParams, wanted: string | u
     untested,
     floor,
     triples: before.triples,
+    inferred,
   };
 }
 
@@ -409,5 +431,18 @@ export function cleanLine(r: CleanRecord): string {
   const shown = found.slice(0, 8).map((s) => `frame ${s.frame} ${s.joint}`).join(', ');
   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));
-  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²`;
+  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}`;
+}
+
+/**
+ * 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
+ * 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;
 }

package/src/pose.ts

@@ -23,7 +23,13 @@ import { isObject, parseJson, Problems, refuseUnknownKeys, typeName } from './pr
 
 export const POSE_SPEC = 'rig-pose-sequence/1';
 export const POSE_SPACE = { units: 'picture-px', origin: 'top-left', y: 'down' } as const;
-const STATES = ['observed', 'occluded', 'missing'] as const;
+/**
+ * `inferred` (rig-c/pose#63): a position the detector supplied but did not see
+ * — it carries `at` like `observed`, and retarget keys it the same; what it
+ * changes is what a reading may claim from it (POSTURE does not read a hip tilt
+ * off inferred hips).
+ */
+const STATES = ['observed', 'occluded', 'missing', 'inferred'] as const;
 export type JointState = (typeof STATES)[number];
 
 export interface Joint {
@@ -62,9 +68,18 @@ export interface CleanSpike {
   frame: number;
   joint: Body18;
 }
+/**
+ * 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.
+ */
+export interface HipsInferred {
+  by: 'declared';
+}
 export interface CleanRecord {
   spec: typeof CLEAN_SPEC;
-  params: { loop: boolean; legs: number; rest: number };
+  /** `hipsInferred` is present only when clean marked the hips (`--hips-inferred`). */
+  params: { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
   /**
    * `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
@@ -219,10 +234,10 @@ function readCamera(p: Problems, where: string, camera: unknown, frames: number
   return out;
 }
 
-/** `cleaned`: { spec, params: { loop, legs, rest }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }. */
+/** `cleaned`: { spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }. */
 function readCleaned(p: Problems, where: string, c: unknown, frames: number | null): CleanRecord | undefined {
   const cw = `${where} "cleaned"`;
-  const shape = '{ spec, params: { loop, legs, rest }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }';
+  const shape = '{ spec, params: { loop, legs, rest, hipsInferred? }, spikes: { found: [{ frame, joint }], untested: [frame] }, jitter: { before, after } }';
   if (!isObject(c)) {
     p.add('POSE_CLEANED', `${cw} is ${typeName(c)}; it is the record rig-pose clean writes, ${shape}`);
     return undefined;
@@ -234,9 +249,17 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
   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 }`);
+    if (!isObject(q)) p.add('POSE_CLEANED', `${cw} "params" is ${typeName(q)}; it must be { loop, legs, rest, hipsInferred? }`);
     else {
-      refuseUnknownKeys(p, 'POSE_CLEANED', `${cw} "params"`, q, ['loop', 'legs', 'rest']);
+      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" }`);
+        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)`);
+        }
+      }
       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`);
     }
@@ -277,11 +300,11 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
     }
   }
   if (p.list.length > before) return undefined;
-  const q = c.params as { loop: boolean; legs: number; rest: number };
+  const q = c.params as { loop: boolean; legs: number; rest: number; hipsInferred?: HipsInferred };
   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 },
+    params: { loop: q.loop, legs: q.legs, rest: q.rest, ...(q.hipsInferred !== undefined ? { hipsInferred: { by: q.hipsInferred.by } } : {}) },
     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],
@@ -324,6 +347,8 @@ function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Bo
       }
     } else if (state === 'observed') {
       p.add('POSE_JOINT_AT', `${jw} is "observed" and has no "at"; an observed joint has a position`);
+    } else if (state === 'inferred') {
+      p.add('POSE_JOINT_AT', `${jw} is "inferred" and has no "at"; an inferred joint is a position the detector supplied but did not see, so it has one`);
     }
     if ('score' in j) {
       if (typeof j.score !== 'number' || !Number.isFinite(j.score)) p.add('POSE_JOINT_SCORE', `${jw} "score" is ${typeName(j.score)}; it must be a finite number`);
@@ -474,6 +499,6 @@ 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 }, 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: { 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`;
 }

package/src/run.ts

@@ -8,7 +8,7 @@ import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeF
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { readMap, resolveMap, type JointMap, type Rest } from './map.ts';
-import { cleanLine } from './clean.ts';
+import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
@@ -225,7 +225,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     p.throwIfAny();
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore);
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned));
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);

package/src/verify.ts

@@ -246,8 +246,19 @@ export interface Posture {
   rigShoulder: string | null;
   /** Reference frames on which the hips (tilt) and the hips and shoulders (sway) are all good. */
   frames: { tilt: number; sway: number; of: number };
-  /** Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's aim). */
-  tilt: { reference: Range; rig: Range; ratio: number };
+  /**
+   * Hip-line tilt, Spine degrees (r_hip → l_hip; the rig: the pelvis chain's
+   * aim). Null when every frame with both hips good has an `inferred` hip
+   * (#63): the tilt is not read, and `tiltWhy` says why.
+   */
+  tilt: { reference: Range; rig: Range; ratio: number } | null;
+  /** Present only when `tilt` is null: why it was not read. */
+  tiltWhy?: string;
+  /**
+   * Present only when some frame with both hips good has an `inferred` hip:
+   * how many such frames the tilt left out, and where the state came from.
+   */
+  hipsInferred?: { frames: number; source: string };
   /**
    * Sway: the x-range of mid_hip − mid_shoulder, in rig units (the reference's
    * picture px × the figure scale) and in each body's own shoulder widths.
@@ -282,8 +293,17 @@ const medianOf = (xs: number[]): number => {
  * the joints it needs are good), the rig is the gated build posed by rig-c.
  * Null when the map has no pelvis chain (joints exactly r_hip, l_hip) or no
  * translate.
+ *
+ * Inferred hips (#63): a frame on which either hip is `inferred` is left out of
+ * the tilt — its hip line is a position the detector supplied but did not see,
+ * and a tilt read off it would be the detector's guess reported as the dancer's.
+ * When that is every frame (`clean --hips-inferred` marks them all), the tilt
+ * is null and `tiltWhy` names the reason and its source (`inferredSource`, read
+ * from the clean record). On some frames only, the tilt is read over the rest
+ * and the line counts the frames left out. Sway is read as before, inferred
+ * hips included: it is a different measure, and the card leaves it as it is.
  */
-export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number): Posture | null {
+export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number, inferredSource = 'source not stated'): Posture | null {
   const pelvis = map.chains.find((c) => c.joints.length === 2 && c.joints[0] === 'r_hip' && c.joints[1] === 'l_hip');
   if (pelvis === undefined || map.translate === null || r.origin === null || r.scale === null) return null;
   const s = r.scale.factor;
@@ -294,11 +314,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const refTilt: number[] = [];
   const refSway: number[] = [];
   const refSw: number[] = [];
-  frames.forEach((_, i) => {
+  let inferred = 0;
+  frames.forEach((f, i) => {
     const rh = at(i, 'r_hip');
     const lh = at(i, 'l_hip');
     if (rh === null || lh === null) return;
-    refTilt.push(pictureAngle(rh, lh));
+    if (f.r_hip?.state === 'inferred' || f.l_hip?.state === 'inferred') inferred++;
+    else refTilt.push(pictureAngle(rh, lh));
     const rs = at(i, 'r_shoulder');
     const ls = at(i, 'l_shoulder');
     if (rs === null || ls === null) return;
@@ -307,9 +329,13 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   });
   const bone = pelvis.bones[0]!;
   const aim = pelvis.aim[0]!;
-  const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
-  const tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
-  tilt.ratio = tilt.rig.range / tilt.reference.range;
+  let tilt: Posture['tilt'] = null;
+  const why = `hips inferred (${inferredSource})`;
+  if (inferred === 0 || refTilt.length > 0) {
+    const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
+    tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
+    tilt.ratio = tilt.rig.range / tilt.reference.range;
+  }
 
   // The rig's mid-shoulder: the point a reach aims at, else the midpoint of the arms' first bones.
   const reach = map.chains.find((c) => c.reach);
@@ -340,7 +366,16 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       ratioSw: rig === null || rig.rangeSw === null ? null : rig.rangeSw / reference.rangeSw,
     };
   }
-  return { pelvis: pelvis.name, rigHip: r.origin.bone, rigShoulder, frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length }, tilt, sway };
+  return {
+    pelvis: pelvis.name,
+    rigHip: r.origin.bone,
+    rigShoulder,
+    frames: { tilt: refTilt.length, sway: refSway.length, of: frames.length },
+    tilt,
+    ...(tilt === null ? { tiltWhy: why } : {}),
+    ...(inferred > 0 ? { hipsInferred: { frames: inferred, source: inferredSource } } : {}),
+    sway,
+  };
 }
 
 const f1 = (x: number) => x.toFixed(1);
@@ -350,8 +385,12 @@ const sg = (x: number) => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
 /** The POSTURE lines. */
 export function postureLines(q: Posture): string[] {
   const over = (k: number) => (k === q.frames.of ? '' : ` over ${k} of ${q.frames.of} frames`);
+  const t = q.tilt;
+  const left = q.hipsInferred === undefined ? '' : `; ${q.hipsInferred.frames} frame(s) with an inferred hip not read (${q.hipsInferred.source})`;
   const out = [
-    `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(q.tilt.reference.range)}° (${sg(q.tilt.reference.min)}° … ${sg(q.tilt.reference.max)}°${over(q.frames.tilt)}), rig ${f1(q.tilt.rig.range)}° (${sg(q.tilt.rig.min)}° … ${sg(q.tilt.rig.max)}°) — rig/reference ${f3(q.tilt.ratio)}`,
+    t === null
+      ? `hip tilt not read: ${q.tiltWhy}`
+      : `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(t.reference.range)}° (${sg(t.reference.min)}° … ${sg(t.reference.max)}°${over(q.frames.tilt)}), rig ${f1(t.rig.range)}° (${sg(t.rig.min)}° … ${sg(t.rig.max)}°) — rig/reference ${f3(t.ratio)}${left}`,
   ];
   const w = q.sway;
   if (w === null) out.push('sway: the reference has no frame with both hips and both shoulders good; not measured');