@rig-c/pose 0.41.0 → 0.43.0

package/src/depth.ts

@@ -13,10 +13,17 @@
  * | segment   | sense when foreshortened | why |
  * | --------- | ------------------------ | --- |
  * | thigh     | forward                  | a hip flexes forward; it extends back too little to foreshorten past the band |
- * | shin      | walk: forward · run: back | the gait rule (rig-c/pose#281, HQ): a walk's lifted foot comes forward, a run's is kicked back — the knee alone cannot say, since it bends forward in both |
+ * | shin      | back                     | the owner's walk statement (rig-c/pose#336): the lifted foot is behind the supporting leg — a knee folds the shin back |
  * | upper arm | with the opposite leg    | in a gait each arm swings with the opposite leg: forward when the other side's thigh is the more foreshortened of the two, back when its own is; forward (a shoulder flexes forward) when neither thigh is foreshortened |
  * | forearm   | forward                  | an elbow bends toward the back of the body, so the forearm folds forward |
  *
+ * The thigh's row is the owner's run statement (rig-c/pose#336): the lifted leg
+ * is in front, its knee protruding — a raised thigh brings the knee forward.
+ * The table is the same in a walk and a run, so `clean --depth walk|run` writes
+ * the same signs for both; the gait it records decides which joint
+ * `--draw-order depth` orders the legs by (`src/draworder.ts`): a walk by the
+ * ankle (the lifted foot behind), a run by the knee (the lifted knee in front).
+ *
  * "Forward" is the trunk's facing: toward the camera (+1) when the figure faces
  * it (its left shoulder and hip drawn right of its right ones), away (−1) when
  * it faces away, and undecided (sign 0) when the trunk is side-on — shoulders
@@ -86,8 +93,8 @@ export interface DerivedDepth {
   signs: { toward: number; away: number; flat: number };
 }
 
-/** Each frame's depth, derived from the picture's lengths for `gait` (the table above). */
-export function deriveDepth(track: readonly Joints[], gait: DepthGait): DerivedDepth {
+/** Each frame's depth, derived from the picture's lengths (the table above; the same for every gait). */
+export function deriveDepth(track: readonly Joints[]): DerivedDepth {
   const lengths = new Map(DEPTH_SEGMENT_NAMES.map((s) => [s, track.map((j) => drawn(j, s))]));
   const rest = {} as DerivedDepth['rest'];
   for (const k of ['upper_arm', 'forearm', 'thigh', 'shin'] as const) {
@@ -112,7 +119,7 @@ export function deriveDepth(track: readonly Joints[], gait: DepthGait): DerivedD
       if (r === null) continue;
       let sense: -1 | 1;
       const kind = kindOf(s);
-      if (kind === 'shin') sense = gait === 'walk' ? 1 : -1;
+      if (kind === 'shin') sense = -1;
       else if (kind === 'upper_arm') {
         // The arm swings with the opposite leg: its own thigh and the other side's, by how foreshortened each is.
         const own = ratio(`${s.slice(0, 2)}thigh` as DepthSegment);
@@ -143,19 +150,52 @@ export function segmentDepth(d: SegmentDepth, length: number): number {
   return d.sign * (length / d.ratio) * Math.sqrt(1 - r * r);
 }
 
+/**
+ * A limb's two joint depths on one frame, px (+ toward the camera): its middle joint (the upper segment's) and its end
+ * joint (the middle's plus the lower segment's), from the shoulder or hip at 0, unrounded. Null where the upper segment
+ * is not named and placed; `end` null where the lower one is not (the middle joint does not need it: rig-c/pose#336).
+ */
+export function limbJointDepths(joints: Joints, depth: FrameDepth, limb: Limb): { mid: number; end: number | null } | null {
+  const [upper, lower] = LIMBS[limb];
+  const du = depth[upper];
+  const dl = depth[lower];
+  const lu = drawn(joints, upper);
+  const ll = drawn(joints, lower);
+  if (du === undefined || lu === null) return null;
+  const mid = segmentDepth(du, lu);
+  return { mid, end: dl === undefined || ll === null ? null : mid + segmentDepth(dl, ll) };
+}
+
+/**
+ * rig-c/pose#336: the frames of a derived depth on which a shin leans the way the trunk faces — the sign table before
+ * #336, where a walk's foreshortened shin read forward. The table since leans it back (−facing) in both gaits, and a run's
+ * never changed, so only a record a release before #336 cleaned with `--depth walk` carries one. A record with no
+ * foreshortened shin reads the same under both tables and is not listed.
+ */
+export function forwardShinFrames(track: readonly Joints[], frames: ReadonlyArray<{ depth?: FrameDepth }>): number[] {
+  const out: number[] = [];
+  frames.forEach((f, i) => {
+    const face = facingOf(track[i] ?? {});
+    if (face === 0) return;
+    if ((['r_shin', 'l_shin'] as const).some((s) => f.depth?.[s]?.source === 'derived' && f.depth[s]!.sign === face)) out.push(i);
+  });
+  return out;
+}
+
+/** The DEPTH_RECLEAN refusal (#336): the file, the gait it records, the frames (the first five), and what to run. */
+export function depthRecleanText(file: string, gait: DepthGait | null, frames: readonly number[]): string {
+  const shown = frames.slice(0, 5).join(', ') + (frames.length > 5 ? `, … +${frames.length - 5} more` : '');
+  const g = gait ?? 'walk';
+  return `${file} carries derived depth (clean --depth ${gait ?? '?'}) whose foreshortened shin leans forward, the way the trunk faces, on ${frames.length} frame(s) (${shown}): the sign table before rig-c/pose#336, where a walk's lifted foot read forward. --draw-order depth reads a walk at the ankle and would draw that foot in front of the supporting leg. Clean it again with this version (rig-pose clean --depth ${g}), which leans a foreshortened shin back in both gaits; a sequence cleaned with --depth run by an earlier release is read as it is (its signs did not change), and measured depth is not checked`;
+}
+
 /** The limbs' front-to-back order on one frame, from its depth and its joints' drawn lengths. */
 export function layersOf(joints: Joints, depth: FrameDepth): FrameLayers {
   const z: Partial<Record<Limb, number>> = {};
   for (const limb of LIMB_NAMES) {
-    const [upper, lower] = LIMBS[limb];
-    const du = depth[upper];
-    const dl = depth[lower];
-    const lu = drawn(joints, upper);
-    const ll = drawn(joints, lower);
-    if (du === undefined || dl === undefined || lu === null || ll === null) continue;
-    const mid = segmentDepth(du, lu);
-    const end = mid + segmentDepth(dl, ll);
-    z[limb] = Math.round(((mid + end) / 2) * 100) / 100;
+    const j = limbJointDepths(joints, depth, limb);
+    if (j === null || j.end === null) continue;
+    z[limb] = Math.round(((j.mid + j.end) / 2) * 100) / 100;
   }
   const placed = LIMB_NAMES.filter((l) => z[l] !== undefined).sort((a, b) => z[b]! - z[a]! || LIMB_NAMES.indexOf(a) - LIMB_NAMES.indexOf(b));
   const order: Limb[][] = [];

package/src/draworder.ts

@@ -36,19 +36,38 @@
  *   ordered, holds the order before; before the first decided frame, the setup
  *   order — or, on a looped sequence, the order the clip ends in, held across
  *   the seam. A key is written where the order changes, and none while it is the
- *   setup order from the start.
+ *   setup order from the start. Its time is half a frame before the frame it
+ *   shows on (0 on frame 0), the rule the switches' attachment keys follow
+ *   (`keyAtFrame` in `switch.ts`): a key exactly on a frame time is a tie the
+ *   render breaks a frame late about half the time (rig-c/pose#325).
+ * - **By the joint the gait names** (rig-c/pose#336, the owner's two
+ *   statements). On a sequence cleaned with `--depth walk` the pair is ordered
+ *   by each leg's ankle depth (the hip at 0, plus the thigh's, plus the shin's:
+ *   `limbJointDepths`' end) — in a walk the lifted foot is behind the supporting
+ *   leg; with `--depth run` by the knee depth (the thigh's: its middle) — in a
+ *   run the lifted leg is in front, its knee protruding. The limb mean cannot
+ *   say either: a lifted leg's thigh forward and shin back cancel in it, and a
+ *   walk's flat thigh leaves it at most half a shin (35 px on the fixtures),
+ *   under the limb tie. The tie is scaled to the joint, what a flat chain can
+ *   hold there: √(1 − 0.95²) × thigh at the knee, × (thigh + shin) at the
+ *   ankle, the smaller leg's. Measured depth names no gait and keeps the limb
+ *   mean and its tie (#304).
  *
  * Pure: no clock, no randomness, no disk.
  */
 import type { Body18 } from './joints.ts';
-import { FLAT_BAND, LIMBS, type FrameLayers, type Limb } from './depth.ts';
+import { FLAT_BAND, LIMBS, limbJointDepths, type FrameLayers, type Limb } from './depth.ts';
 import { knownSetsOf, type JointMap, type Rest, type RigSets } from './map.ts';
-import { DEPTH_SEGMENTS, type DepthSegment, type FrameDepth, type Joint } from './pose.ts';
+import { DEPTH_SEGMENTS, type DepthGait, type DepthSegment, type FrameDepth, type Joint } from './pose.ts';
+import { keyAtFrame } from './switch.ts';
 
 /** The limb pairs `--draw-order depth` keys. */
 export const DRAW_ORDER_PAIRS: ReadonlyArray<readonly [Limb, Limb]> = [['r_leg', 'l_leg']];
 /** What one segment inside the flat band can hide out of the picture, per unit of its rest length: √(1 − 0.95²). */
 export const TIE_PER_LENGTH = Math.sqrt(1 - FLAT_BAND[0] * FLAT_BAND[0]);
+/** The joint a gait's legs are ordered by (rig-c/pose#336): a walk's lifted foot is behind, a run's lifted knee in front. */
+export const ORDER_JOINT: Record<DepthGait, LegJoint> = { walk: 'ankle', run: 'knee' };
+export type LegJoint = 'knee' | 'ankle';
 /** The DRAWORDER line's cap, characters (the span list is cut to it; the report carries every span). */
 export const DRAW_ORDER_LINE_MAX = 260;
 
@@ -56,7 +75,7 @@ export interface DrawOrderOffset {
   slot: string;
   offset: number;
 }
-/** One key as written into the animation (`t` the frame's time). */
+/** One key as written into the animation (`t` half a frame before the frame it shows on, 0 on frame 0: rig-c/pose#325). */
 export interface DrawOrderKey {
   t: number;
   offsets?: DrawOrderOffset[];
@@ -71,6 +90,8 @@ export interface DrawOrderPair {
   keyed: boolean;
   /** #281's tie for the pair, px: depths closer than this hold the order before (null where a rest length is unread: no tie, equal depths only). */
   tie: number | null;
+  /** #336: the joint the pair is ordered by, from the gait clean recorded (the tie then the joint's); absent, the limb mean (#304). */
+  by?: LegJoint;
   /** Why the pair is not keyed. */
   why?: string;
   /** The slots of anything else drawn between the pair's slots, in setup order (#324: the line counts them first and cuts this list). */
@@ -80,7 +101,7 @@ export interface DrawOrderPair {
 export interface DrawOrderGap {
   a: string;
   b: string;
-  /** |depth a − depth b| over the frames both limbs read, px: the median and the largest. */
+  /** |depth a − depth b| over the frames both limbs read, px: the median and the largest (at the pair's joint, when it has one). */
   median: number | null;
   max: number | null;
   /** The same as a fraction of the leg (upper + lower rest length of the limb the tie is read from); null where a rest length is unread. */
@@ -103,7 +124,7 @@ export interface DrawOrderSpan {
 }
 export interface DrawOrderReading {
   pairs: DrawOrderPair[];
-  /** The `drawOrder` timeline, with the frame each key sits on. */
+  /** The `drawOrder` timeline as written, with the frame each key first shows on. */
   keys: Array<DrawOrderKey & { frame: number }>;
   /** Every span of one decided order, setup or keyed, in frame order per pair. */
   spans: DrawOrderSpan[];
@@ -225,12 +246,15 @@ function restOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | unde
 
 /**
  * #281's tie for two limbs, px: √(1 − 0.95²) × (upper + lower ÷ 2), the smaller limb's; null where a rest length is unread.
+ * By a joint (#336): √(1 − 0.95²) × upper at the knee, × (upper + lower) at the ankle — what a flat chain can hold there.
  * `leg` is that limb's upper + lower rest length (#324's unit for the gap).
  */
-function tieOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, limbs: readonly [Limb, Limb]): { tie: number | null; leg: number | null } {
+function tieOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, limbs: readonly [Limb, Limb], by: LegJoint | undefined): { tie: number | null; leg: number | null } {
   const rests = limbs.map((l) => {
     const [u, w] = LIMBS[l].map((s) => restOf(track, depth, s));
-    return u === null || u === undefined || w === null || w === undefined ? null : { hidden: u + w / 2, leg: u + w };
+    // The knee's tie needs the upper segment alone (#336: a leg whose ankle is never placed still orders at the knee).
+    if (by === 'knee') return u === null || u === undefined ? null : { hidden: u, leg: w === null || w === undefined ? null : u + w };
+    return u === null || u === undefined || w === null || w === undefined ? null : { hidden: by === 'ankle' ? u + w : u + w / 2, leg: u + w };
   });
   if (rests[0] == null || rests[1] == null) return { tie: null, leg: null };
   const r = rests[1].hidden < rests[0].hidden ? rests[1] : rests[0];
@@ -240,13 +264,13 @@ function tieOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undef
 const round = (x: number, k: number): number => Math.round(x * 10 ** k) / 10 ** k;
 
 /** One pair's leg depth gap against its tie over the frames (the rule's own test: unequal and at least the tie). */
-function gapOf(pair: DrawOrderPair, layers: readonly FrameLayers[], leg: number | null): DrawOrderGap {
+function gapOf(pair: DrawOrderPair, zs: ReadonlyArray<Partial<Record<Limb, number>>>, leg: number | null): DrawOrderGap {
   const tie = pair.tie ?? 0;
   const gaps: number[] = [];
   let passed = 0;
-  for (const l of layers) {
-    const za = l.depth[pair.limbs[0]];
-    const zb = l.depth[pair.limbs[1]];
+  for (const z of zs) {
+    const za = z[pair.limbs[0]];
+    const zb = z[pair.limbs[1]];
     if (za === undefined || zb === undefined) continue;
     gaps.push(Math.abs(za - zb));
     if (za !== zb && Math.abs(za - zb) >= tie) passed++;
@@ -262,25 +286,42 @@ function gapOf(pair: DrawOrderPair, layers: readonly FrameLayers[], leg: number
 /**
  * The draw-order keys from the frames' layers. `track` and `depth` are the sequence's
  * joints and depth per frame (the rest lengths the tie reads); `order` is the rig's
- * setup draw order (the compiled model's slots); `times` the frames' times.
+ * setup draw order (the compiled model's slots); `times` the frames' times. `gait` is
+ * the gait clean recorded for its derived depth: a walk orders by the ankle, a run by
+ * the knee (#336); none (measured depth) by the limb mean (#304).
  */
-export function drawOrderFromDepth(layers: readonly FrameLayers[], track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, times: readonly number[], map: JointMap, rest: Rest, order: ReadonlyArray<{ name: string; bone: string }>, sets?: RigSets, loop = false): DrawOrderReading {
+export function drawOrderFromDepth(layers: readonly FrameLayers[], track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, times: readonly number[], map: JointMap, rest: Rest, order: ReadonlyArray<{ name: string; bone: string }>, sets?: RigSets, loop = false, gait: DepthGait | null = null): DrawOrderReading {
+  const by = gait === null ? undefined : ORDER_JOINT[gait];
   const resolved = DRAW_ORDER_PAIRS.map((p) => resolvePair(p, map, rest, order, sets));
   const legs = resolved.map((r) => {
-    const t = tieOf(track, depth, r.pair.limbs);
+    const t = tieOf(track, depth, r.pair.limbs, by);
     r.pair.tie = t.tie;
+    if (by !== undefined) r.pair.by = by;
     return t.leg;
   });
+  // #336: per frame, each limb's depth at the gait's joint (rounded as the layers are); without a gait, the layers' limb means.
+  const zs: ReadonlyArray<Partial<Record<Limb, number>>> =
+    by === undefined
+      ? layers.map((l) => l.depth)
+      : track.map((j, i) => {
+          const z: Partial<Record<Limb, number>> = {};
+          for (const limb of new Set(DRAW_ORDER_PAIRS.flat())) {
+            const d = depth[i] === undefined ? null : limbJointDepths(j, depth[i]!, limb);
+            const v = d === null ? null : by === 'knee' ? d.mid : d.end;
+            if (v !== null) z[limb] = Math.round(v * 100) / 100;
+          }
+          return z;
+        });
   const names = order.map((s) => s.name);
   // Per pair, per frame: who is behind ('a' | 'b'), or null for the setup order before any decision.
   const states = resolved.map((r) => {
     const tie = r.pair.tie ?? 0;
     const pass = (start: 'a' | 'b' | null): Array<'a' | 'b' | null> => {
       let state = start;
-      return layers.map((l) => {
+      return zs.map((z) => {
         if (!r.pair.keyed) return null;
-        const za = l.depth[r.pair.limbs[0]];
-        const zb = l.depth[r.pair.limbs[1]];
+        const za = z[r.pair.limbs[0]];
+        const zb = z[r.pair.limbs[1]];
         if (za !== undefined && zb !== undefined && za !== zb && Math.abs(za - zb) >= tie) state = za < zb ? 'a' : 'b';
         return state;
       });
@@ -298,12 +339,14 @@ export function drawOrderFromDepth(layers: readonly FrameLayers[], track: readon
       .sort((x, y) => names.indexOf(x.slot) - names.indexOf(y.slot));
   const keys: DrawOrderReading['keys'] = [];
   let last = '[]';
-  for (let f = 0; f < layers.length; f++) {
+  for (let f = 0; f < zs.length; f++) {
     const offs = offsetsAt(f);
     const text = JSON.stringify(offs);
     if (text === last) continue;
     last = text;
-    keys.push(offs.length === 0 ? { frame: f, t: times[f]! } : { frame: f, t: times[f]!, offsets: offs });
+    // Half a frame before the frame it shows on, as the switches' keys (`keyAtFrame`, rig-c/pose#325).
+    const t = keyAtFrame(times, f);
+    keys.push(offs.length === 0 ? { frame: f, t } : { frame: f, t, offsets: offs });
   }
   const spans: DrawOrderSpan[] = [];
   resolved.forEach((r, k) => {
@@ -314,7 +357,7 @@ export function drawOrderFromDepth(layers: readonly FrameLayers[], track: readon
       else spans.push({ behind: s === 'a' ? r.pair.a : r.pair.b, front: s === 'a' ? r.pair.b : r.pair.a, frames: [f, f], keyed: (s === 'a' ? r.aBehind : r.bBehind).length > 0 });
     });
   });
-  return { pairs: resolved.map((r) => r.pair), keys, spans, gaps: resolved.map((r, k) => gapOf(r.pair, layers, legs[k]!)) };
+  return { pairs: resolved.map((r) => r.pair), keys, spans, gaps: resolved.map((r, k) => gapOf(r.pair, zs, legs[k]!)) };
 }
 
 /** The animation's `drawOrder` value: the keys without their frames. */
@@ -330,7 +373,9 @@ const span = (f: [number, number]): string => (f[0] === f[1] ? `${f[0]}` : `${f[
  */
 export function drawOrderLines(d: DrawOrderReading, prefix = 'DRAWORDER '): string[] {
   const keyed = d.spans.filter((s) => s.keyed);
-  const head = `${prefix}from depth, ${d.keys.length} key(s) over ${keyed.length} span(s)`;
+  // #336: a keyed pair ordered by a joint names it and its joint-scaled tie.
+  const joint = d.pairs.find((p) => p.by !== undefined && p.keyed);
+  const head = `${prefix}from depth${joint === undefined ? '' : ` by the ${joint.by} (${joint.by === 'ankle' ? 'walk' : 'run'}; tie ${joint.tie === null ? 'none' : `${joint.tie} px`})`}, ${d.keys.length} key(s) over ${keyed.length} span(s)`;
   const groups = new Map<string, string[]>();
   for (const s of keyed) {
     const g = `${s.behind} behind ${s.front}`;
@@ -366,12 +411,18 @@ export function drawOrderLines(d: DrawOrderReading, prefix = 'DRAWORDER '): stri
 /** px with its fraction of the leg: "12.3 px (0.084 leg)". */
 const pxLeg = (px: number | null, legs: number | null): string => (px === null ? 'unread' : `${px} px${legs === null ? '' : ` (${legs} leg)`}`);
 
+/** " at the knee" / " at the ankle" for a pair ordered by a joint (#336), else nothing. */
+const gapAt = (d: DrawOrderReading, g: DrawOrderGap): string => {
+  const j = d.pairs.find((p) => p.a === g.a && p.b === g.b)?.by;
+  return j === undefined ? '' : ` at the ${j}`;
+};
+
 /**
  * The DRAWGAP lines (rig-c/pose#324): one per pair, keyed or not — the leg depth gap's median and
  * max against the tie, and how many frames passed it. Cut to `DRAW_ORDER_LINE_MAX` characters.
  */
 export function drawGapLines(d: DrawOrderReading, prefix = 'DRAWGAP '): string[] {
   return (d.gaps ?? []).map((g) =>
-    `${prefix}${g.a} / ${g.b}: leg depth gap median ${pxLeg(g.median, g.medianLegs)}, max ${pxLeg(g.max, g.maxLegs)}, against the tie of ${g.tie === null ? 'none (a rest length is unread; equal depths only)' : pxLeg(g.tie, g.tieLegs)}; ${g.passed} of ${g.frames} frame(s) passed it`.slice(0, DRAW_ORDER_LINE_MAX),
+    `${prefix}${g.a} / ${g.b}: leg depth gap${gapAt(d, g)} median ${pxLeg(g.median, g.medianLegs)}, max ${pxLeg(g.max, g.maxLegs)}, against the tie of ${g.tie === null ? 'none (a rest length is unread; equal depths only)' : pxLeg(g.tie, g.tieLegs)}; ${g.passed} of ${g.frames} frame(s) passed it`.slice(0, DRAW_ORDER_LINE_MAX),
   );
 }

package/src/legs.ts

@@ -58,6 +58,7 @@
  * frames (`closeLoop`), so the loop carries no net travel.
  */
 import type { Chain, JointMap, Rest } from './map.ts';
+import type { ContactKeysReading } from './contacts.ts';
 
 type Pt = [number, number];
 /** A world 2×2: columns (a, c) — the x axis — and (b, d) — the y axis. */
@@ -522,6 +523,12 @@ export interface Feet {
    * `supportsOf` on every reading.
    */
   signal?: SupportSignal;
+  /**
+   * rig-c/pose#303: what `--contact-keys` did — the keys, the frames they cover,
+   * the support without them and the runs they changed. Set by `contactKeysOf`,
+   * applied last; absent without the flag.
+   */
+  contactKeys?: ContactKeysReading;
 }
 
 /** A run of frames whose support the lower-ankle rule (rig-c/pose#113) reads differently from the reading before it. */