@rig-c/pose 0.22.2 → 0.24.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`
 
@@ -352,7 +354,7 @@ Bone rotation cannot carry every pose: an arm behind the head, a forearm toward
 - `place` (optional): `"by-hip"` places a hand that meets the body by its offset from the hip ([below](#alternate-drawings-alternates)).
 - Each name resolves against the built rig and the map, and a miss is refused by name, listing what exists: `MAP_ALT_SLOT`, `MAP_ALT_ATTACHMENT`, `MAP_ALT_HIDES`, `MAP_ALT_CHAIN`, `MAP_ALT_JOINT`, `MAP_ALT_POSE`, `MAP_ALT_DRAWN`, `MAP_ALT_OFFSET` (a bone that is not a bone of the set's chains) and `MAP_ALT_PLACE`.
 
-**When one shows.** Per frame and per set, the distance is the largest difference, in degrees, between a segment of its chains as the retarget asked for it (after holds, the short hold, the flip guard and the hinge check; before any range clamp) and the same segment in its key skeleton. On each frame the nearest set within `--switch-tolerance` (default 25°) shows, ties going to the map's order; a run of one set shorter than `--switch-min` (default 0.25 s) is dropped and the base art shows there. Both figures were fixed before a run ([#6](https://github.com/rig-c/pose/issues/6)). Sets compete only with those they share a slot (shown or hidden) or an offset bone with, so a drawing of each arm can show at once; two that compete never overlap.
+**When one shows.** Per frame and per set, the distance is the largest difference, in degrees, between a segment of its chains as the retarget asked for it (after holds, the short hold, the flip guard and the hinge check; before any range clamp) and the same segment in its key skeleton, with a foreshortened segment (`SHORT`) weighted at `0.5 ×` (`SHORT_SWITCH_WEIGHT`, [#180](https://github.com/rig-c/pose/issues/180)). On each frame the nearest set within `--switch-tolerance` (default 25°) shows, ties going to the map's order; once entered, a set stays active until its distance exceeds `--switch-tolerance + 15°` (`SWITCH_LEAVE_HYSTERESIS`, [#180](https://github.com/rig-c/pose/issues/180)) for at least `--switch-min` (default 0.25 s) or a competing set with a lower distance enters within `--switch-tolerance`; a run of one set shorter than `--switch-min` is dropped and the base art shows there. Sets compete only with those they share a slot (shown or hidden) or an offset bone with, so a drawing of each arm can show at once; two that compete never overlap.
 
 **Where a switch is keyed: `--switch-at`.** By default (`first`) a boundary — the frame a set starts showing on, and the frame the base art or the next set comes back on — is where the selection above puts it: the first frame within the tolerance, often a frame where the arm is slowing into the pose, so the change of drawing can be seen on a nearly still arm. `--switch-at peak` moves each boundary to the frame within ±`--switch-min`/2 (±3 frames at 24 fps with the default 0.25 s) where the chains it changes turn fastest, so the cut lands in motion ([#31](https://github.com/rig-c/pose/issues/31)). The speed on a frame is the largest |angular speed| in degrees per frame, a central difference of the target world angles (one-sided on the first and last frame), over every segment of the leaving set's and the arriving set's chains; it is read on the same targets as the distance, before the range clamp and any set's `turn`, which depend on where the spans are. The window is clipped so every span keeps `--switch-min`, a gap between two spans of one set keeps it too (the bridging holds), no boundary reaches its neighbour, and a set with `frames` shows only inside them. In it, a frame qualifies only if the set the move newly shows is within **2 × `--switch-tolerance`** of its key skeleton on every frame it newly shows it on; the boundary goes to the fastest qualifying frame, and stays when none qualifies. A tie goes to the frame nearest the original, then the earlier. A boundary between two sets moves once.
 
@@ -360,7 +362,7 @@ The bound exists because speed alone rewarded showing art far from its pose. Unb
 
 Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's old and new frame (the same under `first`), the frames and seconds it moved, the speed on both and its window, and the report carries the same under `moved`.
 
-**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. Between two sets that both draw an arm behind the torso, a frame that belongs to neither set stays behind (the nearer set's layer); the default front slot is for a frame no set can claim **and** whose arm is read in front — not a fallback ([#136](https://github.com/rig-c/pose/issues/136), [#139](https://github.com/rig-c/pose/issues/139), [#162](https://github.com/rig-c/pose/issues/162)). A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
+**What is written.** An `attachment` track per slot whose picture changes: the set's attachment (or `null` for a hidden slot) where a span starts, and the slot's setup attachment, as the compiled model states it, where it ends. A direct switch from one set to another puts the first set's slots back to setup on the second's first frame, so an extra slot that is empty at setup goes empty. Between two sets that both draw an arm behind the torso, a frame that belongs to neither set stays behind (the set nearer in hand position and segment distance, not frame count); the default front slot is for a frame no set can claim **and** whose arm is read in front — not a fallback ([#136](https://github.com/rig-c/pose/issues/136), [#139](https://github.com/rig-c/pose/issues/139), [#162](https://github.com/rig-c/pose/issues/162), [#180](https://github.com/rig-c/pose/issues/180)). A switch onto frame *i* is keyed halfway between frames *i*−1 and *i*: a stepped key on the frame's own time fires a frame late wherever a player's accumulated time lands just below it (rig-c's docs/AUTHORING.md §4.5), and halfway both the pose's times and a renderer's `i / fps` see it on frame *i*. Before the first key a slot shows its setup attachment, so no key is written at 0 unless a span starts there. Offsets are `translate` keys at the same times, `stepped`. rig-c's gate checks these keys like any other.
 
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds, held as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 
@@ -369,7 +371,7 @@ Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's
 
 **How far a set's art may turn: `turn`.** A drawing reads right only near the angle it was painted at. A set may state, per bone with a `drawn` angle, how far its art may turn from it, `"turn": { "sleeve_r0": [-20, 20] }`. While the set shows, the bone is held within it: its target becomes drawn + clamp(wrap(target − drawn), min, max), each bone on its own world angle, so a forearm under a held upper arm keeps its own target. The landing check measures against the held angle. The overflow the pose asked for is listed as `ART-RANGE`. A `turn` on a bone the set has no `drawn` angle for is refused (`MAP_ALT_TURN`).
 
-**A raised arm placed against the head: `--raised-by-head`.** The pose's angles put a hand where it is against the dancer's own shoulder. On a rig whose shoulders sit nearer its head, or whose head is larger, the same angles put a hand raised beside the head on top of it. With `--raised-by-head` (off by default, [#62](https://github.com/rig-c/pose/issues/62)) a set draws an arm **raised** when its `drawn` angle for the chain's first bone (the upper arm) is within 30° of straight up (a world angle of 60°–120°). While that set shows, the arm's wrist goes where the reference's is **against the head**:
+**A raised arm placed against the head: `--raised-by-head`.** The pose's angles put a hand where it is against the dancer's own shoulder. On a rig whose shoulders sit nearer its head, or whose head is larger, the same angles put a hand raised beside the head on top of it. With `--raised-by-head` (off by default, [#62](https://github.com/rig-c/pose/issues/62), [#179](https://github.com/rig-c/pose/issues/179)) a set places a chain by the head when its key skeleton (`pose`) puts the chain's wrist within `2 × eye_dist` (`RAISED_WRIST_EYES = 2`) of the head centre (the midpoint of `r_eye` and `l_eye`, or `nose` when the eyes are absent from the key skeleton); a chain whose wrist sits farther keeps its shoulder-based pose angles regardless of its upper arm's `drawn` angle. While that set shows, the arm's wrist goes where the reference's is **against the head**:
 
 - The unit is the **eye distance**: on each side, its median over the span. That is the reference's |r_eye − l_eye|, and on the rig the distance between the two points the head chain's `"a>b"` aim names. The head centre is the eyes' midpoint on each frame. The head chain is the one carrying the eye line (r_eye → l_eye, either way round). The flag is refused without one, or with one not aimed `"a>b"` (`RAISED_HEAD`).
 - The target is rig head centre + (reference wrist − reference head centre) × (rig eye distance ÷ reference eye distance), the picture's y turned up, per frame.

package/package.json

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