@rig-c/pose 0.8.0 → 0.8.1

package/README.md

@@ -38,6 +38,7 @@ Nothing is written until every check passes:
 
 and what the run cannot decide for you it lists:
 
+- `RIGC` — the rig-c version and entry that gated and posed the run (also `rigc` in the report): a later rig-c can change the bytes.
 - `HOLD` — a joint missing, or scored under `--min-score`, holds its last good value; one line per span, with the frames and the reason.
 - `SHORT` — a segment shorter in the picture than `--short` of its median length (with `--short <fraction>`; off by default) has its angle there interpolated, not read; one line per span, with the chain, the segment, the frames and the lowest fraction. Below.
 - `END-ON` — a `SHORT` run lasting at least 0.15 s: the limb points at the camera, a pose the rig cannot draw.
@@ -109,6 +110,8 @@ Exit codes: `0` written, `1` refused (every reason printed, nothing written), `2
 
 **From COCO-17** — the layout most pose models and datasets use — `rig-pose convert --coco in.json --out pose.json`, or `retarget --coco`. The input is `{ "format": "coco17-sequence/1", "width", "height", "source", "frames": [{ "t", "keypoints" }] }`, keypoints in COCO's order as 17 `[x, y, score]` or 51 numbers, or `null` for a frame with nobody. The mapping: COCO's `left_*`/`right_*` → body-18's `l_*`/`r_*` (both are the subject's sides), a score of 0 → `missing`, and body-18's `neck`, which COCO lacks, is the shoulders' midpoint scored the lower of the two (OpenPose's definition).
 
+
+**The older name.** `rig-c-pose-frames/0`, written by the extraction jobs this package's demos were made from, is the same file under another spec string. It has `space.units` "painting-px" and an `fps` key; each frame's `t` is the time read. It is read as it is.
 ## The map: `rig-pose-map/1`
 
 Which bones carry which joints. You write it for your rig:
@@ -178,7 +181,7 @@ Either way the `SWITCH` line ends with `moved on …, off …`: each boundary's
 **TURN.** The cutoff was measured on the three lines across the body before it was fixed ([#6](https://github.com/rig-c/pose/issues/6)): on the 13 s front-facing dance their picture length never drops under 0.81 of its median and none reverses; on a second sequence the hip line falls to 0.17 at frames 465–491 (side-on) and the eye line to 0.22 at 26–58 (head in profile), and 3 frames reverse. 0.5 lies between. A line is reversed when it points more than 90° from the subject's right joint to the left (front-facing, it points at 0°). The lines are read after holds and smoothing, held and smoothed as the map's points are even where the map does not use them; a line whose points are good on no frame is named as not measured.
 
 
-**A stopgap window: `frames`.** A set may state `"frames": [[first, last], …]`: it shows only inside those windows, and on them it is chosen over any set within tolerance that has no window. It is for two sets whose key skeletons the angles cannot tell apart. Measured on HQ's dancer, the hands clasped behind the back and the hands low in front differ by only 2–21°, and the wrist and hand-point scores do not separate them either; the cue that might is #33's depth state. It is recorded in the map as a stopgap, not a selection rule.
+**A stopgap window: `frames`.** A set may state `"frames": [[first, last], …]`: it shows only inside those windows, and on them it is chosen over any set within tolerance that has no window. It is for two sets whose key skeletons the angles cannot tell apart. Measured on HQ's dancer, the hands clasped behind the back and the hands low in front differ by only 2–21°, and the wrist and hand-point scores do not separate them either; the cue that might is #33's depth state. It is recorded in the map as a stopgap, not a selection rule. A window **restricts** a set; it never forces one. Where the set does not show inside its window, the run says why in a `FRAMES` line: the stretch, and whether the pose there was past the tolerance (with the largest distance), or within it but the run was dropped.
 
 **How far a set's art may turn: `turn`.** A drawing reads right only near the angle it was painted at. A set may state, per bone with a `drawn` angle, how far its art may turn from it, `"turn": { "sleeve_r0": [-20, 20] }`. While the set shows, the bone is held within it: its target becomes drawn + clamp(wrap(target − drawn), min, max), each bone on its own world angle, so a forearm under a held upper arm keeps its own target. The landing check measures against the held angle. The overflow the pose asked for is listed as `ART-RANGE`. A `turn` on a bone the set has no `drawn` angle for is refused (`MAP_ALT_TURN`).
 ## Compare: the rig's render against the video

package/cli.ts

@@ -33,6 +33,8 @@ retarget
   --coco                read --pose as coco17-sequence/1 and convert it first
   --person <id>         the person to follow when the sequence holds more than one
   --base-motion <path>  the rig's motion spec, when it is not motion.json beside rig.json
+  --images <dir>        passed to rigc build: where the rig spec's images are, when its own "images" path
+                        does not reach them (a rig.json copied away from its images)
   --min-score <s>       a joint scored below s is not good on that frame and holds its last good
                         value (default: 0.3); a joint with no score is good
   --smooth <n>          Savitzky–Golay over n frames of joint positions: a centred least-squares cubic,
@@ -154,7 +156,7 @@ function shortOf(f: Map<string, string>): number | 'off' {
 }
 
 function retargetArgs(argv: string[]): RetargetArgs {
-  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report'], ['coco']);
+  const f = parseFlags(argv, ['rig', 'map', 'pose', 'out', 'name', 'person', 'base-motion', 'images', 'min-score', 'smooth', 'flip', 'short', 'bends', 'bend-tolerance', 'switch-tolerance', 'switch-min', 'switch-at', 'profile', 'build', 'render', 'report'], ['coco']);
   const bends = f.get('bends') ?? 'refuse';
   if (bends !== 'refuse' && bends !== 'clamp') throw new Usage(`--bends is "${bends}"; it must be refuse or clamp`);
   const switchAt = f.get('switch-at') ?? 'first';
@@ -172,6 +174,7 @@ function retargetArgs(argv: string[]): RetargetArgs {
     coco: f.has('coco'),
     person: f.get('person'),
     baseMotion: f.get('base-motion'),
+    images: f.get('images'),
     minScore: num(f, 'min-score', 0.3, (n) => n >= 0, 'a number ≥ 0'),
     smooth: smoothOf(f),
     flip: flipOf(f),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rig-c/pose",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Puts motion from a body-18 pose sequence onto a rig built with rig-c: bone keys in rig-c's motion format, checked through rig-c's gate before anything is written. A CLI for agents that cannot see the rig.",
   "type": "module",
   "bin": {

package/src/pose.ts

@@ -50,6 +50,16 @@ export interface PoseSequence {
 
 const TOP_KEYS = ['spec', 'space', 'width', 'height', 'source', 'frames'];
 
+/**
+ * The older name the same file went by: `rig-c-pose-frames/0`, written by the
+ * extraction jobs this package's own demos were made from. It is this format
+ * under another spec string, with `space.units` "painting-px" and an `fps` key
+ * (the time is in each frame's `t`, which wins). It is read as it is; nothing
+ * else about it differs.
+ */
+export const POSE_SPEC_FRAMES0 = 'rig-c-pose-frames/0';
+const FRAMES0_SPACE = { units: 'painting-px', origin: 'top-left', y: 'down' } as const;
+
 /** Read and check a pose sequence; every problem is collected and thrown once. */
 export function readPoseSequence(text: string, where: string): PoseSequence {
   const doc = parseJson(text, where, 'POSE_JSON');
@@ -59,12 +69,15 @@ export function readPoseSequence(text: string, where: string): PoseSequence {
     p.throwIfAny();
     throw new Error('unreachable');
   }
-  refuseUnknownKeys(p, 'POSE_KEYS', where, doc, TOP_KEYS);
+  const frames0 = doc.spec === POSE_SPEC_FRAMES0;
+  refuseUnknownKeys(p, 'POSE_KEYS', where, doc, frames0 ? [...TOP_KEYS, 'fps'] : TOP_KEYS);
   for (const k of TOP_KEYS) if (!(k in doc)) p.add('POSE_KEYS', `${where} has no "${k}"; a ${POSE_SPEC} document carries ${TOP_KEYS.join(', ')}`);
-  if ('spec' in doc && doc.spec !== POSE_SPEC) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}"`);
-  if ('space' in doc && JSON.stringify(doc.space) !== JSON.stringify(POSE_SPACE)) {
-    p.add('POSE_SPACE', `${where} "space" is ${JSON.stringify(doc.space)}; it must be exactly ${JSON.stringify(POSE_SPACE)}`);
+  if ('spec' in doc && doc.spec !== POSE_SPEC && !frames0) p.add('POSE_SPEC', `${where} "spec" is ${typeName(doc.spec)}; this reader reads "${POSE_SPEC}" (and the older name "${POSE_SPEC_FRAMES0}")`);
+  const space = frames0 ? FRAMES0_SPACE : POSE_SPACE;
+  if ('space' in doc && JSON.stringify(doc.space) !== JSON.stringify(space)) {
+    p.add('POSE_SPACE', `${where} "space" is ${JSON.stringify(doc.space)}; for "${frames0 ? POSE_SPEC_FRAMES0 : POSE_SPEC}" it must be exactly ${JSON.stringify(space)}`);
   }
+  if (frames0 && 'fps' in doc && !(typeof doc.fps === 'number' && Number.isFinite(doc.fps) && doc.fps > 0)) p.add('POSE_FPS', `${where} "fps" is ${typeName(doc.fps)}; it must be a positive number (each frame's "t" is the time read)`);
   for (const k of ['width', 'height'] as const) {
     if (k in doc && !(Number.isInteger(doc[k]) && (doc[k] as number) > 0)) p.add('POSE_SIZE', `${where} "${k}" is ${typeName(doc[k])}; it must be a positive integer (picture pixels)`);
   }

package/src/rigc.ts

@@ -96,11 +96,11 @@ export interface Gate {
 }
 
 /** Build `rig` with `motion` under rigc's gate into `dir/build`; nothing is read from a red build. */
-export function gate(rig: string, motion: Record<string, unknown>, dir: string, profile: string): Gate {
+export function gate(rig: string, motion: Record<string, unknown>, dir: string, profile: string, images?: string): Gate {
   mkdirSync(dir, { recursive: true });
   const motionPath = join(dir, 'motion.json');
   writeFileSync(motionPath, `${JSON.stringify(motion, null, 2)}\n`);
-  return buildInto(rig, motionPath, join(dir, 'build'), profile, join(dir, 'build-report.json'));
+  return buildInto(rig, motionPath, join(dir, 'build'), profile, join(dir, 'build-report.json'), images);
 }
 
 /**
@@ -112,8 +112,8 @@ export function gate(rig: string, motion: Record<string, unknown>, dir: string,
  * never copied out, which would carry a path climbing from the scratch
  * directory to the filesystem root. --copy-images puts the pages beside it.
  */
-export function buildInto(rig: string, motionPath: string, out: string, profile: string, report?: string): Gate {
-  const run = runRigc(['build', '--rig', rig, '--motion', motionPath, '--out', out, '--profile', profile, '--copy-images', ...(report === undefined ? [] : ['--report', report])]);
+export function buildInto(rig: string, motionPath: string, out: string, profile: string, report?: string, images?: string): Gate {
+  const run = runRigc(['build', '--rig', rig, '--motion', motionPath, '--out', out, '--profile', profile, '--copy-images', ...(images === undefined ? [] : ['--images', images]), ...(report === undefined ? [] : ['--report', report])]);
   const lines = run.out.split('\n');
   return {
     run,
@@ -196,3 +196,12 @@ export function folds(build: string, animation: string, dir: string, fps: number
     frames: setDir,
   };
 }
+
+/** rig-c's version and the entry its launcher picked (`rigc --version`), so a run names the compiler that gated it. */
+export function rigcVersion(): { version: string; entry: string } {
+  const r = runRigc(['--version']);
+  const lines = r.out.split('\n').map((l) => l.trim()).filter((l) => l !== '');
+  const version = lines.find((l) => /^\d+\.\d+\.\d+/.test(l)) ?? lines[0] ?? 'unknown';
+  const entry = lines.find((l) => l.startsWith('entry:'))?.slice('entry:'.length).trim() ?? 'not stated';
+  return { version, entry };
+}

package/src/run.ts

@@ -7,11 +7,11 @@
 import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { readMap, resolveMap } from './map.ts';
+import { readMap, resolveMap, type JointMap } from './map.ts';
 import { convertCoco17, personTrack, readPoseSequence } from './pose.ts';
 import { lineOf, Problems, Refusal, type Problem } from './problems.ts';
 import { bendLine, endOnLine, flipLine, holdLine, rangeLine, retarget, shortLine, turnLine, type RetargetOptions } from './retarget.ts';
-import { attachmentBones, baseMotionOf, buildInto, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
+import { attachmentBones, baseMotionOf, buildInto, rigcVersion, folds, gate, readBuild, resolveRig, restOf, slotsOf } from './rigc.ts';
 import { artRangeLine, chainsMoving, switchLine, uncoveredFolds } from './switch.ts';
 import { landed, measureLanding, measurePosture, poseFrames, postureLines, ANGLE_TOLERANCE, ORIGIN_TOLERANCE } from './verify.ts';
 
@@ -24,6 +24,8 @@ export interface RetargetArgs extends RetargetOptions {
   coco: boolean;
   person?: string;
   baseMotion?: string;
+  /** Passed to rigc build as --images: the directory the rig spec's images resolve in, when rig.json's own `images` does not point there (a copied rig). */
+  images?: string;
   profile: 'spine' | 'spine-html';
   /** Keep the gated build here. */
   build?: string;
@@ -72,17 +74,19 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
   const scratch = mkdtempSync(join(tmpdir(), 'rig-pose-'));
   try {
     // The rig as it stands, through the gate, so the rest pose is rig-c's reading of a green build.
-    const g0 = gate(input.rig, base, join(scratch, 'base'), a.profile);
+    const g0 = gate(input.rig, base, join(scratch, 'base'), a.profile, a.images);
     if (!g0.green) {
       refuse([{ code: 'RIG_GATE_BASE', text: `${input.rig} with ${input.motion ?? 'no motion spec'} is red under rigc build --profile ${a.profile} before any animation is added (exit ${g0.run.status})` }, ...g0.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
     const doc0 = readBuild(g0.build);
+    const rigc = rigcVersion();
     const rest = restOf(doc0);
     const slots = slotsOf(doc0);
     resolveMap(map, rest, a.map, slots);
 
     const r = retarget(rest, map, frames, times, a, slots);
     say(`rig-pose retarget: ${seq.frames.length} frame(s), ${r.animation.duration.toFixed(3)}s, onto "${input.name}" as "${a.name}" — ${r.animation.tracks.length} track(s); min-score ${a.minScore}, smooth ${a.smooth}, flip ${a.flip === 'off' ? 'off' : `${a.flip}°`}, short ${a.short}, bends ${a.bends} (tolerance ${a.bendTolerance}°)`);
+    say(`  RIGC   rig-c ${rigc.version} (${rigc.entry}) gates and poses this run`);
     if (r.scale !== null) say(`  SCALE  ${r.scale.factor.toFixed(5)} rig units per picture px (rig ${r.scale.rig.toFixed(2)} / pose median ${r.scale.pose.toFixed(2)})`);
     for (const h of r.holds) say(`  HOLD   ${holdLine(h, r.times)}`);
     if (a.short !== 'off') {
@@ -96,12 +100,13 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (map.alternates.length > 0) {
       if (r.switches.length === 0) say(`  SWITCH none — no set within ${a.switchTolerance}° of the pose for ${a.switchMin}s`);
       for (const s of r.switches) say(`  SWITCH ${switchLine(s, r.times)}`);
+      for (const l of windowLines(map, r.switches, r.distances, r.times, a.switchTolerance)) say(`  FRAMES ${l}`);
     }
     for (const e of r.range) say(`  RANGE  ${rangeLine(e, r.times)}`);
     for (const e of r.artRange) say(`  ART-RANGE ${artRangeLine(e, r.times)}`);
 
     const motion = { ...base, animations: { ...animations, [a.name]: r.animation } };
-    const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile);
+    const g1 = gate(input.rig, motion, join(scratch, 'with'), a.profile, a.images);
     if (!g1.green) {
       refuse([{ code: 'RIG_GATE', text: `rigc build --profile ${a.profile} is red with "${a.name}" in (exit ${g1.run.status}); nothing written` }, ...g1.fails.map((f) => ({ code: 'RIGC', text: f }))]);
     }
@@ -139,7 +144,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (a.build !== undefined) {
       // Built again where it will live, not copied: rigc's page paths are relative to the build (#18).
       rmSync(a.build, { recursive: true, force: true });
-      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile);
+      const kept = buildInto(input.rig, join(scratch, 'with', 'motion.json'), resolve(a.build), a.profile, undefined, a.images);
       if (!kept.green) refuse([{ code: 'RIG_GATE', text: `rigc build into --build ${a.build} is red where the same build was green in scratch (exit ${kept.run.status}); nothing written` }, ...kept.fails.map((x) => ({ code: 'RIGC', text: x }))]);
     }
     writeFileSync(a.out, `${JSON.stringify(motion, null, 2)}\n`);
@@ -150,6 +155,7 @@ export function runRetarget(a: RetargetArgs, log: (line: string) => void): RunRe
     if (a.report !== undefined) {
       writeFileSync(a.report, `${JSON.stringify({
         spec: 'rig-pose-report/1',
+        rigc,
         rig: input.name,
         animation: a.name,
         frames: seq.frames.length,
@@ -195,3 +201,37 @@ function spans(ts: number[], step: number): string {
 }
 
 export { lineOf };
+
+/**
+ * For each set with `frames` windows: every stretch of a window the set did not
+ * show on, and why — the pose there was past the tolerance (with the largest
+ * distance), or within it but the run was dropped (shorter than --switch-min, or
+ * taken by another set's span). A window never forces a set; this says so.
+ */
+function windowLines(map: JointMap, switches: ReadonlyArray<{ set: string; frames: [number, number] }>, distances: ReadonlyMap<string, readonly number[]>, times: readonly number[], tolerance: number): string[] {
+  const out: string[] = [];
+  for (const set of map.alternates) {
+    if (set.frames === null) continue;
+    const shown = new Set<number>();
+    for (const sw of switches) if (sw.set === set.name) for (let i = sw.frames[0]; i <= sw.frames[1]; i++) shown.add(i);
+    const d = distances.get(set.name)!;
+    for (const [first, last] of set.frames) {
+      const lastIn = Math.min(last, times.length - 1);
+      const parts: string[] = [];
+      for (let i = first; i <= lastIn;) {
+        if (shown.has(i)) { i++; continue; }
+        let j = i;
+        while (j + 1 <= lastIn && !shown.has(j + 1)) j++;
+        const ds = d.slice(i, j + 1);
+        const worst = Math.max(...ds);
+        const over = ds.filter((x) => x > tolerance).length;
+        const span = i === j ? `frame ${i}` : `frames ${i}–${j}`;
+        parts.push(over === ds.length ? `${span} outside the tolerance (up to ${worst.toFixed(1)}° > ${tolerance}°)` : over === 0 ? `${span} within the tolerance but not shown (a run shorter than --switch-min, or another set's span)` : `${span} partly outside the tolerance (up to ${worst.toFixed(1)}°)`);
+        i = j + 1;
+      }
+      const head = `set "${set.name}" window ${first}–${last}`;
+      out.push(parts.length === 0 ? `${head}: shown on every frame` : `${head}: ${parts.join('; ')} — a window restricts a set, it never forces one`);
+    }
+  }
+  return out;
+}