@rig-c/pose 0.38.0 → 0.40.0

package/src/depth.ts

@@ -0,0 +1,190 @@
+/**
+ * Derived depth (rig-c/pose#281): which way each limb segment leans out of the
+ * picture, read off its 2D length, and the limbs' front-to-back order from it.
+ *
+ * A sequence carries x and y only, so nothing downstream can say which limb is
+ * nearer the camera. A segment drawn shorter than its rest length is tilted out
+ * of the picture plane, and by how much its length says: `ratio` = drawn length
+ * ÷ rest length, the rest length being the larger of the two sides' 95th
+ * percentile picture lengths of that segment over the clip — the straight length
+ * the leg scale reads (`STRAIGHT_PERCENTILE`, #148), per segment. Which way it
+ * tilts the length cannot say; the sign comes from the body:
+ *
+ * | 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 |
+ * | 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 |
+ *
+ * "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
+ * and hips drawn less than `SIDE_ON` trunk lengths wide — since forward is then
+ * across the picture, not into it. A ratio within `FLAT_BAND` is flat, sign 0,
+ * and so is one above it (drawn longer than rest is not a tilt).
+ *
+ * The layers: each joint's depth is its parent's plus its segment's,
+ * sign × rest × √(1 − ratio²) px (rest = drawn ÷ ratio), from the shoulders and
+ * hips at 0; a limb's depth is the mean of its middle and end joints'; the limbs
+ * are ordered nearest first, equal depths (to 0.01 px) sharing a layer. A limb
+ * whose segments are not both named on a frame is not ordered on it.
+ *
+ * Pure: no clock, no randomness, no disk.
+ */
+import type { Body18 } from './joints.ts';
+import { percentile, STRAIGHT_PERCENTILE } from './legs.ts';
+import { DEPTH_SEGMENT_NAMES, DEPTH_SEGMENTS, type DepthGait, type DepthSegment, type DepthSource, type FrameDepth, type Joint, type SegmentDepth } from './pose.ts';
+
+/** A ratio within this band is flat (sign 0): cos 18.2° = 0.95, so a segment within about 18° of the picture plane reads flat. */
+export const FLAT_BAND: readonly [number, number] = [0.95, 1.05];
+/** The trunk is side-on when its shoulders and hips are drawn, on average, less than this many trunk lengths (neck → mid_hip) wide. */
+export const SIDE_ON = 0.1;
+/** The limbs `layers` orders, each by its segments from the trunk out. */
+export const LIMBS = {
+  r_arm: ['r_upper_arm', 'r_forearm'],
+  l_arm: ['l_upper_arm', 'l_forearm'],
+  r_leg: ['r_thigh', 'r_shin'],
+  l_leg: ['l_thigh', 'l_shin'],
+} as const satisfies Record<string, readonly [DepthSegment, DepthSegment]>;
+export type Limb = keyof typeof LIMBS;
+export const LIMB_NAMES = Object.keys(LIMBS) as Limb[];
+
+type Pt = [number, number];
+type Joints = Partial<Record<Body18, Joint>>;
+const at = (j: Joint | undefined): Pt | null => (j === undefined || j.state === 'missing' || j.at === undefined ? null : j.at);
+const kindOf = (s: DepthSegment) => s.slice(2) as 'upper_arm' | 'forearm' | 'thigh' | 'shin';
+const other = (s: DepthSegment): DepthSegment => `${s.startsWith('r_') ? 'l' : 'r'}_${s.slice(2)}` as DepthSegment;
+
+/** A segment's drawn length on a frame; null where a joint is not placed. */
+function drawn(joints: Joints, s: DepthSegment): number | null {
+  const [a, b] = DEPTH_SEGMENTS[s];
+  const pa = at(joints[a]);
+  const pb = at(joints[b]);
+  return pa === null || pb === null ? null : Math.hypot(pb[0] - pa[0], pb[1] - pa[1]);
+}
+
+/** The trunk's facing on a frame: +1 toward the camera, −1 away, 0 side-on or not placed. */
+export function facingOf(joints: Joints): -1 | 0 | 1 {
+  const p = (n: Body18) => at(joints[n]);
+  const [rs, ls, rh, lh, neck] = [p('r_shoulder'), p('l_shoulder'), p('r_hip'), p('l_hip'), p('neck')];
+  if (rs === null || ls === null || rh === null || lh === null || neck === null) return 0;
+  const trunk = Math.hypot(neck[0] - (rh[0] + lh[0]) / 2, neck[1] - (rh[1] + lh[1]) / 2);
+  if (!(trunk > 0)) return 0;
+  const width = (ls[0] - rs[0] + (lh[0] - rh[0])) / 2 / trunk;
+  return width > SIDE_ON ? 1 : width < -SIDE_ON ? -1 : 0;
+}
+
+export interface DerivedDepth {
+  /** Per frame, each segment whose joints are placed. */
+  frames: FrameDepth[];
+  /** Each segment kind's rest length, px (the larger side's 95th percentile); null where neither side is ever placed. */
+  rest: Record<'upper_arm' | 'forearm' | 'thigh' | 'shin', number | null>;
+  /** Frames the trunk faced the camera, faced away, and was side-on (or not placed). */
+  facing: { toward: number; away: number; side: number };
+  /** Segment-frames by sign. */
+  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 {
+  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) {
+    const sides = (['r', 'l'] as const).map((side) => percentile(lengths.get(`${side}_${k}`)!.filter((v): v is number => v !== null), STRAIGHT_PERCENTILE)).filter((v) => Number.isFinite(v) && v > 0);
+    rest[k] = sides.length === 0 ? null : Math.max(...sides);
+  }
+  const facing = { toward: 0, away: 0, side: 0 };
+  const signs = { toward: 0, away: 0, flat: 0 };
+  const frames = track.map((joints, i) => {
+    const face = facingOf(joints);
+    if (face === 1) facing.toward++;
+    else if (face === -1) facing.away++;
+    else facing.side++;
+    const ratio = (s: DepthSegment): number | null => {
+      const d = lengths.get(s)![i];
+      const r = rest[kindOf(s)];
+      return d === null || d === undefined || r === null ? null : d / r;
+    };
+    const out: FrameDepth = {};
+    for (const s of DEPTH_SEGMENT_NAMES) {
+      const r = ratio(s);
+      if (r === null) continue;
+      let sense: -1 | 1;
+      const kind = kindOf(s);
+      if (kind === 'shin') sense = gait === 'walk' ? 1 : -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);
+        const opp = ratio(other(`${s.slice(0, 2)}thigh` as DepthSegment));
+        sense = own === null || opp === null || Math.min(own, opp) >= FLAT_BAND[0] || own === opp ? 1 : opp < own ? 1 : -1;
+      } else sense = 1;
+      const sign = (r < FLAT_BAND[0] ? face * sense : 0) as -1 | 0 | 1;
+      if (sign === 1) signs.toward++;
+      else if (sign === -1) signs.away++;
+      else signs.flat++;
+      out[s] = { ratio: r, sign: sign === 0 ? 0 : sign, source: 'derived' };
+    }
+    return out;
+  });
+  return { frames, rest, facing, signs };
+}
+
+/** One frame's layers: the limbs nearest first, equal depths sharing a layer, and each limb's depth (px, + toward the camera). */
+export interface FrameLayers {
+  order: Limb[][];
+  depth: Partial<Record<Limb, number>>;
+}
+
+/** The depth one segment adds to its distal joint over its proximal one, px: sign × rest × √(1 − ratio²). */
+export function segmentDepth(d: SegmentDepth, length: number): number {
+  if (d.sign === 0 || !(d.ratio > 0)) return 0;
+  const r = Math.min(d.ratio, 1);
+  return d.sign * (length / d.ratio) * Math.sqrt(1 - r * r);
+}
+
+/** 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 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[][] = [];
+  for (const l of placed) {
+    const last = order[order.length - 1];
+    if (last !== undefined && z[last[0]!] === z[l]) last.push(l);
+    else order.push([l]);
+  }
+  return { order, depth: z };
+}
+
+/** A frame's layers as text: "r_arm > l_arm = r_leg > l_leg". */
+export const orderText = (order: Limb[][]): string => order.map((g) => g.join(' = ')).join(' > ');
+
+/** The source a sequence's depth came from, or null when its frames carry none. */
+export function depthSourceOf(frames: ReadonlyArray<{ depth?: FrameDepth }>): DepthSource | null {
+  for (const f of frames) for (const d of Object.values(f.depth ?? {})) return d.source;
+  return null;
+}
+
+/**
+ * retarget's DEPTH line (rig-c/pose#281): where the depth came from, on how many
+ * frames the limbs were ordered, and which limb was in front alone how often.
+ */
+export function depthLine(layers: readonly FrameLayers[], frames: ReadonlyArray<{ depth?: FrameDepth }>, gait: DepthGait | null): string {
+  const source = depthSourceOf(frames);
+  const from = source === null ? 'the sequence\'s depth (no segment named)' : source === 'derived' ? `the sequence's derived depth (clean --depth ${gait ?? '?'})` : 'the sequence\'s measured depth';
+  const ordered = layers.filter((l) => l.order.length > 0).length;
+  const front = LIMB_NAMES.map((limb) => `${limb} ${layers.filter((l) => l.order[0]?.length === 1 && l.order[0][0] === limb).length}`).join(', ');
+  const tied = layers.filter((l) => (l.order[0]?.length ?? 0) > 1).length;
+  return `DEPTH  layers from ${from}: the limbs ordered front to back on ${ordered} of ${layers.length} frame(s); in front alone: ${front}; tied in front on ${tied} (the report's layers)`;
+}

package/src/draworder.ts

@@ -0,0 +1,290 @@
+/**
+ * Draw order from depth (rig-c/pose#304): `retarget --draw-order depth` keys
+ * rig-c's `drawOrder` timeline from the limbs' derived depth (`layers`, #281),
+ * so the limb that reads farther from the camera is drawn behind the nearer one
+ * on that frame.
+ *
+ * - **The format.** rig-c's motion spec carries one `drawOrder` timeline per
+ *   animation, beside `tracks`: keys of `{ t, offsets? }`, each offset
+ *   `{ slot, offset }` = how many places later than its SETUP index the slot is
+ *   drawn, every key a complete statement against the setup order, and a key
+ *   with no `offsets` the setup order again. Keys are stepped.
+ * - **The pairs.** The legs (`r_leg`, `l_leg`); the arms crossing the trunk are
+ *   a later card. A limb is the map's chains naming its middle or end joint
+ *   (knee, ankle), their bones and every bone under them no other chain maps;
+ *   its slots are the slots on those bones, and an alternate set's slot on none
+ *   of them goes with the limb whose chain the set depicts, when it depicts one
+ *   of the two (a set keeps its own switch and takes the order of the limb it
+ *   replaces). A pair is keyed when its slots overlap in the rig's draw order:
+ *   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.
+ * - **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
+ *   #281's tie: the depth a limb can hold while both its segments read flat,
+ *   √(1 − 0.95²) × (upper + lower ÷ 2) of its rest lengths, the smaller limb's of
+ *   the two (a flat segment carries no depth, so closer than that the band
+ *   cannot tell them). A frame inside the tie, or where either limb is not
+ *   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.
+ *
+ * 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 { knownSetsOf, type JointMap, type Rest, type RigSets } from './map.ts';
+import { DEPTH_SEGMENTS, type DepthSegment, type FrameDepth, type Joint } from './pose.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 DRAWORDER line's cap, characters (the span list is cut to it; the report carries every span). */
+export const DRAW_ORDER_LINE_MAX = 260;
+
+export interface DrawOrderOffset {
+  slot: string;
+  offset: number;
+}
+/** One key as written into the animation (`t` the frame's time). */
+export interface DrawOrderKey {
+  t: number;
+  offsets?: DrawOrderOffset[];
+}
+export interface DrawOrderPair {
+  /** The map chain names standing for the two limbs (the first chain of each). */
+  a: string;
+  b: string;
+  limbs: [Limb, Limb];
+  /** Each limb's slots, in setup order. */
+  slots: { a: string[]; b: string[] };
+  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;
+  /** Why the pair is not keyed. */
+  why?: string;
+}
+export interface DrawOrderSpan {
+  /** The chain drawn behind, and the one in front. */
+  behind: string;
+  front: string;
+  frames: [number, number];
+  /** False where the setup order already draws it so (no key needed). */
+  keyed: boolean;
+}
+export interface DrawOrderReading {
+  pairs: DrawOrderPair[];
+  /** The `drawOrder` timeline, with the frame each key sits on. */
+  keys: Array<DrawOrderKey & { frame: number }>;
+  /** Every span of one decided order, setup or keyed, in frame order per pair. */
+  spans: DrawOrderSpan[];
+}
+
+interface Resolved {
+  pair: DrawOrderPair;
+  /** Setup index of every slot of the pair's run. */
+  lo: number;
+  hi: number;
+  /** Offsets with `a` behind, and with `b` behind; empty = the setup order. */
+  aBehind: DrawOrderOffset[];
+  bBehind: DrawOrderOffset[];
+}
+
+/** The joints of a limb that name its chains: the middle and the end. */
+function limbJoints(limb: Limb): string[] {
+  const [upper, lower] = LIMBS[limb];
+  return [DEPTH_SEGMENTS[upper][1], DEPTH_SEGMENTS[lower][1]];
+}
+
+/** The pair's run with `behind`'s slots first: each moved slot's offset from its setup index. */
+function arrangement(order: readonly string[], lo: number, behind: readonly string[], front: readonly string[]): DrawOrderOffset[] {
+  const placed = [...behind, ...front];
+  const out: DrawOrderOffset[] = [];
+  placed.forEach((slot, k) => {
+    const offset = lo + k - order.indexOf(slot);
+    if (offset !== 0) out.push({ slot, offset });
+  });
+  return out.sort((x, y) => order.indexOf(x.slot) - order.indexOf(y.slot));
+}
+
+function resolvePair(pairLimbs: readonly [Limb, Limb], map: JointMap, rest: Rest, order: ReadonlyArray<{ name: string; bone: string }>, sets: RigSets | undefined): Resolved {
+  const names = order.map((s) => s.name);
+  const chainsOf = (limb: Limb) => map.chains.filter((c) => limbJoints(limb).some((j) => (c.joints as readonly string[]).includes(j)));
+  const mapped = new Map(map.chains.flatMap((c) => c.bones.map((b) => [b, c.name] as const)));
+  const [ca, cb] = [chainsOf(pairLimbs[0]), chainsOf(pairLimbs[1])];
+  const pair: DrawOrderPair = { a: ca[0]?.name ?? pairLimbs[0], b: cb[0]?.name ?? pairLimbs[1], limbs: [pairLimbs[0], pairLimbs[1]], slots: { a: [], b: [] }, keyed: false, tie: null };
+  const none = (why: string): Resolved => ({ pair: { ...pair, why }, lo: 0, hi: -1, aBehind: [], bBehind: [] });
+  for (const [limb, cs] of [[pairLimbs[0], ca], [pairLimbs[1], cb]] as const) {
+    if (cs.length === 0) return none(`no chain of the map names ${limbJoints(limb).join(' or ')} (the ${limb.replace('_', ' ')})`);
+  }
+  // The limb's bones: its chains' and every bone under them that no other chain maps.
+  const bonesOf = (cs: typeof ca): Set<string> => {
+    const own = new Set(cs.flatMap((c) => c.bones));
+    const chainNames = new Set(cs.map((c) => c.name));
+    const out = new Set(own);
+    for (const [b] of rest) {
+      if (out.has(b)) continue;
+      const m = mapped.get(b);
+      if (m !== undefined && !chainNames.has(m)) continue;
+      for (let p = rest.get(b)?.parent ?? null; p !== null; p = rest.get(p)?.parent ?? null) {
+        if (own.has(p)) {
+          out.add(b);
+          break;
+        }
+        const pm = mapped.get(p);
+        if (pm !== undefined && !chainNames.has(pm)) break;
+      }
+    }
+    return out;
+  };
+  const [ba, bb] = [bonesOf(ca), bonesOf(cb)];
+  const slotsA = new Set(order.filter((s) => ba.has(s.bone)).map((s) => s.name));
+  const slotsB = new Set(order.filter((s) => bb.has(s.bone)).map((s) => s.name));
+  // An alternate set's slot on neither limb's bones goes with the limb whose chain the set depicts (one of the two).
+  const known = knownSetsOf(map, sets);
+  const [na, nb] = [new Set(ca.map((c) => c.name)), new Set(cb.map((c) => c.name))];
+  for (const alt of map.alternates) {
+    const depictsA = alt.chains.some((c) => na.has(c));
+    const depictsB = alt.chains.some((c) => nb.has(c));
+    if (depictsA === depictsB) continue;
+    for (const slot of Object.keys(known.get(alt.name)?.slots ?? alt.slots)) {
+      if (!names.includes(slot) || slotsA.has(slot) || slotsB.has(slot)) continue;
+      (depictsA ? slotsA : slotsB).add(slot);
+    }
+  }
+  const a = names.filter((n) => slotsA.has(n));
+  const b = names.filter((n) => slotsB.has(n));
+  pair.slots = { a, b };
+  if (a.length === 0 || b.length === 0) return none(`${a.length === 0 ? pair.a : pair.b} has no slot (no slot on its bones or on a set depicting it)`);
+  const idx = [...a, ...b].map((n) => names.indexOf(n)).sort((x, y) => x - y);
+  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)`);
+  return { pair: { ...pair, keyed: true }, lo, hi, aBehind: arrangement(names, lo, a, b), bBehind: arrangement(names, lo, b, a) };
+}
+
+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. */
+function restOf(track: readonly Joints[], depth: ReadonlyArray<FrameDepth | undefined>, s: DepthSegment): number | null {
+  const [p, q] = DEPTH_SEGMENTS[s];
+  const vals: number[] = [];
+  track.forEach((j, i) => {
+    const d = depth[i]?.[s];
+    const a = j[p];
+    const b = j[q];
+    if (d === undefined || !(d.ratio > 0) || a?.at === undefined || b?.at === undefined || a.state === 'missing' || b.state === 'missing') return;
+    vals.push(Math.hypot(b.at[0] - a.at[0], b.at[1] - a.at[1]) / d.ratio);
+  });
+  if (vals.length === 0) return null;
+  vals.sort((x, y) => x - y);
+  const m = vals.length >> 1;
+  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) => {
+    const [u, w] = LIMBS[l].map((s) => restOf(track, depth, s));
+    return u === null || u === undefined || w === null || w === undefined ? null : u + w / 2;
+  });
+  return hidden.some((h) => h === null) ? null : Math.round(TIE_PER_LENGTH * Math.min(hidden[0]!, hidden[1]!) * 100) / 100;
+}
+
+/**
+ * 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.
+ */
+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 {
+  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 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) => {
+        if (!r.pair.keyed) return null;
+        const za = l.depth[r.pair.limbs[0]];
+        const zb = l.depth[r.pair.limbs[1]];
+        if (za !== undefined && zb !== undefined && za !== zb && Math.abs(za - zb) >= tie) state = za < zb ? 'a' : 'b';
+        return state;
+      });
+    };
+    const first = pass(null);
+    // A loop's first frames continue its last: a tie at the start holds the order the clip ends in.
+    return loop && first.length > 0 ? pass(first[first.length - 1]!) : first;
+  });
+  const offsetsAt = (f: number): DrawOrderOffset[] =>
+    resolved
+      .flatMap((r, k) => {
+        const s = states[k]![f];
+        return s === null || s === undefined ? [] : s === 'a' ? r.aBehind : r.bBehind;
+      })
+      .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++) {
+    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 });
+  }
+  const spans: DrawOrderSpan[] = [];
+  resolved.forEach((r, k) => {
+    const st = states[k]!;
+    st.forEach((s, f) => {
+      if (s === null) return;
+      if (f > 0 && st[f - 1] === s) spans[spans.length - 1]!.frames[1] = f;
+      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 };
+}
+
+/** The animation's `drawOrder` value: the keys without their frames. */
+export const drawOrderKeys = (d: DrawOrderReading): DrawOrderKey[] => d.keys.map(({ frame: _frame, ...k }) => k);
+
+/** Frame runs as text: "3–12". */
+const span = (f: [number, number]): string => (f[0] === f[1] ? `${f[0]}` : `${f[0]}–${f[1]}`);
+
+/**
+ * The DRAWORDER lines (rig-c/pose#304): the keys and the spans they key, per
+ * "behind" relation, cut to `DRAW_ORDER_LINE_MAX` characters; then one line per
+ * pair not keyed, saying why.
+ */
+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)`;
+  const groups = new Map<string, string[]>();
+  for (const s of keyed) {
+    const g = `${s.behind} behind ${s.front}`;
+    groups.set(g, [...(groups.get(g) ?? []), span(s.frames)]);
+  }
+  // The spans as text, grouped by relation, cut where the next one would pass the cap with its "more" tail.
+  const text = (n: number): string => {
+    const parts: string[] = [];
+    let left = n;
+    for (const [g, list] of groups) {
+      if (left === 0) break;
+      parts.push(`${g} ${list.slice(0, left).join(', ')}`);
+      left -= Math.min(left, list.length);
+    }
+    const more = keyed.length - n;
+    return `${head} (${parts.join('; ')}${more > 0 ? ` … +${more} more in the report's drawOrder` : ''})`;
+  };
+  let n = keyed.length;
+  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));
+  return lines;
+}