@rig-c/pose 0.31.1 → 0.33.0

package/src/seams.ts

@@ -0,0 +1,241 @@
+/**
+ * The seam reading's projection (rig-c/pose#216): which neighbour pairs a rig
+ * declares, and what `rigc render --seam` found between them, as report rows.
+ * Pure — the render itself is `src/rigc.ts`'s.
+ *
+ * **Where the pairs come from.** A rig spec does not carry them: `rig.json`
+ * holds bones, slots and skins, and @rig-c/parts records a limb's segments in
+ * `parts.json` beside the rig directory (each part's `limb`: `name`,
+ * `segment`, and below a joint `joint`). So the pairs are read from the
+ * `parts.json` the run is given (`--parts`), the way @rig-c/parts' own
+ * `check` reads them (rig-c/parts#503): each limb's consecutive segments, the
+ * upper and the one below, a pair named twice counting once in either order.
+ * Each part is drawn by the slot of its name.
+ *
+ * **The floor** is @rig-c/parts' (#503), so the two tools agree on what a seam
+ * opening is: a frame's gap or ghost counts when it holds more cells than its
+ * box is long (its longer side, in cells) — thicker than one cell. rigc counts
+ * a cell drawn when its centre is painted at half opacity, so an outline that
+ * moves by less than a cell flips the cells along it: a line one cell deep
+ * holds at most as many cells as its box is long, and a hole of any area more.
+ * The rule types no number; it reads rigc's own `px`, `cell` and `box`.
+ *
+ * A reading, never a gate: nothing here refuses a run for what it finds.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isObject, parseJson, Refusal } from './problems.ts';
+
+export type SeamKind = 'gap' | 'ghost';
+export const SEAM_KINDS: readonly SeamKind[] = ['gap', 'ghost'];
+
+/** One declared neighbour pair: two part names, each drawn by the slot of its name. */
+export interface SeamPair {
+  /** `"<a>|<b>"`, the form rigc and @rig-c/parts name a pair by. */
+  pair: string;
+  a: string;
+  b: string;
+  /** Where it was declared: `config.limbs.<limb> segment <n>, joint "<joint>"`, once per declaration. */
+  declared: string[];
+}
+
+/** One `report.json` `seams` row: one consecutive span of one kind over the floor (#216). */
+export interface SeamSpan {
+  pair: string;
+  kind: SeamKind;
+  /** Inclusive render frame indices, rigc's `f<index>.png`. */
+  frames: [number, number];
+  /** Those frames' times in seconds, rigc's. */
+  times: [number, number];
+  /** The most cells of this kind on any frame of the span. */
+  maxPx: number;
+}
+
+/** One `report.json` `seamPairs` row: what the reading said of one declared pair. */
+export interface SeamPairReading {
+  pair: string;
+  declared: string[];
+  /** `read`: rigc read a band; `skip`: rigc read none (the two drawings share no cell at rest); `unread`: not rendered, `reason` says why. */
+  status: 'read' | 'skip' | 'unread';
+  /** Frames over the floor, of either kind, ascending. */
+  opens: number[];
+  /** The most cells over the floor on any frame; 0 when none opens. */
+  maxPx: number;
+  /** Frames rigc named open whose every opening is one cell thick — under the floor, not in `seams`. */
+  underFloor: number[];
+  reason?: string;
+}
+
+const PARTS_SPEC = 'PARTS_JSON';
+
+/** `--parts`: a `parts.json`, or a directory holding one. */
+export function partsPath(path: string): string {
+  if (!existsSync(path)) throw new Refusal([{ code: 'ARG_PATH', text: `--parts ${path} does not exist` }]);
+  if (statSync(path).isDirectory()) {
+    const file = join(path, 'parts.json');
+    if (!existsSync(file)) throw new Refusal([{ code: 'ARG_PATH', text: `--parts ${path} is a directory with no parts.json (@rig-c/parts writes it to <out>/, beside rig/)` }]);
+    return file;
+  }
+  return path;
+}
+
+/**
+ * The neighbour pairs `parts.json` declares, in its limbs' order: each limb's
+ * consecutive segments by `segment`. A record that is not one is refused by
+ * name; a part with no `limb` declares nothing.
+ */
+export function readSeamPairs(text: string, path: string): SeamPair[] {
+  const doc = parseJson(text, path, PARTS_SPEC);
+  if (!isObject(doc) || !Array.isArray(doc.parts)) throw new Refusal([{ code: PARTS_SPEC, text: `${path} is not @rig-c/parts' parts.json: it has no "parts" array` }]);
+  const problems: Array<{ code: string; text: string }> = [];
+  const limbs = new Map<string, Array<{ part: string; segment: number; joint: string | undefined }>>();
+  doc.parts.forEach((p: unknown, i: number) => {
+    if (!isObject(p) || typeof p.name !== 'string' || p.name === '') {
+      problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}]: expected a record with a "name" string` });
+      return;
+    }
+    if (p.limb === undefined) return;
+    const l = p.limb;
+    if (!isObject(l) || typeof l.name !== 'string' || !Number.isSafeInteger(l.segment) || (l.segment as number) < 0 || (l.joint !== undefined && typeof l.joint !== 'string')) {
+      problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}] ("${p.name}") limb: expected { name: string, segment: integer ≥ 0, joint?: string }, found ${JSON.stringify(l)}` });
+      return;
+    }
+    const segs = limbs.get(l.name) ?? [];
+    if (segs.some((s) => s.segment === l.segment)) problems.push({ code: PARTS_SPEC, text: `${path} parts[${i}] ("${p.name}"): limb "${l.name}" segment ${String(l.segment)} is already part "${segs.find((s) => s.segment === l.segment)!.part}"` });
+    segs.push({ part: p.name, segment: l.segment as number, joint: l.joint as string | undefined });
+    limbs.set(l.name, segs);
+  });
+  if (problems.length > 0) throw new Refusal(problems);
+  const out: SeamPair[] = [];
+  for (const [limb, segs] of limbs) {
+    segs.sort((x, y) => x.segment - y.segment);
+    for (let i = 1; i < segs.length; i++) {
+      const [up, low] = [segs[i - 1]!, segs[i]!];
+      const declared = `config.limbs.${limb} segment ${low.segment}${low.joint === undefined ? '' : `, joint "${low.joint}"`}`;
+      const hit = out.find((x) => (x.a === up.part && x.b === low.part) || (x.a === low.part && x.b === up.part));
+      if (hit !== undefined) hit.declared.push(declared);
+      else out.push({ pair: `${up.part}|${low.part}`, a: up.part, b: low.part, declared: [declared] });
+    }
+  }
+  return out;
+}
+
+/** A frame's opening of one kind is over the floor when it holds more cells than its box, in cells, is long. */
+export function overFloor(hit: { px: number; cell: number; box: readonly number[] }): boolean {
+  const long = Math.round(Math.max(hit.box[2]! - hit.box[0]!, hit.box[3]! - hit.box[1]!) / hit.cell);
+  return hit.px > long;
+}
+
+interface SeamHit {
+  index: number;
+  time: number;
+  px: number;
+  cell: number;
+  box: number[];
+}
+interface SeamDocPair {
+  a: string;
+  b: string;
+  status: 'read' | 'skip';
+  opens: number[];
+  gap: { frames: SeamHit[] };
+  ghost: { frames: SeamHit[] };
+}
+
+/** `seam.json` (`rigc-seam/1`): the fields this projection reads, checked; anything else is rigc's. */
+export function readSeamDoc(text: string, path: string): SeamDocPair[] {
+  const doc = parseJson(text, path, 'SEAM_JSON');
+  const bad = (what: string): never => {
+    throw new Refusal([{ code: 'SEAM_JSON', text: `${path}: ${what}; rig-c's rigc-seam/1 (its AUTHORING §8.8) is the contract this reads` }]);
+  };
+  if (!isObject(doc) || doc.spec !== 'rigc-seam/1' || !Array.isArray(doc.pairs)) return bad('expected spec "rigc-seam/1" with a "pairs" array');
+  return doc.pairs.map((p: unknown, i: number) => {
+    if (!isObject(p) || typeof p.a !== 'string' || typeof p.b !== 'string' || (p.status !== 'read' && p.status !== 'skip') || !Array.isArray(p.opens)) return bad(`pairs[${i}]: expected a, b, status read|skip, opens`);
+    const kind = (k: SeamKind) => {
+      const o = p[k];
+      if (!isObject(o) || !Array.isArray(o.frames)) return bad(`pairs[${i}].${k}: expected { frames }`);
+      const frames = o.frames.map((h: unknown, j: number) => {
+        if (!isObject(h) || !Number.isSafeInteger(h.index) || typeof h.time !== 'number' || !Number.isSafeInteger(h.px) || typeof h.cell !== 'number' || !(h.cell > 0) || !Array.isArray(h.box) || h.box.length !== 4 || !h.box.every((v) => typeof v === 'number')) {
+          return bad(`pairs[${i}].${k}.frames[${j}]: expected index, time, px, cell > 0, box [minX, minY, maxX, maxY]`);
+        }
+        return { index: h.index as number, time: h.time, px: h.px as number, cell: h.cell, box: h.box as number[] };
+      });
+      return { frames };
+    };
+    return { a: p.a, b: p.b, status: p.status, opens: p.opens.filter((n): n is number => typeof n === 'number'), gap: kind('gap'), ghost: kind('ghost') };
+  });
+}
+
+/** Runs of consecutive frame indices among `hits` (ascending), each with its first and last time and its most cells. */
+function runsOf(hits: readonly SeamHit[]): Array<{ frames: [number, number]; times: [number, number]; maxPx: number }> {
+  const out: Array<{ frames: [number, number]; times: [number, number]; maxPx: number }> = [];
+  for (const h of hits) {
+    const last = out[out.length - 1];
+    if (last !== undefined && h.index === last.frames[1] + 1) {
+      last.frames[1] = h.index;
+      last.times[1] = h.time;
+      last.maxPx = Math.max(last.maxPx, h.px);
+    } else out.push({ frames: [h.index, h.index], times: [h.time, h.time], maxPx: h.px });
+  }
+  return out;
+}
+
+/**
+ * The report's rows from one `seam.json`: per declared pair its reading, and
+ * per pair and kind one row per consecutive span of frames over the floor —
+ * in the pairs' order, gap before ghost, spans in frame order.
+ */
+export function projectSeams(pairs: readonly SeamPair[], doc: readonly SeamDocPair[], unread: ReadonlyMap<string, string>): { seams: SeamSpan[]; seamPairs: SeamPairReading[] } {
+  const seams: SeamSpan[] = [];
+  const seamPairs: SeamPairReading[] = [];
+  for (const p of pairs) {
+    const why = unread.get(p.pair);
+    const d = doc.find((x) => x.a === p.a && x.b === p.b);
+    if (why !== undefined || d === undefined) {
+      seamPairs.push({ pair: p.pair, declared: p.declared, status: 'unread', opens: [], maxPx: 0, underFloor: [], reason: why ?? 'seam.json holds no row for it' });
+      continue;
+    }
+    const opens = new Set<number>();
+    let maxPx = 0;
+    for (const k of SEAM_KINDS) {
+      const over = d[k].frames.filter(overFloor);
+      for (const h of over) {
+        opens.add(h.index);
+        maxPx = Math.max(maxPx, h.px);
+      }
+      for (const r of runsOf(over)) seams.push({ pair: p.pair, kind: k, frames: r.frames, times: r.times, maxPx: r.maxPx });
+    }
+    const sorted = [...opens].sort((x, y) => x - y);
+    seamPairs.push({ pair: p.pair, declared: p.declared, status: d.status, opens: sorted, maxPx, underFloor: d.opens.filter((f) => !opens.has(f)) });
+  }
+  return { seams, seamPairs };
+}
+
+/** Frame indices as runs, `[0-6, 8, 13]`, the form rigc prints a frame list in. */
+export function frameRuns(frames: readonly number[]): string {
+  const runs: string[] = [];
+  for (let i = 0; i < frames.length; ) {
+    let j = i;
+    while (j + 1 < frames.length && frames[j + 1] === frames[j]! + 1) j++;
+    runs.push(i === j ? String(frames[i]) : `${frames[i]}-${frames[j]}`);
+    i = j + 1;
+  }
+  return `[${runs.join(', ')}]`;
+}
+
+/** The run's `SEAM` lines: one per span, one per pair not read or skipped, and the count. */
+export function seamLines(r: { seams: readonly SeamSpan[]; seamPairs: readonly SeamPairReading[] }, fps: number): string[] {
+  const out: string[] = [];
+  for (const s of r.seams) {
+    out.push(`pair "${s.pair}" ${s.kind} on frame(s) ${s.frames[0]}-${s.frames[1]} (t=${s.times[0].toFixed(3)}–${s.times[1].toFixed(3)}s) at ${fps} fps, max ${s.maxPx} px — over the one-cell floor; a reading, not a gate`);
+  }
+  for (const p of r.seamPairs) {
+    if (p.status === 'unread') out.push(`pair "${p.pair}": not read — ${p.reason}`);
+    else if (p.status === 'skip') out.push(`pair "${p.pair}": SKIP — rigc read no band (the two drawings share no cell at the setup pose), so nothing was measured`);
+    else if (p.underFloor.length > 0) out.push(`pair "${p.pair}": ${p.underFloor.length} frame(s) ${frameRuns(p.underFloor)} open one cell thick, under the floor — not reported`);
+  }
+  const read = r.seamPairs.filter((p) => p.status === 'read').length;
+  const pairsOpen = new Set(r.seams.map((s) => s.pair)).size;
+  out.push(`${r.seams.length} span(s) over ${pairsOpen} pair(s) at ${fps} fps — ${read} of ${r.seamPairs.length} declared pair(s) read; a reading, not a gate`);
+  return out;
+}

package/src/verify.ts

@@ -10,10 +10,12 @@
  */
 import { poseRawAnimation, poseRawSetup, type CompiledDocument, type RawBone } from 'rig-c/core';
 import type { Body18 } from './joints.ts';
-import { aimAngle, aimEnds, pointAt, type JointMap } from './map.ts';
+import { aimAngle, aimEnds, pointAt, type Chain, type JointMap } from './map.ts';
 import type { HipsInferred, Joint, PelvisFit, Run } from './pose.ts';
 import type { Retarget } from './retarget.ts';
-import { pictureAngle, pointOn, wrap } from './retarget.ts';
+import { meanSecondDiff, pictureAngle, pointOn, wrap } from './retarget.ts';
+
+const DEG = 180 / Math.PI;
 
 export interface Landing {
   bone: string;
@@ -708,3 +710,110 @@ export function postureLines(q: Posture): string[] {
   }
   return out;
 }
+
+/**
+ * One keyed bone's jitter against its map pair's (rig-c/pose#236): the mean
+ * |second difference| of its local rotation as rig-c's poser posed the gated
+ * build — its world matrix in its parent's axes, P⁻¹C, so a rotate key's value
+ * up to a constant — against the same figure of its pair's picture angle, less
+ * the pair of the nearest keyed bone above it (as the rig's local rotation is
+ * against its parent). Both are read on the same triples: three consecutive
+ * frames on which every pose point the two pairs need is good.
+ */
+export interface JitterRow {
+  bone: string;
+  chain: string;
+  joints: [string, string];
+  /** The nearest keyed bone above it, whose pair the pose's local angle is read against; null at the top. */
+  against: string | null;
+  /** °/frame², rounded to 1e-4; null when no triple was read. */
+  rig: number | null;
+  pair: number | null;
+  /** rig ÷ pair; null when either is unread or the pair is still (its figure rounds to 0). */
+  ratio: number | null;
+  triples: number;
+  /** Whether the bone is aimed by a `reach` chain. */
+  reach: boolean;
+}
+
+/** #236: a JITTER row for every bone a chain keys with a rotate track, in map order (a face or body dial bone excepted: its key drives a slider, not a pair). */
+export function measureJitter(posed: ReadonlyArray<ReadonlyMap<string, RawBone>>, map: JointMap, r: Retarget, frames: ReadonlyArray<Partial<Record<Body18, Joint>>>, minScore: number): JitterRow[] {
+  const dials = new Set([r.face?.yaw?.bone, r.face?.pitch?.bone, r.body?.yaw?.bone].filter((b): b is string => b !== undefined));
+  const rotated = new Set(r.animation.tracks.filter((tr) => 'bone' in tr && tr.property === 'rotate').map((tr) => ('bone' in tr ? tr.bone : '')));
+  const pairs = new Map<string, { chain: Chain; joints: [string, string] }>();
+  for (const c of map.chains) {
+    c.bones.forEach((b, k) => {
+      if (k + 1 >= c.joints.length || dials.has(b) || !rotated.has(b) || pairs.has(b)) return;
+      pairs.set(b, { chain: c, joints: [c.joints[k]!, c.joints[k + 1]!] });
+    });
+  }
+  const n = Math.min(posed.length, frames.length);
+  const at = (i: number, j: string): [number, number] | null => {
+    const v = pointOn(frames[i]!, j, minScore);
+    return typeof v === 'string' ? null : v;
+  };
+  const pairAngle = (b: string, i: number): number | null => {
+    const [j0, j1] = pairs.get(b)!.joints;
+    const p0 = at(i, j0);
+    const p1 = at(i, j1);
+    return p0 === null || p1 === null || (p0[0] === p1[0] && p0[1] === p1[1]) ? null : pictureAngle(p0, p1);
+  };
+  const out: JitterRow[] = [];
+  for (const [b, { chain, joints }] of pairs) {
+    let against: string | null = null;
+    const first = posed[0]?.get(b);
+    for (let a = first?.parent ?? null; a !== null; a = posed[0]!.get(a)?.parent ?? null) {
+      if (pairs.has(a)) {
+        against = a;
+        break;
+      }
+    }
+    const rig: number[] = [];
+    const pose: number[] = [];
+    const good: boolean[] = [];
+    for (let i = 0; i < n; i++) {
+      const bone = posed[i]!.get(b)!;
+      const parent = bone.parent === null ? undefined : posed[i]!.get(bone.parent);
+      rig.push(parent === undefined ? Math.atan2(bone.c, bone.a) * DEG : localAngle(parent, bone));
+      const own = pairAngle(b, i);
+      const up = against === null ? 0 : pairAngle(against, i);
+      good.push(own !== null && up !== null);
+      pose.push(own === null || up === null ? 0 : wrap(own - up));
+    }
+    const ok = (i: number) => good[i] === true;
+    const jr = meanSecondDiff([rig], ok);
+    const jp = meanSecondDiff([pose], ok);
+    const r4 = (v: number | null) => (v === null ? null : Math.round(v * 10000) / 10000);
+    out.push({
+      bone: b,
+      chain: chain.name,
+      joints,
+      against,
+      rig: r4(jr.value),
+      pair: r4(jp.value),
+      // A pair whose figure rounds to 0 is still: a ratio over its float noise would name nothing.
+      ratio: jr.value === null || jp.value === null || r4(jp.value) === 0 ? null : Number((jr.value / jp.value).toFixed(3)),
+      triples: jr.triples,
+      reach: chain.reach,
+    });
+  }
+  return out;
+}
+
+/** A bone's rotation in its parent's axes, degrees: the angle of P⁻¹C's x axis. */
+function localAngle(p: RawBone, c: RawBone): number {
+  const det = p.a * p.d - p.b * p.c;
+  if (det === 0) return Math.atan2(c.c, c.a) * DEG;
+  const la = (p.d * c.a - p.b * c.c) / det;
+  const lc = (-p.c * c.a + p.a * c.c) / det;
+  return Math.atan2(lc, la) * DEG;
+}
+
+/** The `JITTER` line of one keyed bone (#236). */
+export function jitterLine(j: JitterRow): string {
+  const f = (v: number | null) => (v === null ? 'not measured' : `${v.toFixed(4)}°/f²`);
+  const vs = j.against === null ? `the pair's angle` : `the pair's angle against "${j.against}"'s pair`;
+  if (j.triples === 0) return `bone "${j.bone}" (chain "${j.chain}", ${j.joints[0]} → ${j.joints[1]}${j.reach ? ', reach' : ''}): not measured — no three consecutive frames on which the pose points of ${vs} are good`;
+  const ratio = j.ratio === null ? (j.pair === 0 ? ' — the pair is still' : '') : ` (${j.ratio.toFixed(2)}×)`;
+  return `bone "${j.bone}" (chain "${j.chain}", ${j.joints[0]} → ${j.joints[1]}${j.reach ? ', reach' : ''}): mean |Δ²| of the keyed local rotation as posed ${f(j.rig)} against ${vs} ${f(j.pair)}${ratio}, over ${j.triples} frame triple(s); a reading`;
+}