@rig-c/pose 0.40.0 → 0.42.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

@@ -19,7 +19,13 @@
  *   together they fill one unbroken run of the setup order. A slot of anything
  *   else drawn between them would be re-layered by the swap — that is changing
  *   the setup order, not keying the pair — so the pair is not keyed and the line
- *   names the slot.
+ *   counts the slots between them first, then names them as far as the line's
+ *   cap allows (#324; the report's `why` and `between` carry every one).
+ * - **The gap (#324).** Per pair, keyed or not, the leg depth gap |depth a −
+ *   depth b| over the frames both limbs read — its median and max, in px and as
+ *   a fraction of the leg (upper + lower rest length of the limb the tie is read
+ *   from) — against the tie, and the frames that passed it: the `DRAWGAP` line
+ *   and the report's `drawOrder.gaps`.
  * - **The rule.** On each frame the limb whose depth is the lower (farther from
  *   the camera) is drawn behind: its slots first in the pair's run, in their
  *   setup order, then the other's — when the two depths differ by at least
@@ -30,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;
 
@@ -50,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[];
@@ -65,8 +90,29 @@ 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). */
+  between?: string[];
+}
+/** One pair's leg depth gap against its tie (#324): the figures that say why a pair keyed little or nothing. */
+export interface DrawOrderGap {
+  a: string;
+  b: string;
+  /** |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. */
+  medianLegs: number | null;
+  maxLegs: number | null;
+  /** The pair's tie, px and as a fraction of the leg. */
+  tie: number | null;
+  tieLegs: number | null;
+  /** Frames whose gap passed the tie (decided an order), of the frames both limbs read. */
+  passed: number;
+  frames: number;
 }
 export interface DrawOrderSpan {
   /** The chain drawn behind, and the one in front. */
@@ -78,10 +124,12 @@ 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[];
+  /** Per pair, the leg depth gap against the tie (#324); keyed or not. */
+  gaps?: DrawOrderGap[];
 }
 
 interface Resolved {
@@ -164,10 +212,19 @@ function resolvePair(pairLimbs: readonly [Limb, Limb], map: JointMap, rest: Rest
   const lo = idx[0]!;
   const hi = idx[idx.length - 1]!;
   const between = names.slice(lo, hi + 1).filter((n) => !slotsA.has(n) && !slotsB.has(n));
-  if (between.length > 0) return none(`their slots do not overlap in the draw order: ${between.map((n) => `"${n}"`).join(', ')} ${between.length === 1 ? 'is' : 'are'} drawn between them, and a swap would re-layer ${between.length === 1 ? 'it' : 'them'} (the setup order is not changed here)`);
+  if (between.length > 0) return { ...none(betweenWhy(between, between.length)), pair: { ...pair, why: betweenWhy(between, between.length), between } };
   return { pair: { ...pair, keyed: true }, lo, hi, aBehind: arrangement(names, lo, a, b), bBehind: arrangement(names, lo, b, a) };
 }
 
+/** The not-keyed reason for slots drawn between the pair: the count first, then the first `shown` of the list (#324). */
+function betweenWhy(between: readonly string[], shown: number): string {
+  const tail = 'the setup order is not changed here';
+  if (between.length === 1) return shown > 0 ? `1 slot: "${between[0]}" is drawn between them, and a swap would re-layer it (${tail})` : `1 slot is drawn between them (… +1 more), and a swap would re-layer it (${tail})`;
+  const more = between.length - shown;
+  const list = `${between.slice(0, shown).map((n) => `"${n}"`).join(', ')}${more > 0 ? `${shown > 0 ? ', ' : ''}… +${more} more` : ''}`;
+  return `${between.length} slots are drawn between them (${list}), and a swap would re-layer them (${tail})`;
+}
+
 type Joints = Partial<Record<Body18, Joint>>;
 
 /** A segment's rest length as the depth states it (drawn ÷ ratio), the median over the frames that name it; null where none does. */
@@ -187,33 +244,84 @@ function restOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | unde
   return vals.length % 2 === 1 ? vals[m]! : (vals[m - 1]! + vals[m]!) / 2;
 }
 
-/** #281's tie for two limbs, px: √(1 − 0.95²) × (upper + lower ÷ 2), the smaller limb's; null where a rest length is unread. */
-function tieOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, limbs: readonly [Limb, Limb]): number | null {
-  const hidden = limbs.map((l) => {
+/**
+ * #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], 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 : u + w / 2;
+    // 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 };
   });
-  return hidden.some((h) => h === null) ? null : Math.round(TIE_PER_LENGTH * Math.min(hidden[0]!, hidden[1]!) * 100) / 100;
+  if (rests[0] == null || rests[1] == null) return { tie: null, leg: null };
+  const r = rests[1].hidden < rests[0].hidden ? rests[1] : rests[0];
+  return { tie: Math.round(TIE_PER_LENGTH * r.hidden * 100) / 100, leg: r.leg };
+}
+
+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, zs: ReadonlyArray<Partial<Record<Limb, number>>>, leg: number | null): DrawOrderGap {
+  const tie = pair.tie ?? 0;
+  const gaps: number[] = [];
+  let passed = 0;
+  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++;
+  }
+  gaps.sort((x, y) => x - y);
+  const m = gaps.length >> 1;
+  const median = gaps.length === 0 ? null : gaps.length % 2 === 1 ? gaps[m]! : (gaps[m - 1]! + gaps[m]!) / 2;
+  const max = gaps.length === 0 ? null : gaps[gaps.length - 1]!;
+  const legs = (x: number | null): number | null => (x === null || leg === null || !(leg > 0) ? null : round(x / leg, 3));
+  return { a: pair.a, b: pair.b, median: median === null ? null : round(median, 2), max: max === null ? null : round(max, 2), medianLegs: legs(median), maxLegs: legs(max), tie: pair.tie, tieLegs: legs(pair.tie), passed, frames: gaps.length };
 }
 
 /**
  * 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));
-  for (const r of resolved) r.pair.tie = tieOf(track, depth, r.pair.limbs);
+  const legs = resolved.map((r) => {
+    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;
       });
@@ -231,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) => {
@@ -247,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 };
+  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. */
@@ -263,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}`;
@@ -285,6 +397,32 @@ export function drawOrderLines(d: DrawOrderReading, prefix = 'DRAWORDER '): stri
   while (n > 1 && text(n).length > DRAW_ORDER_LINE_MAX) n--;
   const why = d.pairs.every((p) => !p.keyed) ? 'no pair keyed' : 'the setup order holds on every frame';
   const lines = [keyed.length === 0 ? `${head} (${why})` : text(n)];
-  for (const p of d.pairs) if (!p.keyed) lines.push(`${prefix}${p.a} / ${p.b} not keyed: ${p.why}`.slice(0, DRAW_ORDER_LINE_MAX));
+  for (const p of d.pairs) {
+    if (p.keyed) continue;
+    const line = (why: string | undefined): string => `${prefix}${p.a} / ${p.b} not keyed: ${why}`;
+    // Slots between the pair: the count first, the list cut until the line fits (#324).
+    let shown = p.between?.length ?? 0;
+    while (p.between !== undefined && shown > 0 && line(betweenWhy(p.between, shown)).length > DRAW_ORDER_LINE_MAX) shown--;
+    lines.push(line(p.between === undefined ? p.why : betweenWhy(p.between, shown)).slice(0, DRAW_ORDER_LINE_MAX));
+  }
   return lines;
 }
+
+/** 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${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. */

package/src/outdir.ts

@@ -14,7 +14,7 @@ export type OutDirs = Map<string, string[]>;
 
 const writable = (dir: string): boolean => {
   try {
-    accessSync(dir, constants.W_OK);
+    accessSync(dir, constants.W_OK | constants.X_OK);
     return true;
   } catch {
     return false;
@@ -22,9 +22,9 @@ const writable = (dir: string): boolean => {
 };
 
 /**
- * Check where each named output lands: its directory is there, or the nearest existing ancestor
- * is a directory this process can write into. A miss is added to `p`; a directory still to make
- * is added to `dirs`. A directory a flag names itself (--build, --render) is checked by its parent.
+ * Check where each named output lands: its directory is there and this process can write into it
+ * (rig-c/pose#323), or the nearest existing ancestor is a directory this process can write into.
+ * A miss is added to `p`; a directory still to make is added to `dirs`. A directory a flag names itself (--build, --render) is checked by its parent.
  */
 export function planOutDirs(outputs: ReadonlyArray<readonly [string, string | undefined]>, p: Problems, dirs: OutDirs = new Map()): OutDirs {
   for (const [flag, path] of outputs) {
@@ -33,7 +33,7 @@ export function planOutDirs(outputs: ReadonlyArray<readonly [string, string | un
     let up = dir;
     while (!existsSync(up) && dirname(up) !== up) up = dirname(up);
     if (!statSync(up).isDirectory()) p.add('ARG_PATH', up === dir ? `${flag} ${path} — ${dir} is not a directory` : `${flag} ${path} — ${up} is a file, so directory ${dir} cannot be made under it`);
-    else if (up !== dir && !writable(up)) p.add('ARG_PATH', `${flag} ${path} — ${up} is not writable, so directory ${dir} cannot be made under it`);
+    else if (!writable(up)) p.add('ARG_PATH', up === dir ? `${flag} ${path} — ${dir} is not writable` : `${flag} ${path} — ${up} is not writable, so directory ${dir} cannot be made under it`);
     else if (up !== dir) dirs.set(dir, [...(dirs.get(dir) ?? []), `${flag} ${path}`]);
   }
   return dirs;