@rig-c/pose 0.39.0 → 0.41.0

package/src/reduce.ts

@@ -48,6 +48,8 @@ export interface ReduceBone {
   dense: number[];
   /** Frame indices that must keep a key regardless (the first and last always do). */
   keep: ReadonlySet<number>;
+  /** Its own world-aim tolerance in degrees, in place of the call's (rig-c/pose#283: its chain's). */
+  tolerance?: number;
 }
 export interface ReduceHip {
   bone: string;
@@ -78,6 +80,12 @@ export interface Reduced {
   rows: ReduceRow[];
   /** Each bone's world-aim error on every frame (reduced less dense, degrees), as the poser evaluates the reduced keys. */
   errors: Map<string, number[]>;
+  /**
+   * rig-c/pose#320: each trunk root whose smoothing (`smoothTrunk`, #116) was not kept because it left a bone it
+   * manages past that bone's own tolerance — the bone, its smoothed worst error and its tolerance (degrees); the
+   * fitted keys stand. Absent when every smoothing was kept.
+   */
+  unsmoothed?: Array<{ root: string; bone: string; worst: number; tolerance: number }>;
 }
 
 // ---------------------------------------------------------------------------
@@ -328,6 +336,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
   const byName = new Map<string, ReduceBone>();
   for (const b of bones) {
     if (byName.has(b.bone)) throw new Error(`reduce: bone "${b.bone}" is given twice`);
+    if (b.tolerance !== undefined && !(Number.isFinite(b.tolerance) && b.tolerance > 0)) throw new Error(`reduce: bone "${b.bone}"'s tolerance is ${b.tolerance}°, not a positive number`);
     if (b.dense.length !== n) throw new Error(`reduce: bone "${b.bone}" has ${b.dense.length} dense key(s) for ${n} frame(s)`);
     byName.set(b.bone, b);
   }
@@ -349,7 +358,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     const keys = fitTrack(times, samples, {
       targets,
       keep: keptFrames(b.keep, n, `bone "${b.bone}"`),
-      tolerance,
+      tolerance: b.tolerance ?? tolerance,
       error: (i, v) => Math.abs(v[0]! - targets[i]![0]!),
     });
     const e = trackAt(keys, samples, 1).map((v, i) => v[0]! - targets[i]![0]!);
@@ -604,7 +613,9 @@ function solveLimbPreservingJitter(
  * above the sequence's own. Optimizing knot values and handle y-coordinates
  * jointly within the ±tolerance world-aim tube removes those C0 breaks while
  * keeping any limb chains hanging from the trunk within 0.04 of their landing
- * and jitter.
+ * and jitter. The tube's bounds are a penalty, not a constraint: a root whose
+ * smoothing leaves any bone it manages past that bone's own tolerance keeps its
+ * fitted keys instead, recorded in `out.unsmoothed` (rig-c/pose#320).
  */
 export function smoothTrunk(
   times: readonly number[],
@@ -617,11 +628,12 @@ export function smoothTrunk(
   if (n < 4 || trunkBones.size === 0) return;
   const samples = samplesOf(times);
   const byName = new Map(bones.map((b) => [b.bone, b]));
+  /** rig-c/pose#283: a bone's own tolerance (its chain's under a per-chain --reduce), else the call's. */
+  const tolOf = (b: string): number => byName.get(b)?.tolerance ?? tolerance;
   const roots = [...trunkBones].filter((b) => {
     const info = byName.get(b);
     return info !== undefined && (info.above === null || !trunkBones.has(info.above));
   });
-  const tolInner = 0.985 * tolerance;
 
   for (const root of roots) {
     const rootKeys = out.rotate.get(root);
@@ -646,8 +658,10 @@ export function smoothTrunk(
     const targetRoot = rootInfo.dense.map((d, i) => d - eAboveRoot[i]!);
     const yRootOld = yOldOf.get(root)!;
 
-    const rootLb = targetRoot.map((t) => t - tolInner);
-    const rootUb = targetRoot.map((t) => t + tolInner);
+    // #283: each bone's own tolerance (its chain's under a per-chain --reduce; the call's otherwise).
+    const rootInner = 0.985 * tolOf(root);
+    const rootLb = targetRoot.map((t) => t - rootInner);
+    const rootUb = targetRoot.map((t) => t + rootInner);
     let smRoot = optimizeBasis(basisOf.get(root)!, rootLb, rootUb);
     let eRoot = smRoot.y.map((v, i) => v - targetRoot[i]!);
 
@@ -667,14 +681,15 @@ export function smoothTrunk(
       for (const h of headBones) {
         const dH = byName.get(h)!.dense;
         const targetH = dH.map((d, i) => d - eRoot[i]!);
-        const smH = optimizeBasis(basisOf.get(h)!, targetH.map((t) => t - tolInner), targetH.map((t) => t + tolInner));
+        const hInner = 0.985 * tolOf(h);
+        const smH = optimizeBasis(basisOf.get(h)!, targetH.map((t) => t - hInner), targetH.map((t) => t + hInner));
         smSub.set(h, smH);
         eSub.set(h, smH.y.map((v, i) => v - targetH[i]!));
       }
       for (const b0 of arm0Bones) {
         const yOld = yOldOf.get(b0)!;
         const wOld = Math.max(...out.errors.get(b0)!.map(Math.abs));
-        const cap = Math.min(0.98 * tolerance, wOld + 0.035 * tolerance);
+        const cap = Math.min(0.98 * tolOf(b0), wOld + 0.035 * tolOf(b0));
         const targetB = byName.get(b0)!.dense.map((d, i) => d - eRoot[i]!);
         const smB = solveLimbPreservingJitter(basisOf.get(b0)!, yOld, targetB.map((t) => t - cap), targetB.map((t) => t + cap));
         smSub.set(b0, smB);
@@ -685,7 +700,7 @@ export function smoothTrunk(
         const eUp = eSub.get(up)!;
         const yOld = yOldOf.get(b1)!;
         const wOld = Math.max(...out.errors.get(b1)!.map(Math.abs));
-        const cap = Math.min(0.98 * tolerance, wOld + 0.035 * tolerance);
+        const cap = Math.min(0.98 * tolOf(b1), wOld + 0.035 * tolOf(b1));
         const targetB = byName.get(b1)!.dense.map((d, i) => d - eUp[i]!);
         const smB = solveLimbPreservingJitter(basisOf.get(b1)!, yOld, targetB.map((t) => t - cap), targetB.map((t) => t + cap));
         smSub.set(b1, smB);
@@ -699,17 +714,17 @@ export function smoothTrunk(
       for (let i = 0; i < n; i++) {
         for (const h of headBones) {
           const eh = eSub.get(h)![i]!;
-          if (Math.abs(eh) > 0.99 * tolerance) {
-            tightenAround(i, Math.abs(eh) - 0.975 * tolerance);
+          if (Math.abs(eh) > 0.99 * tolOf(h)) {
+            tightenAround(i, Math.abs(eh) - 0.975 * tolOf(h));
             anyTightened = true;
           }
         }
         for (const b of [...arm0Bones, ...arm1Bones]) {
           const wOld = Math.max(...out.errors.get(b)!.map(Math.abs));
-          const cap = Math.min(0.985 * tolerance, wOld + 0.04 * tolerance);
+          const cap = Math.min(0.985 * tolOf(b), wOld + 0.04 * tolOf(b));
           const eb = eSub.get(b)![i]!;
           if (Math.abs(eb) > cap) {
-            tightenAround(i, Math.abs(eb) - (cap - 0.01 * tolerance));
+            tightenAround(i, Math.abs(eb) - (cap - 0.01 * tolOf(b)));
             anyTightened = true;
           }
         }
@@ -730,6 +745,16 @@ export function smoothTrunk(
       }
     };
 
+    // rig-c/pose#320: the smoothing is kept only within every managed bone's own tolerance; past it, the fitted keys
+    // (within it by construction) stand, and the run says so.
+    const past = allManaged.map((b) => {
+      const e = b === root ? eRoot : eSub.get(b)!;
+      return { b, worst: Math.max(...e.map(Math.abs)) };
+    }).find((x) => x.worst > tolOf(x.b));
+    if (past !== undefined) {
+      (out.unsmoothed ??= []).push({ root, bone: past.b, worst: past.worst, tolerance: tolOf(past.b) });
+      continue;
+    }
     updateBone(root, smRoot.keys, eRoot);
     for (const b of [...headBones, ...arm0Bones, ...arm1Bones]) {
       updateBone(b, smSub.get(b)!.keys, eSub.get(b)!);
@@ -827,6 +852,8 @@ export interface UnderBone {
   /** The dense rotate keys (unwrapped, as written). */
   dense: readonly number[];
   keep: ReadonlySet<number>;
+  /** Its own world-aim tolerance in degrees, in place of the call's (rig-c/pose#283). */
+  tolerance?: number;
 }
 
 /**
@@ -879,7 +906,7 @@ export function reduceUnderScale(times: readonly number[], bones: readonly Under
       return Math.abs(wrap180(Math.atan2(w[1], w[0]) * DEG - b.target[i]!));
     };
     const keep = keptFrames(b.keep, n, `bone "${b.bone}"`);
-    const rk = fitTrack(times, samples, { targets: solved.map((k) => [k]), keep, tolerance, error: (i, v) => aimError(i, v[0]!) });
+    const rk = fitTrack(times, samples, { targets: solved.map((k) => [k]), keep, tolerance: b.tolerance ?? tolerance, error: (i, v) => aimError(i, v[0]!) });
     const kAt = trackAt(rk, samples, 1).map((v) => v[0]!);
     const ae = worstOf(kAt.map((_, i) => i), (i) => aimError(i, kAt[i]!))!;
     rows.push({ bone: b.bone, kind: 'angle', before: n, after: rk.length, worst: ae.worst, frame: ae.frame });

package/src/retarget.ts

@@ -79,7 +79,7 @@ import { aimAngle, aimEnds, bodyYawSets, descends, faceYawSets, knownSetsOf, par
 import type { Joint, Travel } from './pose.ts';
 import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import type { ArtRange, AttachmentKey, ByHip, Raised, ReachShort, SetRuns, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, phaseGroupProblems, RAISED_WRIST_EYES, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
 import type { BlendHold, Closure, Feet, Floor, LegScale, LegSegmentRatio, PathPose, Posing, Side, Stance } from './legs.ts';
 import { figureScaleOf, freeAnkleShiftOf, holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, percentile, plantHip, posePath, rootOf, scaleSupport, shiftOver, SIDES, stanceOf, stanceRangeOf, STRAIGHT_PERCENTILE, supportsOf, tipOf, unshortenStanceShin } from './legs.ts';
@@ -369,6 +369,34 @@ export interface ReachReading {
   ratio: number | null;
 }
 
+/**
+ * rig-c/pose#282: where a `reach` chain's bone starts against the source joint
+ * it re-aims from. The pose's pair starts at the translated joint, which the
+ * rig puts at the translated bone's posed origin; the reach aims from its own
+ * bone's posed origin. The distance between the two, at setup and on the
+ * frames, is the lever #236 names — a reading, with a WARN past
+ * `REACH_ORIGIN_WARN` of the segment. One per reach chain, in map order.
+ */
+export interface ReachOrigin {
+  chain: string;
+  bone: string;
+  /** The pair: the chain's first joint (the translated joint) and its second. */
+  joints: [string, string];
+  /** The translated bone, whose posed origin is where the rig puts the source joint. */
+  anchor: string;
+  /** The distance at setup, world units. */
+  setup: number;
+  /** The largest distance as posed on the frames, world units, and its frame. */
+  posed: { max: number; frame: number };
+  /** The reached length: the pair's median picture length, scaled (world units). */
+  segment: number;
+  /** max(setup, posed.max) ÷ segment. */
+  ofSegment: number;
+  /** ofSegment > threshold. */
+  warn: boolean;
+  threshold: number;
+}
+
 /**
  * Mean |second difference| of a series of angles, degrees: |wrap(v[i+1] − v[i])
  * − wrap(v[i] − v[i−1])| over every i whose three frames `ok` admits (every
@@ -419,6 +447,8 @@ export interface Retarget {
   scaleFit: ScaleFit | null;
   /** The spans each alternate set shows, with their art turn. */
   switches: Switch[];
+  /** rig-c/pose#279: per set without a `phase`, the runs it was nearest on and the runs the minimum span suppressed. */
+  switchRuns: SetRuns[];
   /** 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. */
@@ -475,6 +505,8 @@ export interface Retarget {
   nodSkipped: NodSkipped | null;
   /** Each `reach` chain hanging below a bone the animation turns or translates (#236): its aim's departure from the pose pair's angle. */
   reach: ReachReading[];
+  /** rig-c/pose#282: each `reach` chain's origin against the source joint it re-aims from; empty when the map has none. */
+  reachOrigin: ReachOrigin[];
   /** rig-c/pose#288: the pelvis bone's source; null when the map has no pelvis chain and the sequence no track. */
   pelvis: PelvisReading | null;
 }
@@ -1486,6 +1518,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   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;
   const reachAims = new Map<string, { aim: number[]; pair: number[]; length: number }>();
+  /** #282: per reach chain, the distance from its bone's posed origin to the anchor's on each frame (the last aim's). */
+  const reachGaps = new Map<string, number[]>();
   if (reaches.length > 0 && t !== null && scale !== null) {
     const s = scale.factor;
     const tb = rest.get(t.bone)!;
@@ -1494,8 +1528,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const anchor = series.get(c.joints[0]!)!;
       const end = series.get(c.joints[1]!)!;
       const angles: number[] = [];
+      const gaps: number[] = [];
       for (let i = 0; i < n; i++) {
         const o = posedOrigin(b, i);
+        gaps.push(Math.hypot(o[0] - (tb.worldX + travel[i]![0]), o[1] - (tb.worldY + travel[i]![1])));
         const tx = tb.worldX + travel[i]![0] + (end[i]![0] - anchor[i]![0]) * s;
         const ty = tb.worldY + travel[i]![1] - (end[i]![1] - anchor[i]![1]) * s;
         const d = Math.hypot(tx - o[0], ty - o[1]);
@@ -1503,6 +1539,7 @@ 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);
+      reachGaps.set(c.name, gaps);
       // #236: the aim as reached, before its own range clamp, beside the pair's own angle (a reading).
       reachAims.set(c.name, { aim: [...angles], pair: Array.from({ length: n }, (_, i) => pictureAngle(anchor[i]!, end[i]!)), length: median(Array.from({ length: n }, (_, i) => Math.hypot(end[i]![0] - anchor[i]![0], end[i]![1] - anchor[i]![1]) * s)) });
     };
@@ -3087,6 +3124,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   if (headNodTrack !== null) tracks.push(headNodTrack);
   tracks.push(...sw.offsetTracks, ...sw.slotTracks);
   const reach = reachReadings(rest, map, tracks, reachAims, t?.bone ?? null);
+  const reachOrigin = reachOrigins(rest, map, reachAims, reachGaps, t?.bone ?? null);
 
   const pivot = pivotOf(rest, t?.bone ?? null, legs);
   const pelvis = pelvisReadingOf(pelvisChain, opts.pelvis, track, fromTrack, tracks);
@@ -3099,8 +3137,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   return {
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale, scaleFit,
-    switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, segments, legStraight, rigLeg, scales, feet, planted: plantOn, stance, floor, blendHold, closure, openDrift, ankles, pivot, raised, byHip, face, body, figureScale, headNod: headNodReading, nodSkipped, reach, pelvis,
+    switches: sw.switches, switchRuns: sw.runs, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
+    legScale, segments, legStraight, rigLeg, scales, feet, planted: plantOn, stance, floor, blendHold, closure, openDrift, ankles, pivot, raised, byHip, face, body, figureScale, headNod: headNodReading, nodSkipped, reach, reachOrigin, pelvis,
   };
 }
 
@@ -3209,6 +3247,47 @@ function reachReadings(rest: Rest, map: JointMap, tracks: ReadonlyArray<MotionTr
   return out;
 }
 
+/**
+ * #282: a reach bone whose origin sits more than this fraction of the segment
+ * from the source joint is warned. The aim from an origin a fraction f up the
+ * pair turns about 1 ÷ (1 − f) times the pair's turn (#236's lever: the example
+ * wave's trunk, f = 0.5, measured 2.00×); 0.2 is 1.25×, a quarter more turn
+ * than the pose has.
+ */
+export const REACH_ORIGIN_WARN = 0.2;
+
+/** #282: each reach chain's origin against the anchor's, at setup and as posed, in map order. */
+function reachOrigins(rest: Rest, map: JointMap, aims: ReadonlyMap<string, { length: number }>, gaps: ReadonlyMap<string, number[]>, anchor: string | null): ReachOrigin[] {
+  const out: ReachOrigin[] = [];
+  if (anchor === null) return out;
+  const a0 = rest.get(anchor)!;
+  for (const c of map.chains) {
+    const got = aims.get(c.name);
+    const g = gaps.get(c.name);
+    if (!c.reach || got === undefined || g === undefined) continue;
+    const b = c.bones[0]!;
+    const bo = rest.get(b)!;
+    const setup = r3(Math.hypot(bo.worldX - a0.worldX, bo.worldY - a0.worldY));
+    let frame = 0;
+    for (let i = 1; i < g.length; i++) if (g[i]! > g[frame]!) frame = i;
+    const max = r3(g[frame] ?? 0);
+    const segment = r3(got.length);
+    const ofSegment = got.length > 0 ? r3(Math.max(setup, max) / got.length) : 0;
+    out.push({ chain: c.name, bone: b, joints: [c.joints[0]!, c.joints[1]!], anchor, setup, posed: { max, frame }, segment, ofSegment, warn: ofSegment > REACH_ORIGIN_WARN, threshold: REACH_ORIGIN_WARN });
+  }
+  return out;
+}
+
+/** #282: the `REACH-ORIGIN` line, one per reach chain. */
+export function reachOriginLine(e: ReachOrigin, times: readonly number[]): string {
+  return `chain "${e.chain}" bone "${e.bone}" (${e.joints[0]} → ${e.joints[1]}): its origin ${e.setup.toFixed(2)} units from the source joint ${e.joints[0]} (bone "${e.anchor}"'s origin) at setup, up to ${e.posed.max.toFixed(2)} on the frames (frame ${e.posed.frame}, t=${times[e.posed.frame]!.toFixed(3)}s): ${e.ofSegment.toFixed(3)} of the ${e.segment.toFixed(2)}-unit segment`;
+}
+
+/** #282: the WARN of a reach chain whose origin sits past REACH_ORIGIN_WARN of the segment. */
+export function reachOriginWarn(e: ReachOrigin): string {
+  return `REACH_ORIGIN: chain "${e.chain}" bone "${e.bone}" starts ${e.ofSegment.toFixed(3)} of the segment from ${e.joints[0]}, past ${e.threshold.toFixed(2)}: re-aimed from there, it turns more than the pair (JITTER bone "${e.bone}"); "reach": false follows the measured angle`;
+}
+
 /** The `REACH` line of a reach chain whose aim departs from its pair (#236). */
 export function reachCostLine(e: ReachReading, times: readonly number[]): string {
   const f = (v: number | null) => (v === null ? 'not measured' : `${v.toFixed(4)}°/f²`);