@rig-c/pose 0.20.5 → 0.21.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 the rolling 25-frame median trunk length over the sequence median so residual camera zoom does not shrink earlier phrases against a zoomed-in ending, and the shared thigh + shin straight lengths are capped at the larger 95th-percentile whole-leg `hip → ankle` length so a drifting knee split does not inflate their sum, [#159](https://github.com/rig-c/pose/issues/159)), 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)): `{ "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), compresses each axis into its declared range so peaks are scaled rather than clipped flat, and keys the named dial bone's `rotate` track (`FACE`).
 
 ### A joint's range: `range`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.20.5",
+  "version": "0.21.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,221 @@
+/**
+ * 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;
+
+export interface FaceSpan {
+  min: number;
+  max: number;
+  range: number;
+}
+
+export interface FaceAxisReading {
+  bone: string;
+  limits: [number, number];
+  read: FaceSpan;
+  mapped: FaceSpan;
+  /** Compression factors [kNeg, kPos] in (0, 1] applied to negative and positive read angles. */
+  scale: [number, number];
+  /** Pearson 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 corrOf(a: readonly number[], b: readonly number[]): number {
+  if (a.length < 2 || a.length !== b.length) return 1;
+  const ma = a.reduce((x, y) => x + y, 0) / a.length;
+  const mb = b.reduce((x, y) => x + y, 0) / b.length;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < a.length; i++) {
+    const xa = a[i]! - ma;
+    const xb = b[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 };
+}
+
+/**
+ * Compress a read angle series into `axis.range` (`[min, max]` with `min <= 0 <= max`):
+ * negative readings scale by `kNeg = min(1, limits[0] / rawMin)` and positive
+ * readings by `kPos = min(1, limits[1] / rawMax)`, so peaks above the range are
+ * compressed to the limit rather than clipped flat, while motion already inside
+ * the range keeps unit gain (`1`).
+ */
+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 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 ? x * kNeg : x * kPos));
+  return {
+    bone: axis.bone,
+    limits: [limits[0], 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]}]°: ${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

@@ -842,12 +842,16 @@ 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): StanceLower {
   const out = {} as Record<Side, number[]>;
   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 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]));
+    const n = len.length;
+    const globalStraight = percentile(len, STRAIGHT_PERCENTILE);
+    out[s] = len.map((l, i) => {
+      const straight = inPlace || n <= 25 ? globalStraight : percentile(len.slice(Math.max(0, i - 24), Math.min(n, i + 25)), STRAIGHT_PERCENTILE);
+      return straight > 1e-9 && Number.isFinite(l) ? Math.min(STANCE_BOUNDS[0], l / straight) : STANCE_BOUNDS[0];
+    });
   }
   return out;
 }

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

@@ -83,6 +83,8 @@ import type { ArtRange, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOpti
 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 type { FaceReading } from './face.ts';
+import { readFace } from './face.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -322,6 +324,8 @@ 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;
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -433,6 +437,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 +687,20 @@ 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 poseScale: number[] | null =
+    t !== null && scale !== null && !inPlace
+      ? (() => {
+          const [pa, pb] = t.scale.pose;
+          const A = series.get(pa)!;
+          const B = series.get(pb)!;
+          const raw = A.map((a, i) => Math.hypot(B[i]![0] - a[0], B[i]![1] - a[1]));
+          return raw.map((_, i) => {
+            const win = raw.slice(Math.max(0, i - 12), Math.min(n, i + 13)).filter((v) => v > 1e-6);
+            const m = win.length > 0 ? median(win) : scale!.pose;
+            return m > 1e-6 ? m / scale!.pose : 1;
+          });
+        })()
+      : 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 +726,40 @@ 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) {
+      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)));
+      const rawBySeg = new Map(rawSegments.map((seg) => [seg, [...seg.lengths]]));
+      for (const seg of rawSegments) {
+        const globalStraight = straightByKind.get(seg.kind)!;
+        const peers = rawSegments.filter((s) => s.kind === seg.kind);
+        seg.lengths = rawBySeg.get(seg)!.map((l, i) => {
+          const lo = Math.max(0, i - 24);
+          const hi = Math.min(n, i + 25);
+          let localStraight = 0;
+          for (const peer of peers) localStraight = Math.max(localStraight, percentile(rawBySeg.get(peer)!.slice(lo, hi), STRAIGHT_PERCENTILE));
+          if (chainTotals.length > 0 && straightByKind.size >= 2) {
+            let sumKindStraight = 0;
+            for (const kind of straightByKind.keys()) {
+              let ks = 0;
+              for (const s of rawSegments) if (s.kind === kind) ks = Math.max(ks, percentile(rawBySeg.get(s)!.slice(lo, hi), STRAIGHT_PERCENTILE));
+              sumKindStraight += ks;
+            }
+            let maxChainTotal = 0;
+            for (const tot of chainTotals) maxChainTotal = Math.max(maxChainTotal, percentile(tot.slice(lo, hi), STRAIGHT_PERCENTILE));
+            if (sumKindStraight > maxChainTotal && maxChainTotal > 1e-6) {
+              localStraight *= maxChainTotal / sumKindStraight;
+            }
+          }
+          return localStraight > 1e-6 ? l * (globalStraight / localStraight) : l;
+        });
+      }
+    }
     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 +838,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);
     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 +1034,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 +1354,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 +1389,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,
   };
 }
 

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;
@@ -157,6 +158,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 +185,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) {
@@ -317,6 +324,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, 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, 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 },

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)!;