@rig-c/pose 0.39.0 → 0.41.0

package/src/draworder.ts

@@ -0,0 +1,377 @@
+/**
+ * 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
+ *   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
+ *   #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;
+  /** 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. */
+  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. */
+  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[];
+  /** Per pair, the leg depth gap against the tie (#324); keyed or not. */
+  gaps?: DrawOrderGap[];
+}
+
+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(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. */
+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.
+ * `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 } {
+  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 };
+  });
+  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, layers: readonly FrameLayers[], 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]];
+    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.
+ */
+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));
+  const legs = resolved.map((r) => {
+    const t = tieOf(track, depth, r.pair.limbs);
+    r.pair.tie = t.tie;
+    return t.leg;
+  });
+  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, gaps: resolved.map((r, k) => gapOf(r.pair, layers, legs[k]!)) };
+}
+
+/** 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) 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)`}`);
+
+/**
+ * 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),
+  );
+}

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;

package/src/pelvis.ts

@@ -31,6 +31,11 @@
  *   scan runs down to where the colour was found. The first patch that holds
  *   and is not the background is the garment; with none, the midpoint's median
  *   is read as it is.
+ *   The line is fitted through the band's top edge (rig-c/pose#318): where a
+ *   strip of the garment is too thin for the colour test (a waistband drawn as
+ *   two ink lines), the tops step between the strip's lines, and each column
+ *   is followed up to its topmost garment pixel; an edge that cuts across the
+ *   band under it (a fold) is declined.
  *
  * The forearms are not read: pixels near the segments elbow → wrist (and the
  * hands) are masked, since a hanging arm passes the hips in a walk. A frame
@@ -76,13 +81,17 @@ export const MAX_RMS = 2.5;
 export const ARM_RADIUS = 0.15;
 /** Hips closer than this in the picture, px, have no span to read across (a figure seen side-on). */
 export const MIN_SPAN = 6;
+/** The band's top is taken above the scan's tops only when their climbs to it differ by more than this many rows (rig-c/pose#318): each end of a clean edge's climb is found to a row. */
+export const CLIMB_SPREAD = 2;
+/** The band's top is climbed against at most this many garment colours (rig-c/pose#318): a paletted garment's own, or a painted one's fullest cells. */
+export const MAX_CLOTH = 16;
 
 /**
  * One frame's reading: the tilt (Spine degrees, r_hip → l_hip), or why it was declined. A waistband
  * read through the window mean says so (`mean`), and one whose colour was found below the hips says
- * how far (`below`, px).
+ * how far (`below`, px); one whose band top lay above the colour's edge in some columns says how many (`raised`, #318).
  */
-export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number } | { kind: string; why: string };
+export type Reading = { tilt: number; cover: number; rms: number; mean?: true; below?: number; raised?: number } | { kind: string; why: string };
 
 /** The frame as RGB over white, its background colour, and which pixels are masked (forearms, hands). */
 interface Frame {
@@ -321,6 +330,7 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
       }
     }
   }
+  const raised = toBandTop(f, tops, g, top, colourAt);
   const share = tops.length / cols;
   if (share < MIN_COVER) {
     return above > cols / 2 ? { kind: 'garment above the band', why: `the garment runs above the band read (${above} of ${cols} columns carry its colour ${(1.5 * span).toFixed(0)} px above the hips); no waistband edge` } : { kind: 'waistband edge too short', why: `the garment's top edge is found in ${tops.length} of the ${cols} columns between the hips (${(100 * share).toFixed(0)}% < ${100 * MIN_COVER}%)` };
@@ -329,7 +339,197 @@ function waistband(f: Frame, c: Pt, span: number, x0: number, x1: number, cols:
   if (fit === null) return { kind: 'no line', why: 'the garment\'s top edge does not fit a line (fewer than three columns)' };
   if (fit.rms > MAX_RMS) return { kind: 'not a straight waistband', why: `the garment's top edge lies ${fit.rms.toFixed(2)} px from its line (root mean square > ${MAX_RMS}); not a straight waistband` };
   if (Math.abs(Math.atan(fit.m)) * (180 / Math.PI) > 45) return { kind: 'waistband too steep', why: `the garment's top edge runs ${(Math.atan(fit.m) * (180 / Math.PI)).toFixed(1)}° from level; a waistband is within 45°` };
-  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}) };
+  const off = notTheBand(f, fit, tops, top, colourAt);
+  if (off !== null) return off;
+  return { tilt: tiltOf(fit.m, rHip, lHip), cover: share, rms: fit.rms, ...(isMean ? { mean: true as const } : {}), ...(below > 0 ? { below } : {}), ...(raised > 0 ? { raised } : {}) };
+}
+
+/**
+ * rig-c/pose#318: the band's top edge, the topmost garment boundary in each column. The three-row test misses garment
+ * above the row it finds when a strip of it is too thin to carry the colour three rows deep (through the window mean,
+ * a strip between two ink lines never does), so the tops step between a strip's top line and the cloth under its lower
+ * line. The garment's colours are the picture's own: the pixels of three rows in each column `DITHER_RADIUS + 1` below
+ * the row the scan found, clear of the edge's blend (an outline there would lend the colour above to the garment). The
+ * thing above has one colour, `a`: the median, over the columns read, of the rows from the scan's top down to
+ * `3 · (DITHER_RADIUS + 1)` above the topmost top — clear of the edge's blend, an outline and a window, and by area, so
+ * a line crossing it or a tilted band's outline in a few of its rows does not move it. From each top
+ * the column is followed up, pixel by pixel, while a pixel is no nearer to `a` than to the nearest garment pixel (cloth
+ * of any shade, and the ink lines on it, are); a climb that reaches the scan's top or a forearm does not see the top.
+ * The band's top is the topmost cloth pixel on the path (within `GARMENT_DIFF` of a garment pixel), from where the climb
+ * stopped down to the scan's three rows: an outline above it, or a line leaving the band upward, is ink, not garment;
+ * a thin strip's cloth between its two lines is garment. A clean edge climbs
+ * about the same rows in every column — the distance between two boundaries each found to a row — so only when the
+ * climbs differ by more than `CLIMB_SPREAD` rows (90th less 10th percentile) do the columns take their topmost garment
+ * row — and a column whose top was not seen is then not read, since its scan top is the lower level; otherwise the
+ * tops stay exactly as read. Nothing is done when the colour above is the garment's (its median
+ * within `GARMENT_DIFF`). Rewrites `tops` in place; returns how many moved.
+ */
+function toBandTop(f: Frame, tops: Pt[], g: RGB, top: number, colourAt: (x: number, y: number) => RGB | null): number {
+  if (tops.length === 0) return 0;
+  const lift = DITHER_RADIUS + 1;
+  const ya = Math.min(...tops.map((p) => p[1])) - 3 * lift;
+  if (ya < top) return 0;
+  // The garment's colours, at most `MAX_CLOTH`: a paletted garment's few, as they are; a painted one's many, as the mean
+  // colours of the `MAX_CLOTH` fullest cells of a `GARMENT_DIFF / 2` grid (first filled first among equals). The climb
+  // compares each pixel against them all, so their number is bounded whatever the span.
+  const exact = new Map<string, RGB>();
+  const cells = new Map<string, { s: RGB; n: number }>();
+  const step = GARMENT_DIFF / 2;
+  for (const [x, y0] of tops) {
+    for (let k = 0; k < 3; k++) {
+      const y = y0 + lift + k;
+      if (y < 0 || y >= f.h || f.masked(x, y)) continue;
+      const p = f.rgb(x, y);
+      if (exact.size <= MAX_CLOTH) exact.set(p.join(','), p);
+      const key = p.map((v) => Math.floor(v / step)).join(',');
+      const c = cells.get(key);
+      if (c === undefined) cells.set(key, { s: [p[0], p[1], p[2]], n: 1 });
+      else {
+        c.s[0] += p[0];
+        c.s[1] += p[1];
+        c.s[2] += p[2];
+        c.n++;
+      }
+    }
+  }
+  const cloth: RGB[] = exact.size <= MAX_CLOTH ? [...exact.values()] : [...cells.values()].sort((u, v) => v.n - u.n).slice(0, MAX_CLOTH).map((c) => [c.s[0] / c.n, c.s[1] / c.n, c.s[2] / c.n]);
+  if (cloth.length === 0) return 0;
+  // The colour above: the median of the region, channel by channel, read twice over it rather than held.
+  const a = regionMedian((visit) => {
+    for (const [x] of tops) {
+      for (let y = top; y <= ya; y++) {
+        const p = f.masked(x, y) ? null : colourAt(x, y);
+        if (p !== null) visit(p);
+      }
+    }
+  });
+  if (a === null) return 0;
+  if (diff(a, g) <= GARMENT_DIFF) return 0;
+  const nearest = (p: RGB, cs: RGB[]) => Math.min(...cs.map((q) => diff(p, q)));
+  const climbs = tops.map(([x, y0]) => {
+    let y = y0;
+    while (true) {
+      if (y - 1 < top || f.masked(x, y - 1)) return null;
+      const p = f.rgb(x, y - 1);
+      if (diff(p, a) < nearest(p, cloth)) break;
+      y--;
+    }
+    // The band's top: the topmost cloth pixel on the path, from where the climb stopped down to the scan's three rows.
+    for (let v = y; v <= y0 + 2; v++) if (v < f.h && nearest(f.rgb(x, v), cloth) <= GARMENT_DIFF) return y0 - v;
+    return null;
+  });
+  const ks = climbs.filter((k): k is number => k !== null).sort((p, q) => p - q);
+  if (ks.length === 0) return 0;
+  const rank = (q: number) => ks[Math.min(ks.length - 1, Math.max(0, Math.ceil(q * ks.length) - 1))]!;
+  if (rank(0.9) - rank(0.1) <= CLIMB_SPREAD) return 0;
+  let moved = 0;
+  const read = tops.flatMap((t, i): Pt[] => {
+    const k = climbs[i];
+    if (k === null || k === undefined) return [];
+    if (k !== 0) moved++;
+    return [[t[0], t[1] - k]];
+  });
+  tops.splice(0, tops.length, ...read);
+  return moved;
+}
+
+/**
+ * The median, channel by channel, of the colours a region yields (`median`'s value: the middle one, or the mean of the
+ * two middle ones), without holding them: a first pass counts each channel's values by whole step (0–255), which names
+ * the step the middle rank falls in; a second keeps only the values in that step, as distinct values and counts. Memory
+ * is the 256 counts and the distinct values of one step. Null for an empty region.
+ */
+function regionMedian(each: (visit: (p: RGB) => void) => void): RGB | null {
+  const bin = (v: number) => Math.max(0, Math.min(255, Math.floor(v)));
+  const hist = [new Float64Array(256), new Float64Array(256), new Float64Array(256)];
+  let n = 0;
+  each((p) => {
+    n++;
+    for (let k = 0; k < 3; k++) hist[k]![bin(p[k]!)]!++;
+  });
+  if (n === 0) return null;
+  const m = n >> 1;
+  const ranks = n % 2 === 1 ? [m] : [m - 1, m];
+  // For each channel and rank: the step it falls in and its rank within the step.
+  const want = [0, 1, 2].map((k) => ranks.map((r) => {
+    let below = 0;
+    for (let b = 0; b < 256; b++) {
+      const c = hist[k]![b]!;
+      if (r < below + c) return { b, r: r - below };
+      below += c;
+    }
+    throw new Error('unreachable: a rank beyond the count');
+  }));
+  const kept = [0, 1, 2].map(() => new Map<number, Map<number, number>>());
+  for (let k = 0; k < 3; k++) for (const w of want[k]!) kept[k]!.set(w.b, new Map());
+  each((p) => {
+    for (let k = 0; k < 3; k++) {
+      const vs = kept[k]!.get(bin(p[k]!));
+      if (vs !== undefined) vs.set(p[k]!, (vs.get(p[k]!) ?? 0) + 1);
+    }
+  });
+  const at = (k: number, w: { b: number; r: number }) => {
+    let below = 0;
+    for (const [v, c] of [...kept[k]!.get(w.b)!.entries()].sort((u, z) => u[0] - z[0])) {
+      if (w.r < below + c) return v;
+      below += c;
+    }
+    throw new Error('unreachable: a rank beyond the step');
+  };
+  return [0, 1, 2].map((k) => {
+    const vs = want[k]!.map((w) => at(k, w));
+    return vs.length === 1 ? vs[0]! : (vs[0]! + vs[1]!) / 2;
+  }) as RGB;
+}
+
+/**
+ * rig-c/pose#318: the edge the waistband reader fitted is declined when it cuts across the band instead of running
+ * along it — a fold's edge under a band the colour test passed over. Above the edge, in each column read, the colour
+ * `DITHER_RADIUS + 1` rows up (past the outline and the window's blend) is followed up while it holds within
+ * `GARMENT_DIFF`; where it stops is the band's top. When at least `MIN_COVER` of the columns read show such a band (not
+ * the ground, not open up to the scan's top), its top is fitted as a line. The two lines bound a strip of thickness
+ * `ta` and `tb` at the read columns' ends. A line inside a band of thickness t across a width W departs from the band's
+ * direction by at most atan(t / W); an edge whose strip more than doubles across the hips (|ta − tb| > min(ta, tb)), or
+ * crosses the band's top, cuts across the garment instead of running along the band.
+ *
+ * Null when the edge is the band's (or nothing above it is a band to hold it to).
+ */
+function notTheBand(f: Frame, fit: { m: number; q: number }, tops: Pt[], top: number, colourAt: (x: number, y: number) => RGB | null): Reading | null {
+  const edgeAt = (x: number) => fit.m * x + fit.q;
+  const bandTops: Pt[] = [];
+  for (const [x, y] of tops) {
+    const s = y - (DITHER_RADIUS + 1);
+    if (s < top || f.masked(x, s)) continue;
+    const c0 = colourAt(x, s);
+    if (c0 === null || diff(c0, f.bg) <= FIGURE_DIFF) continue;
+    let v = s;
+    let closed = false;
+    while (v - 1 >= top) {
+      if (f.masked(x, v - 1)) break;
+      const p = colourAt(x, v - 1);
+      if (p === null) break;
+      if (diff(p, c0) > GARMENT_DIFF) {
+        closed = true;
+        break;
+      }
+      v--;
+    }
+    if (closed) bandTops.push([x, v]);
+  }
+  if (bandTops.length < MIN_COVER * tops.length) return null;
+  const band = fitLine(bandTops);
+  if (band === null || band.rms > MAX_RMS) return null;
+  const xa = Math.min(...tops.map((p) => p[0]));
+  const xb = Math.max(...tops.map((p) => p[0]));
+  const ta = edgeAt(xa) - (band.m * xa + band.q);
+  const tb = edgeAt(xb) - (band.m * xb + band.q);
+  if (Math.abs(ta - tb) <= Math.min(ta, tb)) return null;
+  const deg = (m: number) => Math.atan(m) * (180 / Math.PI);
+  const allow = Math.max(0, Math.min(ta, tb));
+  return {
+    kind: 'edge leaves the band',
+    why: `the garment's edge fitted across the hips runs ${Math.abs(deg(fit.m) - deg(band.m)).toFixed(1)}° from the top of the band above it (${bandTops.length} of ${tops.length} columns; the band ${ta.toFixed(1)} px thick at x ${xa} and ${tb.toFixed(1)} px at x ${xb}); an edge inside a band ${allow.toFixed(1)} px thick at its thinnest departs from it by at most ${deg(allow / (xb - xa)).toFixed(1)}° across the ${xb - xa} px read, so this edge cuts across the garment (a fold), not along the band`,
+  };
 }
 
 /**
@@ -420,6 +620,8 @@ function viaNote(readings: Reading[]): string {
   const parts: string[] = [];
   if (mean > 0) parts.push(`${mean} through the ${2 * DITHER_RADIUS + 1}×${2 * DITHER_RADIUS + 1} window mean (the garment's colour does not hold pixel by pixel: a dithered or paletted picture)`);
   if (below > 0) parts.push(`${below} with the colour found below the hips (up to ${Math.max(...ok.map((r) => r.below ?? 0)).toFixed(1)} px; the hips on the band's edge)`);
+  const raised = ok.filter((r) => r.raised !== undefined);
+  if (raised.length > 0) parts.push(`${raised.length} with the band's top read above the colour's edge in some columns (up to ${Math.max(...raised.map((r) => r.raised ?? 0))} columns: a strip too thin to carry the colour, read as its top line)`);
   return parts.length === 0 ? '' : `; of the frames read, ${parts.join(', ')}`;
 }