@rig-c/pose 0.16.0 → 0.18.0

package/src/reduce.ts

@@ -18,6 +18,13 @@
  * target is its world error: errors do not pile up down a chain. A knot's value
  * is the target's, not the dense key's.
  *
+ * Scaled bones (rig-c/pose#94). A `scalex` track is thinned in value space
+ * within `SCALE_REDUCE` (`reduceScale`). A bone under a scaled bone is not
+ * keyed by the formula above but through its parent's posed matrix (legs.ts
+ * `posePath`), so `reduceUnderScale` solves its keys again through its parent
+ * as reduced and reads each error as the world aim, and the world length, it
+ * lands on.
+ *
  * Every error is read after the numbers are rounded as written and evaluated as
  * rig-c's poser evaluates them (`curveAt`): the curve is the poser's ten-piece
  * polyline, not the cubic. The poser is the judge — run.ts measures the landing
@@ -52,12 +59,13 @@ export interface ReduceHip {
 }
 export interface ReduceRow {
   bone: string;
-  kind: 'angle' | 'origin';
+  /** `scale`: a `scalex` track (#94), its error the bone's world x-axis length against its setup length times the scale asked. */
+  kind: 'angle' | 'origin' | 'scale';
   /** Dense key count. */
   before: number;
   /** Reduced key count. */
   after: number;
-  /** The largest error over all frames: degrees of world aim for a bone, world units for the hip. */
+  /** The largest error over all frames: degrees of world aim for a bone, world units for the hip, a fraction of the setup length for a scale. */
   worst: number;
   /** The first frame where it is. */
   frame: number;
@@ -67,6 +75,8 @@ export interface Reduced {
   hip: ReducedKey[] | null;
   /** The bones in the order given, then the hip. */
   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[]>;
 }
 
 // ---------------------------------------------------------------------------
@@ -186,6 +196,11 @@ const r3 = (v: number): number => {
   const r = Math.round(v * 1000) / 1000;
   return Object.is(r, -0) ? 0 : r;
 };
+/** A scale as the retarget writes one (retarget.ts `r6`). */
+const r6 = (v: number): number => {
+  const r = Math.round(v * 1e6) / 1e6;
+  return Object.is(r, -0) ? 0 : r;
+};
 
 /** One track to reduce: its targets per frame (one array per frame, a value per channel) and how a frame's error is read. */
 interface Fit {
@@ -194,6 +209,8 @@ interface Fit {
   tolerance: number;
   /** The error at frame `i` of `values` against the target. */
   error: (i: number, values: readonly number[]) => number;
+  /** How a written value is rounded: 0.001 (an angle, a translate) unless given. */
+  round?: (v: number) => number;
 }
 
 /** The frame with the largest error over `frames` (the first, on a tie), or null when there is none. */
@@ -242,7 +259,8 @@ function solveHandles(a: ReducedKey, b: ReducedKey, channel: number, hx1: number
 function fitTrack(times: readonly number[], samples: readonly number[], fit: Fit): ReducedKey[] {
   const n = times.length;
   const channels = fit.targets[0]!.length;
-  const keyOn = (i: number): ReducedKey => ({ t: times[i]!, v: fit.targets[i]!.map(r3) });
+  const round = fit.round ?? r3;
+  const keyOn = (i: number): ReducedKey => ({ t: times[i]!, v: fit.targets[i]!.map(round) });
   const knots = [...new Set([0, n - 1, ...fit.keep])].sort((x, y) => x - y);
   const curves = new Map<number, number[]>();
   const done: number[] = [];
@@ -266,7 +284,7 @@ function fitTrack(times: readonly number[], samples: readonly number[], fit: Fit
     const hx2 = times[k0]! + (2 * (times[k1]! - times[k0]!)) / 3;
     const handles = Array.from({ length: channels }, (_, c) => solveHandles(a, b, c, hx1, hx2, interior, samples, (i) => fit.targets[i]![c]!));
     if (handles.every((h) => h !== null)) {
-      const curve = handles.flatMap(([cy1, cy2]) => [hx1, r3(cy1), hx2, r3(cy2)]);
+      const curve = handles.flatMap(([cy1, cy2]) => [hx1, round(cy1), hx2, round(cy2)]);
       const bent = errorWith({ ...a, curve });
       if (bent.worst <= fit.tolerance) {
         curves.set(k0, curve);
@@ -304,8 +322,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
   if (!(Number.isFinite(tolerance) && tolerance > 0)) throw new Error(`reduce: the tolerance is ${tolerance}°, not a positive number`);
   if (hip !== null && !(Number.isFinite(hip.tolerance) && hip.tolerance > 0)) throw new Error(`reduce: the hip's tolerance is ${hip.tolerance} units, not a positive number`);
   // The poser samples at the running sum of the frame steps (verify.ts `poseFrames`).
-  const samples: number[] = [times[0]!];
-  for (let i = 1; i < n; i++) samples.push(samples[i - 1]! + (times[i]! - times[i - 1]!));
+  const samples = samplesOf(times);
 
   const byName = new Map<string, ReduceBone>();
   for (const b of bones) {
@@ -341,6 +358,7 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     rowOf.set(b.bone, { bone: b.bone, kind: 'angle', before: n, after: keys.length, worst: worst.worst, frame: worst.frame });
   }
   const rows = bones.map((b) => rowOf.get(b.bone)!);
+  const errorsOrdered = new Map(bones.map((b) => [b.bone, errors.get(b.bone)!]));
   const ordered = new Map(bones.map((b) => [b.bone, rotate.get(b.bone)!]));
 
   let hipKeys: ReducedKey[] | null = null;
@@ -357,5 +375,147 @@ export function reduceKeys(times: readonly number[], bones: readonly ReduceBone[
     const worst = worstOf(at.map((_, i) => i), (i) => world(i, at[i]!))!;
     rows.push({ bone: hip.bone, kind: 'origin', before: n, after: hipKeys.length, worst: worst.worst, frame: worst.frame });
   }
-  return { rotate: ordered, hip: hipKeys, rows };
+  return { rotate: ordered, hip: hipKeys, rows, errors: errorsOrdered };
+}
+
+/** The times the poser samples a track at: the running sum of the frame steps (verify.ts `poseFrames`). */
+export function samplesOf(times: readonly number[]): number[] {
+  const samples: number[] = [times[0]!];
+  for (let i = 1; i < times.length; i++) samples.push(samples[i - 1]! + (times[i]! - times[i - 1]!));
+  return samples;
+}
+
+// ---------------------------------------------------------------------------
+// scales, and bones keyed through a scaled parent (rig-c/pose#94)
+// ---------------------------------------------------------------------------
+
+/**
+ * The tolerance a reduced `scalex` track is held to: half of the landing
+ * check's scale tolerance (verify.ts `SCALE_TOLERANCE`, 1e-4 of the setup
+ * length), so a reduced curve cannot fail the check it is re-run against.
+ */
+export const SCALE_REDUCE = 5e-5;
+
+/**
+ * One `scalex` track of a bone with no scaled bone above it, reduced: its world
+ * x-axis length over setup is its own scale, so the error is the value's
+ * distance from the scale asked.
+ */
+export function reduceScale(times: readonly number[], bone: string, asked: readonly number[], keep: ReadonlySet<number>, tolerance: number): { keys: ReducedKey[]; at: number[]; row: ReduceRow } {
+  const n = times.length;
+  if (asked.length !== n) throw new Error(`reduce: bone "${bone}" asks ${asked.length} scale(s) for ${n} frame(s)`);
+  const samples = samplesOf(times);
+  const keys = fitTrack(times, samples, { targets: asked.map((v) => [v]), keep: keptFrames(keep, n, `bone "${bone}" scalex`), tolerance, error: (i, v) => Math.abs(v[0]! - asked[i]!), round: r6 });
+  const at = trackAt(keys, samples, 1).map((v) => v[0]!);
+  const worst = worstOf(at.map((_, i) => i), (i) => Math.abs(at[i]! - asked[i]!))!;
+  return { keys, at, row: { bone, kind: 'scale', before: n, after: keys.length, worst: worst.worst, frame: worst.frame } };
+}
+
+/** A world 2×2: columns (a, c) — the x axis — and (b, d) — the y axis (legs.ts `M2`). */
+export type M2 = [number, number, number, number];
+const DEG = 180 / Math.PI;
+const mul = (p: M2, q: M2): M2 => [p[0] * q[0] + p[1] * q[2], p[0] * q[1] + p[1] * q[3], p[2] * q[0] + p[3] * q[2], p[2] * q[1] + p[3] * q[3]];
+const inv = (m: M2): M2 => {
+  const det = m[0] * m[3] - m[1] * m[2];
+  return [m[3] / det, -m[1] / det, -m[2] / det, m[0] / det];
+};
+const apply = (m: M2, v: [number, number]): [number, number] => [m[0] * v[0] + m[1] * v[1], m[2] * v[0] + m[3] * v[1]];
+const rot = (deg: number): M2 => {
+  const r = deg / DEG;
+  return [Math.cos(r), -Math.sin(r), Math.sin(r), Math.cos(r)];
+};
+const scaleX = (s: number): M2 => [s, 0, 0, 1];
+/** A bone's setup local 2×2 in its parent's axes: inv(parent's setup world) · its setup world (legs.ts `posePath`'s L0). */
+export const setupLocal = (parentWorld0: M2, world0: M2): M2 => mul(inv(parentWorld0), world0);
+/** `p · q`. */
+export const mulM2 = mul;
+const IDENTITY: M2 = [1, 0, 0, 1];
+export { IDENTITY as M2_IDENTITY };
+const wrap180 = (d: number): number => {
+  const x = ((d + 180) % 360 + 360) % 360 - 180;
+  return x === -180 ? 180 : x;
+};
+
+/**
+ * A mapped bone under a scaled bone (legs.ts `posePath`: keyed through its
+ * parent's posed matrix), reduced once the bones above it are. Its parent's
+ * world 2×2 is posed from keys already reduced — a bone the key formula holds
+ * for (`rigid`: R(turn) · its setup world · diag(scale, 1), its turn and scale
+ * the reduced ones), or another bone of the same call given before it — times
+ * the setup locals of the unmapped bones between (`via`).
+ */
+export interface UnderBone {
+  bone: string;
+  parent: { rigid: { turn: readonly number[]; world0: M2; scale: readonly number[] }; via: M2 } | { under: string; via: M2 };
+  /** Its setup local 2×2 in its parent's axes: inv(parent's setup world) · its setup world, by rig-c's setup. */
+  local: M2;
+  /** Its setup world x-axis length. */
+  len0: number;
+  /** The world angle its x axis is asked on every frame (degrees), and the scale of it asked (1: none). */
+  target: readonly number[];
+  asked: readonly number[];
+  /** The dense rotate keys (unwrapped, as written). */
+  dense: readonly number[];
+  keep: ReadonlySet<number>;
+}
+
+/**
+ * Each bone under a scaled bone, in the order given (parents first): its
+ * rotate and scalex keys re-solved through its parent's reduced posed matrix
+ * (the key that puts its x axis on the target, and the scale that gives it the
+ * length asked), then reduced — the rotate with its error read as the world aim
+ * it lands on through that matrix, the scale with its error read as the world
+ * length over setup against the scale asked, on the rotate as reduced. Its
+ * world error is its own fit error, as down a chain the key formula holds for.
+ */
+export function reduceUnderScale(times: readonly number[], bones: readonly UnderBone[], tolerance: number, scaleTolerance: number): { rotate: Map<string, ReducedKey[]>; scale: Map<string, ReducedKey[]>; rows: ReduceRow[] } {
+  const n = times.length;
+  const samples = samplesOf(times);
+  const world = new Map<string, M2[]>();
+  const rotate = new Map<string, ReducedKey[]>();
+  const scale = new Map<string, ReducedKey[]>();
+  const rows: ReduceRow[] = [];
+  for (const b of bones) {
+    for (const [what, xs] of [['target', b.target], ['asked', b.asked], ['dense', b.dense]] as const) {
+      if (xs.length !== n) throw new Error(`reduce: bone "${b.bone}" has ${xs.length} ${what} value(s) for ${n} frame(s)`);
+    }
+    const p = b.parent;
+    let parent: M2[];
+    if ('under' in p) {
+      const above = world.get(p.under);
+      if (above === undefined) throw new Error(`reduce: bone "${b.bone}" hangs from bone "${p.under}", which is not given before it`);
+      parent = above.map((m) => mul(m, p.via));
+    } else {
+      parent = Array.from({ length: n }, (_, i) => mul(mul(mul(rot(p.rigid.turn[i]!), p.rigid.world0), scaleX(p.rigid.scale[i]!)), p.via));
+    }
+    const l0: [number, number] = [b.local[0], b.local[2]];
+    const a0 = Math.atan2(l0[1], l0[0]) * DEG;
+    /** The x axis's world vector through the parent on frame i, at rotate key k, before its own scale. */
+    const axis = (i: number, k: number) => apply(parent[i]!, apply(rot(k), l0));
+    // The dense keys re-solved through the reduced parent (posePath's solve).
+    const solved = b.target.map((t, i) => {
+      const v = apply(inv(parent[i]!), [b.asked[i]! * b.len0 * Math.cos(t / DEG), b.asked[i]! * b.len0 * Math.sin(t / DEG)]);
+      const k = Math.atan2(v[1], v[0]) * DEG - a0;
+      return b.dense[i]! + wrap180(k - b.dense[i]!);
+    });
+    const aimError = (i: number, k: number) => {
+      const w = axis(i, k);
+      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 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 });
+    // The scale that gives it the length asked on the rotate as reduced.
+    const reach = kAt.map((k, i) => Math.hypot(...axis(i, k)) / b.len0);
+    const sk = fitTrack(times, samples, { targets: reach.map((r, i) => [b.asked[i]! / r]), keep, tolerance: scaleTolerance, error: (i, v) => Math.abs(v[0]! * reach[i]! - b.asked[i]!), round: r6 });
+    const sAt = trackAt(sk, samples, 1).map((v) => v[0]!);
+    const se = worstOf(sAt.map((_, i) => i), (i) => Math.abs(sAt[i]! * reach[i]! - b.asked[i]!))!;
+    rows.push({ bone: b.bone, kind: 'scale', before: n, after: sk.length, worst: se.worst, frame: se.frame });
+    world.set(b.bone, parent.map((m, i) => mul(mul(mul(m, rot(kAt[i]!)), b.local), scaleX(sAt[i]!))));
+    rotate.set(b.bone, rk);
+    scale.set(b.bone, sk);
+  }
+  return { rotate, scale, rows };
 }

package/src/retarget.ts

@@ -57,6 +57,10 @@
  * are posed from the final targets of the bones above. A target out of reach
  * goes to the reach limit along the head-relative direction (REACH); the set's
  * `turn` is part of the solve, and only a forearm it still holds is ART-RANGE.
+ * A set with `place: "by-hip"` (rig-c/pose#93) gets the same solve against the
+ * hip, in the same pass: each of its chains whose key skeleton puts the wrist
+ * within one hip width of the mid-hip lands where the reference's wrist is from
+ * its mid-hip, in hip widths.
  *
  * The lines across the body — hips, shoulders, eyes — are read from the pose
  * after holds, whether the map uses them or not: a line under
@@ -72,12 +76,13 @@ import type { Body18 } from './joints.ts';
 import { isBody18, VIRTUAL } from './joints.ts';
 import type { Chain, JointMap, Rest, RigSlots } from './map.ts';
 import { aimAngle, aimEnds, descends, partBone, pointParts, rigPoint } from './map.ts';
-import type { Joint } from './pose.ts';
+import type { Joint, Travel } from './pose.ts';
+import { TRAVEL_IN_PLACE } from './pose.ts';
 import { Problems, Refusal } from './problems.ts';
-import type { ArtRange, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
+import type { ArtRange, ByHip, Raised, ReachShort, SlotTrack, Switch, SwitchOptions } from './switch.ts';
 import { clampArt, coveredChains, isRaised, measureArt, overflow, RANGE_SLACK, reachLimit, runsOf, selectSwitches, twoBone } from './switch.ts';
-import type { Feet, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
-import { isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, supportsOf, tipOf } from './legs.ts';
+import type { BlendHold, Closure, Feet, Floor, LegScale, PathPose, Posing, Side, Stance } from './legs.ts';
+import { holdBlend, isLegSegment, legScaleOf, legsOf, pathFrom, plantHip, posePath, rootOf, SIDES, stanceOf, stanceRangeOf, supportsOf, tipOf } from './legs.ts';
 
 const DEG = 180 / Math.PI;
 
@@ -108,8 +113,12 @@ export interface RetargetOptions extends SwitchOptions {
   plantFeet?: boolean;
   /** With plantFeet: a free ankle within this many leg lengths of the floor plants both feet, its leg stretched to reach it (`legs.ts` stanceOf, #60); 'off' (the default) plants one. */
   stance?: number | 'off';
+  /** With plantFeet: the floor's world y every support span is planted on (#85); absent, the median of the spans' planted heights. */
+  floor?: number;
   /** While a set whose arm is drawn raised shows, its wrist is placed against the rig's head in eye distances (rig-c/pose#62); false (the default) keeps the pose's angles. */
   raisedByHead?: boolean;
+  /** The sequence's `travel` (rig-c/pose#92): "in-place" makes --plant-feet let the supporting foot follow its own track and close the loop; absent, nothing changes. */
+  travel?: Travel;
 }
 
 export interface Hold {
@@ -288,12 +297,20 @@ export interface Retarget {
   planted: boolean;
   /** With --stance: the frames planted both and lifted, and the free leg's stretch (#60). */
   stance: Stance | null;
+  /** With --plant-feet: the one floor every support span was planted on, and each span's shift onto it (#85). */
+  floor: Floor | null;
+  /** With --plant-feet: the supporting leg stretched on the blend frames so its ankle stays on the floor (#85). */
+  blendHold: BlendHold | null;
+  /** With --plant-feet on an in-place sequence: the hip's x drift closed over the loop (#92). */
+  closure: Closure | null;
   /** Each ankle's world position on every frame, as the keys put it, when legs are scaled or feet planted. */
   ankles: { bones: Record<Side, string>; at: Record<Side, Pt[]> } | null;
   /** The translated bone's origin against its thigh roots' midpoint, at setup. */
   pivot: Pivot | null;
   /** With --raised-by-head: each raised set's span on each raised chain, its wrist placed against the head. */
   raised: Raised[];
+  /** Each span of a `place: "by-hip"` set on each chain it places, its wrist placed against the hip (#93). */
+  byHip: ByHip[];
 }
 
 /** The hip's pivot against the thigh roots, at setup (rig-c/pose#47). */
@@ -394,6 +411,9 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // eye line with an "a>b" aim, whose two ends are the rig's eyes.
   const head = opts.raisedByHead === true ? headOf(map) : null;
   if (head !== null && 'problem' in head) p.add('RAISED_HEAD', head.problem);
+  // `place: "by-hip"` (#93) measures against the hip in hip widths: the map must name the rig's two hip points.
+  const hips = map.alternates.some((a) => a.place !== undefined && a.place !== null) ? hipOf(map) : null;
+  if (hips !== null && 'problem' in hips) p.add('PLACE_HIP', hips.problem);
 
   // Every point the map reads, held where it is not good.
   const needed = new Set<string>();
@@ -606,9 +626,14 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // which are aimed from where the hip is.
   const legScaleOn = opts.legScale !== undefined && opts.legScale !== 'off';
   const plantOn = opts.plantFeet === true;
+  /** #92: an in-place sequence under --plant-feet — the supporting foot follows its own track, no step releases, the loop closed. */
+  const inPlace = plantOn && opts.travel === TRAVEL_IN_PLACE;
+  let closure: Closure | null = null;
   const legScale: LegScale[] = [];
   const scales = new Map<string, number[]>();
   let stance: Stance | null = null;
+  let floor: Floor | null = null;
+  let blendHold: BlendHold | null = null;
   let feet: Feet | null = null;
   let legs: ReturnType<typeof legsOf> | null = null;
   let legPath: string[] | null = null;
@@ -635,7 +660,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       const hipOf = (s: Side) => series.get(`${s}_hip`);
       const ankleOf = (s: Side) => series.get(`${s}_ankle`);
       const hr = hipOf('r'), hl = hipOf('l'), ar = ankleOf('r'), al = ankleOf('l');
-      if (hr !== undefined && hl !== undefined && ar !== undefined && al !== undefined) feet = supportsOf({ r: ar, l: al }, { r: hr, l: hl }, keyTimes, secondsOf);
+      if (hr !== undefined && hl !== undefined && ar !== undefined && al !== undefined) feet = supportsOf({ r: ar, l: al }, { r: hr, l: hl }, keyTimes, secondsOf, inPlace, plantOn); // #113: planted, the support is read from the lower ankle
       else if (plantOn) p.add('LEGS_MAP', `--plant-feet reads both hips and both ankles from the pose; the map's chains use ${['r_hip', 'l_hip', 'r_ankle', 'l_ankle'].filter((j) => !series.has(j)).join(', ')} nowhere`);
     }
   }
@@ -664,6 +689,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     if (legScale.length === 0 && !p.any) p.add('LEGS_MAP', '--leg-scale scales the leg segments (two of one side\'s hip, knee and ankle), and the map aims none');
   }
   if (opts.stance !== undefined && opts.stance !== 'off' && !plantOn) p.add('STANCE', `--stance ${opts.stance} plants the free foot beside the supporting one that --plant-feet holds, and --plant-feet is not given`);
+  if (opts.floor !== undefined && !plantOn) p.add('FLOOR', `--floor ${opts.floor} is the floor --plant-feet plants every support span on, and --plant-feet is not given`);
+  if (opts.floor !== undefined && !Number.isFinite(opts.floor)) p.add('FLOOR', `--floor is ${opts.floor}; it must be a finite world y`);
   p.throwIfAny();
   /** Every bone on the legs' path posed on frame i, by the targets as they stand. */
   const poseLegs = (i: number): PathPose => {
@@ -684,32 +711,56 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       return { r: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.r.ankleBone : ''), l: tipOf(rest, lp, legs !== null && 'legs' in legs ? legs.legs.l.ankleBone : '') };
     });
     const tb = rest.get(t!.bone)!;
-    const hip = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY]);
+    // #85: every support span on one floor — the median of their planted heights, or --floor.
+    // #92: in place, the supporting ankle's own picture x, scaled, is the track its anchor follows.
+    const follow = inPlace ? (i: number, s: Side) => series.get(`${s}_ankle`)![i]![0] * scale!.factor : undefined;
+    const planted = plantHip(feet!, (i, s) => offsets[i]![s], (i) => poseTravel[i]!, [tb.worldX, tb.worldY], opts.floor, follow);
+    const hip = planted.hip;
+    floor = planted.floor;
+    closure = planted.closure;
     for (let i = 0; i < n; i++) travel[i] = [hip[i]![0] - tb.worldX, hip[i]![1] - tb.worldY];
-    // --stance (#60): with the hip placed, a free ankle within the tolerance of the floor has its leg
-    // stretched (every bone of its chain's scalex, about the chain's root) until it reaches it.
-    if (opts.stance !== undefined && opts.stance !== 'off') {
-      const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
-      const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
-      const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
-      stance = stanceOf(feet!, ankleSeries, opts.stance, (i) => {
-        const lp = poseLegs(i);
-        return {
-          root: { r: world(i, lp.origin.get(L.r.chain.bones[0]!)!), l: world(i, lp.origin.get(L.l.chain.bones[0]!)!) },
-          ankle: { r: world(i, tipOf(rest, lp, L.r.ankleBone)), l: world(i, tipOf(rest, lp, L.l.ankleBone)) },
-        };
-      });
+    const L = (legs as { legs: Record<Side, { chain: Chain; ankleBone: string }> }).legs;
+    const world = (i: number, v: Pt): Pt => [hip[i]![0] + v[0], hip[i]![1] + v[1]];
+    /** Both legs posed on frame i by the scales as they stand, world (y up): each chain's root and ankle. */
+    const posedFeet = (i: number) => {
+      const lp = poseLegs(i);
+      return {
+        root: { r: world(i, lp.origin.get(L.r.chain.bones[0]!)!), l: world(i, lp.origin.get(L.l.chain.bones[0]!)!) },
+        ankle: { r: world(i, tipOf(rest, lp, L.r.ankleBone)), l: world(i, tipOf(rest, lp, L.l.ankleBone)) },
+      };
+    };
+    /** Every bone of a side's chain has its scalex multiplied by the stretch keyed on that side. */
+    const stretchChain = (stretch: ReadonlyArray<{ side: Side; k: number } | null>) => {
       for (const side of SIDES) {
-        if (!stance.stretch.some((x) => x?.side === side)) continue;
+        if (!stretch.some((x) => x?.side === side)) continue;
         for (const b of L[side].chain.bones) {
           const own = scales.get(b);
           const s = own === undefined ? new Array<number>(n).fill(1) : [...own];
-          stance.stretch.forEach((x, i) => {
+          stretch.forEach((x, i) => {
             if (x?.side === side) s[i] = s[i]! * x.k;
           });
           scales.set(b, s);
         }
       }
+    };
+    // #85: on a blend frame the hip is between two derivations; the supporting leg is stretched
+    // (stanceOf's mechanism, its bounds) so its ankle stays on the floor. Before --stance, whose
+    // floor is that supporting ankle. #95: the lower bound on a frame is the leg's own range there.
+    const ankleSeries = { r: series.get('r_ankle')!, l: series.get('l_ankle')! };
+    const lower = stanceRangeOf(ankleSeries, { r: series.get('r_hip')!, l: series.get('l_hip')! });
+    blendHold = holdBlend(planted.blends, n, posedFeet, lower);
+    stretchChain(blendHold.stretch);
+    // --stance (#60): with the hip placed, a free ankle within the tolerance of the floor has its leg
+    // stretched (every bone of its chain's scalex, about the chain's root) until it reaches it.
+    if (opts.stance !== undefined && opts.stance !== 'off') {
+      stance = stanceOf(feet!, ankleSeries, opts.stance, posedFeet, secondsOf, lower);
+      // The supporting leg (the blend's) and the free leg (the stance's) are different chains on a frame.
+      for (let i = 0; i < n; i++) {
+        const b = blendHold.stretch[i];
+        if (b !== null && b !== undefined && stance.stretch[i]?.side === b.side) p.add('LEGS_STRETCH', `frame ${i}: chain "${L[b.side].chain.name}" is stretched both as the supporting leg of a blend (k ${b.k}) and as the free leg of --stance (k ${stance.stretch[i]!.k}); one chain takes one stretch`);
+      }
+      p.throwIfAny();
+      stretchChain(stance.stretch);
     }
   }
   if (t !== null && scale !== null) {
@@ -851,44 +902,60 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   // neither. A target out of reach is placed at the reach limit along the head-relative direction
   // (`reachLimit`, a REACH line). The set's `turn` is part of the solve: a held upper arm has its forearm
   // re-aimed at the placed wrist, and only a forearm the turn still holds is ART-RANGE.
+  // `place: "by-hip"` (#93) is the same solve against the hip: while a set that asks for it shows, each chain
+  // its key skeleton puts the wrist within one hip width of the mid-hip (`byHipChains`) has its wrist placed
+  // at the rig's mid-hip + the reference's offset from its mid-hip, in hip widths (each side's median over the
+  // span). The rig's hips are the two points `hipOf` reads off the map, posed as the eyes are.
   const raised: Raised[] = [];
+  const byHip: ByHip[] = [];
   const raisedArt: Array<{ sw: Switch; entries: ArtRange[] }> = [];
-  const raisedJobs: Array<{ sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; l0: number; l1: number; farthest: number; eyePoints: [string, string] }> = [];
-  if (head !== null && !('problem' in head)) {
-    const eyesOn = (i: number): { centre: Pt; dist: number } => {
-      const a = posedPoint(head.points[0], i);
-      const b = posedPoint(head.points[1], i);
+  const raisedJobs: Array<{ anchor: Anchor; sw: Switch; chain: Chain; wrist: (i: number) => Pt; before: Pt[]; reference: Pt[]; placed: Pt[]; refEye: number; rigEye: number; short: Array<{ i: number; how: 'far' | 'near' | 'missed'; shortfall: number }>; upperHeld: number[]; l0: number; l1: number; farthest: number }> = [];
+  const headOk: Anchor | null = head !== null && !('problem' in head) ? { kind: 'head', joints: head.joints, points: head.points } : null;
+  const hipsOk: Anchor | null = hips !== null && !('problem' in hips) ? { kind: 'hip', joints: hips.joints, points: hips.points } : null;
+  if (headOk !== null || hipsOk !== null) {
+    /** The anchor's two rig points posed on frame i: their midpoint and their distance apart. */
+    const pairOn = (an: Anchor, i: number): { centre: Pt; dist: number } => {
+      const a = posedPoint(an.points[0], i);
+      const b = posedPoint(an.points[1], i);
       return { centre: [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2], dist: Math.hypot(b[0] - a[0], b[1] - a[1]) };
     };
-    const headBones = new Set([...head.points.flatMap((x) => pointParts(x).map(partBone))]);
-    const ra = series.get(head.joints[0])!;
-    const rb = series.get(head.joints[1])!;
-    const refCentre = (i: number): Pt => [(ra[i]![0] + rb[i]![0]) / 2, (ra[i]![1] + rb[i]![1]) / 2];
     for (const s of sw.switches) {
       const set = map.alternates.find((a) => a.name === s.set)!;
       const art: ArtRange[] = [];
       for (const cn of s.chains) {
         const c = map.chains.find((x) => x.name === cn)!;
         const drawn = set.drawn[c.bones[0]!];
-        if (drawn === undefined || !isRaised(drawn)) continue;
-        const label = `--raised-by-head: set "${set.name}" draws chain "${c.name}" raised (bone "${c.bones[0]}" at ${drawn}°)`;
+        const up = headOk !== null && drawn !== undefined && isRaised(drawn);
+        const low = hipsOk !== null && set.place?.chains.includes(c.name) === true;
+        if (up && low) {
+          p.add('PLACE_BOTH', `set "${set.name}" chain "${c.name}": --raised-by-head places its wrist against the head (bone "${c.bones[0]}" drawn at ${drawn}°, raised), and "place": "by-hip" against the hip (its key skeleton's wrist within one hip width of the mid-hip); a wrist is placed against one — drop "place" from the set or the flag`);
+          continue;
+        }
+        const anchor = up ? headOk : low ? hipsOk : null;
+        if (anchor === null) continue;
+        const ra = series.get(anchor.joints[0])!;
+        const rb = series.get(anchor.joints[1])!;
+        const refCentre = (i: number): Pt => [(ra[i]![0] + rb[i]![0]) / 2, (ra[i]![1] + rb[i]![1]) / 2];
+        const anchorBones = new Set([...anchor.points.flatMap((x) => pointParts(x).map(partBone))]);
+        const label = up ? `--raised-by-head: set "${set.name}" draws chain "${c.name}" raised (bone "${c.bones[0]}" at ${drawn}°)` : `"place": "by-hip": set "${set.name}" places chain "${c.name}"'s wrist against the hip`;
+        const CHAIN = up ? 'RAISED_CHAIN' : 'PLACE_CHAIN';
         if (c.bones.length !== 2) {
-          p.add('RAISED_CHAIN', `${label}, and the chain has ${c.bones.length} bone(s); the wrist is placed by a two-bone solve, so it must have two (upper arm, forearm)`);
+          p.add(CHAIN, `${label}, and the chain has ${c.bones.length} bone(s); the wrist is placed by a two-bone solve, so it must have two (upper arm, forearm)`);
           continue;
         }
         if (c.reach || c.aim.some((x) => x.includes('>'))) {
-          p.add('RAISED_CHAIN', `${label}, and it aims ${JSON.stringify(c.aim)}${c.reach ? ' with "reach"' : ''}; the solve turns each bone about its own origin toward the next point, so each must aim "x" or at one point`);
+          p.add(CHAIN, `${label}, and it aims ${JSON.stringify(c.aim)}${c.reach ? ' with "reach"' : ''}; the solve turns each bone about its own origin toward the next point, so each must aim "x" or at one point`);
           continue;
         }
         const [b0, b1] = c.bones as [string, string];
-        const moved = [...headBones].filter((h) => h === b0 || h === b1 || descends(rest, h, b0));
+        const moved = [...anchorBones].filter((h) => h === b0 || h === b1 || descends(rest, h, b0));
         if (moved.length > 0) {
-          p.add('RAISED_CHAIN', `${label}, and the head's eye point ${moved.map((h) => `"${h}"`).join(', ')} turns with it; the wrist cannot be placed against a head the arm moves`);
+          p.add(CHAIN, up ? `${label}, and the head's eye point ${moved.map((h) => `"${h}"`).join(', ')} turns with it; the wrist cannot be placed against a head the arm moves` : `${label}, and the hip point ${moved.map((h) => `"${h}"`).join(', ')} turns with it; the wrist cannot be placed against a hip the arm moves`);
           continue;
         }
         const wristSpec = c.aim[1] === 'x' ? `${b1}:tip` : c.aim[1]!;
         if (c.aim[1] === 'x' && !(rest.get(b1)!.length > 1e-9)) {
-          p.add('RAISED_CHAIN', `${label}, and its last bone "${b1}" aims "x" with no length; its wrist (the tip) is its origin, so there is nothing to place`);
+          p.add(CHAIN, `${label}, and its last bone "${b1}" aims "x" with no length; its wrist (the tip) is its origin, so there is nothing to place`);
           continue;
         }
         const wristOf = (i: number): Pt => posedPoint(wristSpec, i);
@@ -897,9 +964,10 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const span: number[] = [];
         for (let i = s.frames[0]; i <= s.frames[1]; i++) span.push(i);
         const refEye = median(span.map((i) => Math.hypot(rb[i]![0] - ra[i]![0], rb[i]![1] - ra[i]![1])));
-        const rigEye = median(span.map((i) => eyesOn(i).dist));
+        const rigEye = median(span.map((i) => pairOn(anchor, i).dist));
         if (!(refEye > 1e-9) || !(rigEye > 1e-9)) {
-          p.add('RAISED_EYES', `${label}: over frames ${s.frames[0]}–${s.frames[1]} the median eye distance is ${refEye > 1e-9 ? `${rigEye} units on the rig (points "${head.points[0]}", "${head.points[1]}")` : `${refEye}px in the reference (${head.joints[0]}, ${head.joints[1]})`}; an eye distance of 0 is no unit`);
+          if (up) p.add('RAISED_EYES', `${label}: over frames ${s.frames[0]}–${s.frames[1]} the median eye distance is ${refEye > 1e-9 ? `${rigEye} units on the rig (points "${anchor.points[0]}", "${anchor.points[1]}")` : `${refEye}px in the reference (${anchor.joints[0]}, ${anchor.joints[1]})`}; an eye distance of 0 is no unit`);
+          else p.add('PLACE_HIPS', `${label}: over frames ${s.frames[0]}–${s.frames[1]} the median hip width is ${refEye > 1e-9 ? `${rigEye} units on the rig (points "${anchor.points[0]}", "${anchor.points[1]}")` : `${refEye}px in the reference (${anchor.joints[0]}, ${anchor.joints[1]})`}; a hip width of 0 is no unit`);
           continue;
         }
         // The rig's own lengths, and each bone's aim against the vector it carries, at setup.
@@ -914,7 +982,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const t1 = targets.get(b1)!;
         const turn0 = set.turn[b0];
         const turn1 = set.turn[b1];
-        const job: (typeof raisedJobs)[number] = { sw: s, chain: c, wrist: wristOf, before: [], reference: [], placed: [], refEye, rigEye, short: [], upperHeld: [], l0, l1, farthest: 0, eyePoints: head.points };
+        const job: (typeof raisedJobs)[number] = { anchor, sw: s, chain: c, wrist: wristOf, before: [], reference: [], placed: [], refEye, rigEye, short: [], upperHeld: [], l0, l1, farthest: 0 };
         /** Per frame of the span: the forearm's art turn the re-aim asked, and how far past its turn. */
         const foreAsked: number[] = [];
         const foreOver: number[] = [];
@@ -923,7 +991,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
         const upperOver: number[] = [];
         const heldMiss: number[] = [];
         for (const i of span) {
-          const h = eyesOn(i);
+          const h = pairOn(anchor, i);
           const rc = refCentre(i);
           // The reference's wrist from its head centre, in its eye distances, y turned up.
           const ref: Pt = [(refWrist[i]![0] - rc[0]) / refEye, -(refWrist[i]![1] - rc[1]) / refEye];
@@ -988,7 +1056,7 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
             for (let k = a; k <= b; k++) if (heldMiss[k]! > heldMiss[worst]!) worst = k;
             const first = s.frames[0] + a;
             const last = s.frames[0] + b;
-            art.push({ set: set.name, chain: c.name, bone: b0, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(upperOver[worst]!), turn: r3(upperAsked[worst]!), limits: turn0, clamped: true, shortfall: r3(heldMiss[worst]!) });
+            art.push({ set: set.name, chain: c.name, bone: b0, frames: [first, last], seconds: r6(endOf(last) - keyTimes[first]!), maxOverflow: r3(upperOver[worst]!), turn: r3(upperAsked[worst]!), limits: turn0, clamped: true, shortfall: r3(heldMiss[worst]!), ...(up ? {} : { anchor: 'hip' as const }) });
           }
         }
         if (turn1 !== undefined) {
@@ -1020,8 +1088,8 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
   for (const job of raisedJobs) {
     const after: Pt[] = [];
     for (let i = job.sw.frames[0]; i <= job.sw.frames[1]; i++) {
-      const a = posedPoint(job.eyePoints[0], i);
-      const b = posedPoint(job.eyePoints[1], i);
+      const a = posedPoint(job.anchor.points[0], i);
+      const b = posedPoint(job.anchor.points[1], i);
       const w = job.wrist(i);
       after.push([(w[0] - (a[0] + b[0]) / 2) / job.rigEye, (w[1] - (a[1] + b[1]) / 2) / job.rigEye]);
     }
@@ -1035,12 +1103,12 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       short.push({ frames: [job.short[k]!.i, job.short[m]!.i], how: job.short[k]!.how, shortfall: { max: r6(Math.max(...fs)), median: r6(median(fs)) } });
       k = m + 1;
     }
-    raised.push({
+    const unit = { rig: r6(job.rigEye), reference: r6(job.refEye) };
+    const entry = {
       set: job.sw.set,
       chain: job.chain.name,
       frames: job.sw.frames,
       seconds: secondsOf(job.sw.frames),
-      eyes: { rig: r6(job.rigEye), reference: r6(job.refEye) },
       reference: round(job.reference),
       placed: round(job.placed),
       before: round(job.before),
@@ -1049,7 +1117,11 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
       short,
       upperHeld: job.upperHeld,
       reach: { min: r6(Math.abs(job.l0 - job.l1)), max: r6(job.l0 + job.l1), farthest: r6(job.farthest) },
-    });
+    };
+    // The unit sits after `seconds`, as the report has always written it.
+    const { set, chain, frames, seconds, ...body } = entry;
+    if (job.anchor.kind === 'head') raised.push({ set, chain, frames, seconds, eyes: unit, ...body });
+    else byHip.push({ set, chain, frames, seconds, hips: unit, ...body });
   }
 
   // The legs on their final targets: a bone under a scaled bone is keyed through
@@ -1110,10 +1182,49 @@ export function retarget(rest: Rest, map: JointMap, frames: ReadonlyArray<Partia
     animation: { duration: keyTimes[n - 1]!, tracks },
     times: keyTimes, targets, origin, holds, bends, short, endOn, flips, scale,
     switches: sw.switches, shown: sw.shown, distances: sw.distances, turns, turnsUnread, range, artRange,
-    legScale, scales, feet, planted: plantOn, stance, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised,
+    legScale, scales, feet, planted: plantOn, stance, floor, blendHold, closure, ankles, pivot: pivotOf(rest, t?.bone ?? null, legs), raised, byHip,
   };
 }
 
+/** What a placed wrist is measured against: the head (#62, the eyes) or the hip (#93, the hips) — two pose joints and the rig's two points. */
+interface Anchor {
+  kind: 'head' | 'hip';
+  joints: [string, string];
+  points: [string, string];
+}
+
+/** The hips as `place: "by-hip"` reads them: two pose joints (r_hip, l_hip) and the rig's two hip points. */
+interface Hips {
+  joints: [string, string];
+  points: [string, string];
+}
+
+/**
+ * The rig's hip points for `place: "by-hip"` (#93): the two points a chain
+ * carrying the hip line (r_hip → l_hip, either way round) names with an "a>b"
+ * aim — a pelvis turned by its hip line; else the origins of the first bones of
+ * the two chains that start at r_hip and at l_hip — the legs, whose roots are
+ * the hip joints; or why the map names neither.
+ */
+function hipOf(map: JointMap): Hips | { problem: string } {
+  for (const c of map.chains) {
+    for (let k = 0; k + 1 < c.joints.length; k++) {
+      const a = c.joints[k]!;
+      const b = c.joints[k + 1]!;
+      if (!((a === 'r_hip' && b === 'l_hip') || (a === 'l_hip' && b === 'r_hip'))) continue;
+      const aim = c.aim[k]!;
+      if (!aim.includes('>')) continue;
+      const [pa, pb] = aimEnds(c.bones[k]!, aim);
+      return { joints: [a, b], points: [pa, pb] };
+    }
+  }
+  const from = (j: string, other: string) => map.chains.find((c) => c.joints[0] === j && c.joints[1] !== other);
+  const r = from('r_hip', 'l_hip');
+  const l = from('l_hip', 'r_hip');
+  if (r !== undefined && l !== undefined) return { joints: ['r_hip', 'l_hip'], points: [r.bones[0]!, l.bones[0]!] };
+  return { problem: `"place": "by-hip" places a wrist against the hip in hip widths, read on the rig between two hip points: the two a chain carrying the hip line (r_hip → l_hip) names with an "a>b" aim, or else the first bones' origins of the two chains starting at r_hip and l_hip (the legs); the map has neither (${r === undefined && l === undefined ? 'no chain starts at r_hip or l_hip' : `no chain starts at ${r === undefined ? 'r_hip' : 'l_hip'}`})` };
+}
+
 /** The head as --raised-by-head reads it: the chain carrying the eye line, its two pose joints and the rig's two eye points. */
 interface Head {
   chain: string;