@rig-c/pose 0.15.0 → 0.17.0

package/src/run.ts

@@ -14,11 +14,11 @@ import { isObject, lineOf, parseJson, Problems, Refusal, type Problem } from './
 import { boneIdentity, droppedLine, keptOutLine, mergeProblems, readFragment, readIdle, targetOf, trackLabel, type IdleReading, type RigcTrack, type Target } from './idle.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type MotionTrack, type RetargetOptions } from './retarget.ts';
 import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
-import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
+import { artRangeLine, chainsMoving, raisedLine, RAISED_WITHIN, reachLine, switchLine, uncoveredFolds } from './switch.ts';
 import { landed, measureFeet, measureLanding, measurePosture, measureShear, poseFrames, postureLines } from './verify.ts';
 import { legsOf } from './legs.ts';
 import { reduceKeys, type ReduceBone, type Reduced } from './reduce.ts';
-import type { LegScale, Stance } from './legs.ts';
+import type { BlendHold, Floor, LegScale, Stance } from './legs.ts';
 
 export interface RetargetArgs extends RetargetOptions {
   rig: string;
@@ -108,7 +108,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
-    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, 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.carryIdle === true ? ', carry-idle' : ''}${a.merge !== undefined ? `, merge ${a.merge}` : ''}${a.reduce !== undefined ? `, reduce ${a.reduce}°${a.reduceHip !== undefined ? ` (hip ${a.reduceHip} units)` : ''}` : ''}`);
+    say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, 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)` : ''}` : ''}`);
     say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     say(`  CLEAN  ${cleanLine(seq.cleaned!)}`);
     if (a.smoothAlias !== undefined) say(`  SMOOTH --smooth is carried by clean; ignored (given ${a.smoothAlias}; this sequence was cleaned with legs ${seq.cleaned!.params.legs}, rest ${seq.cleaned!.params.rest})`);
@@ -130,6 +130,9 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
+    if (a.raisedByHead === true && r.raised.length === 0) say(`  RAISED none — no set drawing an arm within ${RAISED_WITHIN}° of straight up showed; no key moved`);
+    for (const e of r.raised) say(`  RAISED ${raisedLine(e, r.times)}`);
+    for (const e of r.raised) if (e.short.length > 0) say(`  REACH  ${reachLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
     for (const l of r.legScale) say(`  LEG-SCALE ${legScaleLine(l, r.times)}`);
     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`);
@@ -140,6 +143,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
       say(`  FEET   supports: ${f.supports.map((x) => `${x.side} ${span(x.frames)}`).join(', ') || 'none'}`);
       say(`  FEET   jumps (both ankles and mid_hip > 0.05 leg lengths above their rolling floor, ≥ 2 frames): ${f.jumps.map(span).join(', ') || 'none'}`);
       say(`  FEET   steps (the supporting ankle > 0.03 leg lengths a frame; re-planted after 2 frames < 0.01): ${f.steps.map((x) => `${x.side} ${span(x.frames)} → ${x.to === null ? 'the pose\'s travel' : `${x.to} supports`}, ${x.replant === null ? 'never re-planted' : `re-planted at ${x.replant}`}`).join('; ') || 'none'}`);
+      if (r.floor !== null) {
+        const legBones = legBonesOf(map);
+        if (legBones !== null) say(`  FEET   ${floorLine(r.floor, setupLegs(rest, legBones))}`);
+      }
+      if (r.blendHold !== null) for (const l of blendLines(r.blendHold, r.times)) say(`  FEET   ${l}`);
     }
     if (r.stance !== null) for (const l of stanceLines(r.stance, r.times)) say(`  STANCE ${l}`);
 
@@ -225,7 +233,8 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     p.throwIfAny();
 
     const lengths = new Map(doc.bones.map((b) => [b.name, b.length ?? 0]));
-    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned));
+    const hips = seq.cleaned?.params.hipsInferred;
+    const posture = measurePosture(posed, lengths, map, r, frames, a.minScore, inferredSource(seq.cleaned), hips?.by === 'measured' ? hips : null);
     if (posture !== null) for (const l of postureLines(posture)) say(`  POSTURE ${l}`);
     const legBones = legBonesOf(map);
     const feetReading = legBones === null ? null : measureFeet(posed, lengths, r, legBones);
@@ -273,7 +282,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         frames: seq.frames.length,
         duration: r.animation.duration,
         cleaned: seq.cleaned,
-        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', idle: idleName, carryIdle: a.carryIdle === true, merge: a.merge ?? null, reduce: a.reduce ?? 'off', reduceHip: a.reduceHip ?? 'off' },
+        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' },
         scale: r.scale,
         holds: r.holds,
         short: r.short,
@@ -289,10 +298,11 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
         turns: r.turns,
         range: r.range,
         artRange: r.artRange,
+        raised: r.raised,
         legScale: r.legScale.map(({ scale: _scale, ...rest }) => rest),
         pivot: r.pivot,
-        stance: r.stance === null ? null : { tolerance: r.stance.tolerance, bounds: r.stance.bounds, runs: r.stance.runs, over: r.stance.over },
-        feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, reading: feetReading },
+        stance: r.stance === null ? null : { tolerance: r.stance.tolerance, release: r.stance.release, minSeconds: r.stance.minSeconds, bounds: r.stance.bounds, runs: r.stance.runs, over: r.stance.over },
+        feet: r.feet === null ? null : { planted: r.planted, legLength: r.feet.legLength, supports: r.feet.supports, jumps: r.feet.jumps, steps: r.feet.steps, changes: r.feet.changes, floor: r.floor?.y ?? null, shifts: r.floor?.shifts ?? [], blend: r.blendHold === null ? null : { bounds: r.blendHold.bounds, runs: r.blendHold.runs, over: r.blendHold.over }, reading: feetReading },
         shear,
         idleDropped: idle === null ? null : idle.dropped,
         idleKeptOut: idle === null ? null : idle.keptOut,
@@ -412,7 +422,7 @@ export function cameraLine(camera: readonly CameraFrame[], times: readonly numbe
   const fastest = [...steps].sort((x, y) => Math.abs(y.d) - Math.abs(x.d) || x.to - y.to).slice(0, 3);
   const sign = (d: number) => `${d < 0 ? '−' : '+'}${Math.abs(d).toFixed(4)}`;
   const inl = camera.reduce((m, c) => Math.min(m, c.inliers), Infinity);
-  return `${source ?? '(source not stated)'}: the sequence carries the picture's camera against frame 0's; its joints are normalised by it (p′ = (p − t) / s): s ${ss[lo]!.toFixed(4)} (frame ${lo}) … ${ss[hi]!.toFixed(4)} (frame ${hi}) over ${camera.length} frames; s changes fastest at ${fastest.map((x) => `frame ${x.to - 1}→${x.to} (t=${times[x.to]!.toFixed(3)}s) ${sign(x.d)}`).join(', ') || 'no frame (one frame only)'}${source?.startsWith('hand-labelled') === true ? '' : `; fewest background inliers ${inl}`}`;
+  return `${source ?? '(source not stated)'}: the sequence carries the picture's camera against frame 0's; its joints are normalised by it (p′ = (p − t) / s): s ${ss[lo]!.toFixed(4)} (frame ${lo}) … ${ss[hi]!.toFixed(4)} (frame ${hi}) over ${camera.length} frames; s changes fastest at ${fastest.map((x) => `frame ${x.to - 1}→${x.to} (t=${times[x.to]!.toFixed(3)}s) ${sign(x.d)}`).join(', ') || 'no frame (one frame only)'}${source?.startsWith('hand') === true ? '' : `; fewest background inliers ${inl}`}`;
 }
 
 /** Each leg's first bone (its root, the thigh) and last bone (whose tip is the ankle), when the map has both. */
@@ -422,6 +432,45 @@ function legBonesOf(map: JointMap): { r: { root: string; ankle: string }; l: { r
   return { r: { root: l.legs.r.chain.bones[0]!, ankle: l.legs.r.ankleBone }, l: { root: l.legs.l.chain.bones[0]!, ankle: l.legs.l.ankleBone } };
 }
 
+/** Each side's rig leg at setup, world units: its thigh's origin to its ankle (the leg's last bone's tip), by rig-c's setup pose. */
+export function setupLegs(rest: Rest, legs: { r: { root: string; ankle: string }; l: { root: string; ankle: string } }): { r: number; l: number } {
+  const of = (s: 'r' | 'l') => {
+    const o = rest.get(legs[s].root)!;
+    const b = rest.get(legs[s].ankle)!;
+    return Math.hypot(b.worldX + b.a * b.length - o.worldX, b.worldY + b.c * b.length - o.worldY);
+  };
+  return { r: of('r'), l: of('l') };
+}
+
+/**
+ * The FEET floor line (#85): the floor's world y and where it came from, each
+ * support span's shift onto it in world units and in that side's rig leg at
+ * setup, and the shifts' range in the two legs' mean.
+ */
+export function floorLine(floor: Floor, leg: { r: number; l: number }): string {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `${x[0]}` : `${x[0]}–${x[1]}`);
+  const sign = (v: number, d: number) => `${v < 0 ? '−' : '+'}${Math.abs(v).toFixed(d)}`;
+  const ss = floor.shifts.map((x) => x.shift);
+  const lo = Math.min(...ss);
+  const hi = Math.max(...ss);
+  const mean = (leg.r + leg.l) / 2;
+  return `floor: world y ${floor.y.toFixed(2)} (${floor.given ? 'given by --floor' : `the median of the ${floor.shifts.length} support span(s)' planted heights`}); each span's supporting ankle moved onto it, the hip and everything above with it — shift per span in units (leg lengths: the rig's at setup, thigh origin → ankle, r ${leg.r.toFixed(1)}, l ${leg.l.toFixed(1)} units): ${floor.shifts.map((x) => `${x.side} ${span(x.frames)} ${sign(x.shift, 2)} (${sign(x.shift / leg[x.side], 4)})`).join(', ')}; range ${sign(lo, 2)} … ${sign(hi, 2)} units = ${((hi - lo) / mean).toFixed(4)} leg lengths`;
+}
+
+/**
+ * The FEET blend lines (#85): one per run of blend frames whose supporting leg
+ * was stretched to keep its ankle on the floor, with the stretch keyed; one per
+ * run whose stretch fell past its bounds (`past the bounds`, as STANCE says it).
+ */
+export function blendLines(h: BlendHold, times: readonly number[]): string[] {
+  const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
+  const out: string[] = [];
+  for (const r of h.runs) out.push(`blend held on the floor: supporting foot ${r.side} ${span(r.frames)} — the hip blends between two derivations there, so its leg is stretched by k ${r.k.min.toFixed(4)}–${r.k.max.toFixed(4)} within [${h.bounds[0]}, ${h.bounds[1]}] to keep the ankle on the floor`);
+  if (h.runs.length === 0) out.push('blend held on the floor: no blend frame left a supporting ankle off the floor');
+  for (const o of h.over) out.push(`past the bounds: supporting foot ${o.side} ${span(o.frames)} — ${o.needed === null ? 'its ankle is not below its leg\'s root, so no stretch reaches the floor' : `the floor needed k ${o.needed.toFixed(4)}, past [${h.bounds[0]}, ${h.bounds[1]}]; held at the bound`}, the foot left up to ${o.left.toFixed(2)} units from the floor`);
+  return out;
+}
+
 /**
  * The STANCE lines (#60): one per run of planted-both or lifted frames, with
  * the tolerance and the stretch keyed; one per run a stretch was capped.
@@ -429,9 +478,13 @@ function legBonesOf(map: JointMap): { r: { root: string; ankle: string }; l: { r
 export function stanceLines(st: Stance, times: readonly number[]): string[] {
   const span = (x: [number, number]) => (x[0] === x[1] ? `frame ${x[0]} (t=${times[x[0]]!.toFixed(3)}s)` : `frames ${x[0]}–${x[1]} (t=${times[x[0]]!.toFixed(3)}–${times[x[1]]!.toFixed(3)}s)`);
   const tol = `the tolerance ${st.tolerance} leg lengths`;
-  const out = st.runs.map((r) => (r.state === 'both'
+  const release = `planted again under ${st.release} of it, ${(st.release * st.tolerance).toFixed(4)}`;
+  const other = (r: Stance['runs'][number]) => (r.state === 'both' ? 'lifted' : 'planted-both');
+  const out = st.runs.map((r) => (r.absorbed === true
+    ? `absorbed: free foot ${r.side} ${span(r.frames)} — read ${r.state === 'both' ? 'planted both' : 'lifted'} (its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture; ${tol}, ${release}) for ${r.frames[1] - r.frames[0] + 1} frame(s), under ${st.minSeconds} s between two ${other(r)} runs; it takes their state`
+    : r.state === 'both'
     ? `planted both: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, within ${tol}; its leg stretched by k ${r.k!.min === r.k!.max ? r.k!.max.toFixed(4) : `${r.k!.min.toFixed(4)} … ${r.k!.max.toFixed(4)}`} (largest ${r.k!.max.toFixed(4)})`
-    : `lifted: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, over ${tol}; the pose's height kept`));
+    : `lifted: free foot ${r.side} ${span(r.frames)} — its ankle up to ${r.maxHeight.toFixed(4)} leg lengths above the supporting one in the picture, over ${tol} (${release}); the pose's height kept`));
   for (const o of st.over) out.push(`past the bounds: free foot ${o.side} ${span(o.frames)} — ${o.needed === null ? 'its ankle is not below its leg\'s root, so no stretch reaches the floor' : `the floor needed k ${o.needed.toFixed(4)}, past [${st.bounds[0]}, ${st.bounds[1]}]; held at the bound`}, the foot left up to ${o.left.toFixed(2)} units from the floor`);
   return out;
 }

package/src/switch.ts

@@ -129,6 +129,8 @@ export interface ArtRange {
   limits: [number, number];
   /** Whether the bone was held at the limit (the set's `turn`) or followed the pose (its chain's `range` only). */
   clamped: boolean;
+  /** --raised-by-head (#62): on a held upper arm, the most the re-aimed forearm left the wrist short of its placed point, eye distances; `turn` and `maxOverflow` are then the upper arm's on that frame. */
+  shortfall?: number;
 }
 
 export interface Uncovered {
@@ -580,6 +582,9 @@ function moveText(m: Move): string {
 }
 
 export function artRangeLine(e: ArtRange, times: readonly number[]): string {
+  if (e.shortfall !== undefined) {
+    return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" held at its turn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s the re-aimed forearm leaves the wrist up to ${e.shortfall.toFixed(2)} eye distances short of its placed point (the upper arm asked ${sg(e.turn)} from drawn, ${deg(e.maxOverflow)} past) — demand for another drawing of the set`;
+  }
   return `set "${e.set}" chain "${e.chain}" bone "${e.bone}" turned ${sg(e.turn)} from drawn (range [${e.limits[0]}, ${e.limits[1]}]) ${spanOf(e.frames, times)}: ${e.seconds.toFixed(3)}s, up to ${deg(e.maxOverflow)} past it; ${e.clamped ? 'held at the limit' : 'the bone follows the pose'} — demand for another drawing of the set`;
 }
 
@@ -603,3 +608,162 @@ export function clampArt(switches: readonly Switch[], map: JointMap, targets: Ma
     }
   }
 }
+
+/**
+ * A set's arm is raised (rig-c/pose#62) when its `drawn` world angle on the
+ * chain's first bone (the upper arm) is within this many degrees of straight up.
+ */
+export const RAISED_WITHIN = 30;
+
+/** Whether a drawn world angle, Spine degrees, is within `RAISED_WITHIN` of straight up (90°). */
+export const isRaised = (drawn: number): boolean => Math.abs(wrap(drawn - 90)) <= RAISED_WITHIN;
+
+type P2 = [number, number];
+
+/**
+ * A two-bone solve in the world (y up): the directions, degrees, of the vector
+ * from the shoulder to the elbow (`upper`) and from the elbow to the wrist
+ * (`fore`) that put the wrist on `target`, for bones of lengths `l0` and `l1`.
+ * `side` is the elbow's bend: +1 when the forearm turns counter-clockwise from
+ * the upper arm, −1 clockwise. Out of reach (farther than l0 + l1, nearer than
+ * |l0 − l1|, beyond a relative 1e-6) both point straight at the target and
+ * `reached` is false; on the shoulder, where there is no direction, `upper` is
+ * null. `reachLimit` puts a target inside first, so the raised solve always reaches.
+ */
+export function twoBone(shoulder: P2, target: P2, l0: number, l1: number, side: 1 | -1): { upper: number; fore: number; reached: boolean } | { upper: null; reached: false } {
+  const dx = target[0] - shoulder[0];
+  const dy = target[1] - shoulder[1];
+  const d = Math.hypot(dx, dy);
+  if (d < 1e-9) return { upper: null, reached: false };
+  const theta = Math.atan2(dy, dx) * (180 / Math.PI);
+  const eps = 1e-6 * Math.max(1, l0 + l1);
+  if (d > l0 + l1 + eps || d < Math.abs(l0 - l1) - eps) return { upper: theta, fore: theta, reached: false };
+  const cos = Math.min(1, Math.max(-1, (l0 * l0 + d * d - l1 * l1) / (2 * l0 * d)));
+  const upper = theta - side * Math.acos(cos) * (180 / Math.PI);
+  const r = upper * (Math.PI / 180);
+  const ex = shoulder[0] + l0 * Math.cos(r);
+  const ey = shoulder[1] + l0 * Math.sin(r);
+  return { upper: wrap(upper), fore: Math.atan2(target[1] - ey, target[0] - ex) * (180 / Math.PI), reached: true };
+}
+
+/** Where a raised wrist is placed: the target itself, or the reach limit (rig-c/pose#62, HQ's ruling). */
+export interface Placement {
+  point: P2;
+  /** `in`: the target is within reach. `far` / `near`: past l0 + l1, or nearer than |l0 − l1|, and placed on the ray from the head centre. `missed`: that ray never enters the reach; placed at the reach's point nearest the target. */
+  how: 'in' | 'far' | 'near' | 'missed';
+}
+
+/**
+ * The raised wrist's placement. The arm reaches the annulus about the shoulder
+ * between |l0 − l1| and l0 + l1. A target inside it is kept. Otherwise the wrist
+ * goes on the ray from the head centre through the target, at the point of
+ * that ray inside the annulus nearest the target — the reach limit along the
+ * head-relative direction. The ray can cross the annulus twice (out and back
+ * through the inner disc, or through the whole ring): of the reachable stretches
+ * the one nearest the target wins, a tie going to the point nearer the head. A
+ * ray that never enters it (`missed`) gives the annulus point nearest the
+ * target, on the line from the shoulder through it (toward the head centre when
+ * the target is on the shoulder).
+ */
+export function reachLimit(centre: P2, target: P2, shoulder: P2, l0: number, l1: number): Placement {
+  const rMin = Math.abs(l0 - l1);
+  const rMax = l0 + l1;
+  const eps = 1e-9 * Math.max(1, rMax);
+  const dT = Math.hypot(target[0] - shoulder[0], target[1] - shoulder[1]);
+  if (dT >= rMin - eps && dT <= rMax + eps) return { point: target, how: 'in' };
+  const how = dT > rMax ? 'far' : 'near';
+  const vx = target[0] - centre[0];
+  const vy = target[1] - centre[1];
+  const L = Math.hypot(vx, vy);
+  if (L > 1e-9) {
+    const u: P2 = [vx / L, vy / L];
+    // |C + s·u − S|² = s² + 2·s·b + c
+    const b = u[0] * (centre[0] - shoulder[0]) + u[1] * (centre[1] - shoulder[1]);
+    const c = (centre[0] - shoulder[0]) ** 2 + (centre[1] - shoulder[1]) ** 2;
+    const roots = (r: number): [number, number] | null => {
+      const disc = b * b - c + r * r;
+      return disc < 0 ? null : [-b - Math.sqrt(disc), -b + Math.sqrt(disc)];
+    };
+    const outer = roots(rMax);
+    const stretches: Array<[number, number]> = [];
+    if (outer !== null) {
+      const lo = Math.max(0, outer[0]);
+      const hi = outer[1];
+      const inner = rMin > 0 ? roots(rMin) : null;
+      if (hi >= lo) {
+        if (inner === null || inner[1] <= lo || inner[0] >= hi) stretches.push([lo, hi]);
+        else {
+          if (inner[0] > lo) stretches.push([lo, inner[0]]);
+          if (inner[1] < hi) stretches.push([inner[1], hi]);
+        }
+      }
+    }
+    let best: number | null = null;
+    for (const [lo, hi] of stretches) {
+      const s = Math.min(Math.max(L, lo), hi);
+      if (best === null || Math.abs(s - L) < Math.abs(best - L) - 1e-9 || (Math.abs(Math.abs(s - L) - Math.abs(best - L)) <= 1e-9 && s < best)) best = s;
+    }
+    if (best !== null) return { point: [centre[0] + best * u[0], centre[1] + best * u[1]], how };
+  }
+  const from: P2 = dT > 1e-9 ? target : centre;
+  const k = Math.hypot(from[0] - shoulder[0], from[1] - shoulder[1]) || 1;
+  const r = Math.min(Math.max(dT, rMin), rMax);
+  return { point: [shoulder[0] + (r * (from[0] - shoulder[0])) / k, shoulder[1] + (r * (from[1] - shoulder[1])) / k], how: 'missed' };
+}
+
+/** A run of frames whose target was out of reach, one way. */
+export interface ReachShort {
+  frames: [number, number];
+  how: 'far' | 'near' | 'missed';
+  /** |target − placed| in the rig's eye distances: the most, and the median, over the run. */
+  shortfall: { max: number; median: number };
+}
+
+/** One span of a raised set on one chain: its wrist placed against the head (rig-c/pose#62). */
+export interface Raised {
+  set: string;
+  chain: string;
+  frames: [number, number];
+  seconds: number;
+  /** The unit: the eye distance's median over the span, the rig's in world units, the reference's in picture px. */
+  eyes: { rig: number; reference: number };
+  /**
+   * Per frame of the span, the wrist's offset from the head centre in eye
+   * distances (x right, y up): the reference's; where the wrist was placed (the
+   * target, or the reach limit); the rig's on the pose's angles; the rig's as
+   * keyed.
+   */
+  reference: P2[];
+  placed: P2[];
+  before: P2[];
+  after: P2[];
+  /** The largest |rig − reference| over the span, x and y, before and after; and the largest |after − placed|, eye distances. */
+  worst: { before: P2; after: P2; placed: number };
+  /** The runs of frames out of the arm's reach (the REACH line). */
+  short: ReachShort[];
+  /** The frames whose upper arm the set's `turn` held: the forearm re-aimed at the placed wrist. */
+  upperHeld: number[];
+  /** The arm's reach (from |l0 − l1| to l0 + l1, world units from the shoulder) and the farthest target from the shoulder over the span. */
+  reach: { min: number; max: number; farthest: number };
+}
+
+const xy = (v: P2) => `(${v[0].toFixed(2)}, ${v[1].toFixed(2)})`;
+const framesText = (fs: readonly number[]): string => {
+  const flag: boolean[] = [];
+  for (const f of fs) flag[f] = true;
+  return runsOf(Array.from({ length: flag.length }, (_, i) => flag[i] === true), 0).map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`)).join(', ');
+};
+
+export function raisedLine(e: Raised, times: readonly number[]): string {
+  const med = (vs: readonly P2[]): P2 => [median(vs.map((v) => v[0])), median(vs.map((v) => v[1]))];
+  const held = e.upperHeld.length === 0 ? 'the upper arm within its turn on every frame' : `the upper arm held by the set's turn on ${e.upperHeld.length} frame(s) (${framesText(e.upperHeld)}), the forearm re-aimed`;
+  const out = e.short.length === 0 ? 'every target in reach' : `out of reach on ${e.short.reduce((k, s) => k + s.frames[1] - s.frames[0] + 1, 0)} frame(s) (REACH)`;
+  return `set "${e.set}" chain "${e.chain}" ${spanOf(e.frames, times)}: the wrist placed against the head; eye distance (median) rig ${e.eyes.rig.toFixed(2)} units, reference ${e.eyes.reference.toFixed(2)} px; wrist − head centre in eye distances (x right, y up), median reference ${xy(med(e.reference))}, placed ${xy(med(e.placed))}, before ${xy(med(e.before))}, after ${xy(med(e.after))}; worst |rig − reference| before ${xy(e.worst.before)}, after ${xy(e.worst.after)}; worst |after − placed| ${e.worst.placed.toFixed(2)}; ${held}; ${out}`;
+}
+
+/** The REACH line: a raised span whose target was out of the arm's reach on some frames — the proportions, not the art's range, were the limit. */
+export function reachLine(e: Raised, times: readonly number[]): string {
+  const why = { far: `farther than l0 + l1 = ${e.reach.max.toFixed(1)}`, near: `nearer than |l0 − l1| = ${e.reach.min.toFixed(1)}`, missed: 'and the ray from the head centre never enters the reach; placed at the reach\'s point nearest it' } as const;
+  const runs = e.short.map((s) => `${spanOf(s.frames, times)} ${s.how === 'missed' ? 'out of reach' : why[s.how]}${s.how === 'missed' ? `, ${why.missed}` : ''}: up to ${s.shortfall.max.toFixed(2)} eye distances short (median ${s.shortfall.median.toFixed(2)})`);
+  return `set "${e.set}" chain "${e.chain}": the target out of the arm's reach from the shoulder — ${runs.join('; ')}; the wrist placed at the reach limit along the head-relative direction (the farthest target ${e.reach.farthest.toFixed(1)} units from the shoulder). Not ART-RANGE: the rig's proportions, not the art's range, were the limit`;
+}

package/src/verify.ts

@@ -11,7 +11,7 @@
 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 { Joint } from './pose.ts';
+import type { HipsInferred, Joint, Run } from './pose.ts';
 import type { Retarget } from './retarget.ts';
 import { pictureAngle, pointOn, wrap } from './retarget.ts';
 
@@ -259,6 +259,14 @@ export interface Posture {
    * how many such frames the tilt left out, and where the state came from.
    */
   hipsInferred?: { frames: number; source: string };
+  /**
+   * Present only when the hips were measured (#86, `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`.
+   */
+  tiltMeasured?: { method: string; frames: number; read: number; interpolated: number; held: number; heldSpans: Run[] };
   /**
    * 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.
@@ -302,8 +310,14 @@ const medianOf = (xs: number[]): number => {
  * from the clean record). On some frames only, the tilt is read over the rest
  * 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.
  */
-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'): Posture | null {
+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');
   if (pelvis === undefined || map.translate === null || r.origin === null || r.scale === null) return null;
   const s = r.scale.factor;
@@ -315,11 +329,18 @@ export function measurePosture(posed: Array<Map<string, RawBone>>, lengths: Read
   const refSway: number[] = [];
   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 };
   frames.forEach((f, i) => {
     const rh = at(i, 'r_hip');
     const lh = at(i, 'l_hip');
     if (rh === null || lh === null) return;
-    if (f.r_hip?.state === 'inferred' || f.l_hip?.state === 'inferred') inferred++;
+    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));
+    if (isInferred && cls !== undefined) {
+      counts[cls]++;
+      refTilt.push(pictureAngle(rh, lh));
+    } else if (isInferred) inferred++;
     else refTilt.push(pictureAngle(rh, lh));
     const rs = at(i, 'r_shoulder');
     const ls = at(i, 'l_shoulder');
@@ -374,6 +395,7 @@ 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]) } } : {}),
     sway,
   };
 }
@@ -386,11 +408,14 @@ const sg = (x: number) => `${x >= 0 ? '+' : '−'}${Math.abs(x).toFixed(1)}`;
 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 left = q.hipsInferred === undefined ? '' : `; ${q.hipsInferred.frames} frame(s) with an inferred hip not read (${q.hipsInferred.source})`;
   const out = [
     t === null
       ? `hip tilt not read: ${q.tiltWhy}`
-      : `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(t.reference.range)}° (${sg(t.reference.min)}° … ${sg(t.reference.max)}°${over(q.frames.tilt)}), rig ${f1(t.rig.range)}° (${sg(t.rig.min)}° … ${sg(t.rig.max)}°) — rig/reference ${f3(t.ratio)}${left}`,
+      : `hip tilt range (chain "${q.pelvis}", r_hip → l_hip, Spine degrees): reference ${f1(t.reference.range)}° (${sg(t.reference.min)}° … ${sg(t.reference.max)}°${over(q.frames.tilt)}), rig ${f1(t.rig.range)}° (${sg(t.rig.min)}° … ${sg(t.rig.max)}°) — rig/reference ${f3(t.ratio)}${measured}${left}`,
   ];
   const w = q.sway;
   if (w === null) out.push('sway: the reference has no frame with both hips and both shoulders good; not measured');