@rig-c/pose 0.22.2 → 0.23.0

package/README.md

@@ -143,10 +143,11 @@ 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`.
+- `FACE` — with `face` in the map ([#138](https://github.com/rig-c/pose/issues/138), [#173](https://github.com/rig-c/pose/issues/173)): 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, when `face.yaw.sets` (or `face.sets`) is declared, every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `face` in `--report`.
+- `BODY` — per-frame body yaw read from the camera-normalised shoulder width (`r_shoulder + l_shoulder`) and hip width (`r_hip + l_hip`) projected perpendicular to the trunk against the sequence's standing width (`yaw ≈ acos(w / w_standing)`, [#173](https://github.com/rig-c/pose/issues/173)): its overall and opening (`frames 0–47`) range, every span with `|yaw| ≥ 45°`, and, when `body.yaw` or `body.sets` is declared in the map, its knee-mapped dial keys and every yaw-switched set's entered spans, swap count, and any `hides` slot keyed by another track, written as `body` 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:
+`--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`, `body` (`standing`, `read`, `over45`, `framesOver45`, and with `body.yaw` or `body.sets` in the map, `yaw` and `sets`), `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:
 
 | field | each entry |
 | --- | --- |
@@ -314,7 +315,8 @@ 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`).
+- `face` (optional, [#138](https://github.com/rig-c/pose/issues/138), [#164](https://github.com/rig-c/pose/issues/164), [#173](https://github.com/rig-c/pose/issues/173)): `{ "yaw"?: { "bone": "yaw", "range": [-15, 15], "sets"?: [{ "set": "T1", "above": 45 }] }, "pitch"?: { "bone": "pitch", "range": [-10, 15] }, "sets"?: [{ "set": "T1", "above": 45 }] }` (`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`). When `sets` (`[{ "set": "<name>", "above": <deg> }]`, `0 < above ≤ 90`) is declared on `face.yaw.sets` or `face.sets`, each set enters on frames where `|yaw| ≥ above` (or the highest `above` satisfied when multiple sets are declared) and leaves only when `|yaw| < above − 10°` (`10°` hysteresis), emitting stepped slot `attachment` keys for the set's `slots` and `hides` (resolved from `alternates` in the map or `sets.json` (`rig-parts-sets/1`) beside `rig.json`; an unknown set is refused by name as `MAP_SET_EXISTS`).
+- `body` (optional, [#173](https://github.com/rig-c/pose/issues/173)): `{ "yaw"?: { "bone": "body_yaw", "range": [-30, 30], "sets"?: [{ "set": "T8", "above": 45 }] }, "sets"?: [{ "set": "T8", "above": 45 }] }` (`min ≤ 0 ≤ max`, `min < max`). Maps the per-frame body yaw read from the camera-normalised shoulder and hip width (`BODY`) into `range` with the same `0.8 × range` knee mapping as `face`, keying the named dial bone's `rotate` track, and switches any declared `sets` (`body.sets` or `body.yaw.sets`) with the same `above` / `above − 10°` hysteresis (overriding `face` sets and arm `alternates` on slots they share while active). Without `body` in the map, `BODY` and `--report`'s `body` still report the reading while leaving every track in `motion.json` unchanged.
 
 ### A joint's range: `range`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.22.2",
+  "version": "0.23.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

@@ -5,7 +5,7 @@
  * 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';
+import type { BodyMap, FaceAxis, FaceMap, YawSet } from './map.ts';
 
 type Pt = [number, number];
 
@@ -18,6 +18,21 @@ const DEG = 180 / Math.PI;
  */
 export const FACE_KNEE = 0.8;
 
+/** Hysteresis in degrees for leaving a yaw-selected set (`leave = above - 10°`, `rig-c/pose#173`). */
+export const SET_HYSTERESIS_DEG = 10;
+
+export interface YawSetSwitch {
+  set: string;
+  above: number;
+  leave: number;
+  /** Inclusive `[first, last]` frame spans where the set is shown. */
+  spans: Array<[number, number]>;
+  /** Total number of attachment transitions (enter + leave boundaries inside the clip). */
+  swaps: number;
+  /** Any `hides` slot of this set that is also keyed by another track, with the track that keys it. */
+  hidesKeyed: Array<{ slot: string; by: string }>;
+}
+
 export interface FaceSpan {
   min: number;
   max: number;
@@ -51,6 +66,7 @@ export interface FaceReading {
   };
   yaw?: FaceAxisReading;
   pitch?: FaceAxisReading;
+  sets?: YawSetSwitch[];
 }
 
 const r3 = (v: number): number => {
@@ -246,6 +262,26 @@ export function readFace(
 const f1 = (x: number): string => x.toFixed(1);
 const sg = (x: number): string => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
 
+function formatYawSets(sets: readonly YawSetSwitch[] | undefined, raw: readonly number[]): string {
+  if (sets === undefined || sets.length === 0) return '';
+  const parts = sets.map((s) => {
+    const spanStr = s.spans.length === 0
+      ? 'none (0 swaps)'
+      : `${s.spans.map(([lo, hi]) => {
+          const slice = raw.slice(lo, hi + 1);
+          const sMin = Math.min(...slice);
+          const sMax = Math.max(...slice);
+          const where = lo === hi ? `frame ${lo}` : `frames ${lo}–${hi}`;
+          return `${where} (${lo === hi ? `${sg(sMax)}°` : `${sg(sMin)}° … ${sg(sMax)}°`})`;
+        }).join(', ')} (${s.swaps} swap${s.swaps === 1 ? '' : 's'})`;
+    const hidesStr = s.hidesKeyed.length === 0
+      ? ''
+      : `; hides keyed by another track: ${s.hidesKeyed.map((h) => `slot "${h.slot}" (${h.by})`).join(', ')}`;
+    return `set "${s.set}" (≥ ${s.above}°, leave < ${s.leave}°): ${spanStr}${hidesStr}`;
+  });
+  return `; sets ${parts.join('; ')}`;
+}
+
 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)}°)`;
@@ -255,5 +291,262 @@ export function faceLine(f: FaceReading): string {
     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(', ')}`;
+  const mappedPart = axes.length === 0 ? '' : `; mapped ${axes.join(', ')}`;
+  return `${joints}: ${readPart}${mappedPart}${formatYawSets(f.sets, f.read.rawYaw)}`;
 }
+
+/**
+ * Select yaw-switched sets (`rig-c/pose#173` Part 2):
+ * - A set is entered when `raw[i] >= above` for at least `switchMin` seconds,
+ *   and left when `raw[i] < above - SET_HYSTERESIS_DEG` (`above - 10°`) for at
+ *   least `switchMin` seconds.
+ * - Between two frames of the same set separated by `< switchMin`, nothing flips (`#162`).
+ */
+export function selectYawSets(
+  raw: readonly number[],
+  declared: readonly YawSet[] | undefined,
+  times: readonly number[],
+  switchMin: number,
+): YawSetSwitch[] {
+  if (declared === undefined || declared.length === 0 || raw.length === 0) return [];
+  const n = raw.length;
+  const endOf = (i: number): number => (i + 1 < n ? times[i + 1]! : n > 1 ? 2 * times[i]! - times[i - 1]! : times[i]!);
+  const spanSec = (lo: number, hi: number): number => endOf(hi) - times[lo]!;
+
+  return declared.map((decl) => {
+    const above = decl.above;
+    const leave = r3(above - SET_HYSTERESIS_DEG);
+    const active = new Array<boolean>(n).fill(false);
+    let inSet = false;
+    let i = 0;
+    while (i < n) {
+      if (!inSet) {
+        if (raw[i]! >= above) {
+          let j = i;
+          while (j + 1 < n && raw[j + 1]! >= above) j++;
+          if (spanSec(i, j) >= switchMin - 1e-9) {
+            inSet = true;
+            for (let k = i; k <= j; k++) active[k] = true;
+          }
+          i = j + 1;
+        } else {
+          i++;
+        }
+      } else {
+        if (raw[i]! < leave) {
+          let j = i;
+          while (j + 1 < n && raw[j + 1]! < leave) j++;
+          if (spanSec(i, j) >= switchMin - 1e-9) {
+            inSet = false;
+          } else {
+            for (let k = i; k <= j; k++) active[k] = true;
+          }
+          i = j + 1;
+        } else {
+          active[i] = true;
+          i++;
+        }
+      }
+    }
+    // #162: bridge any remaining gap between two spans of the same set shorter than switchMin.
+    for (let k = 0; k < n;) {
+      if (active[k]) {
+        k++;
+        continue;
+      }
+      let j = k;
+      while (j + 1 < n && !active[j + 1]) j++;
+      if (k > 0 && j + 1 < n && active[k - 1] && active[j + 1] && spanSec(k, j) < switchMin - 1e-9) {
+        for (let m = k; m <= j; m++) active[m] = true;
+      }
+      k = j + 1;
+    }
+    const spans: Array<[number, number]> = [];
+    for (let k = 0; k < n; k++) {
+      if (!active[k]) continue;
+      const last = spans[spans.length - 1];
+      if (last !== undefined && last[1] === k - 1) last[1] = k;
+      else spans.push([k, k]);
+    }
+    let swaps = 0;
+    for (const [lo, hi] of spans) {
+      swaps++;
+      if (hi < n - 1) swaps++;
+    }
+    return { set: decl.set, above, leave, spans, swaps, hidesKeyed: [] };
+  });
+}
+
+/** Threshold in degrees at or above which a frame is listed on `BODY` as needing a turned-body drawing (`rig-c/pose#173`). */
+export const BODY_TURN_DEG = 45;
+
+export interface BodyReading {
+  /** Camera-normalised standing widths in picture pixels (at frame 0's scale). */
+  standing: {
+    shoulder: number;
+    hip: number;
+  };
+  read: {
+    yaw: FaceSpan;
+    opening: FaceSpan;
+    rawYaw: number[];
+  };
+  /** Inclusive `[first, last]` frame spans where `|yaw| >= BODY_TURN_DEG` (`45°`). */
+  over45: Array<[number, number]>;
+  /** Frame indices where `|yaw| >= BODY_TURN_DEG` (`45°`). */
+  framesOver45: number[];
+  /** Present when the map declares `body.yaw`. */
+  yaw?: FaceAxisReading;
+  /** Present when the map declares `body.sets` or `body.yaw.sets`. */
+  sets?: YawSetSwitch[];
+}
+
+/**
+ * Read per-frame body yaw (degrees) from camera-normalised shoulder width
+ * (`r_shoulder`, `l_shoulder`) and hip width (`r_hip`, `l_hip`), projected
+ * perpendicular to the trunk (`mid_hip → neck`) so raising one shoulder or
+ * tilting the torso in 2D roll does not distort the horizontal torso width,
+ * against the sequence's standing width (`yaw ≈ acos(w / w_standing)`,
+ * `rig-c/pose#173`).
+ *
+ * Sign convention (matching `readFaceAngles`):
+ * - `yaw > 0`: torso turned toward the subject's right (viewer-left, left shoulder nearer).
+ * - `yaw < 0`: torso turned toward the subject's left (viewer-right, right shoulder nearer).
+ */
+export function readBodyYaw(
+  rShoulder: readonly Pt[],
+  lShoulder: readonly Pt[],
+  rHip: readonly Pt[] | null,
+  lHip: readonly Pt[] | null,
+  neck: readonly Pt[] | null,
+  scale: readonly number[] | null,
+  faceYaw: readonly number[] | null,
+): { standing: { shoulder: number; hip: number }; yaw: number[] } {
+  const n = rShoulder.length;
+  const hasHips = rHip !== null && lHip !== null && rHip.length === n && lHip.length === n;
+  const wSh: number[] = [];
+  const wHip: number[] = [];
+  const signs: number[] = [];
+  const revSh: boolean[] = [];
+
+  for (let i = 0; i < n; i++) {
+    const rS = rShoulder[i]!;
+    const lS = lShoulder[i]!;
+    const s = scale !== null && scale[i] !== undefined && scale[i]! > 1e-6 ? scale[i]! : 1;
+    const mS: Pt = [0.5 * (rS[0] + lS[0]), 0.5 * (rS[1] + lS[1])];
+    const mH: Pt = hasHips ? [0.5 * (rHip[i]![0] + lHip[i]![0]), 0.5 * (rHip[i]![1] + lHip[i]![1])] : [mS[0], mS[1] + 100];
+    const top: Pt = neck !== null && neck[i] !== undefined ? neck[i]! : mS;
+    const tx = top[0] - mH[0];
+    const ty = top[1] - mH[1];
+    const tl = Math.hypot(tx, ty);
+    const nx = tl > 1e-6 ? -ty / tl : 1;
+    const ny = tl > 1e-6 ? tx / tl : 0;
+
+    const projSh = ((lS[0] - rS[0]) * nx + (lS[1] - rS[1]) * ny) / s;
+    const absSh = Math.abs(projSh);
+    wSh.push(absSh);
+    revSh.push(projSh < -1e-6);
+
+    if (hasHips) {
+      const rH = rHip[i]!;
+      const lH = lHip[i]!;
+      const projHip = ((lH[0] - rH[0]) * nx + (lH[1] - rH[1]) * ny) / s;
+      wHip.push(Math.abs(projHip));
+    } else {
+      wHip.push(absSh);
+    }
+
+    const neckOff = neck !== null && neck[i] !== undefined ? ((mS[0] - neck[i]![0]) * nx + (mS[1] - neck[i]![1]) * ny) / s : 0;
+    const fy = faceYaw !== null && faceYaw[i] !== undefined ? faceYaw[i]! : 0;
+    let sign = 1;
+    if (Math.abs(neckOff) > 0.05 * Math.max(1, absSh)) sign = neckOff >= 0 ? 1 : -1;
+    else if (Math.abs(fy) > 0.5) sign = fy >= 0 ? 1 : -1;
+    else {
+      const shear = (mS[0] - mH[0]) * nx + (mS[1] - mH[1]) * ny;
+      if (Math.abs(shear) > 1e-6) sign = shear >= 0 ? 1 : -1;
+      else if (i > 0) sign = signs[i - 1]!;
+    }
+    signs.push(sign);
+  }
+
+  const openN = Math.min(n, 48);
+  const sh0 = Math.max(1e-6, Math.min(median(wSh.slice(0, openN)), median(wSh)));
+  const hip0 = Math.max(1e-6, Math.min(median(wHip.slice(0, openN)), median(wHip)));
+
+  const yaw: number[] = [];
+  for (let i = 0; i < n; i++) {
+    if (revSh[i]) {
+      yaw.push(signs[i]! * 90);
+      continue;
+    }
+    const rS = Math.min(1, wSh[i]! / sh0);
+    const rH = hasHips ? Math.min(1, wHip[i]! / hip0) : rS;
+    const mx = Math.min(Math.max(rS, rH), rS / 0.65);
+    const mn = Math.min(rS, rH);
+    const alpha = Math.max(0, Math.min(1, (mx - 0.85) / 0.1));
+    const w = Math.max(0, Math.min(1, alpha * Math.max(rS, rH) + (1 - alpha) * mn));
+    const mag = Math.acos(w) * DEG;
+    yaw.push(mag < 1e-6 ? 0 : signs[i]! * mag);
+  }
+
+  return {
+    standing: { shoulder: r3(sh0), hip: r3(hasHips ? hip0 : 0) },
+    yaw,
+  };
+}
+
+export function readBody(
+  body: BodyMap | undefined,
+  rShoulder: readonly Pt[],
+  lShoulder: readonly Pt[],
+  rHip: readonly Pt[] | null,
+  lHip: readonly Pt[] | null,
+  neck: readonly Pt[] | null,
+  scale: readonly number[] | null,
+  faceYaw: readonly number[] | null,
+): BodyReading {
+  const { standing, yaw } = readBodyYaw(rShoulder, lShoulder, rHip, lHip, neck, scale, faceYaw);
+  const openN = Math.min(yaw.length, 48);
+  const framesOver45: number[] = [];
+  const over45: Array<[number, number]> = [];
+  for (let i = 0; i < yaw.length; i++) {
+    if (Math.abs(yaw[i]!) >= BODY_TURN_DEG) {
+      framesOver45.push(i);
+      const last = over45[over45.length - 1];
+      if (last !== undefined && last[1] === i - 1) last[1] = i;
+      else over45.push([i, i]);
+    }
+  }
+  return {
+    standing,
+    read: {
+      yaw: spanOf(yaw),
+      opening: spanOf(yaw.slice(0, openN)),
+      rawYaw: yaw.map(r3),
+    },
+    over45,
+    framesOver45,
+    ...(body?.yaw === undefined ? {} : { yaw: mapFaceAxis(yaw, body.yaw) }),
+  };
+}
+
+export function bodyLine(b: BodyReading): string {
+  const openEnd = Math.min(b.read.rawYaw.length, 48) - 1;
+  const openAbs = Math.max(Math.abs(b.read.opening.min), Math.abs(b.read.opening.max));
+  const spans = b.over45.map(([lo, hi]) => {
+    const slice = b.read.rawYaw.slice(lo, hi + 1);
+    const sMin = Math.min(...slice);
+    const sMax = Math.max(...slice);
+    const where = lo === hi ? `frame ${lo}` : `frames ${lo}–${hi}`;
+    return `${where} (${lo === hi ? `${sg(sMax)}°` : `${sg(sMin)}° … ${sg(sMax)}°`})`;
+  });
+  const overPart = b.framesOver45.length === 0
+    ? `≥ ${BODY_TURN_DEG}°: none`
+    : `≥ ${BODY_TURN_DEG}° on ${b.framesOver45.length} frame(s): ${spans.join(', ')}`;
+  const head = `r_shoulder + l_shoulder, r_hip + l_hip (standing shoulder ${b.standing.shoulder.toFixed(1)}px, hip ${b.standing.hip.toFixed(1)}px): read yaw ${sg(b.read.yaw.min)}° … ${sg(b.read.yaw.max)}° (${f1(b.read.yaw.range)}°), opening (frames 0–${openEnd}) ${sg(b.read.opening.min)}° … ${sg(b.read.opening.max)}° (max |yaw| ${f1(openAbs)}°); ${overPart}`;
+  const mappedPart = b.yaw === undefined
+    ? ''
+    : `; mapped yaw → bone "${b.yaw.bone}" [${b.yaw.limits[0]}, ${b.yaw.limits[1]}]° (knee [${b.yaw.knee[0]}, ${b.yaw.knee[1]}]°): ${sg(b.yaw.mapped.min)}° … ${sg(b.yaw.mapped.max)}° (scale ${b.yaw.scale[0].toFixed(3)}/${b.yaw.scale[1].toFixed(3)}, r=${b.yaw.corr.toFixed(3)})`;
+  return `${head}${mappedPart}${formatYawSets(b.sets, b.read.rawYaw)}`;
+}
+

package/src/map.ts

@@ -101,20 +101,38 @@ 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 YawSet {
+  set: string;
+  above: number;
+}
 export interface FaceAxis {
   bone: string;
   range: [number, number];
+  sets?: YawSet[];
 }
 export interface FaceMap {
   yaw?: FaceAxis;
   pitch?: FaceAxis;
+  sets?: YawSet[];
+}
+export interface BodyMap {
+  yaw?: FaceAxis;
+  sets?: YawSet[];
 }
 export interface JointMap {
   chains: Chain[];
   translate: Translate | null;
   alternates: AlternateSet[];
   face?: FaceMap;
+  body?: BodyMap;
+}
+
+/** An alternate attachment set from `sets.json` (`rig-parts-sets/1`, `rig-c/pose#173`). */
+export interface RigSet {
+  slots: Record<string, string>;
+  hides: string[];
 }
+export type RigSets = ReadonlyMap<string, RigSet>;
 
 /** What a slot of the built rig shows at setup, and every attachment any skin gives it. */
 export interface RigSlot {
@@ -144,7 +162,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', 'face']);
+  refuseUnknownKeys(p, 'MAP_KEYS', where, doc, ['spec', 'note', 'chains', 'translate', 'alternates', 'face', 'body']);
   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) {
@@ -245,22 +263,60 @@ 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;
+  const body = 'body' in doc ? readBodyMap(p, where, doc.body) : undefined;
   p.throwIfAny();
-  return { chains, translate, alternates, ...(face === undefined ? {} : { face }) };
+  return { chains, translate, alternates, ...(face === undefined ? {} : { face }), ...(body === undefined ? {} : { body }) };
+}
+
+function readYawSets(p: Problems, where: string, raw: unknown, shapeCode: string): YawSet[] | undefined {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    p.add(shapeCode, `${where} is ${typeName(raw)}; it must be a non-empty array of { set, above }`);
+    return undefined;
+  }
+  const out: YawSet[] = [];
+  const seen = new Set<string>();
+  raw.forEach((entry: unknown, i: number) => {
+    const ew = `${where}[${i}]`;
+    if (!isObject(entry)) {
+      p.add(shapeCode, `${ew} is ${typeName(entry)}; it is { set, above }`);
+      return;
+    }
+    refuseUnknownKeys(p, 'MAP_KEYS', ew, entry, ['set', 'above']);
+    const set = typeof entry.set === 'string' && entry.set !== '' ? entry.set : null;
+    if (set === null) p.add('MAP_SET_NAME', `${ew} "set" is ${typeName(entry.set)}; it must be a non-empty string`);
+    else if (seen.has(set)) p.add('MAP_SET_NAME', `${ew} "set" "${set}" names two entries`);
+    if (set !== null) seen.add(set);
+    const above = typeof entry.above === 'number' && Number.isFinite(entry.above) && entry.above > 0 ? entry.above : null;
+    if (above === null) p.add('MAP_SET_ABOVE', `${ew} "above" is ${JSON.stringify(entry.above)}; it must be a positive finite number of degrees`);
+    if (set !== null && above !== null) out.push({ set, above });
+  });
+  return out.length > 0 ? out : undefined;
+}
+
+export function faceYawSets(face: FaceMap | undefined): YawSet[] | undefined {
+  return face?.yaw?.sets ?? face?.sets;
+}
+
+export function bodyYawSets(body: BodyMap | undefined): YawSet[] | undefined {
+  return body?.sets ?? body?.yaw?.sets;
 }
 
 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] } }`);
+    p.add('MAP_FACE_SHAPE', `${fw} is ${typeName(raw)}; it is { yaw?: { bone, range: [min, max], sets? }, pitch?: { bone, range: [min, max] }, sets? }`);
     return undefined;
   }
-  refuseUnknownKeys(p, 'MAP_KEYS', fw, raw, ['yaw', 'pitch']);
-  if (!('yaw' in raw) && !('pitch' in raw)) {
+  refuseUnknownKeys(p, 'MAP_KEYS', fw, raw, ['yaw', 'pitch', 'sets']);
+  if (!('yaw' in raw) && !('pitch' in raw) && !('sets' 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 = {};
+  if ('sets' in raw) {
+    const sets = readYawSets(p, `${fw} "sets"`, raw.sets, 'MAP_FACE_SHAPE');
+    if (sets !== undefined) out.sets = sets;
+  }
   for (const axis of ['yaw', 'pitch'] as const) {
     if (!(axis in raw)) continue;
     const aw = `${fw} "${axis}"`;
@@ -269,19 +325,67 @@ function readFaceMap(p: Problems, where: string, raw: unknown): FaceMap | undefi
       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] };
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, ax, axis === 'yaw' ? ['bone', 'range', 'sets'] : ['bone', 'range']);
+    const sets = axis === 'yaw' && 'sets' in ax ? readYawSets(p, `${aw} "sets"`, ax.sets, 'MAP_FACE_SHAPE') : undefined;
+    const hasBoneOrRange = 'bone' in ax || 'range' in ax || !('sets' in ax);
+    if (hasBoneOrRange) {
+      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], ...(sets === undefined ? {} : { sets }) };
+      }
+    } else if (sets !== undefined) {
+      out.sets = sets;
     }
   }
   return out;
 }
 
+function readBodyMap(p: Problems, where: string, raw: unknown): BodyMap | undefined {
+  const bw = `${where} "body"`;
+  if (!isObject(raw)) {
+    p.add('MAP_BODY_SHAPE', `${bw} is ${typeName(raw)}; it is { yaw?: { bone, range: [min, max] }, sets?: [{ set, above }] }`);
+    return undefined;
+  }
+  refuseUnknownKeys(p, 'MAP_KEYS', bw, raw, ['yaw', 'sets']);
+  if (!('yaw' in raw) && !('sets' in raw)) {
+    p.add('MAP_BODY_SHAPE', `${bw} does not name "yaw" or "sets"; it must name at least one`);
+    return undefined;
+  }
+  const out: BodyMap = {};
+  if ('sets' in raw) {
+    const sets = readYawSets(p, `${bw} "sets"`, raw.sets, 'MAP_BODY_SHAPE');
+    if (sets !== undefined) out.sets = sets;
+  }
+  if ('yaw' in raw) {
+    const aw = `${bw} "yaw"`;
+    const ax = raw.yaw;
+    if (!isObject(ax)) {
+      p.add('MAP_BODY_SHAPE', `${aw} is ${typeName(ax)}; it is { bone, range: [min, max] }`);
+      return undefined;
+    }
+    refuseUnknownKeys(p, 'MAP_KEYS', aw, ax, ['bone', 'range', 'sets']);
+    const sets = 'sets' in ax ? readYawSets(p, `${aw} "sets"`, ax.sets, 'MAP_BODY_SHAPE') : undefined;
+    const hasBoneOrRange = 'bone' in ax || 'range' in ax || !('sets' in ax);
+    if (hasBoneOrRange) {
+      const bone = typeof ax.bone === 'string' && ax.bone !== '' ? ax.bone : null;
+      if (bone === null) p.add('MAP_BODY_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_BODY_RANGE', `${aw} "range" is ${JSON.stringify(v)}; it must be [min, max], two finite numbers of degrees with min ≤ 0 ≤ max and min < max`);
+        return undefined;
+      }
+      if (bone !== null) out.yaw = { bone, range: [v[0] as number, v[1] as number], ...(sets === undefined ? {} : { sets }) };
+    } else if (sets !== undefined) {
+      out.sets = sets;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 const SET_SHAPE = '{ name, slots: { "<slot>": "<attachment>" }, hides?: [slot], chains: [chain], pose: { "<joint>": [x, y] }, drawn?: { "<bone>": deg }, offsets?: { "<bone>": [dx, dy] }, turn?: { "<bone>": [min, max] }, frames?: [[first, last], …], place?: "by-hip" }';
 
 /** The joints a wrist is, for `place: "by-hip"`: a chain whose last joint is one of them carries a wrist. */
@@ -535,8 +639,15 @@ export function rigPoint(rest: Rest, spec: string): [number, number] | null {
   return pointAt(rest, new Map([...rest].map(([n, b]) => [n, b.length])), spec);
 }
 
+export function knownSetsOf(map: JointMap, rigSets: RigSets = new Map()): Map<string, RigSet> {
+  const out = new Map<string, RigSet>();
+  for (const [k, v] of rigSets) out.set(k, v);
+  for (const a of map.alternates) if (!out.has(a.name)) out.set(a.name, { slots: a.slots, hides: a.hides });
+  return out;
+}
+
 /** Check every name the map gives against the rig; every miss is named. */
-export function resolveMap(map: JointMap, rest: Rest, where: string, slots: RigSlots = new Map()): void {
+export function resolveMap(map: JointMap, rest: Rest, where: string, slots: RigSlots = new Map(), rigSets: RigSets = new Map()): void {
   const p = new Problems();
   const all = [...rest.keys()];
   const listed = all.length <= 40 ? all.join(', ') : `${all.slice(0, 40).join(', ')} … (${all.length} in all)`;
@@ -619,6 +730,46 @@ export function resolveMap(map: JointMap, rest: Rest, where: string, slots: RigS
       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)`);
     }
   }
+  if (map.body?.yaw !== undefined) {
+    const ax = map.body.yaw;
+    const label = '"body.yaw"';
+    if (!rest.has(ax.bone)) {
+      p.add('MAP_BONE_EXISTS', `${label} — bone "${ax.bone}" is not in the rig; its bones are ${listed}`);
+    } else {
+      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)`);
+    }
+  }
+  const knownSets = knownSetsOf(map, rigSets);
+  const allSets = [...knownSets.keys()];
+  const setsListed = allSets.length === 0 ? 'none' : allSets.join(', ');
+  const allSlots = [...slots.keys()];
+  const slotsListed = allSlots.length === 0 ? 'none' : allSlots.length <= 40 ? allSlots.join(', ') : `${allSlots.slice(0, 40).join(', ')} … (${allSlots.length} in all)`;
+  for (const [label, declared] of [['"face.yaw.sets"', faceYawSets(map.face)], ['"body.sets"', bodyYawSets(map.body)]] as const) {
+    if (declared === undefined) continue;
+    for (const s of declared) {
+      const def = knownSets.get(s.set);
+      if (def === undefined) {
+        p.add('MAP_SET_EXISTS', `${label} — set "${s.set}" is not in the rig; its sets are ${setsListed}`);
+        continue;
+      }
+      if (slots.size === 0) continue;
+      for (const [slot, att] of Object.entries(def.slots)) {
+        const rs = slots.get(slot);
+        if (rs === undefined) p.add('MAP_ALT_SLOT', `set "${s.set}" — slot "${slot}" is not in the rig; its slots are ${slotsListed}`);
+        else if (!rs.attachments.has(att)) {
+          const has = [...rs.attachments];
+          p.add('MAP_ALT_ATTACHMENT', `set "${s.set}" — slot "${slot}" has no attachment "${att}" under any skin; it has ${has.length === 0 ? 'none' : has.join(', ')}`);
+        }
+      }
+      for (const h of def.hides) {
+        if (!slots.has(h)) p.add('MAP_ALT_HIDES', `set "${s.set}" hides slot "${h}", which is not in the rig; its slots are ${slotsListed}`);
+      }
+    }
+  }
   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

@@ -74,17 +74,17 @@
 import { screenToSpineDegrees } from 'rig-c/transform';
 import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
-import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
-import { aimAngle, aimEnds, descends, partBone, pointParts, rigPoint } from './map.ts';
+import type { Chain, JointMap, Rest, RigSets, RigSlots } from './map.ts';
+import { aimAngle, aimEnds, bodyYawSets, descends, faceYawSets, knownSetsOf, partBone, pointParts, rigPoint } from './map.ts';
 import type { Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import type { ArtRange, AttachmentKey, 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 { 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';
+import type { BodyReading, FaceReading, YawSetSwitch } from './face.ts';
+import { readBody, readFace, readFaceAngles, selectYawSets } from './face.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -326,6 +326,8 @@ export interface Retarget {
   byHip: ByHip[];
   /** With "face" in the map (#138): per-frame yaw/pitch reading and range-compressed mapping. */
   face: FaceReading | null;
+  /** Per-frame body yaw read from camera-normalised shoulder and hip width (#173), and optional "body.yaw" dial mapping. */
+  body: BodyReading | null;
   /** Continuous per-frame figure scale relative to frame 0 (`#163`, `#161`). */
   figureScale: FigureScaleReading;
 }
@@ -430,7 +432,7 @@ function pivotOf(rest: Rest, bone: string | null, legs: ReturnType<typeof legsOf
  * good, when a hinge's side cannot be read off a straight rest, and — with
  * `bends: 'refuse'` — when a hinge bends the wrong way.
  */
-export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, times: readonly number[], opts: RetargetOptions, slots: RigSlots = new Map()): Retarget {
+export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, times: readonly number[], opts: RetargetOptions, slots: RigSlots = new Map(), rigSets: RigSets = new Map()): Retarget {
   const p = new Problems();
   const n = frames.length;
   const t0 = times[0]!;
@@ -462,6 +464,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     needed.add('r_eye');
     needed.add('l_eye');
   }
+  if (map.body !== undefined) {
+    needed.add('r_shoulder');
+    needed.add('l_shoulder');
+  }
   const series = new Map<string, Pt[]>();
   const good = new Map<string, boolean[]>();
   const holds: Hold[] = [];
@@ -1520,6 +1526,109 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       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] })) });
     }
+    const fSets = faceYawSets(map.face);
+    if (fSets !== undefined) face.sets = selectYawSets(face.read.rawYaw, fSets, keyTimes, opts.switchMin);
+  }
+  let body: BodyReading | null = null;
+  {
+    const rSh = heldPt('r_shoulder');
+    const lSh = heldPt('l_shoulder');
+    if (rSh !== null && lSh !== null) {
+      const rHip = heldPt('r_hip');
+      const lHip = heldPt('l_hip');
+      const neck = heldPt('neck');
+      const faceYaw = face !== null ? face.read.rawYaw : (() => {
+        const nose = heldPt('nose');
+        const rEye = heldPt('r_eye');
+        const lEye = heldPt('l_eye');
+        if (nose === null || rEye === null || lEye === null) return null;
+        return readFaceAngles(nose, rEye, lEye, heldPt('r_ear'), heldPt('l_ear')).yaw;
+      })();
+      body = readBody(map.body, rSh, lSh, rHip, lHip, neck, !inPlace && n > 25 ? continuousScale : null, faceYaw);
+      const bodyAx = body.yaw;
+      if (bodyAx !== undefined) {
+        const rest0 = restAngle(rest, bodyAx.bone, 'x');
+        const above = mappedAbove(bodyAx.bone);
+        targets.set(bodyAx.bone, bodyAx.keys.map((v, i) => wrap(rest0 + (above === null ? 0 : turn(above, i)) + v)));
+        tracks.push({ bone: bodyAx.bone, property: 'rotate', keys: bodyAx.keys.map((v, i) => ({ t: keyTimes[i]!, v: [v] })) });
+      }
+      const bSets = bodyYawSets(map.body);
+      if (bSets !== undefined) body.sets = selectYawSets(body.read.rawYaw, bSets, keyTimes, opts.switchMin);
+    }
+  }
+  const activeYawSets: YawSetSwitch[] = [...(face?.sets ?? []), ...(body?.sets ?? [])];
+  if (activeYawSets.some((s) => s.spans.length > 0)) {
+    const known = knownSetsOf(map, rigSets);
+    const slotOrder: string[] = [];
+    for (const tr of sw.slotTracks) if (!slotOrder.includes(tr.slot)) slotOrder.push(tr.slot);
+    for (const s of activeYawSets) {
+      const def = known.get(s.set);
+      if (def === undefined) continue;
+      for (const sl of [...Object.keys(def.slots), ...def.hides]) {
+        if (!slotOrder.includes(sl)) slotOrder.push(sl);
+      }
+    }
+    const yawExactAt = new Map<string, Set<number>>();
+    for (const s of activeYawSets) {
+      const def = known.get(s.set);
+      if (def === undefined) continue;
+      const values: Array<[string, string | null]> = [...Object.entries(def.slots), ...def.hides.map((h): [string, null] => [h, null])];
+      for (const [sl, v] of values) {
+        if (!sw.shown.has(sl)) sw.shown.set(sl, Array.from({ length: n }, () => slots.get(sl)?.setup ?? null));
+        const row = sw.shown.get(sl)!;
+        for (const [lo, hi] of s.spans) {
+          for (let i = lo; i <= hi; i++) row[i] = v;
+          const exact = yawExactAt.get(sl) ?? new Set<number>();
+          exact.add(lo);
+          if (hi + 1 < n) exact.add(hi + 1);
+          yawExactAt.set(sl, exact);
+        }
+      }
+    }
+    const rebuilt: SlotTrack[] = [];
+    for (const sl of slotOrder) {
+      const row = sw.shown.get(sl);
+      if (row === undefined) continue;
+      let prev = slots.get(sl)?.setup ?? null;
+      const keys: AttachmentKey[] = [];
+      const exact = yawExactAt.get(sl);
+      row.forEach((v, i) => {
+        if (v === prev) return;
+        const t = i === 0 ? 0 : exact?.has(i) === true ? keyTimes[i]! : r6((keyTimes[i - 1]! + keyTimes[i]!) / 2);
+        keys.push({ t, v });
+        prev = v;
+      });
+      if (keys.length > 0) rebuilt.push({ slot: sl, property: 'attachment', keys });
+    }
+    sw.slotTracks.splice(0, sw.slotTracks.length, ...rebuilt);
+  }
+  if (activeYawSets.length > 0) {
+    const known = knownSetsOf(map, rigSets);
+    const otherSlotKeyers = new Map<string, string[]>();
+    const addKeyer = (sl: string, who: string) => {
+      const list = otherSlotKeyers.get(sl) ?? [];
+      if (!list.includes(who)) list.push(who);
+      otherSlotKeyers.set(sl, list);
+    };
+    for (const aSw of sw.switches) {
+      for (const sl of [...Object.keys(aSw.slots), ...aSw.hides]) addKeyer(sl, `set "${aSw.set}"`);
+    }
+    for (const s of activeYawSets) {
+      if (s.spans.length === 0) continue;
+      const def = known.get(s.set);
+      if (def === undefined) continue;
+      for (const sl of [...Object.keys(def.slots), ...def.hides]) addKeyer(sl, `set "${s.set}"`);
+    }
+    for (const s of activeYawSets) {
+      const def = known.get(s.set);
+      if (def === undefined) continue;
+      for (const h of def.hides) {
+        const keyers = (otherSlotKeyers.get(h) ?? []).filter((who) => who !== `set "${s.set}"`);
+        if (keyers.length > 0) {
+          s.hidesKeyed.push({ slot: h, by: `slot "${h}" attachment (${keyers.join(', ')})` });
+        }
+      }
+    }
   }
   // 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) {
@@ -1539,7 +1648,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, face, figureScale,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip, face, body, figureScale,
   };
 }
 

package/src/rigc.ts

@@ -13,7 +13,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { poseRawSetup, readModel, type CompiledDocument } from 'rig-c/core';
-import type { InheritMode, Rest, RestBone, RigSlot, RigSlots } from './map.ts';
+import type { InheritMode, Rest, RestBone, RigSet, RigSets, RigSlot, RigSlots } from './map.ts';
 import { isObject, parseJson, Problems, Refusal, typeName } from './problems.ts';
 
 export interface RigInput {
@@ -23,6 +23,32 @@ export interface RigInput {
   name: string;
   /** The motion spec the rig is built with, or null when it has none. */
   motion: string | null;
+  /** Any alternate sets declared in `sets.json` (`rig-parts-sets/1`) beside `rig.json`. */
+  sets: RigSets;
+}
+
+function readRigSets(path: string): RigSets {
+  const out = new Map<string, RigSet>();
+  if (!existsSync(path)) return out;
+  const doc = parseJson(readFileSync(path, 'utf8'), path, 'SETS_JSON');
+  if (!isObject(doc) || (doc.spec !== 'rig-parts-sets/1' && doc.spec !== 'spine-parts-sets/1') || (!isObject(doc.sets) && !Array.isArray(doc.sets))) {
+    throw new Refusal([{ code: 'SETS_SPEC', text: `${path} is not a rig-parts-sets/1 spec with a "sets" object` }]);
+  }
+  const addSet = (name: string, s: unknown) => {
+    if (!isObject(s) || !isObject(s.slots)) return;
+    const slots: Record<string, string> = {};
+    for (const [k, v] of Object.entries(s.slots)) if (typeof v === 'string') slots[k] = v;
+    const hides = Array.isArray(s.hides) ? s.hides.filter((h): h is string => typeof h === 'string') : [];
+    out.set(name, { slots, hides });
+  };
+  if (Array.isArray(doc.sets)) {
+    for (const s of doc.sets) {
+      if (isObject(s) && typeof s.name === 'string') addSet(s.name, s);
+    }
+  } else {
+    for (const [name, s] of Object.entries(doc.sets)) addSet(name, s);
+  }
+  return out;
 }
 
 /**
@@ -49,7 +75,8 @@ export function resolveRig(path: string, baseMotion: string | undefined): RigInp
   if (!isObject(doc) || doc.spec !== 'rigc-rig/1' || typeof doc.name !== 'string') {
     throw new Refusal([{ code: 'RIG_SPEC', text: `${rig} is not a rig spec: "spec" is ${isObject(doc) ? typeName(doc.spec) : typeName(doc)} and "name" ${isObject(doc) ? typeName(doc.name) : '-'}; it must be "rigc-rig/1" with a name` }]);
   }
-  return { rig, name: doc.name, motion };
+  const sets = readRigSets(join(dirname(rig), 'sets.json'));
+  return { rig, name: doc.name, motion, sets };
 }
 
 /** The motion spec the rig is built with, or an empty one under its name. */

package/src/run.ts

@@ -7,7 +7,7 @@
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { readMap, resolveMap, type JointMap, type Rest } from './map.ts';
+import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, inferredSource } from './clean.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
@@ -19,7 +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, smoothTrunk, 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';
+import { bodyLine, faceLine } from './face.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -108,9 +108,25 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const rigc = rigcVersion();
     const rest = restOf(doc0);
     const slots = slotsOf(doc0);
-    resolveMap(map, rest, a.map, slots);
+    resolveMap(map, rest, a.map, slots, input.sets);
 
-    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}) }, slots);
+    const r = retarget(rest, map, frames, times, { ...a, ...(seq.travel !== undefined ? { travel: seq.travel } : {}) }, slots, input.sets);
+    if (fragment.length > 0 && ((r.face?.sets?.length ?? 0) > 0 || (r.body?.sets?.length ?? 0) > 0)) {
+      const known = knownSetsOf(map, input.sets);
+      for (const s of [...(r.face?.sets ?? []), ...(r.body?.sets ?? [])]) {
+        const def = known.get(s.set);
+        if (def === undefined) continue;
+        for (const h of def.hides) {
+          for (const tr of fragment) {
+            const tgt = targetOf(tr);
+            if (tgt?.kind === 'slot' && tgt.name === h) {
+              const by = `slot "${h}" ${tr.property} (--merge ${a.merge})`;
+              if (!s.hidesKeyed.some((x) => x.slot === h && x.by === by)) s.hidesKeyed.push({ slot: h, by });
+            }
+          }
+        }
+      }
+    }
     say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)${a.legScale !== undefined && a.legScale !== 'off' ? `, leg-scale ${a.legScale[0]}–${a.legScale[1]}` : ''}${a.plantFeet === true ? ', plant-feet' : ''}${a.stance !== undefined && a.stance !== 'off' ? `, stance ${a.stance}` : ''}${a.raisedByHead === true ? ', raised-by-head' : ''}${a.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
@@ -161,6 +177,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     }
     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)}`);
+    if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
     // --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);
@@ -192,6 +209,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         ...(map.translate === null ? [] : [map.translate.bone]),
         ...(map.face?.yaw === undefined ? [] : [map.face.yaw.bone]),
         ...(map.face?.pitch === undefined ? [] : [map.face.pitch.bone]),
+        ...(map.body?.yaw === undefined ? [] : [map.body.yaw.bone]),
       ];
       const below = new Map<string, string[]>();
       for (const m of new Set(mapped)) {
@@ -283,7 +301,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     else if (f.meshes.length === 0) say(`  FOLD   rigc render --folds at ${fps} fps: no mesh folds`);
     else for (const m of f.meshes) say(`  FOLD   mesh "${m.attachment}" (slot "${m.slot}") folds on ${m.times.length} frame(s) at ${fps} fps: t=${spans(m.times, 1 / fps)}`);
     const uncovered = f.meshes === null ? null : uncoveredFolds(f.meshes, r.shown, r.times, slots, (slot, att) => chainsMoving(attachmentBones(doc, slot, att), rest, map));
-    if (uncovered !== null && map.alternates.length > 0) {
+    if (uncovered !== null && (map.alternates.length > 0 || (r.face?.sets?.length ?? 0) > 0 || (r.body?.sets?.length ?? 0) > 0)) {
       for (const u of uncovered) say(`  UNCOVERED mesh "${u.attachment}" (slot "${u.slot}"; chains ${u.chains.length === 0 ? 'none' : u.chains.join(', ')}) folds with no switch covering it on ${u.times.length} frame(s): t=${spans(u.times, 1 / fps)}`);
     }
 
@@ -363,8 +381,19 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
                 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 } }),
+                ...(r.face.sets === undefined ? {} : { sets: r.face.sets }),
               },
             }),
+        body: r.body === null
+          ? null
+          : {
+              standing: r.body.standing,
+              read: { yaw: r.body.read.yaw, opening: r.body.read.opening },
+              over45: r.body.over45,
+              framesOver45: r.body.framesOver45,
+              ...(r.body.yaw === undefined ? {} : { yaw: { bone: r.body.yaw.bone, limits: r.body.yaw.limits, knee: r.body.yaw.knee, read: r.body.yaw.read, mapped: r.body.yaw.mapped, scale: r.body.yaw.scale, corr: r.body.yaw.corr } }),
+              ...(r.body.sets === undefined ? {} : { sets: r.body.sets }),
+            },
         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 },