@rig-c/pose 0.20.5 → 0.22.0

package/README.md

@@ -143,6 +143,7 @@ and what the run cannot decide for you it lists:
 - `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.
+- `FACE` — with `face` in the map ([#138](https://github.com/rig-c/pose/issues/138)): per-frame yaw and pitch read from `nose` against the eye midpoint (`r_eye + l_eye`) and, when present, the ear midpoint (`r_ear + l_ear`), de-rolled by the eye line, then compressed into each configured axis's `[min, max]` range (`scale` and correlation `r`), and written as `face` in `--report`.
 - `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`): `spec`, `rigc` (`{ version, entry }`: the rig-c that gated it), `rig`, `animation`, `frames`, `duration`, `cleaned` (the sequence's `cleaned` record, [above](#clean-first-rig-pose-clean)), `options` (every figure the run used, `switchTolerance`, `switchMin`, `switchAt`, `legScale`, `plantFeet`, `stance`, `floor` and `raisedByHead` included), `scale`, `holds`, `short`, `endOn`, `bends`, `flips`, `gate` (rig-c's gate summary, a string), `landings`, `posture`, `folds`, `legScale`, `pivot`, `feet` (`planted`, `legLength`, `supports`, `jumps`, `steps`, `changes`, `lowered`, `floor`, `shifts`, `blend`, `closure`, and the posed `reading`; a jump is an inclusive `[first, last]` pair of frames; `lowered` holds `{ frames, was, now, cause? }` runs (`cause`, where `now` is `null`: `released` or `higher`), present only with `--plant-feet` on a sequence not declared in place ([#113](https://github.com/rig-c/pose/issues/113)); `floor` is the world y every support span was planted on and `shifts` holds one `{ side, frames, shift }` per support span in world units, `null` and empty without `--plant-feet`; `blend` is `{ bounds, runs: [{ side, frames, k: { min, max } }], over: [{ side, frames, needed, left }] }`, the supporting leg stretched on the blend frames, `null` without `--plant-feet`; `closure` is `{ drift, frames }`, the hip's x drift closed over an in-place loop, `null` unless the sequence is `"in-place"` and `--plant-feet` is given), `stance` (`tolerance`, `release`, `minSeconds`, `bounds`, `runs`: `{ state, side, frames, maxHeight, maxDepth?, k, absorbed? }` (`state` is `both`, `lifted` or `below`; `maxDepth`, on a `below` run, is the free ankle's largest distance below the supporting one in leg lengths), `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:
@@ -195,7 +196,7 @@ Re-checked on the exam01 test rig with `--short 0.35 --flip 90 --bends clamp`. O
 
 A knee bending toward the camera is seen from the front only as a shorter leg, and a rig with rigid legs cannot lower its hip without lifting its feet ([#47](https://github.com/rig-c/pose/issues/47)). Two flags, both off by default:
 
-**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the larger of the two sides' 95th-percentile picture lengths for that segment over the sequence ([#148](https://github.com/rig-c/pose/issues/148)), clamped to [min, max]. The card's range is `0.8,1.05`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit.
+**`--leg-scale <min,max>`** scales each mapped leg segment (two of one side's hip, knee and ankle) along its own x axis — a `scalex` key — by its picture length on the frame over its **straight length**, the larger of the two sides' 95th-percentile picture lengths for that segment over the sequence ([#148](https://github.com/rig-c/pose/issues/148); on a non-`in-place` sequence longer than 25 frames, each frame's segment length is normalised by a continuous rate-limited figure-scale signal `figureScaleOf` over `nose → lower ankle` standing height — frame-to-frame step ≤ 1 %, frozen spans ≥ 5 frames held at their median — so camera zoom neither shrinks earlier phrases nor lags behind frozen endings, and `--camera <file>` writes that track as `rig-pose-camera/1` without changing `motion.json`, [#159](https://github.com/rig-c/pose/issues/159), [#161](https://github.com/rig-c/pose/issues/161), [#163](https://github.com/rig-c/pose/issues/163)), clamped to [min, max]. The card's range is `0.8,1.05`. A segment the map aims other than `"x"` is refused (`LEGS_MAP`). `LEG-SCALE` lists each segment's frames clamped at either limit.
 
 rig-c's `scalex` multiplies the bone's x axis, and a child with the `normal` inherit mode takes its parent's whole world matrix. So under a thigh scaled by s, a shin at angle φ in the thigh's axes points at atan2(sin φ, s·cos φ), and is itself scaled by |(s·cos φ, sin φ)|. A child (or its intermediate control bone) with `noScale` or `noScaleOrReflection` ([#153](https://github.com/rig-c/pose/issues/153)) still has its direction carried through the parent's scaled matrix, so its angle is skewed the same way, while rig-c normalises that direction to unit length so the parent's scale is not inherited. The rotate key `turn − turn above` assumes unit scale. A mapped bone under a scaled bone is therefore keyed through its parent's posed matrix: a `rotate` key k and a `scalex` key s' put its world x axis on its target at the scale asked (under `noScale`, s' is the bone's own asked scale s directly). On HQ's dancer the unit-scale formula missed the shins by up to 2.4°, their length by 0.16 of setup and the ankles by 38 units; solved, every bone lands. A `normal` child's art is still sheared by its parent's scale, and a bone under it (a foot) is squashed along the shin: `SHEAR` reads both.
 
@@ -312,6 +313,7 @@ Which bones carry which joints. You write it for your rig:
   ⚠️ **Seen from the front, an elbow's side is not a joint limit.** An elbow flexes toward the camera, and its picture falls on either side of the upper arm depending on how the arm is turned. On a real 13 s front-facing dance (313 frames, RTMPose), the right elbow sat on the "wrong" side of the rig's rest on 165 frames (median 23°), and the left on 200 (median 29°, up to 179° with the hands behind the head). Every one was a real elbow bend. The knees strayed at most 8.8° and 14.7°, which is pose noise around a straight leg. So for front-facing material, arms go `"free"`. Legs on `"rest"` with `--bends clamp` hold only while the knees stay near straight. On a second dance with knee bends (Toca Toca, rig-c/pose#27), that setting straightened the left knee for most of the dance: `leg_l1` was 48.3° off at p90, against 0.0–0.3° with free legs. Leave legs `"free"` unless the dance keeps its knees straight.
 - `mid_hip` and `mid_shoulder` are the midpoints of the two hips and the two shoulders.
 - `translate.scale` is one length measured on both: two points on the rig, two points in the pose (its median over the frames where both are good). Pick a long segment that does not foreshorten much.
+- `face` (optional, [#138](https://github.com/rig-c/pose/issues/138), [#164](https://github.com/rig-c/pose/issues/164)): `{ "yaw"?: { "bone": "yaw", "range": [-15, 15] }, "pitch"?: { "bone": "pitch", "range": [-10, 15] } }` (`min ≤ 0 ≤ max`, `min < max`). Reads per-frame yaw and pitch from `nose` against `r_eye + l_eye` (and `r_ear + l_ear` when present), maps 1:1 inside `0.8 × range` (`[-12, 12]°` on `[-15, 15]°`) and compresses only the overshoot above the knee into the remaining 20% of the range so a single outlier frame does not crush the rest of the clip, and keys the named dial bone's `rotate` track (`FACE`).
 
 ### A joint's range: `range`
 
@@ -357,7 +359,7 @@ The bound exists because speed alone rewarded showing art far from its pose. Unb
 
 Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's old and new frame (the same under `first`), the frames and seconds it moved, the speed on both and its window, and the report carries the same under `moved`.
 
-**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
+**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. Between two sets that both draw an arm behind the torso, a frame that belongs to neither set stays behind (the nearer set's layer); the default front slot is for a frame no set can claim **and** whose arm is read in front — not a fallback ([#136](https://github.com/rig-c/pose/issues/136), [#139](https://github.com/rig-c/pose/issues/139), [#162](https://github.com/rig-c/pose/issues/162)). A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
 
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds, held as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 

package/cli.ts

@@ -165,6 +165,9 @@ retarget
   --report <file>       write the run's measurements (holds, short, endOn, flips, bends, landings, folds,
                         switches, uncovered, turns, range, artRange, raised, byHip,
                         idleDropped, idleKeptOut, merged, reduce) as JSON
+  --camera <file>       write the sequence's camera track (rig-pose-camera/1: continuous figure scale s,
+                        raw standing height ratio, pan tx/ty, and composite videoS) as a sidecar JSON file
+                        without changing motion.json (rig-c/pose#161)
 
   It writes nothing until rigc's gate is green with the animation in, every mapped bone lands on
   the angle the pose asks for (posed by rig-c's own poser), and no hinge bends the wrong way.
@@ -262,7 +265,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', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head']);
+  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', 'camera', 'leg-scale', 'idle', 'merge', 'reduce', 'reduce-hip', 'stance', 'floor'], ['coco', 'plant-feet', 'carry-idle', 'raised-by-head']);
   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';
@@ -299,6 +302,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     build: f.get('build'),
     render: f.get('render'),
     report: f.get('report'),
+    camera: f.get('camera'),
     idle: f.get('idle'),
     carryIdle: f.has('carry-idle'),
     merge: f.get('merge'),

package/package.json

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

@@ -0,0 +1,259 @@
+/**
+ * Face direction (`rig-c/pose#138`): read yaw and pitch per frame from the five
+ * body-18 face points (`nose` against the eye midpoint `r_eye + l_eye` and,
+ * when present, the ear midpoint `r_ear + l_ear`, de-rolled by the eye line),
+ * and map each configured axis into its declared range by compression (never
+ * clipping, so motion changes at the extremes survive).
+ */
+import type { FaceAxis, FaceMap } from './map.ts';
+
+type Pt = [number, number];
+
+const DEG = 180 / Math.PI;
+
+/**
+ * Fraction of each side's limit below which `mapFaceAxis` is 1:1 identity
+ * (`rig-c/pose#164`); above `FACE_KNEE * limit` (`12°` for `15°`, `8°` for `10°`),
+ * a piecewise-linear knee compresses only the overshoot `[k, peak]` into `[k, limit]`.
+ */
+export const FACE_KNEE = 0.8;
+
+export interface FaceSpan {
+  min: number;
+  max: number;
+  range: number;
+}
+
+export interface FaceAxisReading {
+  bone: string;
+  limits: [number, number];
+  /** Knee thresholds `[kneeNeg, kneePos]` in degrees (`FACE_KNEE * limits`), inside which mapping is 1:1. */
+  knee: [number, number];
+  read: FaceSpan;
+  mapped: FaceSpan;
+  /** Peak-to-limit ratios `[kNeg, kPos]` in (0, 1] for negative and positive sides. */
+  scale: [number, number];
+  /** Spearman rank (monotone) correlation between the read angle and the mapped keys over the clip. */
+  corr: number;
+  /** Per-frame read angle in degrees, before range compression. */
+  raw: number[];
+  /** Per-frame mapped rotate key in degrees, rounded to 0.001°. */
+  keys: number[];
+}
+
+export interface FaceReading {
+  ears: boolean;
+  read: {
+    yaw: FaceSpan;
+    pitch: FaceSpan;
+    rawYaw: number[];
+    rawPitch: number[];
+  };
+  yaw?: FaceAxisReading;
+  pitch?: FaceAxisReading;
+}
+
+const r3 = (v: number): number => {
+  const r = Math.round(v * 1000) / 1000;
+  return Object.is(r, -0) ? 0 : r;
+};
+
+function median(xs: readonly number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+function spanOf(xs: readonly number[]): FaceSpan {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const x of xs) {
+    if (x < min) min = x;
+    if (x > max) max = x;
+  }
+  return { min: r3(min), max: r3(max), range: r3(max - min) };
+}
+
+function ranksOf(xs: readonly number[]): number[] {
+  const idx = xs.map((_, i) => i).sort((a, b) => xs[a]! - xs[b]!);
+  const out = new Array<number>(xs.length).fill(0);
+  for (let i = 0; i < idx.length;) {
+    let j = i;
+    while (j + 1 < idx.length && xs[idx[j + 1]!]! === xs[idx[i]!]!) j++;
+    const rank = 0.5 * (i + j);
+    for (let k = i; k <= j; k++) out[idx[k]!] = rank;
+    i = j + 1;
+  }
+  return out;
+}
+
+function corrOf(a: readonly number[], b: readonly number[]): number {
+  if (a.length < 2 || a.length !== b.length) return 1;
+  const ra = ranksOf(a);
+  const rb = ranksOf(b);
+  const ma = ra.reduce((x, y) => x + y, 0) / ra.length;
+  const mb = rb.reduce((x, y) => x + y, 0) / rb.length;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < ra.length; i++) {
+    const xa = ra[i]! - ma;
+    const xb = rb[i]! - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  const den = Math.sqrt(da * db);
+  return den > 1e-9 ? r3(num / den) : 1;
+}
+
+/**
+ * Read per-frame yaw and pitch (degrees) from `nose`, `r_eye`, `l_eye`, and
+ * (when both are present) `r_ear` and `l_ear`.
+ *
+ * Sign convention (matching `rig-c` gallery `look` and the Part 1 range sweep):
+ * - `yaw > 0`: nose turned toward the subject's right (`r_eye`, viewer-left).
+ * - `pitch > 0`: nose tilted down (chin down / nod down).
+ */
+export function readFaceAngles(
+  nose: readonly Pt[],
+  rEye: readonly Pt[],
+  lEye: readonly Pt[],
+  rEar: readonly Pt[] | null,
+  lEar: readonly Pt[] | null,
+): { ears: boolean; yaw: number[]; pitch: number[] } {
+  const n = nose.length;
+  const ears = rEar !== null && lEar !== null && rEar.length === n && lEar.length === n;
+  const xne: number[] = [];
+  const xna: number[] = [];
+  const yne: number[] = [];
+  const yna: number[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const N = nose[i]!;
+    const Er = rEye[i]!;
+    const El = lEye[i]!;
+    const ex = El[0] - Er[0];
+    const ey = El[1] - Er[1];
+    const de = Math.hypot(ex, ey);
+    if (!(de > 1e-9)) {
+      xne.push(xne[i - 1] ?? 0);
+      yne.push(yne[i - 1] ?? 0);
+      if (ears) {
+        xna.push(xna[i - 1] ?? 0);
+        yna.push(yna[i - 1] ?? 0);
+      }
+      continue;
+    }
+    const ux = ex / de;
+    const uy = ey / de;
+    const vx = -uy;
+    const vy = ux;
+    const mex = 0.5 * (Er[0] + El[0]);
+    const mey = 0.5 * (Er[1] + El[1]);
+    xne.push(((mex - N[0]) * ux + (mey - N[1]) * uy) / de);
+    yne.push(((N[0] - mex) * vx + (N[1] - mey) * vy) / de);
+    if (ears) {
+      const Ar = rEar[i]!;
+      const Al = lEar[i]!;
+      const max = 0.5 * (Ar[0] + Al[0]);
+      const may = 0.5 * (Ar[1] + Al[1]);
+      const da = Math.max(de, (Al[0] - Ar[0]) * ux + (Al[1] - Ar[1]) * uy);
+      xna.push(((max - N[0]) * ux + (may - N[1]) * uy) / da);
+      yna.push(((N[0] - max) * vx + (N[1] - may) * vy) / de);
+    }
+  }
+
+  const yne0 = median(yne);
+  const yna0 = ears ? median(yna) : 0;
+  const yaw: number[] = [];
+  const pitch: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const ty = ears ? (2 * xne[i]! + xna[i]!) / 2 : 2 * xne[i]!;
+    const tp = ears ? (yne[i]! - yne0 + (yna[i]! - yna0)) / 2 : yne[i]! - yne0;
+    yaw.push(Math.atan(ty) * DEG);
+    pitch.push(Math.atan(tp) * DEG);
+  }
+  return { ears, yaw, pitch };
+}
+
+function mapKneeSide(u: number, limit: number, peak: number): number {
+  if (!(limit > 1e-9)) return 0;
+  if (!(peak > limit)) return u;
+  const k = FACE_KNEE * limit;
+  if (u <= k) return u;
+  if (u >= peak) return limit;
+  return k + ((limit - k) * (u - k)) / (peak - k);
+}
+
+/**
+ * Compress a read angle series into `axis.range` (`[min, max]` with `min <= 0 <= max`):
+ * readings on a side whose peak stays inside the limit map 1:1 (`f(x) = x`); when a
+ * side's peak exceeds its limit `L`, readings up to the knee `k = FACE_KNEE * L`
+ * (`0.8 * L`, `rig-c/pose#164`) still map 1:1 and only the overshoot `[k, peak]` is
+ * compressed linearly into `[k, L]`.
+ */
+export function mapFaceAxis(raw: readonly number[], axis: FaceAxis): FaceAxisReading {
+  const limits = axis.range;
+  let rawMin = Infinity;
+  let rawMax = -Infinity;
+  for (const x of raw) {
+    if (x < rawMin) rawMin = x;
+    if (x > rawMax) rawMax = x;
+  }
+  const limNeg = -limits[0];
+  const limPos = limits[1];
+  const peakNeg = -rawMin;
+  const peakPos = rawMax;
+  const kNeg = rawMin < limits[0] && rawMin < -1e-9 ? limits[0] / rawMin : 1;
+  const kPos = rawMax > limits[1] && rawMax > 1e-9 ? limits[1] / rawMax : 1;
+  const keys = raw.map((x) => r3(x < 0 ? -mapKneeSide(-x, limNeg, peakNeg) : mapKneeSide(x, limPos, peakPos)));
+  return {
+    bone: axis.bone,
+    limits: [limits[0], limits[1]],
+    knee: [r3(FACE_KNEE * limits[0]), r3(FACE_KNEE * limits[1])],
+    read: spanOf(raw),
+    mapped: spanOf(keys),
+    scale: [r3(kNeg), r3(kPos)],
+    corr: corrOf(raw, keys),
+    raw: [...raw],
+    keys,
+  };
+}
+
+export function readFace(
+  face: FaceMap,
+  nose: readonly Pt[],
+  rEye: readonly Pt[],
+  lEye: readonly Pt[],
+  rEar: readonly Pt[] | null,
+  lEar: readonly Pt[] | null,
+): FaceReading {
+  const { ears, yaw, pitch } = readFaceAngles(nose, rEye, lEye, rEar, lEar);
+  return {
+    ears,
+    read: {
+      yaw: spanOf(yaw),
+      pitch: spanOf(pitch),
+      rawYaw: yaw,
+      rawPitch: pitch,
+    },
+    ...(face.yaw === undefined ? {} : { yaw: mapFaceAxis(yaw, face.yaw) }),
+    ...(face.pitch === undefined ? {} : { pitch: mapFaceAxis(pitch, face.pitch) }),
+  };
+}
+
+const f1 = (x: number): string => x.toFixed(1);
+const sg = (x: number): string => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
+
+export function faceLine(f: FaceReading): string {
+  const joints = f.ears ? 'nose against r_eye + l_eye, r_ear + l_ear' : 'nose against r_eye + l_eye (ears absent)';
+  const readPart = `read yaw ${sg(f.read.yaw.min)}° … ${sg(f.read.yaw.max)}° (${f1(f.read.yaw.range)}°), pitch ${sg(f.read.pitch.min)}° … ${sg(f.read.pitch.max)}° (${f1(f.read.pitch.range)}°)`;
+  const axes: string[] = [];
+  for (const name of ['yaw', 'pitch'] as const) {
+    const ax = f[name];
+    if (ax === undefined) continue;
+    axes.push(`${name} → bone "${ax.bone}" [${ax.limits[0]}, ${ax.limits[1]}]° (knee [${ax.knee[0]}, ${ax.knee[1]}]°): ${sg(ax.mapped.min)}° … ${sg(ax.mapped.max)}° (scale ${ax.scale[0].toFixed(3)}/${ax.scale[1].toFixed(3)}, r=${ax.corr.toFixed(3)})`);
+  }
+  return `${joints}: ${readPart}; mapped ${axes.join(', ')}`;
+}

package/src/legs.ts

@@ -834,6 +834,82 @@ export const STANCE_BOUNDS: readonly [number, number] = [0.92, 1.08];
 /** Per side, per frame: the lower bound of the leg's stretch (#95). */
 export type StanceLower = Record<Side, readonly number[]>;
 
+/** Maximum per-frame relative step of the continuous figure-scale curve (`rig-c/pose#163`). */
+export const FIGURE_SCALE_STEP = 0.01;
+/** Consecutive frames whose raw figure height stays within this many pixels over ≥ `FROZEN_MIN_FRAMES` frames hold their span median (`rig-c/pose#163`). */
+export const FROZEN_STEP_PX = 0.5;
+export const FROZEN_MIN_FRAMES = 5;
+
+function medianOf(xs: readonly number[]): number {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 === 1 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
+}
+
+/**
+ * Continuous per-frame figure scale `s[i]` (`s[0] = 1`, `rig-c/pose#163`,
+ * `rig-c/pose#161`): L2 projection of `log(raw)` onto the rate-limited corridor
+ * `|log(s[i+1] / s[i])| <= log(1 + FIGURE_SCALE_STEP)` (`≤ 1%` per frame),
+ * holding any frozen span (`≥ FROZEN_MIN_FRAMES` frames where consecutive raw
+ * heights move by `≤ FROZEN_STEP_PX`) constant at its span median.
+ */
+export function figureScaleOf(raw: readonly number[], maxStep = FIGURE_SCALE_STEP): number[] {
+  const m = raw.length;
+  if (m === 0) return [];
+  const u = raw.map((v) => Math.log(Math.max(1e-6, v)));
+  const spans: Array<{ lo: number; hi: number; val: number }> = [];
+  for (let i = 0; i < m - 1;) {
+    if (Math.abs(raw[i + 1]! - raw[i]!) > FROZEN_STEP_PX) {
+      i++;
+      continue;
+    }
+    let j = i + 1;
+    while (j + 1 < m && Math.abs(raw[j + 1]! - raw[j]!) <= FROZEN_STEP_PX) j++;
+    if (j - i + 1 >= FROZEN_MIN_FRAMES) {
+      const med = Math.log(Math.max(1e-6, medianOf(raw.slice(i, j + 1))));
+      for (let k = i; k <= j; k++) u[k] = med;
+      spans.push({ lo: i, hi: j, val: med });
+    }
+    i = j + 1;
+  }
+  const r0 = Math.log(1 + maxStep);
+  const r = new Array<number>(Math.max(0, m - 1)).fill(r0);
+  for (const sp of spans) {
+    for (let i = sp.lo; i < sp.hi; i++) r[i] = 0;
+  }
+  for (let k = 0; k + 1 < spans.length; k++) {
+    const a = spans[k]!;
+    const b = spans[k + 1]!;
+    const gap = b.lo - a.hi;
+    if (gap > 0) {
+      const needed = Math.abs(b.val - a.val) / gap;
+      if (needed > r0) {
+        for (let i = a.hi; i < b.lo; i++) r[i] = needed * 1.0001;
+      }
+    }
+  }
+  const lam = new Array<number>(Math.max(0, m - 1)).fill(0);
+  const y = [...u];
+  for (let iter = 0; iter < 5000; iter++) {
+    let maxChange = 0;
+    for (let i = 0; i < m - 1; i++) {
+      const z = lam[i]! + 0.5 * (y[i + 1]! - y[i]!);
+      const thresh = 0.5 * r[i]!;
+      const next = z > thresh ? z - thresh : z < -thresh ? z + thresh : 0;
+      const d = next - lam[i]!;
+      if (Math.abs(d) > 1e-12) {
+        lam[i] = next;
+        y[i] = y[i]! + d;
+        y[i + 1] = y[i + 1]! - d;
+        if (Math.abs(d) > maxChange) maxChange = Math.abs(d);
+      }
+    }
+    if (maxChange < 1e-11) break;
+  }
+  const y0 = y[0]!;
+  return y.map((v) => Math.exp(v - y0));
+}
+
 /**
  * The leg's own range (rig-c/pose#95). Per side, r(i) = the leg's picture
  * length hip → ankle on frame i ÷ its straight length (`STRAIGHT_PERCENTILE`
@@ -842,10 +918,18 @@ export type StanceLower = Record<Side, readonly number[]>;
  * fold as far as the picture's leg is folded on that frame, never less far
  * than the default. A leg with no straight length keeps the default.
  */
-export function stanceRangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>): StanceLower {
+export function stanceRangeOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, inPlace = false, figureScale?: readonly number[]): StanceLower {
   const out = {} as Record<Side, number[]>;
+  const n = ankle.r.length;
+  const scale = !inPlace && n > 25
+    ? (figureScale ?? figureScaleOf(ankle.r.map((ar, i) => Math.max(
+        Math.hypot(ar[0] - hip.r[i]![0], ar[1] - hip.r[i]![1]),
+        Math.hypot(ankle.l[i]![0] - hip.l[i]![0], ankle.l[i]![1] - hip.l[i]![1]),
+      ))))
+    : null;
   for (const s of SIDES) {
-    const len = ankle[s].map((a, i) => Math.hypot(a[0] - hip[s][i]![0], a[1] - hip[s][i]![1]));
+    const raw = ankle[s].map((a, i) => Math.hypot(a[0] - hip[s][i]![0], a[1] - hip[s][i]![1]));
+    const len = scale !== null ? raw.map((l, i) => (scale[i]! > 1e-6 ? l / scale[i]! : l)) : raw;
     const straight = percentile(len, STRAIGHT_PERCENTILE);
     out[s] = len.map((l) => (straight > 1e-9 && Number.isFinite(l) ? Math.min(STANCE_BOUNDS[0], l / straight) : STANCE_BOUNDS[0]));
   }

package/src/map.ts

@@ -101,10 +101,19 @@ export interface AlternateSet {
   /** `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 FaceAxis {
+  bone: string;
+  range: [number, number];
+}
+export interface FaceMap {
+  yaw?: FaceAxis;
+  pitch?: FaceAxis;
+}
 export interface JointMap {
   chains: Chain[];
   translate: Translate | null;
   alternates: AlternateSet[];
+  face?: FaceMap;
 }
 
 /** What a slot of the built rig shows at setup, and every attachment any skin gives it. */
@@ -135,7 +144,7 @@ export function readMap(text: string, where: string): JointMap {
     p.throwIfAny();
     throw new Error('unreachable');
   }
-  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate', 'alternates']);
+  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate', 'alternates', 'face']);
   if (doc.spec !== MAP_SPEC) p.add('MAP_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${MAP_SPEC}"`);
   const chains: Chain[] = [];
   if (!Array.isArray(doc.chains) || doc.chains.length === 0) {
@@ -235,8 +244,42 @@ export function readMap(text: string, where: string): JointMap {
     }
   }
   const alternates = 'alternates' in doc ? readAlternates(p, where, doc.alternates, chains, translate) : [];
+  const face = 'face' in doc ? readFaceMap(p, where, doc.face) : undefined;
   p.throwIfAny();
-  return { chains, translate, alternates };
+  return { chains, translate, alternates, ...(face === undefined ? {} : { face }) };
+}
+
+function readFaceMap(p: Problems, where: string, raw: unknown): FaceMap | undefined {
+  const fw = `${where} "face"`;
+  if (!isObject(raw)) {
+    p.add('MAP_FACE_SHAPE', `${fw} is ${typeName(raw)}; it is { yaw?: { bone, range: [min, max] }, pitch?: { bone, range: [min, max] } }`);
+    return undefined;
+  }
+  refuseUnknownKeys(p, 'MAP_KEYS', fw, raw, ['yaw', 'pitch']);
+  if (!('yaw' in raw) && !('pitch' in raw)) {
+    p.add('MAP_FACE_SHAPE', `${fw} names neither "yaw" nor "pitch"; it must name at least one axis`);
+    return undefined;
+  }
+  const out: FaceMap = {};
+  for (const axis of ['yaw', 'pitch'] as const) {
+    if (!(axis in raw)) continue;
+    const aw = `${fw} "${axis}"`;
+    const ax = raw[axis];
+    if (!isObject(ax)) {
+      p.add('MAP_FACE_SHAPE', `${aw} is ${typeName(ax)}; it is { bone, range: [min, max] }`);
+      continue;
+    }
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, ax, ['bone', 'range']);
+    const bone = typeof ax.bone === 'string' && ax.bone !== '' ? ax.bone : null;
+    if (bone === null) p.add('MAP_FACE_BONE', `${aw} "bone" is ${typeName(ax.bone)}; it must name a bone`);
+    const v = ax.range;
+    if (!Array.isArray(v) || v.length !== 2 || !v.every((x) => typeof x === 'number' && Number.isFinite(x)) || (v[0] as number) > 0 || (v[1] as number) < 0 || (v[0] as number) >= (v[1] as number)) {
+      p.add('MAP_FACE_RANGE', `${aw} "range" is ${JSON.stringify(v)}; it must be [min, max], two finite numbers of degrees with min ≤ 0 ≤ max and min < max`);
+    } else if (bone !== null) {
+      out[axis] = { bone, range: [v[0] as number, v[1] as number] };
+    }
+  }
+  return out;
 }
 
 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" }';
@@ -560,6 +603,22 @@ export function resolveMap(map: JointMap, rest: Rest, where: string, slots: RigS
       p.add('MAP_REACH', `chain "${c.name}" — bone "${b}" reaches from its posed origin, but it does not descend from the translated bone "${t.bone}"; its origin would not travel with the anchor`);
     }
   }
+  if (map.face !== undefined) {
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = map.face[axis];
+      if (ax === undefined) continue;
+      const label = `"face.${axis}"`;
+      if (!rest.has(ax.bone)) {
+        p.add('MAP_BONE_EXISTS', `${label} — bone "${ax.bone}" is not in the rig; its bones are ${listed}`);
+        continue;
+      }
+      const prev = owner.get(ax.bone);
+      if (prev !== undefined) p.add('MAP_BONE_ONCE', `bone "${ax.bone}" is in ${prev.startsWith('"') ? prev : `chain "${prev}"`} and in ${label}; a bone carries one rotate track`);
+      owner.set(ax.bone, label);
+      const o = rest.get(ax.bone)!;
+      if (Math.hypot(o.a, o.c) < 1e-9) p.add('MAP_AIM_LENGTH', `${label} — bone "${ax.bone}" has a collapsed x axis at setup (scale 0)`);
+    }
+  }
   resolveAlternates(p, map.alternates, slots);
   if (p.any) p.list.unshift({ code: 'MAP_RESOLVES', text: `${where} does not resolve against the rig` });
   p.throwIfAny();

package/src/retarget.ts

@@ -82,7 +82,9 @@ import { Problems, Refusal } from './problems.ts';
 import type { ArtRange, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
+import { figureScaleOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
+import type { FaceReading } from './face.ts';
+import { readFace } from './face.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -322,6 +324,28 @@ export interface Retarget {
   raised: Raised[];
   /** Each span of a `place: "by-hip"` set on each chain it places, its wrist placed against the hip (#93). */
   byHip: ByHip[];
+  /** With "face" in the map (#138): per-frame yaw/pitch reading and range-compressed mapping. */
+  face: FaceReading | null;
+  /** Continuous per-frame figure scale relative to frame 0 (`#163`, `#161`). */
+  figureScale: FigureScaleReading;
+}
+
+export interface FigureScaleFrame {
+  frame: number;
+  t: number;
+  /** Continuous rate-limited figure scale relative to frame 0 (`s[0] = 1`, step ≤ 1%/frame, held on frozen spans). */
+  s: number;
+  /** Raw standing-height ratio relative to frame 0 (`raw[i] / raw[0]`). */
+  rawS: number;
+}
+
+export interface FigureScaleReading {
+  /** Largest frame-to-frame relative change `|s[i] - s[i-1]| / s[i-1]` and the frame `i` where it occurs. */
+  maxStep: { step: number; frame: number; t: number };
+  /** Ending scale over frame 0 (`s[n-1] / s[0]`). */
+  endOverStart: number;
+  /** Per-frame continuous scale `s` and raw scale `rawS`. */
+  frames: FigureScaleFrame[];
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -433,6 +457,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     needed.add(map.translate.joint);
     map.translate.scale.pose.forEach((j) => needed.add(j));
   }
+  if (map.face !== undefined) {
+    needed.add('nose');
+    needed.add('r_eye');
+    needed.add('l_eye');
+  }
   const series = new Map<string, Pt[]>();
   const good = new Map<string, boolean[]>();
   const holds: Hold[] = [];
@@ -678,6 +707,60 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       else if (plantOn) p.add('LEGS_MAP', `--plant-feet reads both hips and both ankles from the pose; the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`);
     }
   }
+  const heldPt = (name: string): Pt[] | null => {
+    const known = series.get(name);
+    if (known !== undefined) return known;
+    const h = heldOf(name);
+    return 'never' in h ? null : h.at;
+  };
+  const rawFigureHeight: number[] = (() => {
+    const ar = heldPt('r_ankle');
+    const al = heldPt('l_ankle');
+    const top = heldPt('nose') ?? heldPt('neck');
+    if (ar !== null && al !== null && top !== null) {
+      const h = ar.map((r, i) => Math.max(r[1], al[i]![1]) - top[i]![1]);
+      if (h.every((v) => v > 1e-6)) return h;
+    }
+    const hr = heldPt('r_hip');
+    const hl = heldPt('l_hip');
+    if (ar !== null && al !== null && hr !== null && hl !== null) {
+      const h = ar.map((r, i) => Math.max(Math.hypot(r[0] - hr[i]![0], r[1] - hr[i]![1]), Math.hypot(al[i]![0] - hl[i]![0], al[i]![1] - hl[i]![1])));
+      if (h.every((v) => v > 1e-6)) return h;
+    }
+    if (t !== null) {
+      const [pa, pb] = t.scale.pose;
+      const A = series.get(pa)!;
+      const B = series.get(pb)!;
+      const h = A.map((a, i) => Math.hypot(B[i]![0] - a[0], B[i]![1] - a[1]));
+      if (h.every((v) => v > 1e-6)) return h;
+    }
+    return new Array<number>(n).fill(1);
+  })();
+  const continuousScale = figureScaleOf(rawFigureHeight);
+  const figureScale: FigureScaleReading = (() => {
+    const raw0 = rawFigureHeight[0] ?? 1;
+    let maxStep = 0;
+    let stepFrame = 0;
+    for (let i = 1; i < n; i++) {
+      const prev = continuousScale[i - 1]!;
+      const st = prev > 1e-9 ? Math.abs(continuousScale[i]! - prev) / prev : 0;
+      if (st > maxStep) {
+        maxStep = st;
+        stepFrame = i;
+      }
+    }
+    return {
+      maxStep: { step: r6(maxStep), frame: stepFrame, t: keyTimes[stepFrame] ?? 0 },
+      endOverStart: r6(continuousScale[n - 1] ?? 1),
+      frames: continuousScale.map((s, i) => ({
+        frame: i,
+        t: keyTimes[i]!,
+        s: r6(s),
+        rawS: r6(raw0 > 1e-9 ? rawFigureHeight[i]! / raw0 : 1),
+      })),
+    };
+  })();
+  const poseScale: number[] | null = t !== null && scale !== null && n > 25 && !inPlace ? continuousScale : null;
   if (legScaleOn) {
     const limits = opts.legScale as [number, number];
     const rawSegments: Array<{ chain: string; bone: string; joints: [string, string]; kind: string; lengths: number[]; ownStraight: number }> = [];
@@ -703,6 +786,31 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
     const straightByKind = new Map<string, number>();
     for (const seg of rawSegments) straightByKind.set(seg.kind, Math.max(straightByKind.get(seg.kind) ?? 0, seg.ownStraight));
+    if (!inPlace && n > 25) {
+      for (const seg of rawSegments) {
+        seg.lengths = seg.lengths.map((l, i) => (continuousScale[i]! > 1e-6 ? l / continuousScale[i]! : l));
+        seg.ownStraight = percentile(seg.lengths, STRAIGHT_PERCENTILE);
+      }
+      straightByKind.clear();
+      for (const seg of rawSegments) straightByKind.set(seg.kind, Math.max(straightByKind.get(seg.kind) ?? 0, seg.ownStraight));
+      const byChain = new Map<string, typeof rawSegments>();
+      for (const seg of rawSegments) {
+        const list = byChain.get(seg.chain) ?? [];
+        list.push(seg);
+        byChain.set(seg.chain, list);
+      }
+      const chainTotals = [...byChain.values()].filter((list) => list.length >= 2).map((list) => list[0]!.lengths.map((_, i) => list.reduce((s, seg) => s + seg.lengths[i]!, 0)));
+      if (chainTotals.length > 0 && straightByKind.size >= 2) {
+        let sumKindStraight = 0;
+        for (const ks of straightByKind.values()) sumKindStraight += ks;
+        let maxChainTotal = 0;
+        for (const tot of chainTotals) maxChainTotal = Math.max(maxChainTotal, percentile(tot, STRAIGHT_PERCENTILE));
+        if (sumKindStraight > maxChainTotal && maxChainTotal > 1e-6) {
+          const k = maxChainTotal / sumKindStraight;
+          for (const [kind, ks] of straightByKind) straightByKind.set(kind, ks * k);
+        }
+      }
+    }
     for (const seg of rawSegments) {
       const ls = legScaleOf(seg.lengths, limits, straightByKind.get(seg.kind)!);
       legScale.push({ chain: seg.chain, bone: seg.bone, joints: seg.joints, ...ls });
@@ -781,9 +889,16 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     // (stanceOf's mechanism, its bounds) so its ankle stays on the floor. Before --stance, whose
     // floor is that supporting ankle. #95: the lower bound on a frame is the leg's own range there.
     const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
-    const lower = stanceRangeOf(ankleSeries, { r: series.get('r_hip')!, l: series.get('l_hip')! });
+    const lower = stanceRangeOf(ankleSeries, { r: series.get('r_hip')!, l: series.get('l_hip')! }, inPlace, continuousScale);
     blendHold = holdBlend(planted.blends, n, posedFeet, lower);
+    const beforeBlendX = blendHold.stretch.map((b, i) => (b === null ? 0 : posedFeet(i).ankle[b.side][0]));
     stretchChain(blendHold.stretch);
+    blendHold.stretch.forEach((b, i) => {
+      if (b === null) return;
+      const dx = beforeBlendX[i]! - posedFeet(i).ankle[b.side][0];
+      hip[i]![0] += dx;
+      travel[i]![0] += dx;
+    });
     // --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') {
@@ -970,11 +1085,20 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         if (refEye > 1e-6 && rigEye > 1e-6) nodScale = rigEye / refEye;
       }
       if (neckSeries !== undefined && nodScale !== null) {
-        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
-        const dy = refEN.map((v) => (v - refEN[0]!) * nodScale);
+        const bone = rest.get(hb)!;
+        const parent = bone.parent === null ? null : rest.get(bone.parent)!;
+        let neckRestLen = 0;
+        for (let a = parent; a !== null; a = a.parent === null ? null : rest.get(a.parent)!) {
+          const d = Math.hypot(bone.worldX - a.worldX, bone.worldY - a.worldY);
+          if (d > 1e-6) {
+            neckRestLen = d;
+            break;
+          }
+        }
+        const maxNod = !inPlace && neckRestLen > 1e-6 ? 0.02 * neckRestLen : Infinity;
+        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]) / (poseScale?.[i] ?? 1));
+        const dy = refEN.map((v) => Math.max(-maxNod, Math.min(maxNod, (v - refEN[0]!) * nodScale!)));
         if (dy.some((v) => Math.abs(r3(v)) > 0)) {
-          const bone = rest.get(hb)!;
-          const parent = bone.parent === null ? null : rest.get(bone.parent)!;
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
           for (let i = 0; i < n; i++) {
@@ -1281,6 +1405,26 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
     }
   }
+  let face: FaceReading | null = null;
+  if (map.face !== undefined) {
+    const rEar = series.get('r_ear') ?? (() => {
+      const h = heldOf('r_ear');
+      return 'never' in h ? null : h.at;
+    })();
+    const lEar = series.get('l_ear') ?? (() => {
+      const h = heldOf('l_ear');
+      return 'never' in h ? null : h.at;
+    })();
+    face = readFace(map.face, series.get('nose')!, series.get('r_eye')!, series.get('l_eye')!, rEar, lEar);
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = face[axis];
+      if (ax === undefined) continue;
+      const rest0 = restAngle(rest, ax.bone, 'x');
+      const above = mappedAbove(ax.bone);
+      targets.set(ax.bone, ax.keys.map((v, i) => wrap(rest0 + (above === null ? 0 : turn(above, i)) + v)));
+      tracks.push({ bone: ax.bone, property: 'rotate', keys: ax.keys.map((v, i) => ({ t: keyTimes[i]!, v: [v] })) });
+    }
+  }
   // Scale keys: a scaled leg segment's own scale, or the scale that lands a bone under one at its asked length.
   for (const c of map.chains) {
     for (const b of c.bones) {
@@ -1296,7 +1440,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face, figureScale,
   };
 }
 

package/src/run.ts

@@ -19,6 +19,7 @@ import { landed, measureFeet, measureLanding, measurePosture, measureShear, pose
 import { legsOf, PLANT_SWITCH, STANCE_BOUNDS } from './legs.ts';
 import { M2_IDENTITY, mulM2, reduceKeys, reduceScale, reduceUnderScale, SCALE_REDUCE, setupLocal, type M2, type ReduceBone, type Reduced, type ReduceRow, type UnderBone } from './reduce.ts';
 import type { BlendHold, Closure, Floor, LegScale, Lowered, Side, Stance, SupportScaleRun } from './legs.ts';
+import { faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -40,6 +41,8 @@ export interface RetargetArgs extends RetargetOptions {
   render?: string;
   /** Write the run's measurements as JSON here. */
   report?: string;
+  /** Write the sequence's per-frame relative figure scale and pan as a sidecar JSON here (#161). */
+  camera?: string;
   /** The rig's animation read as its idle (default: idle); naming one the motion spec lacks is refused. */
   idle?: string;
   /** Loop the idle's dropped tracks into the new animation (#43 item 2). */
@@ -71,7 +74,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (path !== undefined && !existsSync(path)) args.add('ARG_PATH', `${flag} ${path} does not exist`);
   }
   // A file this run writes goes into a directory that is there already; --build and --render make theirs.
-  for (const [flag, path] of [['--out', a.out], ['--report', a.report]] as const) {
+  for (const [flag, path] of [['--out', a.out], ['--report', a.report], ['--camera', a.camera]] as const) {
     if (path === undefined) continue;
     const dir = dirname(path);
     if (!existsSync(dir)) args.add('ARG_PATH', `${flag} ${path} — directory ${dir} does not exist`);
@@ -157,6 +160,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       if (r.blendHold !== null) for (const l of blendLines(r.blendHold, r.times)) say(`  FEET   ${l}`);
     }
     if (r.stance !== null) for (const l of stanceLines(r.stance, r.times)) say(`  STANCE ${l}`);
+    if (r.face !== null) say(`  FACE   ${faceLine(r.face)}`);
 
     // --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);
@@ -183,7 +187,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         if ((t.kind === 'bone' || t.kind === 'group') && Array.isArray(sample)) return boneIdentity(property, sample.length);
         return undefined;
       };
-      const mapped = [...map.chains.flatMap((c) => c.bones), ...(map.translate === null ? [] : [map.translate.bone])];
+      const mapped = [
+        ...map.chains.flatMap((c) => c.bones),
+        ...(map.translate === null ? [] : [map.translate.bone]),
+        ...(map.face?.yaw === undefined ? [] : [map.face.yaw.bone]),
+        ...(map.face?.pitch === undefined ? [] : [map.face.pitch.bone]),
+      ];
       const below = new Map<string, string[]>();
       for (const m of new Set(mapped)) {
         for (let b = rest.get(m)?.parent ?? null; b !== null; b = rest.get(b)?.parent ?? null) {
@@ -285,6 +294,35 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
     }
     writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
+    if (a.camera !== undefined) {
+      const ss = r.figureScale.frames.map((x) => x.s);
+      const minS = ss.length === 0 ? 1 : Math.min(...ss);
+      const maxS = ss.length === 0 ? 1 : Math.max(...ss);
+      writeFileSync(a.camera, `${JSON.stringify({
+        spec: 'rig-pose-camera/1',
+        rig: input.name,
+        animation: a.name,
+        frames: r.figureScale.frames.map((f, i) => {
+          const cam = seq.camera?.[i];
+          const camS = cam?.s ?? 1;
+          return {
+            frame: f.frame,
+            t: f.t,
+            s: f.s,
+            rawS: f.rawS,
+            tx: cam?.tx ?? 0,
+            ty: cam?.ty ?? 0,
+            videoS: Number((f.s * camS).toFixed(6)),
+          };
+        }),
+        summary: {
+          minS,
+          maxS,
+          maxStep: r.figureScale.maxStep,
+          endOverStart: r.figureScale.endOverStart,
+        },
+      }, null, 2)}\n`);
+    }
     if (a.render !== undefined && f.meshes !== null && f.frames !== '') {
       rmSync(a.render, { recursive: true, force: true });
       cpSync(f.frames, a.render, { recursive: true });
@@ -317,6 +355,16 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         raised: r.raised,
         // Only when a set declares `place` (#93): a map without one writes the report it always has.
         ...(map.alternates.some((x) => x.place !== undefined && x.place !== null) ? { byHip: r.byHip } : {}),
+        ...(r.face === null
+          ? {}
+          : {
+              face: {
+                ears: r.face.ears,
+                read: { yaw: r.face.read.yaw, pitch: r.face.read.pitch },
+                ...(r.face.yaw === undefined ? {} : { yaw: { bone: r.face.yaw.bone, limits: r.face.yaw.limits, knee: r.face.yaw.knee, read: r.face.yaw.read, mapped: r.face.yaw.mapped, scale: r.face.yaw.scale, corr: r.face.yaw.corr } }),
+                ...(r.face.pitch === undefined ? {} : { pitch: { bone: r.face.pitch.bone, limits: r.face.pitch.limits, knee: r.face.pitch.knee, read: r.face.pitch.read, mapped: r.face.pitch.mapped, scale: r.face.pitch.scale, corr: r.face.pitch.corr } }),
+              },
+            }),
         legScale: r.legScale.map(({ scale: _scale, asked: _asked, ...rest }) => rest),
         pivot: r.pivot,
         stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, ...(r.stance.range === undefined ? {} : { range: r.stance.range }), runs: r.stance.runs, over: r.stance.over },
@@ -328,6 +376,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows },
       }, null, 2)}\n`);
     }
+    if (a.camera !== undefined) say(`  wrote ${a.camera} — camera track (${r.figureScale.frames.length} frames)`);
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);
     return { lines, written: true };
   } finally {

package/src/switch.ts

@@ -498,10 +498,9 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       for (let i = sw.frames[0]; i <= sw.frames[1]; i++) row[i] = o;
     }
   }
-  // #136: when a group's base setup slots sit in front of the torso, an unswitched gap between two
-  // behind-the-torso switches keeps each chain on its behind-the-torso slots on the frames where that
-  // chain stays within tolerance of the surrounding behind sets (with the same minimum-span bridging),
-  // and across a joint behind-to-behind transition where all chains move from one behind set to another.
+  // #136/#139/#162: between two sets that both draw an arm behind the torso, a frame that belongs to
+  // neither set stays behind (the nearer set's layer). The default front slot is for a frame no set can
+  // claim and whose arm is read in front — not a fallback.
   const chainHolds: Array<{ set: string; chain: string; frames: [number, number] }> = [];
   for (const group of groups) {
     const layer = groupLayering(group, map, slots);
@@ -578,6 +577,56 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
           return false;
         });
         if (!frontNear) for (const cn of chains) for (let i = g0; i <= g1; i++) cPick.get(cn)![i] = set0;
+      } else {
+        for (const cn of chains) {
+          const arr = cPick.get(cn)!;
+          const frontSets = group.filter((a) => layer.isFront(a) && a.chains.includes(cn));
+          const d0s = byChain.get(set0.name)?.get(cn);
+          const d1s = byChain.get(set1.name)?.get(cn);
+          for (let i = g0; i <= g1; i++) {
+            if (arr[i] !== null) continue;
+            const claimedFront = frontSets.some((f) => (byChain.get(f.name)?.get(cn)?.[i] ?? Infinity) <= opts.switchTolerance);
+            if (!claimedFront) {
+              const d0 = d0s?.[i] ?? Infinity;
+              const d1 = d1s?.[i] ?? Infinity;
+              arr[i] = d0 <= d1 ? set0 : set1;
+            }
+          }
+          for (let i = g0; i <= g1;) {
+            const a = arr[i];
+            let j = i;
+            while (j + 1 <= g1 && arr[j + 1] === a) j++;
+            const before = arr[i - 1] ?? null;
+            const after = arr[j + 1] ?? null;
+            const span = times[j + 1]! - times[i]!;
+            if (span < opts.switchMin - 1e-9) {
+              if (a === null && before !== null && after !== null) {
+                for (let k = i; k <= j; k++) {
+                  const d0 = d0s?.[k] ?? Infinity;
+                  const d1 = d1s?.[k] ?? Infinity;
+                  arr[k] = d0 <= d1 ? set0 : set1;
+                }
+              } else if (before !== null && before === after && a !== before) {
+                for (let k = i; k <= j; k++) arr[k] = before;
+              }
+            }
+            i = j + 1;
+          }
+          for (let i = g0; i <= g1;) {
+            const a = arr[i];
+            let j = i;
+            while (j + 1 <= g1 && arr[j + 1] === a) j++;
+            const before = arr[i - 1] ?? null;
+            const after = arr[j + 1] ?? null;
+            if (before !== null && before === after && a !== before && times[j + 1]! - times[i]! < opts.switchMin - 1e-9) {
+              for (let k = i; k <= j; k++) arr[k] = before;
+            } else if (a !== null && i > g0 && j < g1 && times[j + 1]! - times[i]! < opts.switchMin - 1e-9) {
+              const fill = before ?? after ?? null;
+              for (let k = i; k <= j; k++) arr[k] = fill;
+            }
+            i = j + 1;
+          }
+        }
       }
       for (const s of layer.touched) {
         if (!shown.has(s)) shown.set(s, Array.from({ length: n }, () => slots.get(s)!.setup));

package/src/verify.ts

@@ -61,13 +61,19 @@ export function poseFrames(doc: CompiledDocument, animation: string, times: read
 export function measureLanding(doc: CompiledDocument, animation: string, map: JointMap, r: Retarget, posed = poseFrames(doc, animation, r.times)): Landing[] {
   const out: Landing[] = [];
   const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
+  const faceBones = new Set([r.face?.yaw?.bone, r.face?.pitch?.bone].filter((b): b is string => b !== undefined));
+  const isFaceSlider = (c: CompiledDocument['constraints'][number]): boolean => c.record?.kind === 'slider' && c.record.bone !== null && faceBones.has(c.record.bone);
+  const hasFaceSliders = faceBones.size > 0 && doc.constraints.some(isFaceSlider);
+  const chainPosed = hasFaceSliders
+    ? poseFrames({ ...doc, constraints: doc.constraints.filter((c) => !isFaceSlider(c)) }, animation, r.times)
+    : posed;
   for (const c of map.chains) {
     c.bones.forEach((b, k) => {
       const aim = c.aim[k]!;
       const asked = r.targets.get(b)!;
       let worst = -1;
       let frame = 0;
-      posed.forEach((bones, i) => {
+      chainPosed.forEach((bones, i) => {
         const reached = aimAngle(bones, lengths, b, aim);
         const e = Math.abs(wrap(reached - asked[i]!));
         if (e > worst) {
@@ -78,6 +84,24 @@ export function measureLanding(doc: CompiledDocument, animation: string, map: Jo
       out.push({ bone: b, worst, frame, kind: 'angle', tolerance: ANGLE_TOLERANCE });
     });
   }
+  if (r.face !== null) {
+    for (const axis of ['yaw', 'pitch'] as const) {
+      const ax = r.face[axis];
+      if (ax === undefined) continue;
+      const asked = r.targets.get(ax.bone)!;
+      let worst = -1;
+      let frame = 0;
+      posed.forEach((bones, i) => {
+        const reached = aimAngle(bones, lengths, ax.bone, 'x');
+        const e = Math.abs(wrap(reached - asked[i]!));
+        if (e > worst) {
+          worst = e;
+          frame = i;
+        }
+      });
+      out.push({ bone: ax.bone, worst, frame, kind: 'angle', tolerance: ANGLE_TOLERANCE });
+    }
+  }
   const setup = new Map(poseRawSetup(doc).bones.map((b) => [b.name, b]));
   for (const [b, asked] of r.scales) {
     const s0 = setup.get(b)!;