@rig-c/pose 0.18.0 → 0.20.0

package/src/verify.ts

@@ -10,8 +10,8 @@
  */
 import { poseRawAnimation, poseRawSetup, type CompiledDocument, type RawBone } from 'rig-c/core';
 import type { Body18 } from './joints.ts';
-import { aimAngle, pointAt, type JointMap } from './map.ts';
-import type { HipsInferred, Joint, Run } from './pose.ts';
+import { aimAngle, aimEnds, pointAt, type JointMap } from './map.ts';
+import type { HipsInferred, Joint, PelvisFit, Run } from './pose.ts';
 import type { Retarget } from './retarget.ts';
 import { pictureAngle, pointOn, wrap } from './retarget.ts';
 
@@ -260,13 +260,25 @@ export interface Posture {
    */
   hipsInferred?: { frames: number; source: string };
   /**
-   * Present only when the hips were measured (#86, `hipsInferred.by` is
+   * Present only when the hips were measured (#86, #106, `hipsInferred.by` is
    * `measured`): the method, how many frames the tilt was read on — the
-   * record's read, interpolated and held frames with both hips good, each
-   * class counted — and the record's held spans. Any other frame with an
-   * inferred hip is left out and counted in `hipsInferred`.
+   * record's read, interpolated, scaled and held frames with both hips good,
+   * each class counted — and the record's spans. Any `unmeasured` frame (corr
+   * < 0.9) or other frame with an inferred hip is left out of `tilt`.
    */
-  tiltMeasured?: { method: string; frames: number; read: number; interpolated: number; held: number; heldSpans: Run[] };
+  tiltMeasured?: {
+    method: string;
+    frames: number;
+    read: number;
+    interpolated: number;
+    held: number;
+    heldSpans: Run[];
+    scaled?: number;
+    scaledSpans?: Run[];
+    unmeasured?: number;
+    unmeasuredSpans?: Run[];
+    fit?: PelvisFit;
+  };
   /**
    * Sway: the x-range of mid_hip − mid_shoulder, in rig units (the reference's
    * picture px × the figure scale) and in each body's own shoulder widths.
@@ -277,6 +289,81 @@ export interface Posture {
     ratio: number | null;
     ratioSw: number | null;
   } | null;
+  /**
+   * Present with `--plant-feet` when there is at least one support span (#107):
+   * per support span, the detrended (centred ±12-frame moving mean removed)
+   * vertical sd, rig/reference ratio and correlation for the hip, the neck, and
+   * eyes − neck.
+   */
+  bounce?: BounceSpan[];
+}
+
+export interface BounceMetric {
+  reference: number;
+  rig: number;
+  ratio: number | null;
+  corr: number | null;
+}
+
+export interface BounceSpan {
+  side: 'r' | 'l';
+  frames: [number, number];
+  hip: BounceMetric;
+  neck: BounceMetric;
+  eyesNeck: BounceMetric;
+}
+
+/** Half-window (frames each side; 25-frame centred window at 24 fps ≈ 1 s) for detrending a support span's bounce (#107). */
+export const POSTURE_DETREND_HALF_WINDOW = 12;
+
+function detrend(xs: readonly number[], w = POSTURE_DETREND_HALF_WINDOW): number[] {
+  const n = xs.length;
+  return xs.map((x, i) => {
+    const lo = Math.max(0, i - w);
+    const hi = Math.min(n - 1, i + w);
+    let sum = 0;
+    for (let k = lo; k <= hi; k++) sum += xs[k]!;
+    return x - sum / (hi - lo + 1);
+  });
+}
+
+function sdOf(xs: readonly number[]): number {
+  if (xs.length === 0) return 0;
+  const mean = xs.reduce((a, b) => a + b, 0) / xs.length;
+  let s2 = 0;
+  for (const x of xs) s2 += (x - mean) * (x - mean);
+  return Math.sqrt(s2 / xs.length);
+}
+
+function corrOf(a: readonly number[], b: readonly number[]): number | null {
+  if (a.length < 2 || a.length !== b.length) return null;
+  const ma = a.reduce((x, y) => x + y, 0) / a.length;
+  const mb = b.reduce((x, y) => x + y, 0) / b.length;
+  let num = 0;
+  let da = 0;
+  let db = 0;
+  for (let i = 0; i < a.length; i++) {
+    const xa = a[i]! - ma;
+    const xb = b[i]! - mb;
+    num += xa * xb;
+    da += xa * xa;
+    db += xb * xb;
+  }
+  const den = Math.sqrt(da * db);
+  return den > 1e-9 ? num / den : null;
+}
+
+function bounceMetric(ref: readonly number[], rig: readonly number[]): BounceMetric {
+  const dr = detrend(ref);
+  const dg = detrend(rig);
+  const sr = sdOf(dr);
+  const sg = sdOf(dg);
+  return {
+    reference: sr,
+    rig: sg,
+    ratio: sr > 1e-9 ? sg / sr : null,
+    corr: corrOf(dr, dg),
+  };
 }
 
 function rangeOf(xs: number[]): Range {
@@ -311,11 +398,12 @@ const medianOf = (xs: number[]): number => {
  * and the line counts the frames left out. Sway is read as before, inferred
  * hips included: it is a different measure, and the card leaves it as it is.
  *
- * Measured hips (#86, `measured`): the hips are inferred on every frame, and
- * turned to a measured angle: read off the picture, interpolated between two
- * close reads, or held from the earlier read. Those three are the measurement,
- * so the tilt is read on them; any other frame with an inferred hip is left
- * out and counted, as above. The line names the held spans.
+ * Measured hips (#86, #106, `measured`): the hips are inferred on every frame,
+ * and turned to a measured angle: read off the picture, interpolated between two
+ * close reads, scaled from the detector's hip line when `fit.corr >= 0.9`, or
+ * held from the earlier read. Those four are the measurement, so the tilt is
+ * read on them; any `unmeasured` frame (`fit.corr < 0.9`) or other frame with
+ * an inferred hip is left out and counted.
  */
 export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: ReadonlyMap<string, number>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number, inferredSource = 'source not stated', measured: Extract<HipsInferred, { by: 'measured' }> | null = null): Posture | null {
   const pelvis = map.chains.find((c) => c.joints.length === 2 && c.joints[0] === 'r_hip' && c.joints[1] === 'l_hip');
@@ -330,16 +418,23 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const refSw: number[] = [];
   let inferred = 0;
   const inClass = (rs: Run[], i: number) => rs.some(([a, b]) => a <= i && i <= b);
-  const counts = { read: 0, interpolated: 0, held: 0 };
+  const counts = { read: 0, interpolated: 0, held: 0, scaled: 0, unmeasured: 0 };
   frames.forEach((f, i) => {
     const rh = at(i, 'r_hip');
     const lh = at(i, 'l_hip');
     if (rh === null || lh === null) return;
     const isInferred = f.r_hip?.state === 'inferred' || f.l_hip?.state === 'inferred';
     const cls = measured === null ? undefined : (['read', 'interpolated', 'held'] as const).find((c) => inClass(measured[c], i));
+    const isScaled = measured !== null && measured.scaled !== undefined && inClass(measured.scaled, i);
+    const isUnmeasured = measured !== null && measured.unmeasured !== undefined && inClass(measured.unmeasured, i);
     if (isInferred && cls !== undefined) {
       counts[cls]++;
       refTilt.push(pictureAngle(rh, lh));
+    } else if (isInferred && isScaled) {
+      counts.scaled++;
+      refTilt.push(pictureAngle(rh, lh));
+    } else if (isInferred && isUnmeasured) {
+      counts.unmeasured++;
     } else if (isInferred) inferred++;
     else refTilt.push(pictureAngle(rh, lh));
     const rs = at(i, 'r_shoulder');
@@ -352,7 +447,7 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const aim = pelvis.aim[0]!;
   let tilt: Posture['tilt'] = null;
   const why = `hips inferred (${inferredSource})`;
-  if (inferred === 0 || refTilt.length > 0) {
+  if ((inferred === 0 && counts.unmeasured === 0) || refTilt.length > 0) {
     const rigTilt = posed.map((b) => aimAngle(b, lengths, bone, aim));
     tilt = { reference: rangeOf(unwrapped(refTilt)), rig: rangeOf(unwrapped(rigTilt)), ratio: 0 };
     tilt.ratio = tilt.rig.range / tilt.reference.range;
@@ -387,6 +482,79 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
       ratioSw: rig === null || rig.rangeSw === null ? null : rig.rangeSw / reference.rangeSw,
     };
   }
+  const bounce: BounceSpan[] = [];
+  if (r.planted && r.feet !== null && r.feet.supports.length > 0) {
+    const scaleNeckIdx = map.translate.scale.pose.indexOf('neck');
+    const neckChain = map.chains.find((c) => c.joints.includes('neck'));
+    const neckJointIdx = neckChain === undefined ? -1 : neckChain.joints.indexOf('neck');
+    const rigNeck = posed[0]?.has('neck')
+      ? 'neck'
+      : scaleNeckIdx >= 0
+        ? map.translate.scale.rig[scaleNeckIdx]!
+        : neckChain !== undefined && neckJointIdx > 0
+          ? (neckChain.aim[neckJointIdx - 1] === 'x' ? `${neckChain.bones[neckJointIdx - 1]}:tip` : neckChain.aim[neckJointIdx - 1]!)
+          : rigShoulder;
+    const headChain = map.chains.find((c) => c.joints.includes('r_eye') && c.joints.includes('l_eye'));
+    const rigNeckY = (b: Map<string, RawBone>): number | null => (rigNeck === null ? null : (pointAt(b, lengths, rigNeck)?.[1] ?? null));
+    const rigEyesY = (b: Map<string, RawBone>): number | null => {
+      if (headChain !== undefined) {
+        const k = headChain.joints.findIndex((j, idx) => idx + 1 < headChain.joints.length && ((j === 'r_eye' && headChain.joints[idx + 1] === 'l_eye') || (j === 'l_eye' && headChain.joints[idx + 1] === 'r_eye')));
+        if (k >= 0) {
+          const ha = headChain.aim[k]!;
+          const hb = headChain.bones[k]!;
+          if (ha.includes('>')) {
+            const [pa, pb] = aimEnds(hb, ha);
+            const ya = pointAt(b, lengths, pa);
+            const yb = pointAt(b, lengths, pb);
+            if (ya !== null && yb !== null) return (ya[1] + yb[1]) / 2;
+          }
+          const p = pointAt(b, lengths, ha === 'x' ? hb : ha);
+          if (p !== null) return p[1];
+        }
+      }
+      if (b.has('eye_r') && b.has('eye_l')) return (b.get('eye_r')!.worldY + b.get('eye_l')!.worldY) / 2;
+      if (b.has('head')) return b.get('head')!.worldY;
+      return rigNeckY(b);
+    };
+    for (const sp of r.feet.supports) {
+      const refHip: number[] = [];
+      const rigHipY: number[] = [];
+      const refNeck: number[] = [];
+      const rigNeckS: number[] = [];
+      const refEyesNeck: number[] = [];
+      const rigEyesNeck: number[] = [];
+      for (let i = sp.frames[0]; i <= sp.frames[1]; i++) {
+        const b = posed[i]!;
+        const rh = at(i, 'r_hip');
+        const lh = at(i, 'l_hip');
+        if (rh !== null && lh !== null) {
+          refHip.push(-((rh[1] + lh[1]) / 2) * s);
+          rigHipY.push(b.get(r.origin.bone)!.worldY);
+        }
+        const nk = at(i, 'neck');
+        const ny = rigNeckY(b);
+        if (nk !== null && ny !== null) {
+          refNeck.push(-nk[1] * s);
+          rigNeckS.push(ny);
+          const re = at(i, 'r_eye');
+          const le = at(i, 'l_eye');
+          const ey = rigEyesY(b);
+          if (re !== null && le !== null && ey !== null) {
+            refEyesNeck.push(-((re[1] + le[1]) / 2 - nk[1]) * s);
+            rigEyesNeck.push(ey - ny);
+          }
+        }
+      }
+      bounce.push({
+        side: sp.side,
+        frames: [sp.frames[0], sp.frames[1]],
+        hip: bounceMetric(refHip, rigHipY),
+        neck: bounceMetric(refNeck, rigNeckS),
+        eyesNeck: bounceMetric(refEyesNeck, rigEyesNeck),
+      });
+    }
+  }
+  const has106 = measured !== null && (measured.scaled !== undefined || measured.unmeasured !== undefined || measured.fit !== undefined);
   return {
     pelvis: pelvis.name,
     rigHip: r.origin.bone,
@@ -395,22 +563,52 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
     tilt,
     ...(tilt === null ? { tiltWhy: why } : {}),
     ...(inferred > 0 ? { hipsInferred: { frames: inferred, source: inferredSource } } : {}),
-    ...(measured !== null ? { tiltMeasured: { method: measured.method, frames: counts.read + counts.interpolated + counts.held, ...counts, heldSpans: measured.held.map(([a, b]): Run => [a, b]) } } : {}),
+    ...(measured !== null
+      ? {
+          tiltMeasured: {
+            method: measured.method,
+            frames: counts.read + counts.interpolated + counts.scaled + counts.held,
+            read: counts.read,
+            interpolated: counts.interpolated,
+            held: counts.held,
+            heldSpans: measured.held.map(([a, b]): Run => [a, b]),
+            ...(has106
+              ? {
+                  scaled: counts.scaled,
+                  scaledSpans: (measured.scaled ?? []).map(([a, b]): Run => [a, b]),
+                  unmeasured: counts.unmeasured,
+                  unmeasuredSpans: (measured.unmeasured ?? []).map(([a, b]): Run => [a, b]),
+                  ...(measured.fit !== undefined ? { fit: { frames: measured.fit.frames, gain: measured.fit.gain, corr: measured.fit.corr } } : {}),
+                }
+              : {}),
+          },
+        }
+      : {}),
     sway,
+    ...(bounce.length > 0 ? { bounce } : {}),
   };
 }
 
 const f1 = (x: number) => x.toFixed(1);
 const f3 = (x: number) => x.toFixed(3);
 const sg = (x: number) => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
+const spansText = (rs: Run[] | undefined) => (rs === undefined || rs.length === 0 ? 'none' : rs.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', '));
 
 /** The POSTURE lines. */
 export function postureLines(q: Posture): string[] {
   const over = (k: number) => (k === q.frames.of ? '' : ` over ${k} of ${q.frames.of} frames`);
   const t = q.tilt;
   const m = q.tiltMeasured;
-  const heldSpans = m === undefined || m.heldSpans.length === 0 ? 'none' : m.heldSpans.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
-  const measured = m === undefined ? '' : `; tilt measured (${m.method}) on ${m.frames} frame(s): ${m.read} read, ${m.interpolated} interpolated, ${m.held} held (held: ${heldSpans})`;
+  const heldSpans = spansText(m?.heldSpans);
+  const scaledPart =
+    m?.scaled !== undefined && m.scaled > 0
+      ? `, ${m.scaled} scaled (scaled: ${spansText(m.scaledSpans)}${m.fit?.gain !== undefined && m.fit.gain !== null && m.fit.corr !== null ? `, gain ${m.fit.gain.toFixed(2)}×, r=${m.fit.corr.toFixed(3)}` : ''})`
+      : '';
+  const unmeasuredPart =
+    m?.unmeasured !== undefined && (m.unmeasured > 0 || (m.fit !== undefined && (m.fit.corr === null || m.fit.corr < 0.9)))
+      ? `; ${m.unmeasured} unmeasured (${spansText(m.unmeasuredSpans)}${m.fit !== undefined ? `, r=${m.fit.corr === null ? 'none' : m.fit.corr.toFixed(3)} < 0.9` : ''})`
+      : '';
+  const measured = m === undefined ? '' : `; tilt measured (${m.method}) on ${m.frames} frame(s): ${m.read} read, ${m.interpolated} interpolated${scaledPart}, ${m.held} held (held: ${heldSpans})${unmeasuredPart}`;
   const left = q.hipsInferred === undefined ? '' : `; ${q.hipsInferred.frames} frame(s) with an inferred hip not read (${q.hipsInferred.source})`;
   const out = [
     t === null
@@ -428,5 +626,11 @@ export function postureLines(q: Posture): string[] {
       out.push(`sway, x-range of mid_hip − mid_shoulder: ${ref}, rig ${f1(w.rig.range)} units (${sw}; mid_hip = "${q.rigHip}", mid_shoulder = "${q.rigShoulder}") — rig/reference ${f3(w.ratio!)} in units${ratioSw}`);
     }
   }
+  if (q.bounce !== undefined) {
+    const fmt = (bm: BounceMetric) => `${bm.ratio === null ? 'n/a' : f3(bm.ratio)} (${f1(bm.rig)}/${f1(bm.reference)}u, r=${bm.corr === null ? 'none' : f3(bm.corr)})`;
+    for (const b of q.bounce) {
+      out.push(`bounce ${b.side} ${b.frames[0]}–${b.frames[1]} (detrended y sd, rig/reference): hip ${fmt(b.hip)}, neck ${fmt(b.neck)}, eyes − neck ${fmt(b.eyesNeck)}`);
+    }
+  }
   return out;
 }