@rig-c/pose 0.2.1 → 0.4.0

package/src/retarget.ts

@@ -23,11 +23,38 @@
  * evaluated at the frame, on each joint's positions after its holds. Centred,
  * it moves no motion in time; a cubic keeps a peak a moving average flattens.
  *
+ * The short hold (rig-c/pose#22) comes next: a segment whose picture length on
+ * a frame is under `short` of its own median length over the sequence is seen
+ * end-on, or collapsed by blur, and its picture direction there is noise. Its
+ * angle on those frames is not read from the pose but interpolated, the short
+ * way round, between the frames either side at or above the cutoff (flat at the
+ * ends: `holdShort`). A run under the cutoff lasting ≥ `END_ON_SECONDS` (spans
+ * merged across a gap of `END_ON_GAP` frame) is listed as `endOn`: a pose the
+ * rig cannot draw, the demand for an alternate drawing (#6).
+ *
  * The flip guard (rig-c/pose#15) then spreads a segment's turn greater than
  * `flip` degrees in one frame over the frames around it, linearly and centred on
  * the jump (`spreadFlips`). It reads the mapped segments' target angles after
- * holds and smoothing and before the hinge check. A reach's target is aimed
- * later, from posed positions, and is not guarded.
+ * holds, smoothing and the short hold, and before the hinge check. A reach's
+ * target is aimed later, from posed positions, and is neither held short nor
+ * guarded.
+ *
+ * Then the switches (rig-c/pose#6, `switch.ts`): with every target known —
+ * reaches included — each alternate set's distance to the pose is read, and the
+ * spans each set shows are chosen. Only then the range clamp: outside the spans
+ * of a set depicting its chain, a bone whose rotate key would leave its
+ * `range` is clamped at the limit (its target becomes the clamped world angle),
+ * in depth order, so a bone below takes the clamped parent into its own key
+ * and still follows the pose; a reach below is aimed again from where the
+ * clamped bones put its origin. Every overflow is listed as `range` demand.
+ * Inside a span nothing is clamped, but a bone with a `drawn` angle is read
+ * against it (`artTurn`, and `artRange` where it leaves its range).
+ *
+ * The lines across the body — hips, shoulders, eyes — are read from the pose
+ * after holds and smoothing, whether the map uses them or not: a line under
+ * `TURN_FRACTION` of its median picture length, or reversed (pointing more
+ * than 90° from the subject's right to left), for ≥ `TURN_SECONDS`, is a `TURN`:
+ * the body or head turned, a pose a flat rig cannot draw. It changes no key.
  *
  * What this cannot know is held to account afterwards: `verify.ts` poses the
  * gated build with rig-c's poser and measures where each bone landed.
@@ -35,14 +62,16 @@
 import { screenToSpineDegrees } from 'rig-c/transform';
 import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
-import type { Chain, JointMap, Rest } from './map.ts';
+import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
 import { aimAngle, rigPoint } from './map.ts';
 import type { Joint } from './pose.ts';
 import { Problems } from './problems.ts';
+import type { ArtRange, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import { coveredChains, measureArt, overflow, RANGE_SLACK, runsOf, selectSwitches } from './switch.ts';
 
 const DEG = 180 / Math.PI;
 
-export interface RetargetOptions {
+export interface RetargetOptions extends SwitchOptions {
   /** A joint with a score below this is not good on that frame (a joint with no score is). */
   minScore: number;
   /** Savitzky–Golay window over joint positions, in frames: 1 = none, else odd and ≥ 5. */
@@ -53,6 +82,8 @@ export interface RetargetOptions {
   bendTolerance: number;
   /** A segment turning more than this many degrees in one frame is spread (`spreadFlips`); 'off' keeps every turn. */
   flip: number | 'off';
+  /** A segment shorter in the picture than this fraction of its median length has its angle held there (`holdShort`); 'off' reads every frame. */
+  short: number | 'off';
 }
 
 export interface Hold {
@@ -97,9 +128,44 @@ export interface Flip {
   clipped: 'start' | 'end' | 'both' | null;
 }
 
+/** One span of frames under the short cutoff: the segment's angle there was interpolated, not read (`holdShort`). */
+export interface Short {
+  chain: string;
+  bone: string;
+  /** The segment the bone carries: from joint, to joint. */
+  joints: [string, string];
+  /** First and last frame under the cutoff; every one of them had its angle replaced, and the frames either side keep the input's. */
+  frames: [number, number];
+  /** The lowest picture length on those frames, as a fraction of the segment's median picture length. */
+  minFraction: number;
+}
+
+/**
+ * A segment under the short cutoff long enough to be a pose (the limb pointing
+ * at the camera), not a blur: short spans merged across a gap of `END_ON_GAP`
+ * frame, lasting ≥ `END_ON_SECONDS`. The demand for an alternate drawing (#6).
+ */
+export interface EndOn {
+  chain: string;
+  bone: string;
+  joints: [string, string];
+  /** First and last frame of the merged run (a gap frame inside it is at or above the cutoff). */
+  frames: [number, number];
+  /** How long it lasts: from the first frame's key time to the end of the last frame (the next frame's key time; for the pose's last frame, one frame on). */
+  seconds: number;
+  minFraction: number;
+}
+
+/** A run under the short cutoff lasting at least this long, in seconds, is listed as `endOn` (rig-c/pose#22). */
+export const END_ON_SECONDS = 0.15;
+/** Short spans this many frames apart or fewer merge into one `endOn` run. */
+export const END_ON_GAP = 1;
+
 export interface MotionKey {
   t: number;
   v: number[];
+  /** `stepped`: the value holds until the next key (the offsets' translate keys). */
+  ease?: 'stepped';
 }
 export interface MotionTrack {
   bone: string;
@@ -108,9 +174,51 @@ export interface MotionTrack {
 }
 export interface Animation {
   duration: number;
-  tracks: MotionTrack[];
+  /** The bone tracks, then any slot `attachment` tracks the switches add (`switch.ts`). */
+  tracks: Array<MotionTrack | SlotTrack>;
+}
+
+/** A line across the body turned: short in the picture, or reversed, long enough to be a pose (the demand for a turned-body drawing). */
+export interface Turn {
+  /** `hip`, `shoulder` or `eye`. */
+  line: string;
+  /** The subject's right joint, then its left twin. */
+  joints: [string, string];
+  /** First and last frame of the run (merged across a gap of `TURN_GAP` frame). */
+  frames: [number, number];
+  seconds: number;
+  /** The lowest picture length on the run's turned frames, as a fraction of the line's median. */
+  minFraction: number;
+  /** Whether the line points from the right joint to the left more than 90° off the subject's right-to-left on any frame of the run. */
+  reversed: boolean;
 }
 
+/** A bone's rotate key past its range outside every span of a set depicting its chain: clamped there, and the demand for an alternate. */
+export interface RangeDemand {
+  chain: string;
+  bone: string;
+  /** First and last frame of the run (merged across a gap of one frame; a gap frame inside is within range or inside a span). */
+  frames: [number, number];
+  seconds: number;
+  /** Degrees past the range, the most on any frame of the run. */
+  maxOverflow: number;
+  /** The rotate key the pose asked for on that frame, degrees relative to setup, before the clamp. */
+  key: number;
+  /** The bone's range, degrees. */
+  limits: [number, number];
+}
+
+/** The lines across the body a `TURN` is read on: the subject's right joint, then its left twin. */
+export const TURN_LINES: ReadonlyArray<[string, string, string]> = [['hip', 'r_hip', 'l_hip'], ['shoulder', 'r_shoulder', 'l_shoulder'], ['eye', 'r_eye', 'l_eye']];
+/** A line shorter in the picture than this fraction of its median is turned (rig-c/pose#6: between the front-facing dance's floor, 0.81, and a side-on body's 0.17–0.49). */
+export const TURN_FRACTION = 0.5;
+/** A turned run lasting at least this long, in seconds, is listed (as `endOn`). */
+export const TURN_SECONDS = 0.15;
+/** Turned spans this many frames apart or fewer merge into one run. */
+export const TURN_GAP = 1;
+/** Range overflow and art-range spans this many frames apart or fewer merge into one run. */
+export const RANGE_GAP = 1;
+
 export interface Retarget {
   animation: Animation;
   /** Key times, seconds from the first frame, as written. */
@@ -121,9 +229,27 @@ export interface Retarget {
   origin: { bone: string; at: Array<[number, number]> } | null;
   holds: Hold[];
   bends: BendEvent[];
+  /** The short hold's spans, per segment in map order. */
+  short: Short[];
+  /** The short runs long enough to be a pose seen end-on. */
+  endOn: EndOn[];
   flips: Flip[];
   /** The figure scale, rig units per picture pixel, and the lengths it came from. */
   scale: { factor: number; pose: number; rig: number } | null;
+  /** The spans each alternate set shows, with their art turn. */
+  switches: Switch[];
+  /** Per switched or hidden slot, what it shows on each frame (null: nothing). */
+  shown: Map<string, Array<string | null>>;
+  /** Per set, its distance to the pose on each frame, degrees. */
+  distances: Map<string, number[]>;
+  /** The lines across the body turned long enough to be a pose. */
+  turns: Turn[];
+  /** The lines across the body that could not be read, and why. */
+  turnsUnread: Array<{ line: string; joints: [string, string]; why: string }>;
+  /** Every run a bone's key was clamped at its range. */
+  range: RangeDemand[];
+  /** Every run a bone inside a span turned from its drawn angle past its range. */
+  artRange: ArtRange[];
 }
 
 type Pt = [number, number];
@@ -237,7 +363,7 @@ const r3 = (v: number) => {
  * 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): Retarget {
+export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, times: readonly number[], opts: RetargetOptions, slots: RigSlots = new Map()): Retarget {
   const p = new Problems();
   const n = frames.length;
   const t0 = times[0]!;
@@ -245,6 +371,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   for (let i = 1; i < n; i++) {
     if (keyTimes[i]! <= keyTimes[i - 1]!) p.add('POSE_TIME', `frames ${i - 1} and ${i} are ${keyTimes[i - 1]}s and ${keyTimes[i]}s after rounding to the microsecond; keys must strictly increase`);
   }
+  /** The end of frame i: the next frame's key time; the last frame lasts as long as the one before it. */
+  const endOf = (i: number): number => (i + 1 < n ? keyTimes[i + 1]! : n > 1 ? 2 * keyTimes[i]! - keyTimes[i - 1]! : keyTimes[i]!);
+  const secondsOf = (run: [number, number]): number => Math.round((endOf(run[1]) - keyTimes[run[0]]!) * 1e6) / 1e6;
 
   // Every point the map reads, held where it is not good.
   const needed = new Set<string>();
@@ -256,15 +385,13 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   const series = new Map<string, Pt[]>();
   const good = new Map<string, boolean[]>();
   const holds: Hold[] = [];
-  for (const name of [...needed].sort()) {
+  /** A point held where it is not good, then smoothed; or why it is good on no frame. */
+  const heldOf = (name: string): { at: Pt[]; good: boolean[]; holds: Hold[] } | { never: string } => {
     const raw = frames.map((f) => pointOn(f, name, opts.minScore));
     const firstGood = raw.findIndex((v) => typeof v !== 'string');
-    if (firstGood < 0) {
-      const why = [...new Set(raw as string[])].slice(0, 3).join('; ');
-      p.add('POSE_POINT_NEVER_GOOD', `point "${name}" is good on none of the ${n} frames (${why}); the map needs it, and there is no value to hold`);
-      continue;
-    }
+    if (firstGood < 0) return { never: [...new Set(raw as string[])].slice(0, 3).join('; ') };
     const out: Pt[] = [];
+    const spans: Hold[] = [];
     let last = firstGood;
     let span: Hold | null = null;
     for (let i = 0; i < n; i++) {
@@ -279,14 +406,66 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       if (span !== null && span.source === last && span.why === v) span.to = i;
       else {
         span = { point: name, from: i, to: i, source: last, why: v };
-        holds.push(span);
+        spans.push(span);
       }
     }
-    series.set(name, savitzkyGolay(out, opts.smooth));
-    good.set(name, raw.map((v) => typeof v !== 'string'));
+    return { at: savitzkyGolay(out, opts.smooth), good: raw.map((v) => typeof v !== 'string'), holds: spans };
+  };
+  for (const name of [...needed].sort()) {
+    const h = heldOf(name);
+    if ('never' in h) {
+      p.add('POSE_POINT_NEVER_GOOD', `point "${name}" is good on none of the ${n} frames (${h.never}); the map needs it, and there is no value to hold`);
+      continue;
+    }
+    holds.push(...h.holds);
+    series.set(name, h.at);
+    good.set(name, h.good);
   }
   p.throwIfAny();
 
+  // TURN: the lines across the body, read from the pose (held and smoothed as the
+  // map's points are, whether or not the map uses them). A reading; no key moves.
+  const turns: Turn[] = [];
+  const turnsUnread: Retarget['turnsUnread'] = [];
+  for (const [line, a, b] of TURN_LINES) {
+    const ends: Pt[][] = [];
+    for (const j of [a, b]) {
+      const known = series.get(j);
+      if (known !== undefined) ends.push(known);
+      else {
+        const h = heldOf(j);
+        if ('never' in h) {
+          turnsUnread.push({ line, joints: [a, b], why: `${j} is good on none of the ${n} frames (${h.never})` });
+          break;
+        }
+        ends.push(h.at);
+      }
+    }
+    if (ends.length < 2) continue;
+    const [A, B] = ends as [Pt[], Pt[]];
+    const lengths = A.map((f, i) => Math.hypot(B[i]![0] - f[0], B[i]![1] - f[1]));
+    const med = median(lengths);
+    if (med < 1e-6) {
+      turnsUnread.push({ line, joints: [a, b], why: `its median picture length is ${med}px; a fraction of it is not a measure` });
+      continue;
+    }
+    const fraction = lengths.map((l) => l / med);
+    const reversed = A.map((f, i) => lengths[i]! > 1e-9 && Math.abs(pictureAngle(f, B[i]!)) > 90);
+    const turned = fraction.map((f, i) => f < TURN_FRACTION || reversed[i]!);
+    for (const run of runsOf(turned, TURN_GAP)) {
+      const seconds = secondsOf(run);
+      if (seconds < TURN_SECONDS - 1e-9) continue;
+      let minFraction = Infinity;
+      let rev = false;
+      for (let i = run[0]; i <= run[1]; i++) {
+        if (!turned[i]) continue;
+        minFraction = Math.min(minFraction, fraction[i]!);
+        rev ||= reversed[i]!;
+      }
+      turns.push({ line, joints: [a, b], frames: run, seconds, minFraction, reversed: rev });
+    }
+  }
+
   // The hip: the travel of one point, scaled, in its parent's axes. It comes
   // first, because a reach is aimed from where the hip has put its bone.
   let origin: Retarget['origin'] = null;
@@ -358,6 +537,39 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   }
   p.throwIfAny();
 
+  // The short hold, on every limb segment the pose aims directly (not a reach, and
+  // not a line across the body from a left joint to its right twin — the hip line,
+  // the eye line — whose shortening is the body or head turning, not a limb seen
+  // end-on; #22's cutoff was measured on limb segments only): its picture length
+  // against its own median, on the points the angle was read from.
+  const short: Short[] = [];
+  const endOn: EndOn[] = [];
+  if (opts.short !== 'off') {
+    const cutoff = opts.short;
+    for (const c of map.chains) {
+      if (c.reach) continue;
+      c.bones.forEach((b, k) => {
+        const joints: [string, string] = [c.joints[k]!, c.joints[k + 1]!];
+        if (isAcross(joints[0], joints[1])) return;
+        const from = series.get(joints[0])!;
+        const to = series.get(joints[1])!;
+        const lengths = from.map((f, i) => Math.hypot(to[i]![0] - f[0], to[i]![1] - f[1]));
+        const med = median(lengths);
+        if (med < 1e-6) {
+          p.add('POSE_SHORT_MEDIAN', `chain "${c.name}" — bone "${b}"'s segment ${joints[0]} → ${joints[1]} has median picture length ${med}px over the ${n} frames; --short measures a frame's length against that median, and there is none to measure against`);
+          return;
+        }
+        const spans = holdShort(targets.get(b)!, lengths.map((l) => l / med), cutoff);
+        for (const s of spans) short.push({ chain: c.name, bone: b, joints, ...s });
+        for (const run of mergeRuns(spans, END_ON_GAP)) {
+          const seconds = Math.round((endOf(run.frames[1]) - keyTimes[run.frames[0]]!) * 1e6) / 1e6;
+          if (seconds >= END_ON_SECONDS - 1e-9) endOn.push({ chain: c.name, bone: b, joints, frames: run.frames, seconds, minFraction: run.minFraction });
+        }
+      });
+    }
+  }
+  p.throwIfAny();
+
   // The flip guard, on every segment the pose aims directly (not a reach).
   const flips: Flip[] = [];
   if (opts.flip !== 'off') {
@@ -390,6 +602,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     return d;
   };
   const reaches = map.chains.filter((c) => c.reach).sort((x, y) => depth(x.bones[0]!) - depth(y.bones[0]!));
+  let aimReach: ((c: Chain) => void) | null = null;
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
@@ -411,7 +624,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const oy = rest.get(b)!.worldY - rest.get(parent)!.worldY;
       return [po[0] + Math.cos(r) * ox - Math.sin(r) * oy, po[1] + Math.sin(r) * ox + Math.cos(r) * oy];
     };
-    for (const c of reaches) {
+    aimReach = (c: Chain): void => {
       const b = c.bones[0]!;
       const anchor = series.get(c.joints[0]!)!;
       const end = series.get(c.joints[1]!)!;
@@ -425,20 +638,56 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       }
       fillLeading(angles, () => p.add('POSE_SEGMENT_ZERO', `chain "${c.name}" — bone "${b}" reaches for ${c.joints[1]}, which the pose puts on the bone's posed origin on every frame; it has no direction`));
       targets.set(b, angles);
-    }
+    };
+    for (const c of reaches) aimReach(c);
   }
   p.throwIfAny();
 
-  // Keys: the bone's turn less the turn of the nearest mapped bone above it.
+  // The switches: with every target known, each set's distance and its spans.
+  const sw = selectSwitches(map, targets, keyTimes, keyTimes[n - 1]!, slots, opts);
+
+  // 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
+  // again from where the clamped bones above put its origin.
   const mappedAbove = (b: string): string | null => {
     for (let a = rest.get(b)!.parent; a !== null; a = rest.get(a)!.parent) if (targets.has(a)) return a;
     return null;
   };
-  const tracks: MotionTrack[] = [];
+  const turn = (bone: string, i: number) => targets.get(bone)![i]! - restOf.get(bone)!;
+  const covered = coveredChains(sw.switches, n);
+  const range: RangeDemand[] = [];
+  const order = map.chains.flatMap((c) => c.bones.map((b) => ({ c, b }))).filter(({ c, b }) => c.reach || b in c.range);
+  order.sort((x, y) => depth(x.b) - depth(y.b));
+  for (const { c, b } of order) {
+    if (c.reach && aimReach !== null) aimReach(c);
+    const limits = c.range[b];
+    if (limits === undefined) continue;
+    const above = mappedAbove(b);
+    const tg = targets.get(b)!;
+    const cov = covered.get(c.name);
+    const over: number[] = [];
+    const asked: number[] = [];
+    for (let i = 0; i < n; i++) {
+      const key = wrap(turn(b, i) - (above === null ? 0 : turn(above, i)));
+      asked.push(key);
+      const o = cov?.[i] === true ? 0 : overflow(key, limits);
+      over.push(o);
+      if (o > RANGE_SLACK) tg[i] = wrap(tg[i]! + Math.min(Math.max(key, limits[0]), limits[1]) - key);
+    }
+    for (const run of runsOf(over.map((o) => o > RANGE_SLACK), RANGE_GAP)) {
+      let worst = run[0];
+      for (let i = run[0]; i <= run[1]; i++) if (over[i]! > over[worst]!) worst = i;
+      range.push({ chain: c.name, bone: b, frames: run, seconds: secondsOf(run), maxOverflow: r3(over[worst]!), key: r3(asked[worst]!), limits });
+    }
+  }
+  p.throwIfAny();
+  const artRange = measureArt(sw.switches, map, targets, endOf, keyTimes, RANGE_GAP);
+
+  // Keys: the bone's turn less the turn of the nearest mapped bone above it.
+  const tracks: Array<MotionTrack | SlotTrack> = [];
   for (const c of map.chains) {
     for (const b of c.bones) {
       const above = mappedAbove(b);
-      const turn = (bone: string, i: number) => targets.get(bone)![i]! - restOf.get(bone)!;
       let prev = 0;
       const keys: MotionKey[] = [];
       for (let i = 0; i < n; i++) {
@@ -451,8 +700,94 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     }
   }
   if (translateTrack !== null) tracks.push(translateTrack);
+  tracks.push(...sw.offsetTracks, ...sw.slotTracks);
+
+  return {
+    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,
+  };
+}
+
+type ShortSpan = Omit<Short, 'chain' | 'bone' | 'joints'>;
+
+/**
+ * The short hold on one angle series (degrees), in place. `fraction` is the
+ * segment's picture length on each frame over its median. Each run of frames
+ * under `cutoff` has its angles replaced by the line from the last frame before
+ * it at or above the cutoff to the first one after it, the short way round; a
+ * run at the start or the end of the series holds the one reliable end flat.
+ * With the fraction against the median and a cutoff under 1, half the frames
+ * at least are at or above it, so every run has a reliable end. Returns the runs.
+ */
+/** A line across the body: a left joint and its right twin (r_hip → l_hip, r_eye → l_eye). */
+export function isAcross(a: string, b: string): boolean {
+  const twin = (x: string): string | null => (x.startsWith('r_') ? `l_${x.slice(2)}` : x.startsWith('l_') ? `r_${x.slice(2)}` : null);
+  return twin(a) === b;
+}
+
+export function holdShort(angles: number[], fraction: readonly number[], cutoff: number): ShortSpan[] {
+  const n = angles.length;
+  const out: ShortSpan[] = [];
+  for (let i = 0; i < n; i++) {
+    if (!(fraction[i]! < cutoff)) continue;
+    let j = i;
+    while (j + 1 < n && fraction[j + 1]! < cutoff) j++;
+    const lo = i - 1;
+    const hi = j + 1;
+    let minFraction = fraction[i]!;
+    for (let k = i + 1; k <= j; k++) minFraction = Math.min(minFraction, fraction[k]!);
+    if (lo >= 0 || hi < n) {
+      const a = lo >= 0 ? angles[lo]! : angles[hi]!;
+      const b = hi < n ? angles[hi]! : a;
+      const turn = wrap(b - a);
+      for (let k = i; k <= j; k++) angles[k] = lo < 0 ? b : wrap(a + (turn * (k - lo)) / (hi - lo));
+    }
+    out.push({ frames: [i, j], minFraction });
+    i = j;
+  }
+  return out;
+}
+
+/** Short spans `gap` frames apart or fewer, as one run each: its first and last frame, and the lowest fraction. */
+export function mergeRuns(spans: readonly ShortSpan[], gap: number): ShortSpan[] {
+  const out: ShortSpan[] = [];
+  for (const s of spans) {
+    const last = out[out.length - 1];
+    if (last !== undefined && s.frames[0] - last.frames[1] - 1 <= gap) {
+      last.frames = [last.frames[0], s.frames[1]];
+      last.minFraction = Math.min(last.minFraction, s.minFraction);
+    } else out.push({ frames: [s.frames[0], s.frames[1]], minFraction: s.minFraction });
+  }
+  return out;
+}
+
+const spanOf = (frames: [number, number], times: readonly number[]): string =>
+  frames[0] === frames[1] ? `frame ${frames[0]} (t=${times[frames[0]]!.toFixed(3)}s)` : `frames ${frames[0]}–${frames[1]} (t=${times[frames[0]]!.toFixed(3)}–${times[frames[1]]!.toFixed(3)}s)`;
+
+export function shortLine(s: Short, times: readonly number[], cutoff: number): string {
+  const lo = s.frames[0] - 1;
+  const hi = s.frames[1] + 1;
+  const held = lo < 0 && hi >= times.length
+    ? 'no frame of the pose is at or above it, so nothing was held'
+    : lo < 0 ? `held flat at frame ${hi}'s angle (the pose starts short)`
+      : hi >= times.length ? `held flat at frame ${lo}'s angle (the pose ends short)`
+        : `interpolated from frame ${lo}'s angle to frame ${hi}'s, the short way round`;
+  return `chain "${s.chain}" bone "${s.bone}" (${s.joints[0]} → ${s.joints[1]}) ${spanOf(s.frames, times)}: picture length down to ${s.minFraction.toFixed(2)} of its median, under ${cutoff}; its direction is not read — ${held}`;
+}
+
+export function turnLine(e: Turn, times: readonly number[]): string {
+  const how = e.reversed ? `reversed (pointing more than 90° from ${e.joints[0]} → ${e.joints[1]}'s own way), picture length down to ${e.minFraction.toFixed(2)} of its median` : `picture length down to ${e.minFraction.toFixed(2)} of its median, under ${TURN_FRACTION}`;
+  return `line "${e.line}" (${e.joints[0]} → ${e.joints[1]}) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s ${how}, ≥ ${TURN_SECONDS}s — the body or head turned, a pose the rig cannot draw`;
+}
+
+export function rangeLine(e: RangeDemand, times: readonly number[]): string {
+  const sg = (v: number) => `${v >= 0 ? '+' : '−'}${Math.abs(v).toFixed(1)}°`;
+  return `chain "${e.chain}" bone "${e.bone}" ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s the pose asks its rotate key past its range [${e.limits[0]}, ${e.limits[1]}] (${sg(e.key)}, up to ${e.maxOverflow.toFixed(1)}° past); clamped at the limit — demand for an alternate`;
+}
 
-  return { animation: { duration: keyTimes[n - 1]!, tracks }, times: keyTimes, targets, origin, holds, bends, flips, scale };
+export function endOnLine(e: EndOn, times: readonly number[], cutoff: number): string {
+  return `chain "${e.chain}" bone "${e.bone}" (${e.joints[0]} → ${e.joints[1]}) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s under ${cutoff} of its median picture length (down to ${e.minFraction.toFixed(2)}), ≥ ${END_ON_SECONDS}s — seen end-on, a pose the rig cannot draw`;
 }
 
 type Spread = Omit<Flip, 'chain' | 'bone' | 'joints'>;

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 { Rest, RestBone } from './map.ts';
+import type { Rest, RestBone, RigSlot, RigSlots } from './map.ts';
 import { isObject, parseJson, Problems, Refusal, typeName } from './problems.ts';
 
 export interface RigInput {
@@ -137,6 +137,41 @@ export function restOf(doc: CompiledDocument): Rest {
   return out;
 }
 
+/** Every slot of the build: what it shows at setup, as the compiled model states it, and every attachment any skin gives it. */
+export function slotsOf(doc: CompiledDocument): RigSlots {
+  const out = new Map<string, RigSlot>();
+  for (const s of doc.slots) {
+    const attachments = new Set<string>();
+    for (const k of doc.skins) for (const name of Object.keys(k.attachments[s.name] ?? {})) attachments.add(name);
+    out.set(s.name, { setup: s.setup, attachments });
+  }
+  return out;
+}
+
+/**
+ * The bones that move an attachment: a weighted mesh's bindings (a linked mesh
+ * its source's), or the slot's bone for anything else — what an uncovered fold
+ * names its chains by.
+ */
+export function attachmentBones(doc: CompiledDocument, slot: string, attachment: string): string[] {
+  const slotBone = doc.slots.find((s) => s.name === slot)?.bone;
+  const find = (sl: string, name: string) => {
+    for (const k of doc.skins) {
+      const g = k.attachments[sl]?.[name]?.geometry;
+      if (g !== undefined) return g;
+    }
+    return undefined;
+  };
+  let g = find(slot, attachment);
+  if (g?.kind === 'linkedmesh') g = find(g.slot, g.source);
+  if (g !== undefined && 'vertices' in g && g.vertices.weighted) {
+    const bones = new Set<string>();
+    for (const v of g.vertices.bindings) for (const b of v) bones.add(b.bone);
+    return [...bones];
+  }
+  return slotBone === undefined ? [] : [slotBone];
+}
+
 export interface MeshFolds {
   slot: string;
   attachment: string;

package/src/run.ts

@@ -1,7 +1,8 @@
 /**
- * `rig-pose retarget`, end to end: read, gate the rig as it is, retarget, gate
- * it with the animation in, measure where the rig landed, read the folds, and
- * write — only when every check passed.
+ * `rig-pose retarget`, end to end: read, gate the rig as it is, retarget (the
+ * switches and the range clamp included), gate it with the animation in,
+ * measure where the rig landed, read the folds (and which no switch covers),
+ * and write — only when every check passed.
  */
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -9,8 +10,9 @@ import { dirname, join, resolve } from 'node:path';
 import { readMap, resolveMap } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.ts';
 import { lineOf, Problems, Refusal, type Problem } from './problems.ts';
-import { bendLine, flipLine, holdLine, retarget, type RetargetOptions } from './retarget.ts';
-import { baseMotionOf, buildInto, folds, gate, readBuild, resolveRig, restOf } from './rigc.ts';
+import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type RetargetOptions } from './retarget.ts';
+import { attachmentBones, baseMotionOf, buildInto, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
+import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
 import { landed, measureLanding, measurePosture, poseFrames, postureLines, ANGLE_TOLERANCE, ORIGIN_TOLERANCE } from './verify.ts';
 
 export interface RetargetArgs extends RetargetOptions {
@@ -74,15 +76,29 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (!g0.green) {
       refuse([{ code: 'RIG_GATE_BASE', text: `${input.rig} with ${input.motion ?? 'no motion spec'} is red under rigc build --profile ${a.profile} before any animation is added (exit ${g0.run.status})` }, ...g0.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
-    const rest = restOf(readBuild(g0.build));
-    resolveMap(map, rest, a.map);
+    const doc0 = readBuild(g0.build);
+    const rest = restOf(doc0);
+    const slots = slotsOf(doc0);
+    resolveMap(map, rest, a.map, slots);
 
-    const r = retarget(rest, map, frames, times, a);
-    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}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, bends ${a.bends} (tolerance ${a.bendTolerance}°)`);
+    const r = retarget(rest, map, frames, times, a, slots);
+    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}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)`);
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
+    if (a.short !== 'off') {
+      for (const s of r.short) say(`  SHORT  ${shortLine(s, r.times, a.short)}`);
+      for (const e of r.endOn) say(`  END-ON ${endOnLine(e, r.times, a.short)}`);
+    }
     if (a.flip !== 'off') for (const fl of r.flips) say(`  FLIP   ${flipLine(fl, r.times, a.flip)}`);
     for (const e of r.bends) say(`  BEND   ${bendLine(e)} — clamped straight`);
+    for (const e of r.turns) say(`  TURN   ${turnLine(e, r.times)}`);
+    for (const u of r.turnsUnread) say(`  TURN   line "${u.line}" (${u.joints[0]} → ${u.joints[1]}) not measured: ${u.why}`);
+    if (map.alternates.length > 0) {
+      if (r.switches.length === 0) say(`  SWITCH none — no set within ${a.switchTolerance}° of the pose for ${a.switchMin}s`);
+      for (const s of r.switches) say(`  SWITCH ${switchLine(s, r.times)}`);
+    }
+    for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
+    for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
 
     const motion = { ...base, animations: { ...animations, [a.name]: r.animation } };
     const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile);
@@ -115,6 +131,10 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     else if (f.meshes === null) say(`  FOLD   rigc render --folds did not read (exit ${f.run.status}); folds not measured`);
     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) {
+      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)}`);
+    }
 
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
@@ -134,15 +154,22 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         animation: a.name,
         frames: seq.frames.length,
         duration: r.animation.duration,
-        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, bends: a.bends, bendTolerance: a.bendTolerance, profile: a.profile },
+        options: { minScore: a.minScore, smooth: a.smooth, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, profile: a.profile },
         scale: r.scale,
         holds: r.holds,
+        short: r.short,
+        endOn: r.endOn,
         bends: r.bends,
         flips: r.flips,
         gate: g1.summary,
         landings,
         posture,
         folds: f.meshes,
+        switches: r.switches,
+        uncovered,
+        turns: r.turns,
+        range: r.range,
+        artRange: r.artRange,
       }, null, 2)}\n`);
     }
     say(`  wrote ${a.out} — animations: ${Object.keys(motion.animations).join(', ')}`);