cozyclay 1.9.0 → 2.0.0

package/tools/bench/fit/motion.mjs

@@ -0,0 +1,85 @@
+/** cskel27 bench utilities. Fitting never samples GT intermediate frames. */
+import { deriveBoneOffsets, forwardKinematics } from "../../../src/ardy/convert.js";
+import { canonicalCskel27Reference } from "../../../src/ardy/to-cskel27.js";
+import { readNpz } from "../../kimodo/read-npz.mjs";
+
+export const readMat = (flat, offset = 0) => Array.from({ length: 3 }, (_, row) => Array.from(flat.slice(offset + row * 3, offset + row * 3 + 3)));
+export const localsAt = (motion, frame) => Array.from({ length: 27 }, (_, joint) => readMat(motion.rotMats, (frame * 27 + joint) * 9));
+export const jointsAt = (motion, frame) => Array.from({ length: 27 }, (_, joint) => Array.from(motion.posedJoints.slice((frame * 27 + joint) * 3, (frame * 27 + joint + 1) * 3)));
+export const vec = (flat, offset = 0) => Array.from(flat.slice(offset, offset + 3));
+export const add = (a, b) => a.map((v, i) => v + b[i]);
+export const sub = (a, b) => a.map((v, i) => v - b[i]);
+export const matVec = (m, v) => m.map(row => row.reduce((sum, x, i) => sum + x * v[i], 0));
+export const smoothstep = t => { const x = Math.max(0, Math.min(1, t)); return x * x * (3 - 2 * x); };
+
+export function member(members, name, shape) {
+	const value = members[name];
+	if (!value?.data || JSON.stringify(value.shape) !== JSON.stringify(shape) || !value.data.every(Number.isFinite)) {
+		throw new Error(`${name}: expected finite [${shape}]`);
+	}
+	return value.data;
+}
+
+export function readMotion(path) {
+	const m = readNpz(path), frames = m.local_rot_mats?.shape[0];
+	if (!Number.isInteger(frames) || frames < 1) throw new Error(`${path}: invalid frame count`);
+	const fps = member(m, "fps", [])[0];
+	if (!(fps > 0)) throw new Error(`${path}: invalid fps`);
+	const personScale = m.person_scale ? member(m, "person_scale", [])[0] : 1;
+	const boneScale = m.bone_scale ? member(m, "bone_scale", [27]) : new Float32Array(27).fill(1);
+	if (!(personScale > 0) || !boneScale.every(v => v > 0)) throw new Error(`${path}: invalid body scale`);
+	return { frames, fps, rotMats: member(m, "local_rot_mats", [frames, 27, 3, 3]),
+		rootPos: member(m, "root_positions", [frames, 3]), posedJoints: member(m, "posed_joints", [frames, 27, 3]), personScale, boneScale };
+}
+
+/** The NPZ decoder reads the archive; only these TWO poses cross into fitting.
+ * In the real workflow this input is the user's A/B pose pair. No temporal
+ * statistics, body measurements, or intermediate GT frames enter any fit. */
+export function readEndpoints(path) {
+	const m = readNpz(path), n = m.local_rot_mats?.shape[0];
+	if (!(n >= 2) || JSON.stringify(m.local_rot_mats.shape.slice(1)) !== "[27,3,3]" || JSON.stringify(m.root_positions?.shape) !== JSON.stringify([n, 3])) {
+		throw new Error(`${path}: expected at least two cskel27 poses`);
+	}
+	return [0, n - 1].map(f => {
+		const rotMats = m.local_rot_mats.data.slice(f * 243, (f + 1) * 243);
+		const rootPos = m.root_positions.data.slice(f * 3, (f + 1) * 3);
+		if (![...rotMats, ...rootPos].every(Number.isFinite)) throw new Error(`${path}: nonfinite endpoint`);
+		return { rotMats, rootPos };
+	});
+}
+
+export function cloneMotion(m) {
+	return { ...m, rotMats: m.rotMats.slice(), rootPos: m.rootPos.slice(), posedJoints: m.posedJoints.slice(), boneScale: m.boneScale?.slice() };
+}
+
+export function bodyOffsets(boneScale = new Float32Array(27).fill(1)) {
+	const reference = canonicalCskel27Reference();
+	return deriveBoneOffsets(reference.posed_joints, reference.local_rot_mats).map((v, j) => v.map(x => x * boneScale[j]));
+}
+
+export function regenerateJoints(motion, offsets = bodyOffsets(motion.boneScale)) {
+	for (let f = 0; f < motion.frames; f++) {
+		const positions = forwardKinematics(localsAt(motion, f), offsets, vec(motion.rootPos, f * 3));
+		for (let j = 0; j < 27; j++) motion.posedJoints.set(positions[j], (f * 27 + j) * 3);
+	}
+	return motion;
+}
+
+export function shiftFrame(motion, frame, delta) {
+	for (let k = 0; k < 3; k++) {
+		motion.rootPos[frame * 3 + k] += delta[k];
+		for (let j = 0; j < 27; j++) motion.posedJoints[(frame * 27 + j) * 3 + k] += delta[k];
+	}
+}
+
+/** F3: retain F2 rotations and metric trajectory, replace estimated proportions
+ * with the CHARACTER's known cskel27 bone factors. Canonical (all ones) is
+ * equivalent to smplToCskel27Motion(..., {boneScale:1}), without re-grounding
+ * or discarding production's temporal smoothing and root corrections. */
+export function fitBody(motion, boneScale = new Float32Array(27).fill(1)) {
+	if (boneScale.length !== 27 || !boneScale.every(v => Number.isFinite(v) && v > 0)) throw new Error("body: expected 27 positive bone factors");
+	const out = cloneMotion(motion);
+	out.boneScale = Float32Array.from(boneScale);
+	out.personScale = 1; // Root remains in metres; never rescale camera translation.
+	return regenerateJoints(out);
+}

package/tools/bench/fit/pin.mjs

@@ -0,0 +1,27 @@
+import { matToQuat, quatToMat } from "../../../src/ardy/convert.js";
+import { slerpQuat } from "../../../src/ardy/retime.js";
+import { cloneMotion, readMat, regenerateJoints, smoothstep, sub, vec } from "./motion.mjs";
+
+/** F4 consumes only two user-known poses, never a GT trajectory. The windows
+ * are capped at half the clip to avoid overlapping A/B constraints. Endpoint
+ * root OFFSETS ramp to zero; no interpolation toward intermediate GT roots.
+ * Regenerating FK keeps the F3 character's bone lengths exactly constant. */
+export function pinEndpoints(motion, [a, b], { windowSeconds = 0.5 } = {}) {
+	if (!(Number.isFinite(windowSeconds) && windowSeconds > 0) || motion.frames < 2) throw new Error("pinning needs positive windowSeconds and at least two frames");
+	const out = cloneMotion(motion), last = motion.frames - 1;
+	const radius = Math.min(windowSeconds * motion.fps, last / 2);
+	const deltaA = sub(vec(a.rootPos), vec(motion.rootPos));
+	const deltaB = sub(vec(b.rootPos), vec(motion.rootPos, last * 3));
+	for (let f = 0; f < motion.frames; f++) {
+		const wa = 1 - smoothstep(f / radius), wb = 1 - smoothstep((last - f) / radius);
+		for (let k = 0; k < 3; k++) out.rootPos[f * 3 + k] += wa * deltaA[k] + wb * deltaB[k];
+		const weight = wa || wb;
+		if (!weight) continue;
+		const target = wa ? a : b;
+		for (let j = 0; j < 27; j++) {
+			const o = (f * 27 + j) * 9;
+			out.rotMats.set(quatToMat(slerpQuat(matToQuat(readMat(motion.rotMats, o)), matToQuat(readMat(target.rotMats, j * 9)), weight)).flat(), o);
+		}
+	}
+	return regenerateJoints(out);
+}

package/tools/bench/fit/remote.mjs

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parseCondition, resolveCondition } from "../extract-bench-lib.mjs";
+
+const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+const sshOptions = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15"];
+const port = process.env.CCLAY_EXTRACT_SSH_PORT;
+const sshFlags = port ? [...sshOptions, "-p", port] : sshOptions;
+const scpFlags = port ? [...sshOptions, "-P", port] : sshOptions;
+const here = fileURLToPath(new URL("../", import.meta.url));
+
+function exec(program, args, log) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(program, args, { stdio: ["ignore", "pipe", "pipe"] });
+		let output = "";
+		const onData = chunk => { output += chunk; if (log) appendFileSync(log, chunk); };
+		child.stdout.on("data", onData); child.stderr.on("data", onData);
+		child.once("error", reject);
+		child.once("close", code => code === 0 ? resolve(output) : reject(new Error(`${program} exited ${code}: ${output.slice(-3000)}`)));
+	});
+}
+
+// Refuse even idle GVHMR workers: a separate sweep can submit to them at any
+// moment. No process is killed. Check again in the SAME remote shell before
+// starting; the caller must still coordinate independent noncooperating jobs.
+const idleCheck = `python3 - <<'PY'
+from pathlib import Path
+import subprocess
+busy = []
+for p in Path('/proc').iterdir():
+    if not p.name.isdigit(): continue
+    try:
+        argv = (p/'cmdline').read_bytes().split(b'\\0')
+        executable = Path(argv[0].decode(errors='replace')).name
+        cmd = b' '.join(argv).decode(errors='replace')
+    except (FileNotFoundError, ProcessLookupError, PermissionError): continue
+    # PyTorch renames /proc/<pid>/comm to pt_main_thread. Inspect argv[0],
+    # not that mutable thread label, including workers idling at only 284 MiB.
+    if 'python' in executable and ('cclay_gvhmr' in cmd or 'cclay_bench' in cmd): busy.append(cmd)
+usage = subprocess.check_output(['nvidia-smi','--query-compute-apps=used_memory','--format=csv,noheader,nounits'], text=True)
+# Leave room for production's 8GB peak with the existing ~1GB ARDY worker.
+used = sum(int(v.strip()) for v in usage.splitlines() if v.strip())
+if busy or used > 1600:
+    raise SystemExit('GPU busy: ' + repr(busy) + '; compute memory=' + str(used) + ' MiB')
+print('GPU idle for GVHMR; compute memory=' + str(used) + ' MiB')
+PY`;
+
+export async function assertGpuIdle(host) {
+	return exec("ssh", [...sshFlags, host, idleCheck]);
+}
+
+/** A cache is bound to the video, focal and source code, never silently reused
+ * for a different camera/condition. Results and logs live locally; ALL box
+ * uploads, caches and model outputs are removed from /tmp/cclay-fit-*.
+ */
+export function incamPlan(baseCondition = "prod", { cameraFMm, env = process.env } = {}) {
+	const base = parseCondition(baseCondition);
+	if (base.fmm) throw new Error("base condition must omit +fmm");
+	const plan = resolveCondition(`${base.name}+fmm`, { cameraFMm, env });
+	if (!plan.runnerArgs.includes("--static-cam")) throw new Error("incam bench requires a static camera");
+	if (plan.path === "worker" && !plan.workerFields.trajectory) throw new Error("incam worker path requires production trajectory correction");
+	return { plan, launcherArgs: plan.path === "direct" ? ["--bench-direct"] : [] };
+}
+
+export async function extractMissingFocal({ input, extract, motion, variant, baseCondition, host }) {
+	if (!host) throw new Error(`missing ${baseCondition}+fmm extraction; pass --host to extract it serially`);
+	await assertGpuIdle(host);
+	return exec(process.execPath, [fileURLToPath(new URL("../extract-bench.mjs", import.meta.url)), "--input", input, "--out", extract, "--motions", motion, "--variants", variant, "--conditions", `${baseCondition}+fmm`, "--host", host]);
+}
+
+export async function extractIncam({ host, video, output, camera, log, force = false, baseCondition = "prod" }) {
+	const files = [
+		[`${here}/cclay_bench_extract_incam.py`, "cclay_bench_extract_incam.py"],
+		[fileURLToPath(new URL("../../ardy/gvhmr_fastpath.py", import.meta.url)), "gvhmr_fastpath.py"],
+		[fileURLToPath(new URL("../../ardy/gvhmr_trajectory.py", import.meta.url)), "gvhmr_trajectory.py"],
+	];
+	const { plan, launcherArgs } = incamPlan(baseCondition, { cameraFMm: camera.gvhmrFMm });
+	const sha = createHash("sha256").update(readFileSync(video));
+	for (const [path] of files) sha.update(readFileSync(path));
+	sha.update(JSON.stringify(plan));
+	const signature = sha.digest("hex"), manifest = `${output}.json`;
+	if (!force && existsSync(output) && existsSync(manifest) && JSON.parse(readFileSync(manifest, "utf8")).signature === signature) return { cached: true, signature };
+	if (!host) throw new Error(`missing camera cache ${output}; pass --host to extract`);
+	await assertGpuIdle(host);
+	const remote = `/tmp/cclay-fit-${Date.now()}-${randomBytes(5).toString("hex")}`;
+	const ssh = command => exec("ssh", [...sshFlags, host, command], log);
+	const scp = (a, b) => exec("scp", [...scpFlags, a, b], log);
+	writeFileSync(log, "");
+	let failure;
+	try {
+		await ssh(`umask 077 && mkdir ${quote(remote)}`);
+		for (const [path, name] of files) await scp(path, `${host}:${remote}/${name}`);
+		await scp(video, `${host}:${remote}/video.mp4`);
+		const args = [`${remote}/cclay_bench_extract_incam.py`, "cclay_gvhmr_extract.py", `${remote}/video.mp4`, `${remote}/incam.npz`, ...launcherArgs, ...plan.runnerArgs, "--out-root", `${remote}/cache`];
+		await ssh(`set -e\n${idleCheck}\ncd ~/cclay-ingest/GVHMR\n.venv/bin/python ${args.map(quote).join(" ")}`);
+		await scp(`${host}:${remote}/incam.npz`, output);
+		const runnerSha = (await ssh("shasum -a 256 ~/cclay-ingest/GVHMR/cclay_gvhmr_extract.py")).trim().split(/\s+/)[0];
+		writeFileSync(manifest, JSON.stringify({ signature, runnerSha, plan, video, createdAt: new Date().toISOString() }, null, 2) + "\n");
+	} catch (error) { failure = error; }
+	try { await ssh(`rm -rf ${quote(remote)}`); } catch (error) { throw new AggregateError([...(failure ? [failure] : []), error], `box cleanup failed: ${remote}`); }
+	if (failure) throw failure;
+	return { cached: false, signature };
+}

package/tools/bench/fit-bench.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/** #432 cumulative fits. No GT intermediate frame is used by this program. */
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { motionArraysToNpzMembers, writeNpz } from "../ardy/npz.mjs";
+import { readNpz } from "../kimodo/read-npz.mjs";
+import { registerCamera } from "./fit/camera.mjs";
+import { fitContacts, validateBoxes } from "./fit/contact.mjs";
+import { fitBody, readEndpoints, readMotion } from "./fit/motion.mjs";
+import { pinEndpoints } from "./fit/pin.mjs";
+import { extractIncam, extractMissingFocal } from "./fit/remote.mjs";
+import { parseCondition } from "./extract-bench-lib.mjs";
+
+export const USAGE = `usage: node tools/bench/fit-bench.mjs --input <gt-render-root> --extract <t2-root>
+       --poses <user-ab-npz-dir> --out <dir> [options]
+
+  --motions walk,run     default: all motion dirs in --input
+  --variant shaded      one variant per output root (default shaded)
+  --base-condition prod T2 baseline without +fmm (e.g. yolo-vitpose); missing +fmm
+                        is extracted serially with --host and the known camera
+  --host user@box        extract missing camera evidence; CCLAY_EXTRACT_HOST fallback
+  --incam-root <dir>     use supplied <dir>/<motion>/incam.npz instead of GPU
+  --window-seconds 0.5   smooth A/B pin falloff, capped at half the clip
+  --body <json>          character's 27 positive bone factors (default all 1)
+  --scene <json>         {boxes:[{min:[x,y,z],max:[x,y,z]}]} in world metres
+  --force-incam          re-extract camera evidence even if cached
+  --help                this text
+
+Writes <out>/<motion>/F0..F5/motion.npz plus result.json and incam.npz.
+F0/F1 copy T2 <base-condition>/<base-condition>+fmm motion.npz BYTE FOR BYTE. F2 adds one static
+camera registration from predicted camera-space pelvis/orientation and known
+OpenCV extrinsics, retaining F1's trajectory. F3 replaces estimated proportions
+with the known character body (canonical cskel27 by default; personScale=1).
+F4 consumes ONLY FIRST/LAST poses of <poses>/<motion>.npz, never intermediate
+GT frames. F5 uses only fitted motion + known floor/boxes; one rigid stance
+support, skeletal segment collisions (not skin), geometry wins over A/B pins.
+No fitting stage uses GT intermediate frames or GT trajectory alignment.
+Only camera, character, A/B poses and scene geometry are user-known inputs.
+GT evaluation is a separate, read-only fit-sanity.mjs program.
+
+GPU runs are serial and refuse ANY other GVHMR process (even an idle worker).
+Wait for other extraction sweeps to finish; never kill another process. Box
+scratch is confined to /tmp/cclay-fit-* and removed on completion/failure.
+For another variant use a separate --out root to avoid overwriting a run.`;
+
+export function parseArgs(args) {
+	const out = { variant: "shaded", baseCondition: "prod", windowSeconds: 0.5, host: process.env.CCLAY_EXTRACT_HOST || process.env.CCLAY_ARDY_HOST };
+	const names = { "--input": "input", "--extract": "extract", "--poses": "poses", "--out": "out", "--motions": "motions", "--variant": "variant", "--base-condition": "baseCondition", "--host": "host", "--incam-root": "incamRoot", "--window-seconds": "windowSeconds", "--body": "body", "--scene": "scene" };
+	for (let i = 0; i < args.length; i++) {
+		const flag = args[i];
+		if (flag === "--help" || flag === "-h") { out.help = true; continue; }
+		if (flag === "--force-incam") { out.forceIncam = true; continue; }
+		if (!names[flag]) throw new Error(`unknown option ${flag}`);
+		const value = args[++i];
+		if (!value || value.startsWith("--")) throw new Error(`${flag} needs a value`);
+		out[names[flag]] = value;
+	}
+	if (out.help) return out;
+	for (const key of ["input", "extract", "poses", "out"]) if (!out[key]) throw new Error(`--${key} is required`);
+	out.windowSeconds = Number(out.windowSeconds);
+	if (!(Number.isFinite(out.windowSeconds) && out.windowSeconds > 0)) throw new Error("--window-seconds must be positive");
+	if (parseCondition(out.baseCondition).fmm) throw new Error("--base-condition must omit +fmm");
+	if (out.motions) out.motions = out.motions.split(",");
+	for (const name of [...(out.motions ?? []), out.variant]) if (!/^[a-zA-Z0-9][a-zA-Z0-9_+.-]*$/.test(name)) throw new Error(`invalid motion/variant name ${name}`);
+	return out;
+}
+
+const json = path => JSON.parse(readFileSync(path, "utf8"));
+const sha = path => createHash("sha256").update(readFileSync(path)).digest("hex");
+
+export async function main(argv = process.argv.slice(2), { missingFocal = extractMissingFocal, cameraEvidence = extractIncam } = {}) {
+	const options = parseArgs(argv);
+	if (options.help) { console.log(USAGE); return; }
+	const motions = options.motions ?? readdirSync(options.input, { withFileTypes: true }).filter(d => d.isDirectory() && existsSync(join(options.input, d.name, options.variant, "video.mp4"))).map(d => d.name).sort();
+	if (!motions.length) throw new Error("no motions found");
+	const boxes = validateBoxes(options.scene ? json(options.scene).boxes : []);
+	const boneScale = options.body ? json(options.body) : new Array(27).fill(1);
+	if (!Array.isArray(boneScale) || boneScale.length !== 27 || !boneScale.every(v => Number.isFinite(v) && v > 0)) throw new Error("--body must contain 27 positive bone factors");
+	for (const name of motions) {
+		const source = join(options.input, name, options.variant), extracted = join(options.extract, name, options.variant);
+		const destination = join(options.out, name), prior = join(destination, "result.json");
+		if (existsSync(prior) && (json(prior).variant !== options.variant || (json(prior).baseCondition ?? "prod") !== options.baseCondition)) throw new Error(`${destination}: belongs to a different variant/base condition; choose another --out`);
+		const conditions = [options.baseCondition, `${options.baseCondition}+fmm`];
+		const paths = { F0: join(extracted, conditions[0], "motion.npz"), F1: join(extracted, conditions[1], "motion.npz"), camera: join(source, "camera.json"), poses: join(options.poses, `${name}.npz`) };
+		for (const path of [paths.F0, paths.camera, paths.poses]) if (!existsSync(path)) throw new Error(`missing input ${path}; wait for the T2 sweep to finish`);
+		if (!existsSync(paths.F1)) {
+			console.log(`extract missing ${name}/${options.variant}/${conditions[1]}`);
+			await missingFocal({ input: options.input, extract: options.extract, motion: name, variant: options.variant, baseCondition: options.baseCondition, host: options.host });
+			if (!existsSync(paths.F1)) throw new Error(`focal extraction did not produce ${paths.F1}`);
+		}
+		for (const condition of conditions) {
+			const result = join(extracted, condition, "result.json");
+			if (existsSync(result) && !json(result).ok) throw new Error(`${result}: extraction did not succeed`);
+		}
+		mkdirSync(destination, { recursive: true });
+		const camera = json(paths.camera), incamPath = join(options.incamRoot ?? options.out, name, "incam.npz");
+		console.log(`fit ${name}/${options.variant}`);
+		const cameraRun = options.incamRoot ? { supplied: resolve(incamPath) } : await cameraEvidence({ host: options.host, video: join(source, "video.mp4"), output: incamPath, camera, log: join(destination, "incam.log"), force: options.forceIncam, baseCondition: options.baseCondition });
+		const f0 = readMotion(paths.F0), f1 = readMotion(paths.F1);
+		if (f0.frames !== f1.frames || f0.fps !== f1.fps) throw new Error(`${name}: F0/F1 timelines disagree`);
+		const incam = readNpz(incamPath);
+		const k = incam.K_fullimg;
+		if (!k?.data || k.shape.join() !== [f1.frames, 3, 3].join() || !k.data.every(Number.isFinite) || Math.abs(k.data[0] - camera.fx) > 0.01 || Math.abs(k.data[4] - camera.fy) > 0.01) throw new Error("incam intrinsics do not match camera.json known focal");
+		const f2 = registerCamera(f1, incam, camera);
+		const f3 = fitBody(f2.motion, boneScale);
+		const f4 = pinEndpoints(f3, readEndpoints(paths.poses), { windowSeconds: options.windowSeconds });
+		const f5 = fitContacts(f4, { boxes });
+		for (const [index, motion] of [f0, f1, f2.motion, f3, f4, f5.motion].entries()) {
+			const directory = join(destination, `F${index}`); mkdirSync(directory, { recursive: true });
+			if (index < 2) copyFileSync(paths[`F${index}`], join(directory, "motion.npz"));
+			else writeNpz(join(directory, "motion.npz"), motionArraysToNpzMembers(motion));
+		}
+		writeFileSync(prior, JSON.stringify({ ok: true, tool: "fit-bench", motion: name, variant: options.variant, baseCondition: options.baseCondition, createdAt: new Date().toISOString(), frames: f1.frames, fps: f1.fps,
+			inputs: Object.fromEntries(Object.entries(paths).map(([key, path]) => [key, { path: resolve(path), sha256: sha(path) }])),
+			cameraRun, cameraRegistration: f2.diagnostics, body: { boneScale, personScale: 1 }, pinning: { windowSeconds: options.windowSeconds, sourceFrames: "first and last ONLY" }, contacts: f5.diagnostics, boxes,
+			deviations: ["F2 one rigid first-pelvis registration; per-frame incam transforms are diagnostic only", "F2 replaces the arbitrary initial floor datum with the camera-predicted pelvis height", "F3 FK regenerates production-smoothed rotations with known character bones; no automatic regrounding", "F4 source NPZ endpoints are in native cskel27 space, not rendered-rig playback space", "F5 one support point at a time; skeletal segment boxes, no skin thickness; scene safety may release locks and move A/B endpoints"],
+		}, null, 2) + "\n");
+		console.log(`ok ${name}: ${f1.frames} frames @ ${f1.fps} fps, F0..F5; contacts ${f5.diagnostics.lockedFrames} frames`);
+	}
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	main().catch(error => { console.error(`fit-bench: ${error.stack ?? error}`); process.exitCode = 1; });
+}

package/tools/bench/fit-sanity.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/** Read-only evaluation, deliberately separate from all fitting code.
+ * This is NOT #431's official rendered-rig scorer. Compare native cskel27
+ * posed_joints at matching seconds (linear GT position interpolation),
+ * without scale/heading/translation/Procrustes alignment. Source playback
+ * applies a rig-dependent scale and bind offsets, absent from these numbers.
+ */
+import { readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { readMotion } from "./fit/motion.mjs";
+
+const args = process.argv.slice(2);
+if (args.length !== 2 || args.includes("--help")) {
+	console.log("usage: node tools/bench/fit-sanity.mjs <fit-root> <gt-source-npz-dir>\nWrites sanity.json and sanity.md under fit-root. Evaluation only; not an input to fitting.");
+	if (!args.includes("--help")) process.exitCode = 2;
+} else {
+	const [root, source] = args;
+	const rows = [];
+	for (const name of readdirSync(root, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name).sort()) {
+		const gt = readMotion(join(source, `${name}.npz`));
+		for (let step = 0; step <= 5; step++) {
+			const motion = readMotion(join(root, name, `F${step}`, "motion.npz"));
+			let relative = 0, rootError = 0;
+			for (let f = 0; f < motion.frames; f++) {
+				const t = f / motion.fps * gt.fps;
+				if (t > gt.frames - 1 + 1e-5) throw new Error(`${name}: fitted timeline exceeds GT source`);
+				const a = Math.floor(t), b = Math.min(gt.frames - 1, a + 1), w = t - a;
+				const at = (j, k) => gt.posedJoints[(a * 27 + j) * 3 + k] * (1 - w) + gt.posedJoints[(b * 27 + j) * 3 + k] * w;
+				const delta = j => [0, 1, 2].map(k => motion.posedJoints[(f * 27 + j) * 3 + k] - at(j, k));
+				const r = delta(0); rootError += Math.hypot(...r);
+				for (let j = 1; j < 27; j++) relative += Math.hypot(...delta(j).map((v, k) => v - r[k]));
+			}
+			rows.push({ motion: name, step: `F${step}`, frames: motion.frames, rootRelativeMm: 1000 * relative / (motion.frames * 26), rootPositionMm: 1000 * rootError / motion.frames });
+		}
+	}
+	const means = Array.from({ length: 6 }, (_, i) => {
+		const step = `F${i}`, selected = rows.filter(r => r.step === step);
+		return { step, rootRelativeMm: selected.reduce((s, r) => s + r.rootRelativeMm, 0) / selected.length, rootPositionMm: selected.reduce((s, r) => s + r.rootPositionMm, 0) / selected.length };
+	});
+	const note = "Native cskel27 posed_joints versus GT source NPZ, matched at f/fps seconds with linear GT position interpolation. Root-relative mean excludes Hips (26 joints); root position is Hips error. No alignment. These are NOT rendered-rig errors: Studio playback changes scale and bind offsets. F2 is camera-registered scene metres; F4 A/B endpoints are native source poses. Official #431 scoring is separate.";
+	const text = `${note}\n\n| Motion | Step | Root-relative mm | Root position mm |\n|---|---|---:|---:|\n${rows.map(r => `| ${r.motion} | ${r.step} | ${r.rootRelativeMm.toFixed(1)} | ${r.rootPositionMm.toFixed(1)} |`).join("\n")}\n\n| Mean over motions | Root-relative mm | Root position mm |\n|---|---:|---:|\n${means.map(r => `| ${r.step} | ${r.rootRelativeMm.toFixed(1)} | ${r.rootPositionMm.toFixed(1)} |`).join("\n")}\n`;
+	writeFileSync(join(root, "sanity.json"), JSON.stringify({ note, rows, means }, null, 2) + "\n");
+	writeFileSync(join(root, "sanity.md"), text);
+	console.log(text);
+}