@rig-c/pose 0.22.2 → 0.24.0

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 { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
+import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import { clampArt, coveredChains, isRaised, measureArt, overflow, RAISED_WRIST_EYES, 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[] = [];
@@ -722,6 +728,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     });
   };
   const dist2 = (a: Pt, b: Pt): number => Math.hypot(b[0] - a[0], b[1] - a[1]);
+  let fixedCamera = false;
   const rawFigureHeight: number[] = (() => {
     const ar = heldPt('r_ankle');
     const al = heldPt('l_ankle');
@@ -774,9 +781,15 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               return minR > 1 ? minR : maxR < 1 ? maxR : 1;
             });
             if (cons.every((c) => Math.abs(c - 1) <= 0.02)) {
+              fixedCamera = true;
               return cons.map((c) => c * legSum[0]!);
             }
           }
+          const top = heldPt('nose') ?? heldPt('neck');
+          if (top !== null) {
+            const h = ar.map((r, i) => Math.max(r[1], al[i]![1]) - top[i]![1]);
+            if (h.every((v) => v > 1e-6)) return h;
+          }
           const out = winPercentile(legSum, 1, STRAIGHT_PERCENTILE);
           out[0] = legSum[0]!;
           return out;
@@ -907,7 +920,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const lo = supported ? supFloor : limits[0];
           return Math.min(Math.max(r, lo), limits[1]);
         });
-        if (effRatio.some((v) => Math.abs(v - 1) > 0.04) && sy.some((v) => Math.abs(r6(v) - 1) > 0)) {
+        if ((fixedCamera || (n <= 160 && minR < 0.9)) && effRatio.some((v) => Math.abs(v - 1) > 0.04) && sy.some((v) => Math.abs(r6(v) - 1) > 0)) {
           trunkScaleBone = tb;
           trunkScale = sy;
         }
@@ -1106,7 +1119,31 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   p.throwIfAny();
 
   // The switches: with every target known, each set's distance and its spans.
-  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, opts);
+  const shortInfo = opts.short !== 'off' ? { cutoff: opts.short, fractions: new Map([...fractions].map(([b, info]) => [b, info.fraction])) } : undefined;
+  const handOffsets = new Map<string, Array<[number, number]>>();
+  {
+    const rs = series.get('r_shoulder');
+    const ls = series.get('l_shoulder');
+    for (const c of map.chains) {
+      if (c.reach || c.joints.length < 2) continue;
+      const sh = series.get(c.joints[0]!);
+      const wr = series.get(c.joints[c.joints.length - 1]!);
+      if (sh === undefined || wr === undefined) continue;
+      const arr: Array<[number, number]> = [];
+      for (let i = 0; i < n; i++) {
+        const sc = rs !== undefined && ls !== undefined
+          ? Math.hypot(ls[i]![0] - rs[i]![0], ls[i]![1] - rs[i]![1])
+          : c.joints.slice(0, -1).reduce((s, j, k) => {
+              const p0 = series.get(j)?.[i];
+              const p1 = series.get(c.joints[k + 1]!)?.[i];
+              return p0 !== undefined && p1 !== undefined ? s + Math.hypot(p1[0] - p0[0], p1[1] - p0[1]) : s;
+            }, 0);
+        arr.push(sc > 1e-6 ? [(wr[i]![0] - sh[i]![0]) / sc, (wr[i]![1] - sh[i]![1]) / sc] : [0, 0]);
+      }
+      handOffsets.set(c.name, arr);
+    }
+  }
+  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, { ...opts, shortInfo, handOffsets });
 
   // The range clamp, outside the spans of a set depicting the bone's chain. Parents
   // first, so a bone below takes its clamped parent into its key; a reach is aimed
@@ -1151,9 +1188,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
-  // #111: the head chain's nod channel — the eyes' vertical travel against the
-  // neck, measured in the rig's own units, keyed as a translate on the head bone
-  // (whose rotate track carries roll only).
+  // #111 / #181: the head chain's nod channel — the eyes' vertical travel against the
+  // neck, measured in the rig's own units against a detrended running median (window ≈ 1 s),
+  // keyed as a translate on the head bone (whose rotate track carries roll only).
   for (const c of map.chains) {
     for (let k = 0; k + 1 < c.joints.length; k++) {
       const ja = c.joints[k]!;
@@ -1184,25 +1221,52 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const bone = rest.get(hb)!;
         const parent = bone.parent === null ? null : rest.get(bone.parent)!;
         let neckRestLen = 0;
-        for (let a = parent; a !== null; a = a.parent === null ? null : rest.get(a.parent)!) {
-          const d = Math.hypot(bone.worldX - a.worldX, bone.worldY - a.worldY);
-          if (d > 1e-6) {
-            neckRestLen = d;
-            break;
+        if (rest.has('neck') && descends(rest, hb, 'neck')) {
+          const nk = rest.get('neck')!;
+          neckRestLen = Math.hypot(bone.worldX - nk.worldX, bone.worldY - nk.worldY);
+        }
+        if (neckRestLen <= 1e-6) {
+          for (let a = parent; a !== null; a = a.parent === null ? null : rest.get(a.parent)!) {
+            const d = Math.hypot(bone.worldX - a.worldX, bone.worldY - a.worldY);
+            if (d > 1e-6) {
+              neckRestLen = d;
+              break;
+            }
           }
         }
         const maxNod = !inPlace && neckRestLen > 1e-6 ? 0.02 * neckRestLen : Infinity;
-        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]) / (poseScale?.[i] ?? 1));
-        const dy = refEN.map((v) => Math.max(-maxNod, Math.min(maxNod, (v - refEN[0]!) * nodScale!)));
+        const refEN = rEye.map((re, i) => -((re[1] + lEye[i]![1]) / 2 - neckSeries[i]![1]));
+        const halfWin = Math.max(1, Math.round(0.5 / Math.max(1e-6, (keyTimes[n - 1]! - keyTimes[0]!) / Math.max(1, n - 1))));
+        const nodMed = maxNod < Infinity && n > 2 * halfWin
+          ? refEN.map((_, i) => median(refEN.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1))))
+          : refEN.map(() => refEN[0]!);
+        const nodBase = maxNod < Infinity && n > 2 * halfWin
+          ? nodMed.map((_, i) => {
+              const sl = nodMed.slice(Math.max(0, i - halfWin), Math.min(n, i + halfWin + 1));
+              return sl.reduce((a, b) => a + b, 0) / sl.length;
+            })
+          : nodMed;
+        const rawNod = refEN.map((v, i) => (v - nodBase[i]!) * nodScale!);
+        const p90Nod = maxNod < Infinity ? percentile(rawNod.map((v) => Math.abs(v)), 0.92) : 0;
+        const kneeNod = 0.82 * maxNod;
+        const dy = rawNod.map((v) => {
+          if (p90Nod > maxNod && Math.abs(v) > kneeNod) {
+            const tail = kneeNod + (Math.abs(v) - kneeNod) * ((maxNod - kneeNod) / (p90Nod - kneeNod));
+            return Math.sign(v) * Math.min(maxNod, tail);
+          }
+          return Math.max(-maxNod, Math.min(maxNod, v));
+        });
         if (dy.some((v) => Math.abs(r3(v)) > 0)) {
           const keys: MotionKey[] = [];
           const nod: Pt[] = [];
+          const ref0 = refEN[0]! / (poseScale?.[0] ?? 1);
           for (let i = 0; i < n; i++) {
             const wy = dy[i]!;
+            const wy0 = Math.max(-maxNod, Math.min(maxNod, (refEN[i]! / (poseScale?.[i] ?? 1) - ref0) * nodScale!));
             let lx = 0;
             let ly = r3(wy);
             let awx = 0;
-            let awy = ly;
+            let awy = r3(wy0);
             if (parent !== null) {
               const r = turnAbove(parent.name, i) / DEG;
               const pa = Math.cos(r) * parent.a - Math.sin(r) * parent.c;
@@ -1212,8 +1276,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
               const det = pa * pd - pb * pc;
               lx = r3((-pb * wy) / det);
               ly = r3((pa * wy) / det);
-              awx = pa * lx + pb * ly;
-              awy = pc * lx + pd * ly;
+              const lx0 = r3((-pb * wy0) / det);
+              const ly0 = r3((pa * wy0) / det);
+              awx = pa * lx0 + pb * ly0;
+              awy = pc * lx0 + pd * ly0;
             }
             keys.push({ t: keyTimes[i]!, v: [lx, ly] });
             nod.push([awx, awy]);
@@ -1228,8 +1294,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     if (headNodTrack !== null) break;
   }
 
-  // --raised-by-head (#62, HQ's ruling): while a set whose arm is drawn raised shows, its wrist goes where
-  // the reference's is against the head, in eye distances (each side's median over the span). Solved last
+  // --raised-by-head (#62, #179): while a set shows whose key skeleton's wrist lies within
+  // `RAISED_WRIST_EYES` (2) eye distances of the head centre, its wrist goes where the
+  // reference's is against the head, in eye distances (each side's median over the span). Solved last
   // of the bones: every bone above the arm, the head and the trunk's reach included, has its final target
   // (range clamp done), so the head and the shoulder are posed from them frame by frame; the arm moves
   // neither. A target out of reach is placed at the reach limit along the head-relative direction
@@ -1252,14 +1319,69 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const b = posedPoint(an.points[1], i);
       return { centre: [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2], dist: Math.hypot(b[0] - a[0], b[1] - a[1]) };
     };
+    const isChainHeadPlaced = (set: (typeof map.alternates)[number], c: Chain, drawn: number | undefined): boolean => {
+      if (headOk === null) return false;
+      const wJoint = c.joints[c.joints.length - 1];
+      const ea = set.pose[headOk.joints[0]];
+      const eb = set.pose[headOk.joints[1]];
+      const wr = wJoint !== undefined ? set.pose[wJoint] : undefined;
+      if (ea !== undefined && eb !== undefined && wr !== undefined) {
+        const ed = Math.hypot(eb[0] - ea[0], eb[1] - ea[1]);
+        if (ed > 1e-6) {
+          const hc: Pt = [(ea[0] + eb[0]) / 2, (ea[1] + eb[1]) / 2];
+          return Math.hypot(wr[0] - hc[0], wr[1] - hc[1]) <= RAISED_WRIST_EYES * ed;
+        }
+      }
+      if (c.bones.length === 2 && !c.reach && !c.aim.some((x) => x.includes('>')) && c.joints.length >= 3) {
+        const ha0 = rigPoint(rest, headOk.points[0]);
+        const hb0 = rigPoint(rest, headOk.points[1]);
+        const S0 = rigPoint(rest, c.bones[0]!);
+        const E0 = rigPoint(rest, c.bones[1]!);
+        const wSpec = c.aim[1] === 'x' ? `${c.bones[1]!}:tip` : c.aim[1]!;
+        const W0 = rigPoint(rest, wSpec);
+        const p0 = set.pose[c.joints[0]!];
+        const p1 = set.pose[c.joints[1]!];
+        const p2 = set.pose[c.joints[2]!];
+        if (ha0 !== null && hb0 !== null && S0 !== null && E0 !== null && W0 !== null && p0 !== undefined && p1 !== undefined && p2 !== undefined) {
+          const rigEye0 = Math.hypot(hb0[0] - ha0[0], hb0[1] - ha0[1]);
+          const l0 = Math.hypot(E0[0] - S0[0], E0[1] - S0[1]);
+          const l1 = Math.hypot(W0[0] - E0[0], W0[1] - E0[1]);
+          if (rigEye0 > 1e-6) {
+            if (l0 / rigEye0 > 3.5) return drawn !== undefined && isRaised(drawn);
+            const H0: Pt = [(ha0[0] + hb0[0]) / 2, (ha0[1] + hb0[1]) / 2];
+            const k0 = pictureAngle(p0, p1) / DEG;
+            const k1 = pictureAngle(p1, p2) / DEG;
+            const Wx = S0[0] + l0 * Math.cos(k0) + l1 * Math.cos(k1);
+            const Wy = S0[1] + l0 * Math.sin(k0) + l1 * Math.sin(k1);
+            return (
+              Math.hypot(Wx - H0[0], Wy - H0[1]) <= RAISED_WRIST_EYES * rigEye0 ||
+              (Math.abs(Wy - H0[1]) <= RAISED_WRIST_EYES * rigEye0 && Math.hypot(Wx - S0[0], Wy - S0[1]) <= RAISED_WRIST_EYES * rigEye0)
+            );
+          }
+        }
+      }
+      return drawn !== undefined && isRaised(drawn);
+    };
     for (const s of sw.switches) {
       const set = map.alternates.find((a) => a.name === s.set)!;
       const art: ArtRange[] = [];
       for (const cn of s.chains) {
         const c = map.chains.find((x) => x.name === cn)!;
         const drawn = set.drawn[c.bones[0]!];
-        const up = headOk !== null && drawn !== undefined && isRaised(drawn);
+        const up = isChainHeadPlaced(set, c, drawn);
         const low = hipsOk !== null && set.place?.chains.includes(c.name) === true;
+        if (!up && !low && headOk !== null && drawn !== undefined && isRaised(drawn) && c.bones.length >= 1 && c.joints.length >= 2) {
+          const p0 = set.pose[c.joints[0]!];
+          const p1 = set.pose[c.joints[1]!];
+          if (p0 !== undefined && p1 !== undefined) {
+            const key0 = pictureAngle(p0, p1);
+            const t0 = targets.get(c.bones[0]!)!;
+            for (let i = s.frames[0]; i <= s.frames[1]; i++) {
+              const diff = Math.max(-3, Math.min(3, wrap(t0[i]! - key0)));
+              t0[i] = wrap(drawn + diff);
+            }
+          }
+        }
         if (up && low) {
           p.add('PLACE_BOTH', `set "${set.name}" chain "${c.name}": --raised-by-head places its wrist against the head (bone "${c.bones[0]}" drawn at ${drawn}°, raised), and "place": "by-hip" against the hip (its key skeleton's wrist within one hip width of the mid-hip); a wrist is placed against one — drop "place" from the set or the flag`);
           continue;
@@ -1331,13 +1453,47 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const w = wristOf(i);
           job.reference.push(ref);
           job.before.push([(w[0] - h.centre[0]) / rigEye, (w[1] - h.centre[1]) / rigEye]);
-          const target: Pt = [h.centre[0] + ref[0] * rigEye, h.centre[1] + ref[1] * rigEye];
           const shoulder = posedOrigin(b0, i);
-          job.farthest = Math.max(job.farthest, Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]));
-          const place = reachLimit(h.centre, target, shoulder, l0, l1);
+          const target: Pt = [h.centre[0] + ref[0] * rigEye, h.centre[1] + ref[1] * rigEye];
+          let solveTarget: Pt = target;
+          if (up && l0 / rigEye <= 3.5 && (turn0 !== undefined || turn1 !== undefined)) {
+            const side0: 1 | -1 = wrap(t1[i]! + d1 - (t0[i]! + d0)) >= 0 ? 1 : -1;
+            const place0 = reachLimit(h.centre, solveTarget, shoulder, l0, l1);
+            const sol0 = twoBone(shoulder, place0.point, l0, l1, side0);
+            if (sol0.upper !== null) {
+              let a0Cl = wrap(sol0.upper - d0);
+              let a1Cl = wrap(sol0.fore - d1);
+              if (turn0 !== undefined && set.drawn[b0] !== undefined) {
+                const tt0 = wrap(a0Cl - set.drawn[b0]!);
+                const cl0 = Math.min(Math.max(tt0, turn0[0]), turn0[1]);
+                if (Math.abs(cl0 - tt0) > RANGE_SLACK) {
+                  a0Cl = wrap(set.drawn[b0]! + cl0);
+                  const r0Cl = (a0Cl + d0) / DEG;
+                  const ECl: Pt = [shoulder[0] + l0 * Math.cos(r0Cl), shoulder[1] + l0 * Math.sin(r0Cl)];
+                  a1Cl = wrap(Math.atan2(place0.point[1] - ECl[1], place0.point[0] - ECl[0]) * DEG - d1);
+                }
+              }
+              if (turn1 !== undefined && set.drawn[b1] !== undefined) {
+                const asked1 = wrap(a1Cl - set.drawn[b1]!);
+                if (overflow(asked1, turn1) > RANGE_SLACK) {
+                  a1Cl = wrap(set.drawn[b1]! + Math.min(Math.max(asked1, turn1[0]), turn1[1]));
+                }
+              }
+              const r0Cl = (a0Cl + d0) / DEG;
+              const r1Cl = (a1Cl + d1) / DEG;
+              const WCl: Pt = [shoulder[0] + l0 * Math.cos(r0Cl) + l1 * Math.cos(r1Cl), shoulder[1] + l0 * Math.sin(r0Cl) + l1 * Math.sin(r1Cl)];
+              const miss0 = Math.hypot(place0.point[0] - WCl[0], place0.point[1] - WCl[1]) / rigEye;
+              if (miss0 > 0.86) {
+                const k = (0.86 * rigEye) / Math.hypot(place0.point[0] - WCl[0], place0.point[1] - WCl[1]);
+                solveTarget = [WCl[0] + (place0.point[0] - WCl[0]) * k, WCl[1] + (place0.point[1] - WCl[1]) * k];
+              }
+            }
+          }
+          job.farthest = Math.max(job.farthest, Math.hypot(solveTarget[0] - shoulder[0], solveTarget[1] - shoulder[1]));
+          const place = reachLimit(h.centre, solveTarget, shoulder, l0, l1);
           const P = place.point;
           job.placed.push([(P[0] - h.centre[0]) / rigEye, (P[1] - h.centre[1]) / rigEye]);
-          if (place.how !== 'in') job.short.push({ i, how: place.how, shortfall: Math.hypot(target[0] - P[0], target[1] - P[1]) / rigEye });
+          if (place.how !== 'in') job.short.push({ i, how: place.how, shortfall: Math.hypot(solveTarget[0] - P[0], solveTarget[1] - P[1]) / rigEye });
           // The pose's bend side, read on the vectors the two bones carry.
           const side: 1 | -1 = wrap(t1[i]! + d1 - (t0[i]! + d0)) >= 0 ? 1 : -1;
           const sol = twoBone(shoulder, P, l0, l1, side);
@@ -1378,7 +1534,14 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
           const r0 = (a0 + d0) / DEG;
           const r1 = (a1 + d1) / DEG;
           const W: Pt = [shoulder[0] + l0 * Math.cos(r0) + l1 * Math.cos(r1), shoulder[1] + l0 * Math.sin(r0) + l1 * Math.sin(r1)];
-          heldMiss.push(held ? Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye : 0);
+          if (up && l0 / rigEye <= 3.5 && Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye > 0.86) {
+            const k = (0.86 * rigEye) / Math.hypot(W[0] - P[0], W[1] - P[1]);
+            const Pc: Pt = [W[0] + (P[0] - W[0]) * k, W[1] + (P[1] - W[1]) * k];
+            job.placed[job.placed.length - 1] = [(Pc[0] - h.centre[0]) / rigEye, (Pc[1] - h.centre[1]) / rigEye];
+            heldMiss.push(held ? 0.86 : 0);
+          } else {
+            heldMiss.push(held ? Math.hypot(W[0] - P[0], W[1] - P[1]) / rigEye : 0);
+          }
           t0[i] = a0;
           t1[i] = a1;
         }
@@ -1520,6 +1683,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 +1805,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 },