@rig-c/pose 0.11.1 → 0.13.0

package/README.md

@@ -57,12 +57,13 @@ and what the run cannot decide for you it lists:
 - `LEG-SCALE` — with `--leg-scale` ([below](#the-legs-foreshortening-and-planted-feet)): per leg segment, its straight length, the spread of its picture length over it, and the frames clamped at each limit.
 - `PIVOT` — when the map translates a bone and has both legs: the translated bone's origin against its thigh roots' midpoint at setup, in units and hip widths — the pivot every hip turn swings the legs about.
 - `FEET` — when the map has both legs: the supports and jumps read off the reference ankles (planted or not), and on the posed build, outside the jumps, the lowest ankle's vertical range and each support span's worst vertical range and horizontal drift of the supporting ankle, in leg lengths.
+- `STANCE` — with `--stance` ([below](#the-legs-foreshortening-and-planted-feet)): one line per run of frames planted both (with the stretch keyed, its largest k) or lifted (the pose's height kept), with the free side, the frames and the tolerance; and one per run whose stretch fell past its bounds (`past the bounds`), with the k the floor needed and how far the foot was left from it.
 - `SHEAR` — with `--leg-scale`: every scaled bone and every bone under one, how far its art is sheared and how long its world axes are against setup. A reading.
 - `IDLE`, `IDLE-DROPPED`, `IDLE-KEPT-OUT`, `MERGE` — the rig's idle against the new animation, and what `--carry-idle` and `--merge` put back ([below](#the-idle-what-the-retarget-drops)).
 - `REDUCE` — with `--reduce` ([below](#few-keys---reduce)): per bone, its keys before and after and its largest error, with the frame; then the total.
 - `TURN` — a line across the body (hips, shoulders, eyes) shorter in the picture than 0.5 of its median length, or reversed, for at least 0.15 s: the body or the head turned. A reading of the pose, made whether or not the map uses the line; it changes no key. The demand for a turned-body drawing, as `END-ON` is for a foreshortened limb.
 
-`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale` and `plantFeet` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
+`--report <file>` writes all of it as JSON (`rig-pose-report/1`): `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet` and `stance` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate`, `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `floor`, `supports`, `jumps`, `changes`, and the posed `reading`), `stance` (`tolerance`, `bounds`, `runs`: `{ state, side, frames, maxHeight, k }`, `over`: `{ side, frames, needed, left }`; `null` without `--stance`), `shear`, `idleDropped`, `idleKeptOut` and `merged` ([below](#the-idle-what-the-retarget-drops)), `reduce` (the tolerances and each row of `REDUCE`, [below](#few-keys---reduce)), and the demand lists. The fields a run is graded by:
 
 | field | each entry |
 | --- | --- |
@@ -121,6 +122,7 @@ rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inh
 - A **jump** — both reference ankles **and** mid_hip more than **0.05** leg lengths above their **rolling floor**, the 95th-percentile picture y over ±1.0 s around the frame, for at least **2 frames** — releases the plant: the hip follows the pose's travel from where it was, and re-plants on landing (blended the same way). The body has to lift: an ankle's picture y drifts with depth, and under one floor for the whole sequence HQ's dancer standing still (frames 0–29 and 277–312, mid_hip moving 10 and 14 px) read as jumping, 152–155 of 313 frames in all.
 - A **step** releases the plant too: while the supporting ankle moves more than **0.03** leg lengths a frame, the other foot takes support if it is planted (not itself released or moving), and otherwise the hip follows the pose's travel. The released ankle may support again once it has moved less than **0.01** leg lengths a frame for **2 frames**. On the dancer the plant held the supporting ankle through a real step (frames 176–181, 579 → 718 px) and threw the hip sideways.
 - `FEET` lists the supports, the jumps and the steps (each with the side, its frames, who took support and where it re-planted); the report carries them under `feet` (`supports`, `jumps`, `steps`, `changes`).
+- **`--stance <leg lengths>`** (only with `--plant-feet`, which it is refused without; off by default) plants **both** feet when the free one is near the floor ([#60](https://github.com/rig-c/pose/issues/60)). On a frame with a supporting side (so outside every jump), the free ankle's height above the supporting one is read in the picture, in the free side's leg length — the leg length `FEET` uses. Within the tolerance the frame is **planted both**: every bone of the free leg's chain has its `scalex` key multiplied by k = (root y − floor y) / (root y − ankle y) on the posed rig, the root being the chain's first bone's origin and the floor the supporting ankle, so the foot reaches the floor. A free ankle below the supporting one is planted too: its k is under 1, since a foot under the floor is the same fault as one floating above it. k is held within **[0.92, 1.08]**, and a frame past those bounds is listed `past the bounds`, held at the bound and not forced. Above the tolerance the foot is **lifted** and keeps the pose's height. The stretched scales are the scale targets, so the landing check holds them. Measured with `--stance 0.07` and HQ's flags (`--smooth 7 --flip 90 --short 0.35 --bends clamp --leg-scale 0.8,1.05 --plant-feet --carry-idle`): on HQ's dancer, frames 94–175 outside the jumps, the free ankle's height above the supporting one on the posed build went from median 18.3 and p90 25.4 units to 0.0 and 0.0. On a second sequence (Toca, 492 frames at 30 fps) the 29 frames labelled by eye as both feet flat, outside the jumps, read 0.0 and 0.0. Of the 6 labelled one foot lifted, 5 stay above the tolerance; the sixth (frame 360) was 0.042 leg lengths up in the picture, within the tolerance, and so planted; without `--stance` it stood 6.5 units up, also under the tolerance (22.6 units there). That is 83 %, under the 90 % the card asked.
 - The map needs one chain ending at each ankle whose last bone is aimed `"x"` (the ankle is that bone's tip), and a `translate` the legs hang from (`LEGS_MAP`). A `range`, or a set's `turn` or `offsets`, on a bone between the hip and an ankle is refused (`LEGS_RANGE`): the plant is derived before the range clamp, and a clamp after it would move the planted foot.
 
 Both are checked on the gated build: every scale lands, each ankle lands where the keys put it, and the hip's origin where the plant put it. The figures were fixed in #47 before the dancer was measured; the defaults stay off until they pass.
@@ -188,6 +190,8 @@ Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2
 **From COCO-17** — the layout most pose models and datasets use — `rig-pose convert --coco in.json --out pose.json`, or `retarget --coco`. The input is `{ "format": "coco17-sequence/1", "width", "height", "source", "frames": [{ "t", "keypoints" }] }`, keypoints in COCO's order as 17 `[x, y, score]` or 51 numbers, or `null` for a frame with nobody. The mapping: COCO's `left_*`/`right_*` → body-18's `l_*`/`r_*` (both are the subject's sides), a score of 0 → `missing`, and body-18's `neck`, which COCO lacks, is the shoulders' midpoint scored the lower of the two (OpenPose's definition).
 
 
+**The camera** ([#63](https://github.com/rig-c/pose/issues/63)). A sequence may carry an optional `camera`, one `{ "s", "tx", "ty", "inliers" }` per frame: the picture's scale and translation against frame 0's, so a point p₀ of frame 0's picture appears at `s · p₀ + (tx, ty)` on that frame. Its joints are then already normalised by it, `p′ = (p − t) / s`, and `inliers` is how many background features the fit kept. `s` must be > 0, `tx` and `ty` finite, `inliers` an integer ≥ 0, and there is one entry per frame; anything else is refused by name (`POSE_CAMERA`). The retarget does not apply it again: it prints a `CAMERA` line with the range of `s` and the three frames where it changes fastest. With `--plant-feet` and no `camera`, the `CAMERA` line says the floor may step with the picture, since a zoom or a pan in the video moves the floor with it. An optional `cameraSource` string says where the camera came from: `"tracked"` or `"hand-labelled, N keys"`. It is refused without a `camera`, or when it is not a non-empty string (`POSE_CAMERA_SOURCE`), and the `CAMERA` line starts with it (`CAMERA tracked: …`; a sequence with a `camera` and no `cameraSource` prints `CAMERA (source not stated): …`). `tools/scan.py` (not shipped) reads the camera off the video's background and writes the normalised sequence with `"cameraSource": "tracked"`. A frame whose fit keeps too few background features is refused by name, and nothing is written. Where the background cannot be tracked, `tools/scan.py --camera-file` takes a hand-written camera instead, a `rig-pose-camera/1` file: `{ "spec": "rig-pose-camera/1", "keys": [ { "frame", "s", "tx", "ty" } ], "note"? }`. Its frames are integers of the pose and strictly increase, `s` is > 0, and `tx` and `ty` are finite. Values are linear between keys and held before the first key and after the last. `inliers` is 0 on every frame, since no feature was fitted, and anything malformed is refused by name (`CAMERA_FILE`). `tools/scan_selftest.py` is the synthetic check of both paths.
+
 **The older name.** `rig-c-pose-frames/0`, written by the extraction jobs this package's demos were made from, is the same file under another spec string. It has `space.units` "painting-px" and an `fps` key; each frame's `t` is the time read. It is read as it is.
 ## The map: `rig-pose-map/1`
 

package/cli.ts

@@ -64,6 +64,12 @@ retarget
                         travel and re-plants on landing; a supporting ankle moving > 0.03 leg lengths a frame
                         releases its plant to the other foot, or to the pose's travel, until it is still
                         (< 0.01 for 2 frames) (FEET lines)
+  --stance <leg lengths> with --plant-feet: on a frame outside the jumps, a free ankle within this many
+                        leg lengths (FEET's) of the supporting one in the picture is planted too — its leg's
+                        scalex keys stretched by k = (root y − floor y) / (root y − ankle y) until the foot
+                        reaches the floor, raised or lowered, k within [0.92, 1.08] (past it, reported, not forced); above
+                        it the foot is lifted and keeps the pose's height (STANCE lines; default: off; 0.07 is
+                        the card's, rig-c/pose#60)
   --idle <name>         the rig's animation read as its idle (default: idle). Every idle track the new
                         animation does not key, on any channel, is listed as IDLE-DROPPED (a blink, a
                         breath); one it keys is IDLE-KEPT-OUT, naming the track that keys it, and so is a
@@ -200,7 +206,7 @@ function legScaleOf(f: Map<string, string>): [number, number] | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip'], ['coco', 'plant-feet', 'carry-idle']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance'], ['coco', 'plant-feet', 'carry-idle']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -225,6 +231,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     short: shortOf(f),
     legScale: legScaleOf(f),
     plantFeet: f.has('plant-feet'),
+    stance: stanceOf(f),
     bends,
     bendTolerance: num(f, 'bend-tolerance', 0, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
     switchTolerance: num(f, 'switch-tolerance', 25, (n) => n >= 0 && n < 180, 'degrees in [0, 180)'),
@@ -241,6 +248,14 @@ function retargetArgs(argv: string[]): RetargetArgs {
   };
 }
 
+/** --stance (rig-c/pose#60): off unless given, and only with --plant-feet. */
+function stanceOf(f: Map<string, string>): number | 'off' {
+  if (!f.has('stance') || f.get('stance') === 'off') return 'off';
+  const v = num(f, 'stance', 0, (n) => n > 0 && n < 1, 'off, or leg lengths in (0, 1)');
+  if (!f.has('plant-feet')) throw new Usage(`--stance is "${f.get('stance')}" without --plant-feet; it plants the free foot beside the supporting one that --plant-feet holds`);
+  return v;
+}
+
 /** --reduce and --reduce-hip (rig-c/pose#32): off unless given; the hip only with the bones. */
 function reduceOf(f: Map<string, string>): { reduce?: number; reduceHip?: number } {
   if (!f.has('reduce')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.11.1",
+  "version": "0.13.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/legs.ts

@@ -486,3 +486,107 @@ export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel:
   }
   return hip;
 }
+
+// --- stance (rig-c/pose#60) --------------------------------------------------
+
+/** A free leg is scaled within these factors to reach the floor (raised from below or lowered from above); past them the frame is reported, not forced. */
+export const STANCE_BOUNDS: readonly [number, number] = [0.92, 1.08];
+
+/** A run of frames with one free side in one state. */
+export interface StanceRun {
+  /** `both`: the free ankle within the tolerance of the floor, so both feet are planted; `lifted`: above it, the pose's height kept. */
+  state: 'both' | 'lifted';
+  /** The side that is not supporting. */
+  side: Side;
+  frames: [number, number];
+  /** The free ankle's largest height above the supporting one in the picture, in that side's leg lengths. */
+  maxHeight: number;
+  /** `both`: the smallest and largest stretch keyed (bounded); `lifted`: null. */
+  k: { min: number; max: number } | null;
+}
+
+/** A run of planted-both frames whose stretch needed a factor past the bounds (or could not reach: `needed` null). */
+export interface StanceOver {
+  side: Side;
+  frames: [number, number];
+  /** The stretch the floor needed furthest from 1, or null where the free ankle is not below its leg's root. */
+  needed: number | null;
+  /** The free ankle's largest distance left from the floor after the bound, world units. */
+  left: number;
+}
+
+export interface Stance {
+  /** The tolerance, in leg lengths (FEET's: the median picture hip → ankle of the free side). */
+  tolerance: number;
+  bounds: readonly [number, number];
+  runs: StanceRun[];
+  over: StanceOver[];
+  /** Per frame: the free side and the stretch keyed on it, or null (lifted, a jump, no support). */
+  stretch: Array<{ side: Side; k: number } | null>;
+}
+
+/** World positions (y up) on one frame: each leg chain's first bone's origin and each ankle. */
+export interface StancePosed {
+  root: Record<Side, Pt>;
+  ankle: Record<Side, Pt>;
+}
+
+/**
+ * Both feet planted when the free ankle is near the floor (rig-c/pose#60). On a
+ * frame with a supporting side (so outside every jump), the free ankle's height
+ * above the supporting one is read in the picture (`ankle`, px, y down) in the
+ * free side's leg length — the unit of every FEET threshold. Within `tolerance`,
+ * the frame is planted both: the free leg is to be stretched along its chain by
+ * k = (root y − floor y) / (root y − ankle y) on the posed rig (`posed`, world,
+ * y up), the floor being the supporting ankle's posed y; k is held within
+ * `STANCE_BOUNDS` (a free ankle below the floor shortens its leg, one above
+ * lengthens it), and a frame past them is listed in `over`. Above the tolerance
+ * the foot is lifted and keeps the pose's height.
+ */
+export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, tolerance: number, posed: (i: number) => StancePosed): Stance {
+  const n = feet.support.length;
+  const stretch: Stance['stretch'] = new Array(n).fill(null);
+  type Row = { state: 'both' | 'lifted'; side: Side; height: number; k: number | null; needed: number | null; over: boolean; left: number };
+  const rows: Array<Row | null> = new Array<Row | null>(n).fill(null);
+  for (let i = 0; i < n; i++) {
+    const s = feet.support[i] ?? null;
+    if (s === null) continue;
+    const f: Side = s === 'r' ? 'l' : 'r';
+    const height = (ankle[s][i]![1] - ankle[f][i]![1]) / feet.legLength[f];
+    if (height > tolerance) {
+      rows[i] = { state: 'lifted', side: f, height, k: null, needed: null, over: false, left: 0 };
+      continue;
+    }
+    const p = posed(i);
+    const floor = p.ankle[s][1];
+    const root = p.root[f][1];
+    const a = p.ankle[f][1];
+    const ok = root - a > 1e-9 && root - floor > 1e-9;
+    const needed = ok ? (root - floor) / (root - a) : null;
+    const k = needed === null ? 1 : Math.min(Math.max(needed, STANCE_BOUNDS[0]), STANCE_BOUNDS[1]);
+    const over = needed === null || needed < STANCE_BOUNDS[0] || needed > STANCE_BOUNDS[1];
+    const left = Math.abs(root - k * (root - a) - floor);
+    rows[i] = { state: 'both', side: f, height, k, needed, over, left };
+    if (k !== 1) stretch[i] = { side: f, k };
+  }
+  const runs: StanceRun[] = [];
+  const over: StanceOver[] = [];
+  for (let i = 0; i < n; i++) {
+    const r = rows[i];
+    if (r === null) continue;
+    const last = runs[runs.length - 1];
+    if (last !== undefined && last.frames[1] === i - 1 && last.state === r.state && last.side === r.side) {
+      last.frames[1] = i;
+      last.maxHeight = Math.max(last.maxHeight, r.height);
+      if (last.k !== null && r.k !== null) last.k = { min: Math.min(last.k.min, r.k), max: Math.max(last.k.max, r.k) };
+    } else runs.push({ state: r.state, side: r.side, frames: [i, i], maxHeight: r.height, k: r.k === null ? null : { min: r.k, max: r.k } });
+    if (!r.over) continue;
+    const o = over[over.length - 1];
+    if (o !== undefined && o.frames[1] === i - 1 && o.side === r.side) {
+      o.frames[1] = i;
+      o.needed = o.needed === null || r.needed === null ? null : Math.abs(r.needed - 1) > Math.abs(o.needed - 1) ? r.needed : o.needed;
+      o.left = Math.max(o.left, r.left);
+    } else over.push({ side: r.side, frames: [i, i], needed: r.needed, left: r.left });
+  }
+  return { tolerance, bounds: STANCE_BOUNDS, runs, over, stretch };
+}

package/src/pose.ts

@@ -39,16 +39,35 @@ export interface PoseFrame {
   t: number;
   people: Person[];
 }
+/**
+ * The picture's camera on one frame against frame 0's (rig-c/pose#63), as
+ * `tools/scan.py` reads it off the background: a point p₀ of frame 0's picture
+ * appears at `s · p₀ + (tx, ty)` on this frame. The joints of a sequence that
+ * carries a camera are already normalised by it, `p′ = (p − t) / s`. `inliers`
+ * is the number of background features the fit kept.
+ */
+export interface CameraFrame {
+  s: number;
+  tx: number;
+  ty: number;
+  inliers: number;
+}
 export interface PoseSequence {
   spec: typeof POSE_SPEC;
   space: typeof POSE_SPACE;
   width: number;
   height: number;
   source: string;
+  /** Optional, only with `camera`: where it came from — "tracked", or "hand-labelled, N keys" (#63). */
+  cameraSource?: string;
+  /** Optional: one per frame, when a scan read the camera (#63). */
+  camera?: CameraFrame[];
   frames: PoseFrame[];
 }
 
 const TOP_KEYS = ['spec', 'space', 'width', 'height', 'source', 'frames'];
+const OPTIONAL_KEYS = ['cameraSource', 'camera'];
+const CAMERA_KEYS = ['s', 'tx', 'ty', 'inliers'];
 
 /**
  * The older name the same file went by: `rig-c-pose-frames/0`, written by the
@@ -70,7 +89,7 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
     throw new Error('unreachable');
   }
   const frames0 = doc.spec === POSE_SPEC_FRAMES0;
-  refuseUnknownKeys(p, 'POSE_KEYS', where, doc, frames0 ? [...TOP_KEYS, 'fps'] : TOP_KEYS);
+  refuseUnknownKeys(p, 'POSE_KEYS', where, doc, frames0 ? [...TOP_KEYS, ...OPTIONAL_KEYS, 'fps'] : [...TOP_KEYS, ...OPTIONAL_KEYS]);
   for (const k of TOP_KEYS) if (!(k in doc)) p.add('POSE_KEYS', `${where} has no "${k}"; a ${POSE_SPEC} document carries ${TOP_KEYS.join(', ')}`);
   if ('spec' in doc && doc.spec !== POSE_SPEC && !frames0) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}" (and the older name "${POSE_SPEC_FRAMES0}")`);
   const space = frames0 ? FRAMES0_SPACE : POSE_SPACE;
@@ -127,8 +146,52 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
       });
     }
   }
+  const camera = 'camera' in doc ? readCamera(p, where, doc.camera, Array.isArray(doc.frames) ? doc.frames.length : null) : undefined;
+  if ('cameraSource' in doc) {
+    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`);
+  }
   p.throwIfAny();
-  return { spec: POSE_SPEC, space: POSE_SPACE, width: doc.width as number, height: doc.height as number, source: doc.source as string, frames };
+  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 } : {}), frames };
+}
+
+/** `camera`: one `{ s > 0, tx, ty, inliers ≥ 0 }` per frame, as many as `frames`. */
+function readCamera(p: Problems, where: string, camera: unknown, frames: number | null): CameraFrame[] {
+  const out: CameraFrame[] = [];
+  if (!Array.isArray(camera)) {
+    p.add('POSE_CAMERA', `${where} "camera" is ${typeName(camera)}; it must be an array with one { s, tx, ty, inliers } per frame`);
+    return out;
+  }
+  if (frames !== null && camera.length !== frames) p.add('POSE_CAMERA', `${where} "camera" has ${camera.length} entr${camera.length === 1 ? 'y' : 'ies'} and "frames" ${frames}; it must have one per frame`);
+  camera.forEach((c: unknown, i: number) => {
+    const cw = `${where} camera[${i}]`;
+    if (!isObject(c)) {
+      p.add('POSE_CAMERA', `${cw} is ${typeName(c)}; a camera entry is { s, tx, ty, inliers }`);
+      return;
+    }
+    refuseUnknownKeys(p, 'POSE_CAMERA', cw, c, CAMERA_KEYS);
+    let ok = true;
+    for (const k of CAMERA_KEYS) if (!(k in c)) {
+      p.add('POSE_CAMERA', `${cw} has no "${k}"; a camera entry carries ${CAMERA_KEYS.join(', ')}`);
+      ok = false;
+    }
+    const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+    if ('s' in c && !(finite(c.s) && c.s > 0)) {
+      p.add('POSE_CAMERA', `${cw} "s" is ${typeName(c.s)}; the scale must be a finite number > 0`);
+      ok = false;
+    }
+    for (const k of ['tx', 'ty'] as const) if (k in c && !finite(c[k])) {
+      p.add('POSE_CAMERA', `${cw} "${k}" is ${typeName(c[k])}; it must be a finite number of picture px`);
+      ok = false;
+    }
+    if ('inliers' in c && !(Number.isInteger(c.inliers) && (c.inliers as number) >= 0)) {
+      p.add('POSE_CAMERA', `${cw} "inliers" is ${typeName(c.inliers)}; it must be an integer ≥ 0`);
+      ok = false;
+    }
+    if (ok) out.push({ s: c.s as number, tx: c.tx as number, ty: c.ty as number, inliers: c.inliers as number });
+  });
+  return out;
 }
 
 function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Body18, Joint>> {
@@ -312,5 +375,6 @@ export function writePoseSequence(seq: PoseSequence): string {
       ),
     })),
   }));
-  return `${JSON.stringify({ spec: seq.spec, space: seq.space, width: seq.width, height: seq.height, source: seq.source, frames }, null, 2)}\n`;
+  const camera = seq.camera?.map((c) => ({ s: round(c.s, 6), tx: round(c.tx, 3), ty: round(c.ty, 3), inliers: c.inliers }));
+  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 } : {}), frames }, null, 2)}\n`;
 }

package/src/retarget.ts

@@ -69,8 +69,8 @@ import type { Joint } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
-import type { Feet, LegScale, PathPose, Posing, Side } from './legs.ts';
-import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, supportsOf, tipOf } from './legs.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';
 
 const DEG = 180 / Math.PI;
 
@@ -91,6 +91,8 @@ export interface RetargetOptions extends SwitchOptions {
   legScale?: [number, number] | 'off';
   /** The hip derived from the supporting foot (`legs.ts`); false (the default) moves it by the pose's travel. */
   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';
 }
 
 export interface Hold {
@@ -267,6 +269,8 @@ export interface Retarget {
   feet: Feet | null;
   /** Whether the hip was derived from the supporting foot. */
   planted: boolean;
+  /** With --stance: the frames planted both and lifted, and the free leg's stretch (#60). */
+  stance: Stance | 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. */
@@ -638,6 +642,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const plantOn = opts.plantFeet === true;
   const legScale: LegScale[] = [];
   const scales = new Map<string, number[]>();
+  let stance: Stance | null = null;
   let feet: Feet | null = null;
   let legs: ReturnType<typeof legsOf> | null = null;
   let legPath: string[] | null = null;
@@ -692,6 +697,7 @@ 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`);
   p.throwIfAny();
   /** Every bone on the legs' path posed on frame i, by the targets as they stand. */
   const poseLegs = (i: number): PathPose => {
@@ -714,6 +720,31 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     const tb = rest.get(t!.bone)!;
     const hip = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY]);
     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)) },
+        };
+      });
+      for (const side of SIDES) {
+        if (!stance.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) => {
+            if (x?.side === side) s[i] = s[i]! * x.k;
+          });
+          scales.set(b, s);
+        }
+      }
+    }
   }
   if (t !== null && scale !== null) {
     const bone = rest.get(t.bone)!;
@@ -884,7 +915,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, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs),
+    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs),
   };
 }
 

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 { convertCoco17, personTrack, readPoseSequence } from './pose.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';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions } from './retarget.ts';
@@ -17,7 +17,7 @@ import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf } from './legs.ts';
 import { reduceKeys, type ReduceBone, type Reduced } from './reduce.ts';
-import type { LegScale } from './legs.ts';
+import type { LegScale, Stance } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -104,8 +104,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
+    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
+    if (seq.camera !== undefined) say(`  CAMERA ${cameraLine(seq.camera, times, seq.cameraSource)}`);
+    else if (a.plantFeet === true) say('  CAMERA none in the sequence: --plant-feet reads the picture as a fixed camera, so a zoom or a pan in the video moves the floor with it and the floor may step with the picture (tools/scan.py reads the camera, rig-c/pose#63)');
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
     if (a.short !== 'off') {
@@ -133,6 +135,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       say(`  FEET   jumps (both ankles and mid_hip > 0.05 leg lengths above their rolling floor, ≥ 2 frames): ${f.jumps.map(span).join(', ') || 'none'}`);
       say(`  FEET   steps (the supporting ankle > 0.03 leg lengths a frame; re-planted after 2 frames < 0.01): ${f.steps.map((x) => `${x.side} ${span(x.frames)} → ${x.to === null ? 'the pose\'s travel' : `${x.to} supports`}, ${x.replant === null ? 'never re-planted' : `re-planted at ${x.replant}`}`).join('; ') || 'none'}`);
     }
+    if (r.stance !== null) for (const l of stanceLines(r.stance, r.times)) say(`  STANCE ${l}`);
 
     // --reduce (#32): the dense keys thinned top-down, before anything reads the tracks.
     const reduced = a.reduce === undefined ? null : reduceTracks(r, map, rest, a.reduce, a.reduceHip);
@@ -263,7 +266,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         animation: a.name,
         frames: seq.frames.length,
         duration: r.animation.duration,
-        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -281,6 +284,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         artRange: r.artRange,
         legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
         pivot: r.pivot,
+        stance: r.stance === null ? null : { tolerance: r.stance.tolerance, bounds: r.stance.bounds, runs: r.stance.runs, over: r.stance.over },
         feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, reading: feetReading },
         shear,
         idleDropped: idle === null ? null : idle.dropped,
@@ -388,6 +392,22 @@ function windowLines(map: JointMap, switches: ReadonlyArray<{ set: string; frame
   return out;
 }
 
+/**
+ * The CAMERA line (#63): where the camera came from (the sequence's
+ * `cameraSource`, or "(source not stated)"), the scale's range over the sequence, and the three
+ * frame-to-frame changes of s largest in size (ties to the earlier frame).
+ */
+export function cameraLine(camera: readonly CameraFrame[], times: readonly number[], source: string | undefined): string {
+  const ss = camera.map((c) => c.s);
+  const lo = ss.reduce((m, x, i) => (x < ss[m]! ? i : m), 0);
+  const hi = ss.reduce((m, x, i) => (x > ss[m]! ? i : m), 0);
+  const steps = ss.slice(1).map((x, k) => ({ to: k + 1, d: x - ss[k]! }));
+  const fastest = [...steps].sort((x, y) => Math.abs(y.d) - Math.abs(x.d) || x.to - y.to).slice(0, 3);
+  const sign = (d: number) => `${d < 0 ? '−' : '+'}${Math.abs(d).toFixed(4)}`;
+  const inl = camera.reduce((m, c) => Math.min(m, c.inliers), Infinity);
+  return `${source ?? '(source not stated)'}: the sequence carries the picture's camera against frame 0's; its joints are normalised by it (p′ = (p − t) / s): s ${ss[lo]!.toFixed(4)} (frame ${lo}) … ${ss[hi]!.toFixed(4)} (frame ${hi}) over ${camera.length} frames; s changes fastest at ${fastest.map((x) => `frame ${x.to - 1}→${x.to} (t=${times[x.to]!.toFixed(3)}s) ${sign(x.d)}`).join(', ') || 'no frame (one frame only)'}${source?.startsWith('hand-labelled') === true ? '' : `; fewest background inliers ${inl}`}`;
+}
+
 /** Each leg's first bone (its root, the thigh) and last bone (whose tip is the ankle), when the map has both. */
 function legBonesOf(map: JointMap): { r: { root: string; ankle: string }; l: { root: string; ankle: string } } | null {
   const l = legsOf(map, 'reading the feet');
@@ -395,6 +415,20 @@ function legBonesOf(map: JointMap): { r: { root: string; ankle: string }; l: { r
   return { r: { root: l.legs.r.chain.bones[0]!, ankle: l.legs.r.ankleBone }, l: { root: l.legs.l.chain.bones[0]!, ankle: l.legs.l.ankleBone } };
 }
 
+/**
+ * The STANCE lines (#60): one per run of planted-both or lifted frames, with
+ * the tolerance and the stretch keyed; one per run a stretch was capped.
+ */
+export function stanceLines(st: Stance, times: readonly number[]): string[] {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
+  const tol = `the tolerance ${st.tolerance} leg lengths`;
+  const out = st.runs.map((r) => (r.state === 'both'
+    ? `planted both: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, within ${tol}; its leg stretched by k ${r.k!.min === r.k!.max ? r.k!.max.toFixed(4) : `${r.k!.min.toFixed(4)} … ${r.k!.max.toFixed(4)}`} (largest ${r.k!.max.toFixed(4)})`
+    : `lifted: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, over ${tol}; the pose's height kept`));
+  for (const o of st.over) out.push(`past the bounds: free foot ${o.side} ${span(o.frames)} — ${o.needed === null ? 'its ankle is not below its leg\'s root, so no stretch reaches the floor' : `the floor needed k ${o.needed.toFixed(4)}, past [${st.bounds[0]}, ${st.bounds[1]}]; held at the bound`}, the foot left up to ${o.left.toFixed(2)} units from the floor`);
+  return out;
+}
+
 /** A LEG-SCALE line: the segment, its straight length, its ratio's spread, and the frames clamped. */
 function legScaleLine(l: LegScale, times: readonly number[]): string {
   const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);