@rig-c/pose 0.39.0 → 0.41.0

package/src/run.ts

@@ -11,13 +11,14 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { knownSetsOf, readMap, resolveMap, type JointMap, type Rest } from './map.ts';
 import { cleanLine, cleanSummaryLine, inferredSource } from './clean.ts';
 import { depthLine, layersOf, type FrameLayers } from './depth.ts';
+import { drawGapLines, drawOrderFromDepth, drawOrderKeys, drawOrderLines, type DrawOrderReading } from './draworder.ts';
 import { convertCoco17, personTrack, readPoseSequence, TRAVEL_IN_PLACE, type CameraFrame } from './pose.ts';
 import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './problems.ts';
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
-import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, pelvisLine, rangeLine, reachCostLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
+import { bendGroupLine, bendGroups, bendLine, endOnLine, flipLine, holdLine, nodLine, pelvisLine, rangeLine, reachCostLine, reachOriginLine, reachOriginWarn, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions, type ScaleBand, type ScaleFit } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, seamRender, slotsOf } from './rigc.ts';
 import { partsPath, projectSeams, readSeamDoc, readSeamPairs, seamLines, type SeamPair } from './seams.ts';
-import { artRangeLine, chainsMoving, phaseLines, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
+import { artRangeLine, chainsMoving, phaseLines, raisedLine, RAISED_WITHIN, reachLine, switchLine, switchMinLines, uncoveredFolds } from './switch.ts';
 import { jitterLine, landed, type FeetReading, type JitterRow, type Landing, measureFeet, measureJitter, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { FRONTAL_DISAGREE, 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';
@@ -64,6 +65,8 @@ export interface RetargetArgs extends RetargetOptions {
   merge?: string;
   /** Thin the mapped bones' rotate keys within this many degrees (#32). */
   reduce?: number;
+  /** With reduce: a map chain's own tolerance in degrees, by chain name, in place of `reduce` on its bones (#283). */
+  reduceChains?: Record<string, number>;
   /** With reduce: thin the hip's translate keys within this many rig units. */
   reduceHip?: number;
   /** With reduce and plantFeet: keep each support span's frames on the supporting leg at its dense keys (#251). */
@@ -76,6 +79,8 @@ export interface RetargetArgs extends RetargetOptions {
    * same in all three and the gate is the same gate.
    */
   output?: 'default' | 'verbose' | 'summary';
+  /** `--draw-order depth` (rig-c/pose#304): key the animation's draw order from the sequence's depth. Absent: no draw-order key, the output as before. */
+  drawOrder?: 'depth';
 }
 
 export interface RunResult {
@@ -128,9 +133,13 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const fragment = a.merge === undefined ? [] : readFragment(parseJson(readFileSync(a.merge, 'utf8'), a.merge, 'MERGE_JSON'), a.merge);
   const mapSnapshot = readReportInput(a.map), poseSnapshot = readReportInput(a.pose);
   const map = readMap(mapSnapshot.bytes.toString('utf8'), a.map);
+  // #283: each chain --reduce names must be the map's; a bone takes its chain's tolerance (the tighter, if two chains name it).
+  let reduceOf = a.reduce === undefined ? null : reduceTolerances(map, a.reduce, a.reduceChains, a.map);
   const poseText = poseSnapshot.bytes.toString('utf8');
   const seq = a.coco ? convertCoco17(poseText, a.pose) : readPoseSequence(poseText, a.pose);
   if (seq.cleaned === undefined) refuse([{ code: 'POSE_NOT_CLEANED', text: notCleaned(a.pose, a.coco) }]);
+  // #304: the draw order is read off the sequence's depth; asked for on a sequence without it, refused by name.
+  if (a.drawOrder === 'depth' && !seq.frames.some((x) => x.depth !== undefined)) refuse([{ code: 'DRAWORDER_NO_DEPTH', text: `--draw-order depth keys the draw order from the sequence's depth, and ${a.pose} carries none (rig-pose-sequence/${seq.cleaned!.params.depth === undefined ? '1 or 1.1, no "depth" on any frame' : '1.2 with no frame naming a segment'}); clean it with --depth walk|run, or retarget without --draw-order` }]);
   const frames = personTrack(seq, a.person, a.pose);
   const times = seq.frames.map((f) => f.t);
 
@@ -164,7 +173,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         }
       }
     }
-    tell(`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)` : ''}${a.reduceKeepPlanted === true ? ', planted legs kept dense' : ''}` : ''}`);
+    tell(`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}°${chainsText(a.reduceChains)}${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}${a.reduceKeepPlanted === true ? ', planted legs kept dense' : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     // #250: the gate was green without it, so nothing else would say the rig's own animations are not in --out.
     const unread = unreadMotionLine(a.rig, input.motion);
@@ -191,6 +200,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     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)}`);
+      // #279: only for a set the minimum span held back, so a run where nothing was suppressed prints what it always has.
+      for (const l of switchMinLines(r.switchRuns, a.switchMin)) say(`  SWITCH-MIN ${l}`);
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
       for (const l of phaseLines(map, r.switches)) say(`  PHASE  ${l}`);
     }
@@ -202,6 +213,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     for (const e of r.byHip) say(`  BY-HIP ${raisedLine(e, r.times)}`);
     for (const e of r.byHip) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.reach) say(`  REACH  ${reachCostLine(e, r.times)}`);
+    // rig-c/pose#282: each reach chain's origin against its source joint; a map without one prints none.
+    for (const e of r.reachOrigin) {
+      say(`  REACH-ORIGIN ${reachOriginLine(e, r.times)}`);
+      if (e.warn) say(`  WARN   ${reachOriginWarn(e)}`);
+    }
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
     // #287: a range that clamps no frame says so once, on the last segment's line (the line count stays one per segment).
     const noClamp = legScaleNoClamp(r.legScale);
@@ -211,6 +227,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     // rig-c/pose#281: the limbs' front-to-back order from the sequence's depth, only when it carries depth.
     const layers: FrameLayers[] | null = seq.frames.some((x) => x.depth !== undefined) ? frames.map((j, i) => layersOf(j, seq.frames[i]!.depth ?? {})) : null;
     if (layers !== null) say(`  ${depthLine(layers, seq.frames, seq.cleaned!.params.depth?.gait ?? null)}`);
+    // rig-c/pose#304: with --draw-order depth, the legs' draw order keyed from those layers.
+    const drawOrder: DrawOrderReading | null = a.drawOrder === 'depth' && layers !== null ? drawOrderFromDepth(layers, frames, seq.frames.map((x) => x.depth), r.times, map, rest, doc0.slots, input.sets, seq.cleaned!.params.loop) : null;
+    if (drawOrder !== null) for (const l of [...drawOrderLines(drawOrder), ...drawGapLines(drawOrder)]) say(`  ${l}`);
     if (r.pivot !== null) say(`  PIVOT  bone "${r.pivot.bone}"'s origin is ${r.pivot.distance.toFixed(2)} units (${r.pivot.hipWidths.toFixed(3)} hip widths) from its thigh roots' midpoint (${r.pivot.roots.join(' + ')}): dx ${r.pivot.offset[0].toFixed(2)}, dy ${r.pivot.offset[1].toFixed(2)}, at setup — the pivot every hip turn swings the legs about`);
     if (r.feet !== null) {
       const f = r.feet;
@@ -237,16 +256,26 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (r.face !== null) say(`  FACE   ${faceLine(r.face)}`);
     if (r.body !== null) say(`  BODY   ${bodyLine(r.body)}`);
 
+    // #320: a mapped bone above a planted or aimed chain --reduce names is held to that chain's tolerance when its own is looser.
+    const held = reduceOf === null || a.reduceChains === undefined ? [] : holdParents(map, rest, new Set(r.targets.keys()), a.reduceChains, reduceOf, r.ankles === null ? [] : [r.ankles.bones.r, r.ankles.bones.l]);
+    if (held.length > 0) {
+      const first = reduceOf!;
+      reduceOf = (bone) => held.find((h) => h.bone === bone)?.to ?? first(bone);
+      for (const h of held) say(`  REDUCE ${heldLine(h)}`);
+    }
     // --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, a.reduceKeepPlanted === true);
+    const reduced = a.reduce === undefined ? null : a.reduceChains === undefined ? reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true) : reduceTracks(r, map, rest, a.reduce, a.reduceHip, a.reduceKeepPlanted === true, reduceOf!);
     if (reduced !== null) {
       for (const row of reduced.rows) {
         const [who, track, what, unit] = row.kind === 'angle' ? ['bone', 'rotate', 'aim', '°'] : row.kind === 'origin' ? ['hip', 'translate', 'origin', ' units'] : ['bone', 'scalex', 'scale', ' of its setup length'];
-        say(`  REDUCE ${who} "${row.bone}" ${track}: ${row.before} → ${row.after} key(s); worst ${what} error ${row.worst.toPrecision(3)}${unit} at frame ${row.frame} (t=${r.times[row.frame]!.toFixed(3)}s)`);
+        const hold = held.find((h) => h.bone === row.bone && row.kind === 'angle');
+        const own = row.kind === 'angle' && reduceOf!(row.bone) !== a.reduce ? (hold === undefined ? ` — within its chain's ${reduceOf!(row.bone)}°` : ` — held to ${hold.to}° for ${hold.for.map((c) => `chain "${c.chain}"`).join(', ')} below it`) : '';
+        say(`  REDUCE ${who} "${row.bone}" ${track}: ${row.before} → ${row.after} key(s); worst ${what} error ${row.worst.toPrecision(3)}${unit} at frame ${row.frame} (t=${r.times[row.frame]!.toFixed(3)}s)${own}`);
       }
+      for (const u of reduced.unsmoothed ?? []) say(`  REDUCE ${unsmoothedLine(u)}`);
       const sum = (kind: ReduceRow['kind'], k: 'before' | 'after') => reduced.rows.filter((x) => x.kind === kind).reduce((t, x) => t + x[k], 0);
       const scales = reduced.rows.some((x) => x.kind === 'scale') ? `; scalex keys ${sum('scale', 'before')} → ${sum('scale', 'after')} within ${SCALE_REDUCE} of the setup length` : '';
-      say(`  REDUCE rotate keys ${sum('angle', 'before')} → ${sum('angle', 'after')} (${(sum('angle', 'before') / sum('angle', 'after')).toFixed(2)}×) within ${a.reduce}°${scales}${a.reduceHip === undefined ? '; the hip stays dense (no --reduce-hip)' : ''}`);
+      say(`  REDUCE rotate keys ${sum('angle', 'before')} → ${sum('angle', 'after')} (${(sum('angle', 'before') / sum('angle', 'after')).toFixed(2)}×) within ${a.reduce}°${chainsText(a.reduceChains)}${scales}${a.reduceHip === undefined ? '; the hip stays dense (no --reduce-hip)' : ''}`);
     }
 
     // The idle against the new animation (#43 item 2): what it drops, and with --carry-idle, looped back in.
@@ -295,7 +324,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const tr of fragment) say(`  MERGE  ${a.merge}: ${trackLabel(tr, groups)}, ${tr.keys.length} key(s) at t=${tr.keys[0]!.t}${tr.keys.length > 1 ? `–${tr.keys[tr.keys.length - 1]!.t}` : ''}s`);
     }
     const added = [...carried, ...fragment];
-    const animation = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    const tracked = added.length === 0 ? r.animation : { ...r.animation, tracks: [...own, ...added] };
+    // #304: rig-c's one draw-order timeline sits on the animation beside its tracks; written only when keyed.
+    const animation = drawOrder === null || drawOrder.keys.length === 0 ? tracked : { ...tracked, drawOrder: drawOrderKeys(drawOrder) };
     const motion = { ...base, animations: { ...animations, [a.name]: animation } };
     const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile, a.images);
     if (!g1.green) {
@@ -314,11 +345,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     const support = a.reduce !== undefined && a.reduceKeepPlanted === true && r.feet !== null ? supportFrames(r.feet.supports) : undefined;
     const landings = measureLanding(doc, a.name, map, r, posed, support).map((l) => {
       if (a.reduce === undefined) return l;
-      if (l.kind === 'angle') return { ...l, tolerance: l.tolerance + a.reduce };
+      // #283: a chain's own tolerance is added as the run's is; the sum is rounded only under a per-chain --reduce.
+      if (l.kind === 'angle') return { ...l, tolerance: a.reduceChains === undefined ? l.tolerance + a.reduce : Number((l.tolerance + reduceOf!(l.bone)).toPrecision(12)) };
       if (l.kind === 'origin' && a.reduceHip !== undefined) return { ...l, tolerance: l.tolerance + a.reduceHip };
       if (l.kind !== 'foot') return l;
       const ankle = l.bone.replace(/:tip$/, '');
-      const by = footReduce(rest, r, ankle, a.reduce, a.reduceHip);
+      const by = footReduce(rest, r, ankle, a.reduce, a.reduceHip, a.reduceChains === undefined ? undefined : reduceOf!);
       // #251: on its support frames every mapped bone from the hip down was kept at its target, so only the hip's tolerance moves it.
       const hip = a.reduceHip ?? 0;
       if (!drift.some((d) => d.bone === l.bone)) {
@@ -326,7 +358,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         const side = lb?.r.ankle === ankle ? 'r' : lb?.l.ankle === ankle ? 'l' : null;
         const legs = (u: number) => (side === null || r.rigLeg === null ? null : u / r.rigLeg[side]);
         const held = support === undefined ? {} : { support: side === null || support[side].size === 0 ? null : { reduce: hip, units: l.tolerance + hip, legLengths: legs(l.tolerance + hip) } };
-        drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: legs(l.tolerance + by), ...held });
+        // #283: under a per-chain --reduce, the tolerance its leg was reduced within.
+        const leg = a.reduceChains === undefined ? {} : { legTolerance: legTolerance(rest, r, ankle, reduceOf!) };
+        drift.push({ bone: l.bone, side, plant: l.tolerance, reduce: by, units: l.tolerance + by, legLengths: legs(l.tolerance + by), ...held, ...leg });
       }
       return { ...l, tolerance: l.tolerance + (l.on === 'support' ? hip : by) };
     });
@@ -389,7 +423,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
 
     assertReportInputs([rigSnapshot,mapSnapshot,poseSnapshot]);
     // Every retarget option as resolved: the report's `options`, and with the name the build record's `flags` (#270).
-    const options = { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}) };
+    const options = { minScore: a.minScore, flip: a.flip, short: a.short, bends: a.bends, bendTolerance: a.bendTolerance, switchTolerance: a.switchTolerance, switchMin: a.switchMin, switchAt: a.switchAt, profile: a.profile, legScale: a.legScale ?? 'off', plantFeet: a.plantFeet === true, stance: a.stance ?? 'off', floor: a.floor ?? null, raisedByHead: a.raisedByHead === true, idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', ...(a.reduceChains === undefined ? {} : { reduceChains: a.reduceChains }), reduceHip: a.reduceHip ?? 'off', ...(a.reduceKeepPlanted === true ? { reduceKeepPlanted: true } : {}), ...(a.drawOrder !== undefined ? { drawOrder: a.drawOrder } : {}) };
     const reportText = writeReport({
         spec: 'rig-pose-report/1',
         rigc,
@@ -414,9 +448,12 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         seams: seamRead.seams,
         seamPairs: seamRead.seamPairs,
         switches: r.switches,
+        switchRuns: r.switchRuns,
         uncovered,
         turns: r.turns,
         reach: r.reach,
+        // Only when the map has a reach chain (#282): a map without one writes the report it always has.
+        ...(r.reachOrigin.length > 0 ? { reachOrigin: r.reachOrigin } : {}),
         range: r.range,
         artRange: r.artRange,
         raised: r.raised,
@@ -448,13 +485,15 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         pelvis: r.pelvis,
         // Only when the sequence carries depth (#281): a sequence without it writes the report it always has.
         ...(layers !== null ? { layers: layers.map((l, frame) => ({ frame, order: l.order, depth: l.depth })) } : {}),
+        // Only with --draw-order depth (#304).
+        ...(drawOrder !== null ? { drawOrder: { source: 'depth', pairs: drawOrder.pairs, keys: drawOrder.keys, spans: drawOrder.spans, gaps: drawOrder.gaps ?? [] } } : {}),
         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 },
         feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, straight: r.legStraight, rigLeg: r.rigLeg, segments: r.segments, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, ...(r.feet.lowered === undefined ? {} : { lowered: r.feet.lowered }), ...(r.feet.tracked === undefined ? {} : { tracked: r.feet.tracked }), floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, ...(r.blendHold.range === undefined ? {} : { range: r.blendHold.range }), runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading, closure: r.closure },
         shear,
         idleDropped: idle === null ? null : idle.dropped,
         idleKeptOut: idle === null ? null : idle.keptOut,
         merged: fragment.map((tr) => ({ track: trackLabel(tr, groups), keys: tr.keys.length })),
-        reduce: reduced === null ? null : { tolerance: a.reduce, hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
+        reduce: reduced === null ? null : { tolerance: a.reduce, ...(a.reduceChains === undefined ? {} : { chains: a.reduceChains }), ...(held.length === 0 ? {} : { held }), ...(reduced.unsmoothed === undefined ? {} : { unsmoothed: reduced.unsmoothed }), hipTolerance: a.reduceHip ?? null, rows: reduced.rows, ankleDrift: drift },
       }, map, { frameTimes: r.times }, f.meshes !== null && doc.slots.length > 0 ? reportRenderDomain(JSON.parse(readFileSync(join(f.frames, '..', 'frames.json'), 'utf8')), a.name) : seamRead.frames === null ? null : reportRenderDomain(seamRead.frames, a.name), {rig:rigSnapshot.identity,map:mapSnapshot.identity,pose:poseSnapshot.identity});
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
@@ -626,7 +665,7 @@ const spanText = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}
  * aim and length it lands on (`reduceUnderScale`). With none, this is #32's
  * reduction, unchanged.
  */
-function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined, keepPlanted: boolean): Reduced {
+function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest, tolerance: number, hipTolerance: number | undefined, keepPlanted: boolean, tolOf: (bone: string) => number = () => tolerance): Reduced {
   const n = r.times.length;
   const keep = new Map<string, Set<number>>();
   const add = (bone: string, ...frames: number[]) => {
@@ -665,7 +704,9 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
     return false;
   };
   const dense = new Map([...rotate].map(([b, tr]) => [b, tr.keys.map((k) => k.v[0]!)]));
-  const bones: ReduceBone[] = [...rotate.values()].filter((tr) => !under(tr.bone)).map((tr) => ({ bone: tr.bone, above: above(tr.bone), dense: dense.get(tr.bone)!, keep: keep.get(tr.bone) ?? new Set<number>() }));
+  // #283: a bone whose chain --reduce names carries its own tolerance; every other takes the run's.
+  const own = (b: string): { tolerance?: number } => (tolOf(b) === tolerance ? {} : { tolerance: tolOf(b) });
+  const bones: ReduceBone[] = [...rotate.values()].filter((tr) => !under(tr.bone)).map((tr) => ({ bone: tr.bone, above: above(tr.bone), dense: dense.get(tr.bone)!, keep: keep.get(tr.bone) ?? new Set<number>(), ...own(tr.bone) }));
   const hipTrack = r.origin === null || hipTolerance === undefined ? undefined : r.animation.tracks.find((tr): tr is MotionTrack => 'bone' in tr && tr.property === 'translate' && tr.bone === r.origin!.bone && tr.keys.every((k) => k.ease === undefined));
   const parent = hipTrack === undefined ? null : rest.get(hipTrack.bone)!.parent;
   const pm = parent === null ? null : rest.get(parent)!;
@@ -758,6 +799,7 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
       asked: r.scales.get(b) ?? new Array<number>(n).fill(1),
       dense: dense.get(b)!,
       keep: keepOf(b),
+      ...own(b),
     };
   });
   const red = reduceUnderScale(r.times, given, tolerance, SCALE_REDUCE);
@@ -782,7 +824,7 @@ function reduceTracks(r: ReturnType<typeof retarget>, map: JointMap, rest: Rest,
  * world aim is within the angle tolerance of its dense one, top-down, so the
  * segments' errors are each bounded and the sum bounds the ankle's.
  */
-export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolerance: number, hipTolerance: number | undefined): number {
+export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolerance: number, hipTolerance: number | undefined, tolOf?: (bone: string) => number): number {
   const top = r.origin?.bone ?? null;
   let sMax = 1;
   for (const s of r.scales.values()) for (const v of s) sMax = Math.max(sMax, v);
@@ -794,7 +836,8 @@ export function footReduce(rest: Rest, r: ReturnType<typeof retarget>, ankle: st
     if (p === null) break;
     lever += Math.hypot(x.worldX - p.worldX, x.worldY - p.worldY);
   }
-  return (hipTolerance ?? 0) + lever * sMax * ((tolerance * Math.PI) / 180 + SCALE_REDUCE);
+  const deg = tolOf === undefined ? tolerance : legTolerance(rest, r, ankle, tolOf);
+  return (hipTolerance ?? 0) + lever * sMax * ((deg * Math.PI) / 180 + SCALE_REDUCE);
 }
 
 function spans(ts: number[], step: number): string {
@@ -1290,6 +1333,8 @@ export interface AnkleDrift {
    * Absent without the flag.
    */
   support?: { reduce: number; units: number; legLengths: number | null } | null;
+  /** rig-c/pose#283: under a per-chain --reduce, the largest tolerance a bone from the hip down to it was reduced within (degrees). */
+  legTolerance?: number;
 }
 
 /** #251: each side's support frames, from the spans --plant-feet read. */
@@ -1301,11 +1346,120 @@ function supportFrames(supports: ReadonlyArray<{ side: 'r' | 'l'; frames: [numbe
 
 /** The drift line: the allowance on one frame, and what it lets a planted ankle slide between two. */
 export function ankleDriftLine(d: AnkleDrift): string {
+  const chainDeg = d.legTolerance;
   const legs = (v: number) => (d.legLengths === null ? '' : ` = ${(d.legLengths * v / d.units).toPrecision(3)} leg lengths`);
   const line = `ankle drift allowed: bone "${d.bone}" ${d.units.toPrecision(3)} units${legs(d.units)} on any one frame (plant ${d.plant.toPrecision(3)} + reduce ${d.reduce.toPrecision(3)}); between two frames up to ${(2 * d.units).toPrecision(3)} units${legs(2 * d.units)}`;
-  if (d.support === undefined) return `${line} — a tighter slide bar needs a smaller --reduce`;
+  if (d.support === undefined) return `${line} — ${chainDeg === undefined ? 'a tighter slide bar needs a smaller --reduce' : `its leg reduced within ${chainDeg}° (--reduce <deg>,<chain>=<deg>); a tighter slide bar needs a smaller one on its chain`}`;
   if (d.support === null) return `${line}; its side never supports, so --reduce-keep-planted keeps no frame of it`;
   const s = d.support;
   const sLegs = (v: number) => (s.legLengths === null ? '' : ` = ${(s.legLengths * v / s.units).toPrecision(3)} leg lengths`);
   return `${line} off its support frames; on them, kept dense (--reduce-keep-planted), ${s.units.toPrecision(3)} units${sLegs(s.units)} (plant ${d.plant.toPrecision(3)} + hip ${s.reduce.toPrecision(3)}), between two frames of a support span up to ${(2 * s.units).toPrecision(3)} units${sLegs(2 * s.units)}`;
 }
+
+/** rig-c/pose#283: the largest tolerance any bone from `ankle` up to the legs' top was reduced within. */
+export function legTolerance(rest: Rest, r: ReturnType<typeof retarget>, ankle: string, tolOf: (bone: string) => number): number {
+  const top = r.origin?.bone ?? null;
+  let deg = tolOf(ankle);
+  for (let b: string | null = rest.get(ankle)!.parent; b !== null && b !== top; b = rest.get(b)!.parent) deg = Math.max(deg, tolOf(b));
+  return deg;
+}
+
+/**
+ * rig-c/pose#283: the reduction's tolerance per bone. Every bone takes `tolerance`
+ * but a bone of a chain `chains` names, which takes that chain's (the smallest,
+ * when two named chains list it). A name the map has no chain for is refused by
+ * name, beside the chains it has.
+ */
+export function reduceTolerances(map: JointMap, tolerance: number, chains: Record<string, number> | undefined, mapPath: string): (bone: string) => number {
+  if (chains === undefined) return () => tolerance;
+  const names = map.chains.map((c) => c.name);
+  const missing = Object.keys(chains).filter((c) => !names.includes(c));
+  if (missing.length > 0) throw new Refusal(missing.map((c) => ({ code: 'POSE_REDUCE', text: `--reduce names chain "${c}", which ${mapPath} does not have; its chains are ${names.map((x) => `"${x}"`).join(', ')}` })));
+  const by = new Map<string, number>();
+  for (const c of map.chains) {
+    const t = Object.hasOwn(chains, c.name) ? chains[c.name] : undefined;
+    if (t === undefined) continue;
+    for (const b of c.bones) by.set(b, Math.min(by.get(b) ?? t, t));
+  }
+  return (bone) => by.get(bone) ?? tolerance;
+}
+
+/** rig-c/pose#320: a mapped bone held to the tolerance of a planted or aimed chain below it. */
+export interface ReduceHeld {
+  /** The held bone, and the map chain it is a bone of (null for a mapped bone no chain lists). */
+  bone: string;
+  chain: string | null;
+  /** Its tolerance as --reduce gave it (the run's, or its own chain's), degrees. */
+  from: number;
+  /** The tolerance it is held to: the tightest planted or aimed chain --reduce names below it, degrees. */
+  to: number;
+  /**
+   * Each such chain below it reduced within `to`, in the map's order: its name, what holds it (`ankle`: it carries
+   * a planted ankle's landing; `aim`: the map aims it), its first bone, and the lever — that bone's origin's setup
+   * distance from the held bone's origin, rig units.
+   */
+  for: Array<{ chain: string; by: 'ankle' | 'aim'; bone: string; lever: number }>;
+}
+
+/**
+ * rig-c/pose#320: every mapped bone above a planted or aimed chain `chains`
+ * names, whose own tolerance (`tolOf`) is looser than that chain's, held to it
+ * — to the tightest such chain when several hang below it. A chain is planted
+ * when it carries an ankle the landing check holds (`ankles`), aimed when the
+ * map gives it an `aim` other than "x".
+ *
+ * The lever. A turn error θ on a bone turns everything under it rigidly: a
+ * chain below has its first bone moved by θ·L (L = `lever`) and its aim turned
+ * by θ. The reduction refits the chain against the turn (`target = dense −
+ * e_above`), so the aim is the chain's own error, but not the move: the ankle
+ * allowance (`footReduce`) sums every segment from the legs' top down — the
+ * held bone's lever among them — times the leg's own degrees. θ·L ≤ θ_leg·L is
+ * θ ≤ θ_leg whatever L is. An aimed chain is refitted, and on the trunk
+ * smoothed (#116), against its parent's error as it stands: held to the
+ * chain's degrees, that error never asks the chain to absorb more than its own
+ * tolerance. A bent chain (an arm, a leg with no ankle check) has only its aim
+ * checked, which the refit holds, so it holds nothing above it. Only a
+ * per-chain entry can be tighter than a bone above it: with none, nothing is held.
+ */
+export function holdParents(map: JointMap, rest: Rest, mapped: ReadonlySet<string>, chains: Record<string, number>, tolOf: (bone: string) => number, ankles: readonly string[]): ReduceHeld[] {
+  const held: ReduceHeld[] = [];
+  for (const c of map.chains) {
+    const t = Object.hasOwn(chains, c.name) ? chains[c.name] : undefined;
+    const top = c.bones[0];
+    const by = c.bones.some((b) => ankles.includes(b)) ? ('ankle' as const) : c.aim.some((x) => x !== 'x') ? ('aim' as const) : null;
+    if (t === undefined || top === undefined || by === null || !rest.has(top)) continue;
+    const at = rest.get(top)!;
+    for (let p = at.parent; p !== null; p = rest.get(p)?.parent ?? null) {
+      if (!mapped.has(p) || c.bones.includes(p) || !(tolOf(p) > t)) continue;
+      const was = held.findIndex((h) => h.bone === p);
+      if (was >= 0 && held[was]!.to < t) continue;
+      const x = rest.get(p)!;
+      const child = { chain: c.name, by, bone: top, lever: Number(Math.hypot(at.worldX - x.worldX, at.worldY - x.worldY).toPrecision(6)) };
+      if (was >= 0 && held[was]!.to === t) held[was]!.for.push(child);
+      else if (was >= 0) held[was] = { ...held[was]!, to: t, for: [child] };
+      else held.push({ bone: p, chain: map.chains.find((m) => m.bones.includes(p))?.name ?? null, from: tolOf(p), to: t, for: [child] });
+    }
+  }
+  return held;
+}
+
+/** rig-c/pose#320: the REDUCE line naming a held bone, the chains it was held for, and why. */
+export function heldLine(h: ReduceHeld): string {
+  const below = h.for.map((c) => `chain "${c.chain}" (${c.by === 'ankle' ? 'a planted ankle' : 'aimed'}; L = ${c.lever} units to bone "${c.bone}")`).join(', ');
+  const why = [
+    ...(h.for.some((c) => c.by === 'ankle') ? ['the ankle allowance counts L at the leg\'s own degrees'] : []),
+    ...(h.for.some((c) => c.by === 'aim') ? ['an aimed chain refits against its parent\'s error within its own'] : []),
+  ].join(' and ');
+  return `held: bone "${h.bone}"${h.chain === null ? '' : ` (chain "${h.chain}")`} reduced within ${h.to}°, not ${h.from}° — for ${below} below it, reduced within ${h.to}°: a turn error θ on bone "${h.bone}" moves a chain below it by θ·L and turns it by θ, and ${why}, so θ ≤ ${h.to}°`;
+}
+
+/** rig-c/pose#320: the REDUCE line for a trunk smoothing (#116) not kept. */
+export function unsmoothedLine(u: { root: string; bone: string; worst: number; tolerance: number }): string {
+  return `smoothing (rig-c/pose#116) from bone "${u.root}" down not kept: it left bone "${u.bone}" at ${u.worst.toPrecision(3)}°, past its ${u.tolerance}°; the fitted keys stand, each within its tolerance`;
+}
+
+/** rig-c/pose#283: the per-chain tolerances as the run and REDUCE lines print them; empty without. */
+export function chainsText(chains: Record<string, number> | undefined): string {
+  if (chains === undefined) return '';
+  return ` (${Object.entries(chains).map(([c, t]) => `chain "${c}" ${t}°`).join(', ')})`;
+}

package/src/switch.ts

@@ -180,8 +180,28 @@ export interface Uncovered {
   times: number[];
 }
 
+/** One run of frames (rig-c/pose#279): first and last frame, how many, and the seconds the minimum span measured it by (first frame's time to the next frame's, the animation's end for the last). */
+export interface FrameRun {
+  frames: [number, number];
+  count: number;
+  seconds: number;
+}
+
+/**
+ * rig-c/pose#279: per set selected by angle (not `phase`), the runs of frames on which it was the nearest set within
+ * the tolerance (inside its `frames` window, before bridging, hysteresis and the minimum span), and the runs the
+ * minimum span dropped — shorter than `switchMin` where they stood — on frames the set did not show in the end.
+ */
+export interface SetRuns {
+  set: string;
+  nearest: FrameRun[];
+  suppressed: FrameRun[];
+}
+
 export interface Switches {
   switches: Switch[];
+  /** rig-c/pose#279: one per set without a `phase`, in the map's order. */
+  runs: SetRuns[];
   /** The `attachment` tracks, one per slot whose picture changes. */
   slotTracks: SlotTrack[];
   /** The offsets' `translate` tracks, one per bone a shown set offsets. */
@@ -490,6 +510,11 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
   const distances = setDistances(map, targets, n, opts.shortInfo);
   const hyst = opts.switchHysteresis ?? SWITCH_LEAVE_HYSTERESIS;
   const switches: Switch[] = [];
+  // rig-c/pose#279: per angle set, the frames it was nearest on and the frames the minimum span dropped it from.
+  const nearestOn = new Map<string, boolean[]>();
+  const droppedOn = new Map<string, boolean[]>();
+  const runOf = (i: number, j: number): FrameRun => ({ frames: [i, j], count: j - i + 1, seconds: r3((j + 1 < n ? times[j + 1]! : duration) - times[i]!) });
+  const runsOfFlags = (flag: readonly boolean[]): FrameRun[] => runsOf(flag, 0).map(([i, j]) => runOf(i, j));
   // rig-c/pose#286: the supporting side on each frame, from the report's support spans (null: no foot, or no set declares a phase).
   const supportAt: Array<Side | null> = Array.from({ length: n }, () => null);
   for (const sp of opts.phaseSupports ?? []) for (let i = sp.frames[0]; i <= Math.min(sp.frames[1], n - 1); i++) supportAt[i] = sp.side;
@@ -546,6 +571,10 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       pick.push(best);
     }
+    for (const a of group) {
+      nearestOn.set(a.name, pick.map((p) => p === a));
+      droppedOn.set(a.name, Array.from({ length: n }, () => false));
+    }
     const bridgeSame = (arr: Array<AlternateSet | null>) => {
       for (let i = 0; i < n;) {
         const a = arr[i];
@@ -604,7 +633,13 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       let j = i;
       while (j + 1 < n && pick[j + 1] === a) j++;
       const to = j + 1 < n ? times[j + 1]! : duration;
-      if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) for (let k = i; k <= j; k++) pick[k] = null;
+      if (a !== null && a !== undefined && to - times[i]! < opts.switchMin - 1e-9) {
+        const dropped = droppedOn.get(a.name)!;
+        for (let k = i; k <= j; k++) {
+          pick[k] = null;
+          dropped[k] = true;
+        }
+      }
       i = j + 1;
     }
     if (hyst > 0) {
@@ -658,8 +693,14 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
       }
       if (dropped) bridgeSame(pick);
     }
+    // rig-c/pose#279: a dropped frame the set came back to (hysteresis, bridging) was not suppressed.
+    for (const a of group) {
+      const dropped = droppedOn.get(a.name)!;
+      for (let k = 0; k < n; k++) if (pick[k] === a) dropped[k] = false;
+    }
     spans(pick, opts);
   }
+  const runs: SetRuns[] = map.alternates.filter((a) => nearestOn.has(a.name)).map((a) => ({ set: a.name, nearest: runsOfFlags(nearestOn.get(a.name)!), suppressed: runsOfFlags(droppedOn.get(a.name)!) }));
   const order = (name: string) => map.alternates.findIndex((a) => a.name === name);
   switches.sort((x, y) => x.frames[0] - y.frames[0] || order(x.set) - order(y.set));
 
@@ -1094,7 +1135,7 @@ export function selectSwitches(map: JointMap, targets: ReadonlyMap<string, reado
     for (let k = 0; k + 1 < keys.length; k++) keys[k]!.ease = 'stepped';
     offsetTracks.push({ bone: b, property: 'translate', keys });
   }
-  return { switches, slotTracks, offsetTracks, shown, distances, chainHolds };
+  return { switches, runs, slotTracks, offsetTracks, shown, distances, chainHolds };
 }
 
 /** Per chain, the frames on which a switch of a set depicting it shows: its art was painted for that pose. */
@@ -1281,6 +1322,27 @@ export function phaseLines(map: JointMap, switches: readonly Switch[]): string[]
   return out;
 }
 
+/** How many runs a `SWITCH-MIN` line lists before it points at the report for the rest. */
+export const SWITCH_MIN_LISTED = 4;
+
+/**
+ * rig-c/pose#279: one `SWITCH-MIN` line per set the minimum span held back — the runs it dropped (frames, count,
+ * seconds), and the set's nearest runs (how many, and the longest) — so a set that matched but was held back reads
+ * apart from one that never matched. A set with nothing suppressed prints no line.
+ */
+export function switchMinLines(runs: readonly SetRuns[], switchMin: number): string[] {
+  const runText = (r: FrameRun) => `${r.count === 1 ? `frame ${r.frames[0]}` : `frames ${r.frames[0]}–${r.frames[1]}`} (${r.count} frame${r.count === 1 ? '' : 's'}, ${r.seconds.toFixed(3)}s)`;
+  const out: string[] = [];
+  for (const s of runs) {
+    if (s.suppressed.length === 0) continue;
+    const listed = s.suppressed.slice(0, SWITCH_MIN_LISTED).map(runText).join(', ');
+    const more = s.suppressed.length > SWITCH_MIN_LISTED ? `, and ${s.suppressed.length - SWITCH_MIN_LISTED} more (the report's switchRuns lists every one)` : '';
+    const longest = s.nearest.reduce((m, r) => (r.count > m.count ? r : m), s.nearest[0]!);
+    out.push(`set "${s.set}": ${s.suppressed.length} run(s) shorter than --switch-min ${switchMin}s not shown: ${listed}${more}; nearest on ${s.nearest.length} run(s), the longest ${runText(longest)}`);
+  }
+  return out;
+}
+
 const spd = (v: number) => `${v.toFixed(1)}°/frame`;
 const win = (w: [number, number]) => (w[0] === w[1] ? `window frame ${w[0]}` : `window frames ${w[0]}–${w[1]}`);
 function moveText(m: Move): string {