@rig-c/pose 0.18.0 → 0.20.0

package/src/legs.ts

@@ -24,15 +24,19 @@
  * **Planted feet.** The hip is no longer the pose's mid_hip travel scaled. On
  * every frame one foot supports: the one whose reference ankle is lower in the
  * picture, changing only when the other ankle has been ≥ `PLANT_SWITCH` leg
- * lengths lower for ≥ `PLANT_SWITCH_SECONDS`. The supporting foot is held where
+ * lengths lower for ≥ `PLANT_SWITCH_SECONDS`, and taking support from the frame
+ * it crossed that margin once confirmed (rig-c/pose#102). The supporting foot is held where
  * it was on the frame it took support, moved in y onto the one floor every span
  * shares (rig-c/pose#85, `plantHip`), and the hip is placed so it stays there,
  * through the posed (scaled) legs. A change of support blends the two
- * derivations over `PLANT_BLEND` frames. A jump — both ankles and mid_hip more
+ * derivations in y over `PLANT_BLEND` frames while taking the new derivation's x
+ * immediately (rig-c/pose#102). A jump — both ankles and mid_hip more
  * than `JUMP_RISE` leg lengths above their rolling floor (the 95th-percentile
- * picture y over ± `FLOOR_SECONDS`), for ≥ `JUMP_FRAMES` frames — releases the
- * plant: the hip follows the pose's travel from where it was, and re-plants on
- * landing. A step does too: while the supporting ankle moves more than
+ * picture y over ± `FLOOR_SECONDS`), for ≥ `JUMP_FRAMES` frames, excluding a
+ * hand-over whose back ankle stays up and holds its height in y (`< STILL_SPEED`
+ * for `STILL_FRAMES` frames) when the front foot lands (a raised heel,
+ * rig-c/pose#101) — releases the plant: the hip follows the pose's travel from
+ * where it was, and re-plants on landing. A step does too: while the supporting ankle moves more than
  * `STEP_SPEED` leg lengths a frame its plant is released, the other foot takes
  * support if it is planted (not released, not moving) and otherwise the hip
  * follows the pose; the released ankle may support again once it has moved
@@ -264,13 +268,16 @@ export interface LegScale {
   high: Array<[number, number]>;
   /** The scale keyed on each frame (clamped). */
   scale: number[];
+  /** The scale the pose asked for on each frame before the clamp floor (`min(ratio, limits[1])`, rig-c/pose#107). */
+  asked: number[];
 }
 
-/** One segment's scale per frame: picture length ÷ its 95th percentile, clamped; and the runs clamped. */
+/** One segment's scale per frame: picture length ÷ its 95th percentile, clamped; its asked scale without the clamp floor (#107); and the runs clamped. */
 export function legScaleOf(lengths: readonly number[], limits: [number, number]): Omit<LegScale, 'chain' | 'bone' | 'joints'> {
   const straight = percentile(lengths, STRAIGHT_PERCENTILE);
   const ratio = lengths.map((l) => l / straight);
   const scale = ratio.map((r) => Math.min(Math.max(r, limits[0]), limits[1]));
+  const asked = ratio.map((r) => Math.min(r, limits[1]));
   const sorted = [...ratio].sort((a, b) => a - b);
   const mid = sorted.length >> 1;
   const median = sorted.length % 2 === 1 ? sorted[mid]! : (sorted[mid - 1]! + sorted[mid]!) / 2;
@@ -281,6 +288,7 @@ export function legScaleOf(lengths: readonly number[], limits: [number, number])
     low: runs(ratio.map((r) => r < limits[0])),
     high: runs(ratio.map((r) => r > limits[1])),
     scale,
+    asked,
   };
 }
 
@@ -337,10 +345,18 @@ export interface Feet {
   /**
    * rig-c/pose#113, read from the lower ankle: each run of frames whose
    * supporting side differs from the reading before #113 (`was`, `now`; null:
-   * no foot supports). Absent where the rule does not apply (in place, or
+   * no foot is planted). Absent where the rule does not apply (in place, or
    * without `lowerAnkle`).
    */
   lowered?: Lowered[];
+  /**
+   * rig-c/pose#119: runs of frames after a jump or a release where no foot is
+   * planted because the only foot free under #113 is the higher one, and the
+   * lower foot supports as a tracked foot (its x follows its own scaled ankle
+   * track, its y sits on #85's floor) until a foot plants. Absent where the
+   * rule does not apply.
+   */
+  tracked?: Array<{ side: Side; frames: [number, number] }>;
 }
 
 /** A run of frames whose support the lower-ankle rule (rig-c/pose#113) reads differently from the reading before it. */
@@ -381,7 +397,9 @@ export function rollingFloor(ys: readonly number[], times: readonly number[]): n
  * other ankle has been that much lower for `PLANT_SWITCH_SECONDS` hands support
  * to it when it is free (as before) and is otherwise released (the hip follows
  * the pose until a foot may take support). Steps and jumps are read as before.
- * The frames whose support this changes are `lowered`.
+ * The frames whose support this changes are `lowered`. On a frame where no foot
+ * is planted because the only foot free is the higher one (rig-c/pose#119), the
+ * lower foot is tracked (`tracked`).
  */
 export function supportsOf(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, readonly Pt[]>, times: readonly number[], secondsOf: (run: [number, number]) => number, inPlace = false, lowerAnkle = false): Feet {
   if (inPlace || !lowerAnkle) return readSupports(ankle, hip, times, secondsOf, inPlace, false).feet;
@@ -405,6 +423,9 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
   for (const s of SIDES) legLength[s] = percentile(ankle[s].map((a, i) => Math.hypot(a[0] - hip[s][i]![0], a[1] - hip[s][i]![1])), 0.5);
   const mean = (legLength.r + legLength.l) / 2;
   // A jump: both ankles and mid_hip above their rolling floors, for ≥ JUMP_FRAMES frames.
+  // #101: at a hand-over the front foot has not landed yet while the back ankle lifts its heel; when
+  // the front foot lands (the first frame after its lifted run) while the back ankle stays up, a back
+  // ankle that holds its height in y (< STILL_SPEED a frame for STILL_FRAMES frames) is a raised heel.
   const midY = hip.r.map((h, i) => (h[1] + hip.l[i]![1]) / 2);
   const rises: Array<{ ys: number[]; unit: number }> = [
     { ys: ankle.r.map((a) => a[1]), unit: legLength.r },
@@ -415,8 +436,23 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     const floor = rollingFloor(ys, times);
     return ys.map((y, i) => floor[i]! - y > JUMP_RISE * unit);
   });
+  const ankleRuns = { r: runs(up[0]!), l: runs(up[1]!) };
+  const stillY = (s: Side, from: number): boolean => {
+    if (from + STILL_FRAMES > n) return false;
+    for (let k = from; k < from + STILL_FRAMES; k++) {
+      if (!up[s === 'r' ? 0 : 1]![k] || Math.abs(ankle[s][k]![1] - ankle[s][k - 1]![1]) / legLength[s] >= STILL_SPEED) return false;
+    }
+    return true;
+  };
+  const raisedHeel = (a: number, b: number): boolean => {
+    const rSpan = ankleRuns.r.find(([s, e]) => s <= a && b <= e)!;
+    const lSpan = ankleRuns.l.find(([s, e]) => s <= a && b <= e)!;
+    if (rSpan[1] === lSpan[1]) return false;
+    const [fSpan, back]: [[number, number], Side] = rSpan[1] < lSpan[1] ? [rSpan, 'l'] : [lSpan, 'r'];
+    return stillY(back, fSpan[1] + 1);
+  };
   const lifted = Array.from({ length: n }, (_, i) => up.every((u) => u[i]));
-  const jumps = runs(lifted).filter(([a, b]) => b - a + 1 >= JUMP_FRAMES);
+  const jumps = runs(lifted).filter(([a, b]) => b - a + 1 >= JUMP_FRAMES && !raisedHeel(a, b));
   const jump = new Array<boolean>(n).fill(false);
   for (const [a, b] of jumps) for (let i = a; i <= b; i++) jump[i] = true;
   // Ankle speeds, leg lengths a frame (0 on the first frame).
@@ -430,11 +466,13 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     return true;
   };
   const support: Array<Side | null> = new Array<Side | null>(n).fill(null);
+  const trkAt: Array<Side | null> = new Array<Side | null>(n).fill(null);
   const changes: Feet['changes'] = [];
   const steps: Step[] = [];
   const open: Partial<Record<Side, Step>> = {};
   let cur: Side | null = null;
   let lowerFrom = -1;
+  let freeFrom = -1;
   const released: number[] = [];
   const lower = (cands: Side[], i: number): Side => (cands.length === 2 ? (ankle.l[i]![1] > ankle.r[i]![1] ? 'l' : 'r') : cands[0]!);
   for (let i = 0; i < n; i++) {
@@ -450,6 +488,7 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     if (jump[i]) {
       cur = null;
       lowerFrom = -1;
+      freeFrom = -1;
       continue;
     }
     const free = (s: Side) => open[s] === undefined && !moving(s, i);
@@ -465,28 +504,44 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
       if (to !== null) changes.push({ frame: i, from: cur, to });
       cur = to;
       lowerFrom = -1;
+      freeFrom = -1;
     } else if (cur === null) {
       const cands = SIDES.filter(may);
       if (cands.length > 0) {
         cur = lower(cands, i);
         changes.push({ frame: i, from: null, to: cur });
         lowerFrom = -1;
+        freeFrom = -1;
       }
     } else {
       const other: Side = cur === 'r' ? 'l' : 'r';
       if ((free(other) || lowerAnkle) && higher(cur)) {
         if (lowerFrom < 0) lowerFrom = i;
-        if (secondsOf([lowerFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
-          if (free(other)) {
-            changes.push({ frame: i, from: cur, to: other });
+        if (free(other)) {
+          if (freeFrom < 0) freeFrom = i;
+          // #102: once confirmed over PLANT_SWITCH_SECONDS, the incoming foot takes support from the landing frame it crossed the margin on.
+          if (secondsOf([freeFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
+            for (let k = freeFrom; k < i; k++) support[k] = other;
+            changes.push({ frame: freeFrom, from: cur, to: other });
             cur = other;
-          } else {
+            lowerFrom = -1;
+            freeFrom = -1;
+          }
+        } else {
+          freeFrom = -1;
+          if (secondsOf([lowerFrom, i]) >= PLANT_SWITCH_SECONDS - 1e-9) {
             cur = null; // #113: the lower foot may not take support (released, or moving); neither foot supports
             released.push(i);
+            lowerFrom = -1;
           }
-          lowerFrom = -1;
         }
-      } else lowerFrom = -1;
+      } else {
+        lowerFrom = -1;
+        freeFrom = -1;
+      }
+    }
+    if (lowerAnkle && cur === null && released[released.length - 1] !== i && SIDES.some((x) => free(x) && higher(x))) {
+      trkAt[i] = lower(['r', 'l'], i);
     }
     support[i] = cur;
   }
@@ -498,7 +553,15 @@ function readSupports(ankle: Record<Side, readonly Pt[]>, hip: Record<Side, read
     if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
     else supports.push({ side: s, frames: [i, i] });
   }
-  return { feet: { legLength, support, supports, jumps, steps, changes }, released };
+  const tracked: Array<{ side: Side; frames: [number, number] }> = [];
+  for (let i = 0; i < n; i++) {
+    const s = trkAt[i];
+    if (s === null || s === undefined) continue;
+    const last = tracked[tracked.length - 1];
+    if (last !== undefined && last.side === s && last.frames[1] === i - 1) last.frames[1] = i;
+    else tracked.push({ side: s, frames: [i, i] });
+  }
+  return { feet: { legLength, support, supports, jumps, steps, changes, ...(tracked.length > 0 ? { tracked } : {}) }, released };
 }
 
 /** One support span's shift onto the floor (rig-c/pose#85): its side, its frames, and floor − its planted height, world units. */
@@ -515,6 +578,8 @@ export interface Floor {
   shifts: FloorShift[];
 }
 
+let trackFn: ((i: number, s: Side) => number) | undefined;
+
 /**
  * The hip's world origin on every frame, from the supporting foot (header),
  * with every support span on one floor (rig-c/pose#85). `offset(i, side)` is
@@ -528,9 +593,11 @@ export interface Floor {
  * floor is `floor` when given (`--floor`, world units), and otherwise the median
  * of the spans' planted heights; each span's anchor moves in y by floor − its
  * planted height, and the hip with it, so everything above follows. A change of
- * support still blends the two derivations over `PLANT_BLEND` frames, now
- * between two spans on the floor; a jump follows the pose's travel from the hip
- * it left (on the floor) and lands on the floor. On a blend frame the hip is
+ * support still blends the two derivations' y over `PLANT_BLEND` frames, now
+ * between two spans on the floor, while holding the planted foot's x from the
+ * frame it lands on (#102); a jump follows the pose's travel from the hip
+ * it left (on the floor), carried so the landing frame meets the floor and no
+ * frame inside the flight puts a foot below it (#103). On a blend frame the hip is
  * between the two derivations, so the supporting ankle is off its anchor:
  * `blends` lists those frames with the anchor's y, and `holdBlend` stretches
  * the supporting leg to keep it there. Null `floor` in the result: there is no
@@ -539,18 +606,24 @@ export interface Floor {
  * `follow(i, side)` (#92, an in-place sequence): the supporting ankle's track,
  * world x. A plant's anchor x then moves by follow(i) − follow(the frame it
  * planted), and the loop is closed (`closeLoop`, `closure` in the result; null
- * without `follow`).
+ * without `follow`). `track(i, side)` (#119): the same world-x ankle track for
+ * `feet.tracked` frames on a sequence not declared in place.
  */
-export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floor?: number, follow?: (i: number, s: Side) => number): { hip: Pt[]; floor: Floor | null; blends: BlendFrame[]; closure: Closure | null } {
-  const picture = placeHip(feet, offset, travel, start, null, follow);
-  const heights = feet.supports.map((sp) => picture.anchors.get(sp.frames[0]));
-  if (heights.length === 0) return { hip: picture.hip, floor: null, blends: picture.blends, closure: null };
-  if (heights.some((h) => h === undefined)) throw new Error('plantHip: a support span starts on a frame no plant started on');
-  const y = floor ?? percentile(heights as number[], 0.5);
-  const shifts = feet.supports.map((sp, k) => ({ side: sp.side, frames: [sp.frames[0], sp.frames[1]] as [number, number], shift: y - heights[k]! }));
-  const placed = placeHip(feet, offset, travel, start, y, follow);
-  const closure = follow === undefined ? null : closeLoop(placed.hip);
-  return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
+export function plantHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: number) => Pt, start: Pt, floor?: number, follow?: (i: number, s: Side) => number, track?: (i: number, s: Side) => number): { hip: Pt[]; floor: Floor | null; blends: BlendFrame[]; closure: Closure | null } {
+  trackFn = track;
+  try {
+    const picture = placeHip(feet, offset, travel, start, null, follow);
+    const heights = feet.supports.map((sp) => picture.anchors.get(sp.frames[0]));
+    if (heights.length === 0) return { hip: picture.hip, floor: null, blends: picture.blends, closure: null };
+    if (heights.some((h) => h === undefined)) throw new Error('plantHip: a support span starts on a frame no plant started on');
+    const y = floor ?? percentile(heights as number[], 0.5);
+    const shifts = feet.supports.map((sp, k) => ({ side: sp.side, frames: [sp.frames[0], sp.frames[1]] as [number, number], shift: y - heights[k]! }));
+    const placed = placeHip(feet, offset, travel, start, y, follow);
+    const closure = follow === undefined ? null : closeLoop(placed.hip);
+    return { hip: placed.hip, floor: { y, given: floor !== undefined, shifts }, blends: placed.blends, closure };
+  } finally {
+    trackFn = undefined;
+  }
 }
 
 /** In place (rig-c/pose#92): the hip's x travel from the first frame to the last before the loop was closed, world units, and the frames it was spread over. */
@@ -589,8 +662,14 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
   const hip: Pt[] = [];
   const anchors = new Map<number, number>();
   const blends: BlendFrame[] = [];
-  /** How the hip is derived on a frame: held over a foot's anchor, or carried by the pose's travel from a frame's hip. */
-  type Mode = { kind: 'plant'; side: Side; anchor: Pt; from: number } | { kind: 'travel'; from: number; at: Pt };
+  const tracked = new Array<Side | null>(n).fill(null);
+  for (const t of feet.tracked ?? []) for (let i = t.frames[0]; i <= t.frames[1]; i++) tracked[i] = t.side;
+  const trkX = trackFn ?? follow;
+  /** How the hip is derived on a frame: held over a foot's anchor, tracking the lower foot on the floor (#119), or carried by the pose's travel from a frame's hip (and for a jump against `floorY`, carried so the landing frame meets the floor and frames inside the flight never go below it, #103). */
+  type Mode =
+    | { kind: 'plant'; side: Side; anchor: Pt; from: number }
+    | { kind: 'track'; side: Side; anchor: Pt; from: number; at: Pt }
+    | { kind: 'travel'; from: number; at: Pt; end?: number; land?: number; carry?: number };
   const of = (mode: Mode, i: number): Pt => {
     if (mode.kind === 'plant') {
       const o = offset(i, mode.side);
@@ -598,9 +677,40 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
       const dx = follow === undefined ? 0 : follow(i, mode.side) - follow(mode.from, mode.side);
       return [mode.anchor[0] + dx - o[0], mode.anchor[1] - o[1]];
     }
+    if (mode.kind === 'track') {
+      const o = offset(i, mode.side);
+      const dx = trkX === undefined ? o[0] - offset(mode.from, mode.side)[0] : trkX(i, mode.side) - trkX(mode.from, mode.side);
+      const y = floorY === null ? mode.at[1] + travel(i)[1] - travel(mode.from)[1] : mode.anchor[1] - o[1];
+      return [mode.anchor[0] + dx - o[0], y];
+    }
     const a = travel(i);
     const b = travel(mode.from);
-    return [mode.at[0] + a[0] - b[0], mode.at[1] + a[1] - b[1]];
+    let y = mode.at[1] + a[1] - b[1];
+    if (mode.carry !== undefined && mode.land !== undefined && mode.end !== undefined && floorY !== null) {
+      if (mode.land < n && i <= mode.land && mode.land > mode.from) {
+        y += mode.carry * ((i - mode.from) / (mode.land - mode.from));
+      }
+      if (i <= mode.end) {
+        y = Math.max(y, floorY - Math.min(offset(i, 'r')[1], offset(i, 'l')[1]));
+      }
+    }
+    return [mode.at[0] + a[0] - b[0], y];
+  };
+  /** A travel span from `startFrame` off frame `from`'s hip `at`: carried to meet `floorY` at landing when it contains a jump (#103). */
+  const makeTravel = (startFrame: number, from: number, at: Pt): Mode => {
+    let end = startFrame;
+    while (end + 1 < n && (feet.support[end + 1] ?? null) === null && (tracked[end + 1] ?? null) === null) end++;
+    const isJump = floorY !== null && feet.jumps.some(([ja, jb]) => ja <= end && jb >= startFrame);
+    if (!isJump) return { kind: 'travel', from, at };
+    const land = end + 1;
+    let carry = 0;
+    if (land < n) {
+      const landSide = (feet.support[land] ?? tracked[land] ?? null)!;
+      const rawLandY = at[1] + travel(land)[1] - travel(from)[1];
+      const targetLandY = floorY - offset(land, landSide)[1];
+      carry = targetLandY - rawLandY;
+    }
+    return { kind: 'travel', from, at, end, land, carry };
   };
   /** A plant from frame i: its anchor's x where the foot is, its y there or on the floor. */
   const plant = (i: number, side: Side, at: Pt): Mode => {
@@ -612,29 +722,45 @@ function placeHip(feet: Feet, offset: (i: number, s: Side) => Pt, travel: (i: nu
   let blendAt = -1;
   for (let i = 0; i < n; i++) {
     const s = feet.support[i] ?? null;
+    const tr = s === null ? (tracked[i] ?? null) : null;
     if (i === 0) {
-      if (s === null) mode = { kind: 'travel', from: 0, at: start };
-      else {
+      if (s !== null) {
         const o = offset(0, s);
         mode = plant(0, s, [start[0] + o[0], start[1] + o[1]]);
+      } else if (tr !== null) {
+        const o = offset(0, tr);
+        mode = { kind: 'track', side: tr, anchor: [start[0] + o[0], floorY ?? (start[1] + o[1])], from: 0, at: start };
+      } else {
+        mode = makeTravel(0, 0, start);
       }
-    } else if (s === null && mode!.kind === 'plant') {
-      mode = { kind: 'travel', from: i - 1, at: hip[i - 1]! };
+    } else if (s !== null) {
+      if (mode!.kind !== 'plant' || mode!.side !== s) {
+        // The new support is held where it is on this frame, under the hip the old derivation gives here.
+        const here = of(mode!, i);
+        const o = offset(i, s);
+        from = mode;
+        mode = plant(i, s, [here[0] + o[0], here[1] + o[1]]);
+        blendAt = i;
+      }
+    } else if (tr !== null) {
+      if (mode!.kind !== 'track' || mode!.side !== tr) {
+        const prev = hip[i - 1]!;
+        const o = offset(i - 1, tr);
+        mode = { kind: 'track', side: tr, anchor: [prev[0] + o[0], floorY ?? (prev[1] + o[1])], from: i - 1, at: prev };
+        from = null;
+        blendAt = -1;
+      }
+    } else if (mode!.kind !== 'travel') {
+      mode = makeTravel(i, i - 1, hip[i - 1]!);
       from = null;
       blendAt = -1;
-    } else if (s !== null && (mode!.kind === 'travel' || (mode as { side: Side }).side !== s)) {
-      // The new support is held where it is on this frame, under the hip the old derivation gives here.
-      const here = of(mode!, i);
-      const o = offset(i, s);
-      from = mode;
-      mode = plant(i, s, [here[0] + o[0], here[1] + o[1]]);
-      blendAt = i;
     }
     const to = of(mode!, i);
     if (from !== null && i - blendAt < PLANT_BLEND) {
       const w = (i - blendAt + 1) / (PLANT_BLEND + 1);
       const f = of(from, i);
-      hip.push([f[0] + (to[0] - f[0]) * w, f[1] + (to[1] - f[1]) * w]);
+      // #102: blend y only; x takes the new derivation immediately so the planted foot does not slide across the blend.
+      hip.push([to[0], f[1] + (to[1] - f[1]) * w]);
       const m = mode!;
       if (m.kind === 'plant') blends.push({ frame: i, side: m.side, y: m.anchor[1] });
     } else {
@@ -783,10 +909,12 @@ export interface StancePosed {
 export function stanceOf(feet: Feet, ankle: Record<Side, readonly Pt[]>, tolerance: number, posed: (i: number) => StancePosed, secondsOf: (run: [number, number]) => number, lower?: StanceLower): Stance {
   const n = feet.support.length;
   const stretch: Stance['stretch'] = new Array(n).fill(null);
+  const tracked = new Array<Side | null>(n).fill(null);
+  for (const t of feet.tracked ?? []) for (let i = t.frames[0]; i <= t.frames[1]; i++) tracked[i] = t.side;
   type Read = { state: StanceState; side: Side; height: number };
   const read: Array<Read | null> = new Array<Read | null>(n).fill(null);
   for (let i = 0; i < n; i++) {
-    const s = feet.support[i] ?? null;
+    const s = feet.support[i] ?? tracked[i] ?? null;
     if (s === null) continue;
     const f: Side = s === 'r' ? 'l' : 'r';
     read[i] = { state: 'both', side: f, height: (ankle[s][i]![1] - ankle[f][i]![1]) / feet.legLength[f] };

package/src/pose.ts

@@ -74,36 +74,63 @@ export interface CleanSpike {
  * pelvis line off the picture (`tools/pelvis.py`, after clean) and turned the
  * hip pair to a measured angle on every frame. The exact shape:
  *
- *   { by: "measured", method: string,
- *     read: Run[], interpolated: Run[], held: Run[],
+ *   { by: "measured", method: string, fit?: { frames, gain, corr },
+ *     read: Run[], interpolated: Run[], scaled?: Run[], held: Run[], unmeasured?: Run[],
  *     declined: Array<{ frames: Run, why: string }> }      Run = [first, last]
  *
  * `method` names the reading. Runs are integer frame indices inside the
  * sequence, first ≤ last, increasing and not overlapping within each list.
  * Every frame of the sequence is in exactly one of `read` (the frame's own
  * reading), `interpolated` (a declined frame between two reads close in time,
- * the angle interpolated) and `held` (any other declined frame, the earlier
- * read carried to the end of its run; at the clip's start, the later read). `declined` lists, with the reason, exactly the frames that are
- * interpolated or held. Anything else is refused by name (POSE_CLEANED).
+ * the angle interpolated), `scaled` (#106: a longer declined run taking the
+ * detector hip line scaled by `fit.gain`), `held` (the earlier read carried to
+ * the end of its run; at the clip's start, the later read) and `unmeasured`
+ * (#106: a longer declined run when `fit.corr` < 0.9). `declined` lists, with
+ * the reason, exactly the non-read frames. Anything else is refused by name
+ * (POSE_CLEANED).
  */
 export type Run = [number, number];
+export interface PelvisFit {
+  frames: number;
+  gain: number | null;
+  corr: number | null;
+}
 export type HipsInferred =
   | { by: 'declared' }
-  | { by: 'measured'; method: string; read: Run[]; interpolated: Run[]; held: Run[]; declined: Array<{ frames: Run; why: string }> };
+  | {
+      by: 'measured';
+      method: string;
+      fit?: PelvisFit;
+      read: Run[];
+      interpolated: Run[];
+      scaled?: Run[];
+      held: Run[];
+      unmeasured?: Run[];
+      declined: Array<{ frames: Run; why: string }>;
+    };
 
 /** A copy of the record, in the writer's key order. */
 export function copyHipsInferred(h: HipsInferred): HipsInferred {
   const runs = (rs: Run[]): Run[] => rs.map(([a, b]) => [a, b]);
-  return h.by === 'declared'
-    ? { by: 'declared' }
-    : { by: 'measured', method: h.method, read: runs(h.read), interpolated: runs(h.interpolated), held: runs(h.held), declined: h.declined.map((d) => ({ frames: [d.frames[0], d.frames[1]], why: d.why })) };
+  if (h.by === 'declared') return { by: 'declared' };
+  return {
+    by: 'measured',
+    method: h.method,
+    ...(h.fit !== undefined ? { fit: { frames: h.fit.frames, gain: h.fit.gain, corr: h.fit.corr } } : {}),
+    read: runs(h.read),
+    interpolated: runs(h.interpolated),
+    ...(h.scaled !== undefined ? { scaled: runs(h.scaled) } : {}),
+    held: runs(h.held),
+    ...(h.unmeasured !== undefined ? { unmeasured: runs(h.unmeasured) } : {}),
+    declined: h.declined.map((d) => ({ frames: [d.frames[0], d.frames[1]], why: d.why })),
+  };
 }
 
-/** The frames a `measured` record gives an angle on (read, interpolated, held), as a set; null for any other record or none. */
+/** The frames a `measured` record gives an angle on (read, interpolated, scaled, held), as a set; null for any other record or none. */
 export function measuredFrames(h: HipsInferred | undefined): Set<number> | null {
   if (h === undefined || h.by !== 'measured') return null;
   const out = new Set<number>();
-  for (const rs of [h.read, h.interpolated, h.held]) for (const [a, b] of rs) for (let f = a; f <= b; f++) out.add(f);
+  for (const rs of [h.read, h.interpolated, h.scaled ?? [], h.held]) for (const [a, b] of rs) for (let f = a; f <= b; f++) out.add(f);
   return out;
 }
 
@@ -123,6 +150,7 @@ export interface HoldParams {
 export interface CleanHold {
   joint: Body18;
   frames: [number, number];
+  excursion?: [number, number];
   jitter: { before: number | null; after: number | null };
 }
 /**
@@ -405,10 +433,16 @@ function readCleaned(p: Problems, where: string, c: unknown, frames: number | nu
         p.add('POSE_CLEANED', `${hw} is ${typeName(h)}; a hold is { joint, frames: [first, last], jitter: { before, after } }`);
         return;
       }
-      refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['joint', 'frames', 'jitter']);
+      refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['joint', 'frames', 'excursion', 'jitter']);
       if (typeof h.joint !== 'string' || !isBody18(h.joint)) p.add('POSE_CLEANED', `${hw} "joint" is ${typeName(h.joint)}; it must be a body-18 joint: ${BODY18.join(', ')}`);
       const f = h.frames;
-      if (!(Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number))) p.add('POSE_CLEANED', `${hw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      const fOk = Array.isArray(f) && f.length === 2 && frameOk(f[0]) && frameOk(f[1]) && (f[0] as number) <= (f[1] as number);
+      if (!fOk) p.add('POSE_CLEANED', `${hw} "frames" is ${typeName(f)}; it must be [first, last], frame indices in ${frameRange}, first ≤ last`);
+      if ('excursion' in h) {
+        const ex = h.excursion;
+        const exOk = Array.isArray(ex) && ex.length === 2 && frameOk(ex[0]) && frameOk(ex[1]) && (ex[0] as number) <= (ex[1] as number) && (!fOk || ((f[0] as number) < (ex[0] as number) && (ex[1] as number) < (f[1] as number)));
+        if (!exOk) p.add('POSE_CLEANED', `${hw} "excursion" is ${typeName(ex)}; it must be [first, last], frame indices strictly inside "frames", first ≤ last`);
+      }
       const j = h.jitter;
       if (!isObject(j)) p.add('POSE_CLEANED', `${hw} "jitter" is ${typeName(j)}; it must be { before, after }`);
       else {
@@ -489,10 +523,22 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     return;
   }
   const before = p.list.length;
-  const CLASSES = ['read', 'interpolated', 'held'] as const;
-  refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by', 'method', ...CLASSES, 'declined']);
-  for (const k of ['method', ...CLASSES, 'declined']) if (!(k in h)) p.add('POSE_CLEANED', `${hw} has no "${k}"; a measured record is ${measuredShape}`);
+  const REQ_CLASSES = ['read', 'interpolated', 'held'] as const;
+  const ALL_CLASSES = ['read', 'interpolated', 'scaled', 'held', 'unmeasured'] as const;
+  refuseUnknownKeys(p, 'POSE_CLEANED', hw, h, ['by', 'method', 'fit', ...ALL_CLASSES, 'declined']);
+  for (const k of ['method', ...REQ_CLASSES, 'declined']) if (!(k in h)) p.add('POSE_CLEANED', `${hw} has no "${k}"; a measured record is ${measuredShape}`);
   if ('method' in h && !(typeof h.method === 'string' && h.method.trim() !== '')) p.add('POSE_CLEANED', `${hw} "method" is ${typeName(h.method)}; it must be a non-empty string naming the reading`);
+  if ('fit' in h) {
+    const f = h.fit;
+    const fw = `${hw} "fit"`;
+    if (!isObject(f)) p.add('POSE_CLEANED', `${fw} is ${typeName(f)}; it must be { frames, gain, corr }`);
+    else {
+      refuseUnknownKeys(p, 'POSE_CLEANED', fw, f, ['frames', 'gain', 'corr']);
+      if (!(Number.isInteger(f.frames) && (f.frames as number) >= 0)) p.add('POSE_CLEANED', `${fw} "frames" is ${typeName(f.frames)}; it must be a whole number of frames ≥ 0`);
+      if (!(f.gain === null || (typeof f.gain === 'number' && Number.isFinite(f.gain)))) p.add('POSE_CLEANED', `${fw} "gain" is ${typeName(f.gain)}; it must be a finite number or null`);
+      if (!(f.corr === null || (typeof f.corr === 'number' && Number.isFinite(f.corr) && f.corr >= -1 && f.corr <= 1))) p.add('POSE_CLEANED', `${fw} "corr" is ${typeName(f.corr)}; it must be a correlation in [-1, 1] or null`);
+    }
+  }
   const range = `[0, ${frames === null ? 'the frame count' : frames - 1}]`;
   /** A run [first, last], or null after naming what is wrong with it. */
   const run = (v: unknown, rw: string): Run | null => {
@@ -524,8 +570,8 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
       if (cur.r[0] <= prev.r[1]) p.add('POSE_CLEANED', `${cur.w} [${cur.r[0]}, ${cur.r[1]}] starts at or before the end of ${prev.w} [${prev.r[0]}, ${prev.r[1]}]; ${what} runs must increase and not overlap`);
     }
   };
-  const classes: Record<(typeof CLASSES)[number], Named[]> = { read: [], interpolated: [], held: [] };
-  for (const c of CLASSES) {
+  const classes: Record<(typeof ALL_CLASSES)[number], Named[]> = { read: [], interpolated: [], scaled: [], held: [], unmeasured: [] };
+  for (const c of ALL_CLASSES) {
     if (!(c in h)) continue;
     const list = h[c];
     if (!Array.isArray(list)) {
@@ -560,12 +606,15 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     });
     ordered(declined, 'declined');
   }
-  // Across lists: the classes are disjoint, they cover every frame, and declined is exactly interpolated ∪ held.
-  for (let x = 0; x < CLASSES.length; x++) {
-    for (let y = x + 1; y < CLASSES.length; y++) {
-      for (const a of classes[CLASSES[x]!]) {
-        for (const b of classes[CLASSES[y]!]) {
-          if (a.r[0] <= b.r[1] && b.r[0] <= a.r[1]) p.add('POSE_CLEANED', `${a.w} [${a.r[0]}, ${a.r[1]}] and ${b.w} [${b.r[0]}, ${b.r[1]}] share frame(s) ${Math.max(a.r[0], b.r[0])}–${Math.min(a.r[1], b.r[1])}; a frame is one of read, interpolated and held`);
+  const has106 = 'scaled' in h || 'unmeasured' in h || 'fit' in h;
+  const classListLabel = has106 ? 'read, interpolated, scaled, held and unmeasured' : 'read, interpolated and held';
+  const filledLabel = has106 ? 'interpolated, scaled, held or unmeasured' : 'interpolated or held';
+  // Across lists: the classes are disjoint, they cover every frame, and declined is exactly the non-read classes.
+  for (let x = 0; x < ALL_CLASSES.length; x++) {
+    for (let y = x + 1; y < ALL_CLASSES.length; y++) {
+      for (const a of classes[ALL_CLASSES[x]!]) {
+        for (const b of classes[ALL_CLASSES[y]!]) {
+          if (a.r[0] <= b.r[1] && b.r[0] <= a.r[1]) p.add('POSE_CLEANED', `${a.w} [${a.r[0]}, ${a.r[1]}] and ${b.w} [${b.r[0]}, ${b.r[1]}] share frame(s) ${Math.max(a.r[0], b.r[0])}–${Math.min(a.r[1], b.r[1])}; a frame is one of ${classListLabel}`);
         }
       }
     }
@@ -586,21 +635,21 @@ function readHipsInferred(p: Problems, hw: string, h: unknown, frames: number |
     return out.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
   };
   const read = set(classes.read);
-  const filled = set([...classes.interpolated, ...classes.held]);
+  const nonRead = set([...classes.interpolated, ...classes.scaled, ...classes.held, ...classes.unmeasured]);
   const dec = set(declined);
   if (frames !== null) {
-    const none = Array.from({ length: frames }, (_, f) => f).filter((f) => !read.has(f) && !filled.has(f));
-    if (none.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(none)} are in none of read, interpolated and held; every frame of the sequence is one of them`);
+    const none = Array.from({ length: frames }, (_, f) => f).filter((f) => !read.has(f) && !nonRead.has(f));
+    if (none.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(none)} are in none of ${classListLabel}; every frame of the sequence is one of them`);
   }
   const both = [...dec].filter((f) => read.has(f)).sort((a, b) => a - b);
   if (both.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(both)} are both read and declined; a frame is read or declined, not both`);
-  const unfilled = [...dec].filter((f) => !read.has(f) && !filled.has(f)).sort((a, b) => a - b);
-  if (unfilled.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(unfilled)} are declined but neither interpolated nor held; a declined frame takes one of them`);
-  const undeclared = [...filled].filter((f) => !dec.has(f)).sort((a, b) => a - b);
-  if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are interpolated or held but not declined; only a frame the reading declined is filled, and "declined" says why`);
+  const unfilled = [...dec].filter((f) => !read.has(f) && !nonRead.has(f)).sort((a, b) => a - b);
+  if (unfilled.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(unfilled)} are declined but neither ${filledLabel}; a declined frame takes one of them`);
+  const undeclared = [...nonRead].filter((f) => !dec.has(f)).sort((a, b) => a - b);
+  if (undeclared.length > 0) p.add('POSE_CLEANED', `${hw}: frame(s) ${spans(undeclared)} are ${filledLabel} but not declined; only a frame the reading declined is filled, and "declined" says why`);
 }
 const holdParamsOf = (h: HoldParams | 'off'): HoldParams | 'off' => (h === 'off' ? 'off' : { speed: h.speed, reach: h.reach, minSeconds: h.minSeconds, blend: h.blend });
-const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: h.jitter.before, after: h.jitter.after } });
+const copyHold = (h: CleanHold): CleanHold => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], ...(h.excursion !== undefined ? { excursion: [h.excursion[0], h.excursion[1]] as [number, number] } : {}), jitter: { before: h.jitter.before, after: h.jitter.after } });
 const copyUnheld = (u: CleanUnheld): CleanUnheld => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value });
 
 function readJoints(p: Problems, pw: string, joints: unknown): Partial<Record<Body18, Joint>> {
@@ -794,7 +843,7 @@ export function writePoseSequence(seq: PoseSequence): string {
     params: { loop: c.params.loop, legs: c.params.legs, rest: c.params.rest, ...(c.params.hipsInferred !== undefined ? { hipsInferred: copyHipsInferred(c.params.hipsInferred) } : {}), ...(c.params.hold !== undefined ? { hold: holdParamsOf(c.params.hold) } : {}) },
     spikes: { found: c.spikes.found.map((s) => ({ frame: s.frame, joint: s.joint })), untested: [...c.spikes.untested] },
     jitter: { before: jit(c.jitter.before), after: jit(c.jitter.after) },
-    ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
+    ...(c.holds !== undefined ? { holds: c.holds.map((h) => ({ joint: h.joint, frames: [h.frames[0], h.frames[1]], ...(h.excursion !== undefined ? { excursion: [h.excursion[0], h.excursion[1]] } : {}), jitter: { before: jit(h.jitter.before), after: jit(h.jitter.after) } })) } : {}),
     ...(c.seams !== undefined ? { seams: c.seams.map((x) => ({ joint: x.joint, frame: x.frame, step: round(x.step, 4), gap: x.gap })) } : {}),
     ...(c.unheld !== undefined ? { unheld: c.unheld.map((u) => ({ joint: u.joint, frames: [u.frames[0], u.frames[1]], test: u.test, value: u.value === null ? null : round(u.value, 4) })) } : {}),
   };