cozyclay 1.9.0 → 2.0.0

package/tools/bench/extract-bench.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * extract-bench.mjs — GVHMR extraction bench (#430, validation step T2).
+ *
+ * Feeds T1 ground-truth renders (<input>/<motion>/<variant>/video.mp4 +
+ * camera.json) to the GPU box under named conditions and converts every
+ * result with production's post-processing, so T3 can score conditions
+ * against the ground truth without re-running anything:
+ *
+ *   <out>/<motion>/<variant>/<condition>/
+ *     gvhmr.npz    the runner's SMPL output, untouched
+ *     motion.npz   cskel27, smplToCskel27Motion -> stabilizeMotion ->
+ *                  guardTrajectoryFloor, written like /ardy/extract writes it
+ *     log.txt      the runner's log, lines prefixed with elapsed seconds
+ *     result.json  flags, detection counts, timings, quality report,
+ *                  stabilisation and trajectory diagnostics
+ *
+ * `prod` is handleExtract's path step for step (fps conform, upload, the
+ * bridge's persistent worker with its request, conversion with the env
+ * defaults); the other conditions call cclay_gvhmr_extract.py directly with
+ * one variable changed. Runs are serial, on the box they use only
+ * /tmp/cclay-bench-<stamp>/ (removed at exit) — the one exception is the
+ * persistent worker's own content-addressed code dir, which gvhmrWorker owns.
+ * Pure logic: extract-bench-lib.mjs.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { conformToExtractFps } from "../ardy/footage.mjs";
+import { qualityReportForMotion } from "../ardy/extract.mjs";
+import { guardTrajectoryFloor } from "../ardy/gvhmr-floor.mjs";
+import { stabilizeMotion } from "../ardy/motion-stabilize.mjs";
+import { motionArraysToNpzMembers, writeNpz } from "../ardy/npz.mjs";
+import { gvhmrWorker } from "../ardy/runners/gvhmr-worker.mjs";
+import { globalChildren, killGroup, streamLines, track } from "../ardy/runners/proc.mjs";
+import { smplToCskel27Motion } from "../ardy/smpl-cskel27.mjs";
+import { readNpz } from "../kimodo/read-npz.mjs";
+import { USAGE, parseArgs, parseRunnerLog, resolveCondition } from "./extract-bench-lib.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPO = resolve(HERE, "..", "..");
+const GVHMR_DIR = "~/cclay-ingest/GVHMR";
+const LAUNCHER = join(HERE, "cclay_bench_runner.py");
+const RUN_TIMEOUT_MS = 30 * 60 * 1000;
+// Same ssh options handleExtract uses (CCLAY_EXTRACT_SSH_PORT included) — the
+// worker client is keyed on them, as the bridge's is.
+const SSH_BASE_OPTS = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15"];
+const SSH_PORT = process.env.CCLAY_EXTRACT_SSH_PORT?.trim() || "";
+const SSH_OPTS = SSH_PORT ? [...SSH_BASE_OPTS, "-p", SSH_PORT] : SSH_BASE_OPTS;
+const SCP_OPTS = SSH_PORT ? [...SSH_BASE_OPTS, "-P", SSH_PORT] : SSH_BASE_OPTS;
+
+/** Spawn a child in its own group; resolve on exit 0, reject with its last
+ *  output line otherwise. Every line (split on \r too, for tqdm) -> onLine. */
+function exec(command, args, { onLine, timeoutMs = 0 } = {}) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(command, args, { detached: true, stdio: ["ignore", "pipe", "pipe"] });
+		track(child);
+		let last = "";
+		const feed = (line) => {
+			for (const part of line.split("\r")) {
+				if (!part.trim()) continue;
+				last = part;
+				onLine?.(part);
+			}
+		};
+		streamLines(child.stdout, feed);
+		streamLines(child.stderr, feed);
+		const timer = timeoutMs ? setTimeout(() => { killGroup(child); reject(new Error(`${command} timed out`)); }, timeoutMs) : null;
+		child.once("error", (err) => { clearTimeout(timer); reject(new Error(`spawn ${command}: ${err.message}`)); });
+		child.once("close", (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolvePromise();
+			else reject(new Error(last.trim() || `${command} exited ${code}`));
+		});
+	});
+}
+
+const ssh = (host, command, options) => exec("ssh", [...SSH_OPTS, host, command], options);
+const scp = (from, to, options) => exec("scp", [...SCP_OPTS, from, to], options);
+const seconds = (since) => Number(((performance.now() - since) / 1000).toFixed(3));
+const readJson = (path) => (existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : null);
+
+function commitId() {
+	const head = spawnSync("git", ["rev-parse", "HEAD"], { cwd: REPO, encoding: "utf8" }).stdout.trim();
+	const dirty = spawnSync("git", ["status", "--porcelain"], { cwd: REPO, encoding: "utf8" }).stdout.trim();
+	return head ? `${head}${dirty ? "-dirty" : ""}` : null;
+}
+
+function discoverMotions(input) {
+	return readdirSync(input, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.filter((entry) => readdirSync(join(input, entry.name), { withFileTypes: true })
+			.some((sub) => sub.isDirectory() && existsSync(join(input, entry.name, sub.name, "video.mp4"))))
+		.map((entry) => entry.name)
+		.sort();
+}
+
+function buildPlan(options) {
+	const motions = options.motions ?? discoverMotions(options.input);
+	const runs = [];
+	for (const motion of motions) {
+		for (const variant of options.variants) {
+			const source = join(options.input, motion, variant);
+			for (const condition of options.conditions) {
+				const camera = readJson(join(source, "camera.json"));
+				runs.push({
+					motion, variant, source,
+					out: join(options.out, motion, variant, condition.name),
+					plan: resolveCondition(condition, { cameraFMm: camera?.gvhmrFMm ?? null, env: process.env }),
+				});
+			}
+		}
+	}
+	return runs;
+}
+
+async function runOne(run, { host, benchDir, worker, commit }) {
+	const started = performance.now();
+	const { motion, variant, source, out, plan } = run;
+	rmSync(out, { recursive: true, force: true });
+	mkdirSync(out, { recursive: true });
+	const logPath = join(out, "log.txt");
+	writeFileSync(logPath, "");
+	const log = (line) => appendFileSync(logPath, `[+${((performance.now() - started) / 1000).toFixed(2)}s] ${line}\n`);
+	const video = join(source, "video.mp4");
+	const videoBytes = readFileSync(video);
+	const camera = readJson(join(source, "camera.json"));
+	const meta = readJson(join(source, "meta.json"));
+	const timings = {};
+	const result = {
+		ok: false,
+		tool: "tools/bench/extract-bench.mjs",
+		commit,
+		createdAt: new Date().toISOString(),
+		motion, variant, condition: plan.name, base: plan.base, fmm: plan.fmm, host,
+		input: {
+			video, sha256: createHash("sha256").update(videoBytes).digest("hex"), bytes: videoBytes.length,
+			camera: camera && { width: camera.width, height: camera.height, fx: camera.fx, gvhmrFMm: camera.gvhmrFMm ?? null },
+			meta: meta && { frames: meta.frames, fps: meta.fps, variant: meta.variant, source: meta.source?.path ?? null },
+		},
+		flags: {
+			path: plan.path, detector: plan.detector, keypoints: plan.keypoints, fMm: plan.fMm,
+			...(plan.path === "direct" ? { runnerArgs: plan.runnerArgs, launcher: plan.detector === "palette" ? "runner" : "bench-launcher" } : { workerRequest: plan.workerFields }),
+			stabilize: plan.stabilize,
+		},
+		timings,
+	};
+	const localTmp = mkdtempSync(join(tmpdir(), "cclay-bench-"));
+	const runKey = `${motion}-${variant}-${plan.name}`.replace(/[^A-Za-z0-9_.-]/g, "_");
+	const remoteDir = `${benchDir}/${runKey}`;
+	const remoteVideo = `${remoteDir}/video.mp4`;
+	const remoteNpz = `${remoteDir}/gvhmr.npz`;
+	const outRoot = `${remoteDir}/gvhmr-out`;
+	let step = "conform";
+	try {
+		// handleExtract's rate ceiling: a ≤30 fps render passes through as is.
+		let at = performance.now();
+		const conformed = await conformToExtractFps(video, join(localTmp, "capped.mp4"));
+		result.conform = { fps: conformed.fps, capped: conformed.capped };
+		timings.conformS = seconds(at);
+
+		step = "upload";
+		at = performance.now();
+		await ssh(host, `umask 077 && mkdir -p '${remoteDir}'`, { timeoutMs: 60000 });
+		await scp(conformed.path, `${host}:${remoteVideo}`, { timeoutMs: 300000 });
+		timings.uploadS = seconds(at);
+
+		step = "extract";
+		at = performance.now();
+		let performanceReport = null;
+		if (plan.path === "worker") {
+			const request = { video: remoteVideo, output: remoteNpz, outRoot, ...plan.workerFields };
+			log(`[bench] worker request ${JSON.stringify(request)}`);
+			performanceReport = await worker().run(request, { timeoutMs: RUN_TIMEOUT_MS, onLine: log });
+		} else {
+			const program = plan.detector === "palette"
+				? "cclay_gvhmr_extract.py"
+				: `${benchDir}/cclay_bench_runner.py cclay_gvhmr_extract.py`;
+			const command = `cd ${GVHMR_DIR} && .venv/bin/python ${program} ${remoteVideo} ${remoteNpz} ${plan.runnerArgs.join(" ")} --out-root ${outRoot}`;
+			log(`[bench] ssh ${command}`);
+			await ssh(host, command, { timeoutMs: RUN_TIMEOUT_MS, onLine: log });
+		}
+		timings.extractS = seconds(at);
+		result.performance = performanceReport;
+
+		step = "fetch";
+		at = performance.now();
+		const gvhmrNpz = join(out, "gvhmr.npz");
+		await scp(`${host}:${remoteNpz}`, gvhmrNpz, { timeoutMs: 120000 });
+		timings.fetchS = seconds(at);
+
+		step = "convert";
+		at = performance.now();
+		const events = performanceReport?.trajectory?.events ?? [];
+		const converted = stabilizeMotion(smplToCskel27Motion(readNpz(gvhmrNpz)), plan.stabilize);
+		const guarded = guardTrajectoryFloor(converted, events);
+		result.quality = qualityReportForMotion(guarded.motion);
+		if (events.length) performanceReport.trajectory.floor = guarded.diagnostics;
+		writeNpz(join(out, "motion.npz"), motionArraysToNpzMembers(guarded.motion));
+		timings.convertS = seconds(at);
+		result.motionInfo = { frames: guarded.motion.frames, fps: guarded.motion.fps, personScale: guarded.motion.personScale };
+		result.stabilization = guarded.motion.stabilization ?? null;
+		result.trajectory = { events, floor: guarded.diagnostics };
+		result.ok = true;
+	} catch (err) {
+		result.error = { step, message: err.message };
+		log(`[bench] FAILED at ${step}: ${err.message}`);
+	} finally {
+		rmSync(localTmp, { recursive: true, force: true });
+		await ssh(host, `rm -rf '${remoteDir}'`, { timeoutMs: 60000 }).catch((err) => log(`[bench] remote cleanup failed: ${err.message}`));
+	}
+	const summary = parseRunnerLog(readFileSync(logPath, "utf8"));
+	const segmentation = result.performance?.segmentation;
+	result.detection = summary.detectedFrames != null
+		? { detector: summary.detector, detectedFrames: summary.detectedFrames, totalFrames: summary.totalFrames, detectionRate: summary.detectionRate, source: summary.detectionSource }
+		: segmentation?.detectedFrames != null
+			? { detector: segmentation.detector, detectedFrames: segmentation.detectedFrames, totalFrames: segmentation.frames, detectionRate: segmentation.detectionRate, source: "worker-segmentation" }
+			: { detector: summary.detector, detectedFrames: null, totalFrames: null, detectionRate: null, source: null };
+	result.runnerLog = summary;
+	timings.totalS = seconds(started);
+	writeFileSync(join(out, "result.json"), `${JSON.stringify(result, null, "\t")}\n`);
+	return result;
+}
+
+async function main() {
+	let options;
+	try {
+		options = parseArgs(process.argv.slice(2), process.env);
+	} catch (err) {
+		console.error(`extract-bench: ${err.message}\n\n${USAGE}`);
+		process.exit(2);
+	}
+	if (options.help) {
+		console.log(USAGE);
+		return;
+	}
+	options.input = resolve(options.input);
+	options.out = resolve(options.out);
+	const runs = buildPlan(options);
+	for (const run of runs) {
+		if (!existsSync(join(run.source, "video.mp4"))) throw new Error(`missing input ${join(run.source, "video.mp4")}`);
+	}
+	if (options.dryRun) {
+		for (const { motion, variant, plan } of runs) {
+			const flags = plan.path === "worker" ? JSON.stringify(plan.workerFields) : plan.runnerArgs.join(" ");
+			console.log(`${motion}/${variant}/${plan.name}\t${plan.path}\t${flags}`);
+		}
+		return;
+	}
+
+	const host = options.host;
+	const commit = commitId();
+	const benchDir = `/tmp/cclay-bench-${Date.now()}-${randomBytes(3).toString("hex")}`;
+	let client = null;
+	const worker = () => (client ??= gvhmrWorker({ host, sshOptions: SSH_OPTS, scpOptions: SCP_OPTS }));
+	const cleanupRemote = () => spawnSync("ssh", [...SSH_OPTS, host, `rm -rf '${benchDir}'`], { stdio: "ignore", timeout: 60000 });
+	process.once("SIGINT", () => {
+		console.error("extract-bench: interrupted; stopping children and removing the box temp dir");
+		client?.stop("extract-cancelled");
+		for (const child of globalChildren) killGroup(child);
+		cleanupRemote();
+		process.exit(130);
+	});
+
+	await ssh(host, `umask 077 && mkdir -p '${benchDir}'`, { timeoutMs: 60000 });
+	if (runs.some((run) => run.plan.path === "direct" && run.plan.detector !== "palette")) {
+		await scp(LAUNCHER, `${host}:${benchDir}/cclay_bench_runner.py`, { timeoutMs: 60000 });
+	}
+	let failures = 0;
+	try {
+		for (const run of runs) {
+			const label = `${run.motion}/${run.variant}/${run.plan.name}`;
+			const previous = readJson(join(run.out, "result.json"));
+			if (previous?.ok && !options.force) {
+				console.log(`skip ${label} (result.json ok; --force re-runs)`);
+				continue;
+			}
+			console.log(`run  ${label} [${run.plan.path}]`);
+			const result = await runOne(run, { host, benchDir, worker, commit });
+			if (!result.ok) failures += 1;
+			const d = result.detection;
+			console.log(`${result.ok ? "ok  " : "FAIL"} ${label} detected ${d.detectedFrames ?? "?"}/${d.totalFrames ?? "?"} (${d.detector ?? "?"})` +
+				` extract ${result.timings.extractS ?? "-"} s total ${result.timings.totalS} s` +
+				(result.ok ? ` quality ${result.quality.pass ? "pass" : "fail"}` : ` — ${result.error.step}: ${result.error.message}`));
+		}
+	} finally {
+		client?.stop("extract-bench-finished");
+		cleanupRemote();
+	}
+	if (failures) {
+		console.error(`extract-bench: ${failures} run(s) failed`);
+		process.exitCode = 1;
+	}
+}
+
+main().catch((err) => {
+	console.error(`extract-bench: ${err.stack ?? err.message}`);
+	process.exit(1);
+});

package/tools/bench/fal-generate.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { buildH3LockedPrompt } from "../../bin/agent/video-adapters.mjs";
+
+export const FAL_MODEL = "minimax/h3-max-turbo/image-to-video";
+export function falRequest({ prompt, firstImage, lastImage }) {
+	if (!String(prompt ?? "").trim() || !firstImage || !lastImage) throw new Error("prompt and both endpoint images are required");
+	// H3's documented contract has no seed field: independent requests, not
+	// a claimed deterministic seed sweep. Do not silently send ignored seeds.
+	return { prompt: buildH3LockedPrompt(prompt), image_url: firstImage, end_image_url: lastImage, resolution: "480P", duration: 5, prompt_expansion_mode: "disabled" };
+}
+export function costFields(value) {
+	if (!value || typeof value !== "object") return {};
+	const out = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (/cost|price|billing|usage/i.test(key)) out[key] = entry;
+		else if (entry && typeof entry === "object") { const nested = costFields(entry); if (Object.keys(nested).length) out[key] = nested; }
+	}
+	return out;
+}
+/** Unbounded queue wait, finite individual HTTP requests. Every response is
+ * logged by the caller. Test injects fetch + wait, never wall-clock polling. */
+export async function runFal(body, { key, fetchImpl = fetch, wait = () => delay(5000), onEvent = () => {} }) {
+	if (!key) throw new Error("fal key is required");
+	const request = async (url, options = {}) => {
+		const response = await fetchImpl(url, { ...options, headers: { authorization: `Key ${key}`, ...options.headers }, signal: AbortSignal.timeout(120000) });
+		if (!response.ok) throw new Error(`fal HTTP ${response.status} at ${new URL(url).pathname}`);
+		const value = await response.json(); onEvent({ at: new Date().toISOString(), url, response: value, cost: costFields(value) }); return value;
+	};
+	const queued = await request(`https://queue.fal.run/${FAL_MODEL}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+	let status = queued;
+	for (;;) {
+		const video = status.video?.url ?? status.output?.video?.url ?? status.video_url;
+		if (video) return { queued, result: status, video };
+		if (["FAILED", "CANCELLED"].includes(status.status)) throw new Error(`fal ${status.status}: ${status.error ?? "no error detail"}`);
+		if (status.status === "COMPLETED") {
+			const url = status.response_url ?? queued.response_url;
+			if (!url) throw new Error("fal completed without response_url");
+			status = await request(url);
+			if (!(status.video?.url ?? status.output?.video?.url ?? status.video_url)) throw new Error("fal completed without video URL");
+			continue;
+		}
+		const url = status.status_url ?? queued.status_url;
+		if (!url) throw new Error("fal queue response lacks status_url");
+		await wait(); status = await request(url);
+	}
+}
+const sha = bytes => createHash("sha256").update(bytes).digest("hex");
+export async function main(argv = process.argv.slice(2)) {
+	const { values: v } = parseArgs({ args: argv, options: { scenario: { type: "string" }, variant: { type: "string", default: "shaded" }, out: { type: "string" }, prompt: { type: "string" }, key: { type: "string" }, runs: { type: "string", default: "3" }, "dry-run": { type: "boolean" }, help: { type: "boolean" } } });
+	if (v.help) { console.log("usage: node tools/bench/fal-generate.mjs --scenario <GT motion dir> --out <clips root> [--prompt <action>] [--key <file>] [--runs 3] [--variant shaded|skin] [--dry-run]\nReads scenario.json prompt or --prompt; writes <out>/<scenario>-<variant>-01/{video.mp4,request.json,A.png,B.png}. No seed is sent (independent H3 requests)."); return; }
+	if (!v.scenario || !v.out) throw new Error("--scenario and --out required");
+	const runs = Number(v.runs); if (!Number.isInteger(runs) || runs < 1) throw new Error("--runs must be a positive integer");
+	if (!["shaded", "skin"].includes(v.variant)) throw new Error("--variant must be shaded or skin");
+	const scenario = resolve(v.scenario), name = basename(scenario), source = join(scenario, v.variant);
+	const meta = JSON.parse(readFileSync(join(source, "meta.json"))), info = existsSync(join(scenario, "scenario.json")) ? JSON.parse(readFileSync(join(scenario, "scenario.json"))) : {};
+	const prompt = v.prompt ?? info.prompt;
+	const still = frame => execFileSync("ffmpeg", ["-v", "error", "-i", join(source, "video.mp4"), "-vf", `select=eq(n\\,${frame})`, "-frames:v", "1", "-f", "image2pipe", "-c:v", "png", "pipe:1"], { maxBuffer: 10 * 1024 * 1024 });
+	const a = still(0), b = still(meta.frames - 1);
+	if (!a.length || !b.length) throw new Error("missing endpoint frame");
+	const body = falRequest({ prompt, firstImage: `data:image/png;base64,${a.toString("base64")}`, lastImage: `data:image/png;base64,${b.toString("base64")}` });
+	const keyPath = v.key ?? resolve(process.env.HOME, "ccFalToMocap/.fal-key");
+	const dry = v["dry-run"] || !existsSync(keyPath);
+	const key = dry ? null : readFileSync(keyPath, "utf8").trim();
+	for (let i = 1; i <= runs; i++) {
+		const dir = join(resolve(v.out), `${name}-${v.variant}-${String(i).padStart(2, "0")}`); mkdirSync(dir, { recursive: true });
+		const recordPath = join(dir, "request.json");
+		if (existsSync(recordPath) && JSON.parse(readFileSync(recordPath)).ok && existsSync(join(dir, "video.mp4"))) { console.log(`skip completed ${basename(dir)}`); continue; }
+		writeFileSync(join(dir, "A.png"), a); writeFileSync(join(dir, "B.png"), b);
+		const record = { model: FAL_MODEL, scenario, variant: v.variant, run: i, independentRun: true, seed: null, dryRun: dry, ok: false, body: { ...body, image_url: "A.png", end_image_url: "B.png" }, endpoints: { A: sha(a), B: sha(b), sourceFrames: [0, meta.frames - 1] }, events: [], cost: null };
+		const save = () => writeFileSync(recordPath, JSON.stringify(record, null, 2) + "\n"); save();
+		if (dry) { console.log(`dry-run ${basename(dir)}: ${v["dry-run"] ? "requested" : "key missing"}`); continue; }
+		try {
+			const result = await runFal(body, { key, onEvent: event => { record.events.push(event); save(); console.log(`[${basename(dir)}] ${event.response.status ?? "result"} ${event.response.request_id ?? ""}`); } });
+			const response = await fetch(result.video, { signal: AbortSignal.timeout(300000) }); if (!response.ok) throw new Error(`video HTTP ${response.status}`);
+			writeFileSync(join(dir, "video.mp4"), Buffer.from(await response.arrayBuffer()));
+			record.ok = true; record.requestId = result.queued.request_id; record.result = result.result;
+			record.cost = record.events.map(e => e.cost).filter(c => Object.keys(c).length); record.costNote = record.cost.length ? "Provider-reported fields, not estimated." : "Provider supplied no cost fields; unknown, not zero.";
+		} catch (error) { record.error = error.message; throw error; } finally { save(); }
+	}
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main().catch(e => { console.error(e.stack); process.exitCode = 1; });

package/tools/bench/fit/README.md

@@ -0,0 +1,189 @@
+# F0-F5 cumulative fitting bench (#432)
+
+```sh
+node tools/bench/fit-bench.mjs \
+  --input /path/to/evidence/gt \
+  --extract /path/to/evidence/exp1/extract \
+  --poses /path/to/evidence/prep/gt-motions \
+  --out /path/to/evidence/exp2/fit \
+  --variant shaded --host yun@ubuntu-baremetal \
+  --motions walk,run,turn,sit,standup,jump,pickup,stepup
+
+# Native YOLO/ViTPose on the grey mannequin. F0 exists in T2; if F1
+# yolo-vitpose+fmm is absent, fit-bench extracts it serially with --host.
+node tools/bench/fit-bench.mjs \
+  --input /path/to/evidence/gt --extract /path/to/evidence/exp1/extract \
+  --poses /path/to/evidence/prep/gt-motions --out /path/to/evidence/exp2/fit-skin \
+  --variant skin --base-condition yolo-vitpose --host yun@ubuntu-baremetal
+
+# Evaluation ONLY. This program's output is never consumed by fitting.
+node tools/bench/fit-sanity.mjs /path/to/evidence/exp2/fit /path/to/evidence/prep/gt-motions
+```
+
+Each `<out>/<motion>/F0..F5/motion.npz` is a normal cskel27 archive:
+`local_rot_mats`, `root_positions`, `posed_joints`, `fps`, with production's
+optional `bone_scale` / `person_scale`. `result.json` records provenance,
+registration, configuration, contact diagnostics and deviations. Camera evidence
+is saved to `<out>/<motion>/incam.npz`, with its run log and cache manifest.
+A different variant or base condition needs a different output root. Existing
+mismatched results are rejected, not silently overwritten. `--base-condition`
+defaults to `prod` (the existing F0/F1 motion bytes are unchanged); it accepts a
+T2 base condition without `+fmm`. F0 is copied from that condition and F1 from
+the same condition with `+fmm`. T2 already supports `yolo-vitpose+fmm` for direct
+runs. If only F1 is missing, the CLI invokes T2 for that one motion/variant/
+condition after the idle-GPU check. It never substitutes F0 for missing F1.
+
+## Information boundary
+
+**No fitting stage reads or measures GT intermediate motion.** The allowed
+inputs are extracted video motion, known camera, known character body, the
+user's two endpoint poses and scene geometry. `readEndpoints` decodes a source
+archive but exposes only its first/last rotation matrices and roots. It never
+examines intermediate arrays, joint trajectories or GT body measurements. A
+test poisons all other source data and exercises the real CLI successfully.
+`fit-sanity.mjs` is a separate read-only evaluator and is the only code here
+that consumes the complete reference trajectory.
+
+| Stage | New information | Operation |
+|---|---|---|
+| F0 | None | Byte-identical T2 `<base-condition>/motion.npz` (default `prod`). |
+| F1 | Known focal | Byte-identical T2 `<base-condition>+fmm/motion.npz`. |
+| F2 | Known static OpenCV camera extrinsics | Register the first F1 pelvis/orientation to the predicted camera-space pelvis/orientation, then apply the same rigid transform to every frame. |
+| F3 | Known character bone factors | Regenerate FK from F2 rotations with canonical offsets times the character's factors. Defaults to all ones, equivalent to `boneScale:1`. |
+| F4 | User's A and B poses only | Slerp local rotations toward A/B; smoothstep endpoint root-offset ramps. Default 0.5 s, capped at half the clip. |
+| F5 | Floor Y=0 and optional axis-aligned boxes | Low/slow stance detection, rigid support locking, floor and skeletal bone/box penetration resolution. |
+
+## F2: why one static registration
+
+The new `cclay_bench_extract_incam.py` imports the box's **unchanged**
+`cclay_gvhmr_extract.py` and runs its `main()` under the same imported
+`FastRuntime` and `trajectory_job` wrappers as the production worker. It passes
+`--static-cam`, known `--f-mm`, production detector/keypoint flags, and
+production smoothing sigma. It does not copy the model or preprocessing
+pipeline and does not edit anything in the GVHMR checkout. For a direct T2
+condition such as `yolo-vitpose`, the camera launcher uses the same YOLO and
+ViTPose flags and **does not** enable `FastRuntime` or `trajectory_job`. The
+bench-only `--bench-direct` switch is removed before calling the runner. This
+keeps camera evidence matched to F1 rather than quietly using palette evidence
+for a YOLO fit. The condition is included in cache signatures and result metadata.
+
+The launcher adds the raw in-camera SMPL-X parameters and recomputes the
+camera pelvis with the same SMPL-X -> SMPL mesh regressor as the runner.
+**SMPL model `transl` is not its mesh-regressed pelvis**, so substituting it
+would introduce a shape-dependent translation error. It smooths camera pelvis
+and root orientation with the runner's own `smooth_motion_params`.
+
+All transforms multiply column vectors. Added NPZ members:
+
+| Member | Shape | Meaning |
+|---|---|---|
+| `incam_raw_global_orient`, `incam_raw_transl` | T,3 | Raw camera-space SMPL-X model parameters. |
+| `incam_raw_body_pose`, `incam_raw_betas` | T,63 / T,10 | Raw model articulation and shape. |
+| `incam_global_orient`, `incam_pelvis` | T,3 | Smoothed camera orientation and mesh-regressed pelvis. |
+| `ayfz_to_camera` | T,4,4 | Per-frame relation between output ayfz pelvis/orientation and the camera prediction. |
+| `ay_to_ayfz` | 4,4 | Runner's exact pre-smoothing normalization, including floor and heading. |
+| `ay_global_orient`, `ay_transl` | T,3 | Raw predicted gravity-aligned model parameters. |
+| `K_fullimg` | T,3,3 | Intrinsics actually used by GVHMR. |
+
+The per-frame `ayfz_to_camera` is diagnostic. Camera-space depth and the
+integrated global trajectory can disagree even with a static camera. Applying
+the entire time-varying relation would replace F1's trajectory with noisy
+monocular camera translation. Instead F2 preserves production's trajectory
+(including stabilization/contact anchoring and any descent/floor correction)
+and only fixes its initial reference frame:
+
+```
+R_f1_to_cam = R_incam[0] * transpose(R_f1[0])
+R = transpose(R_world_to_cam) * R_f1_to_cam
+p_world = transpose(R_world_to_cam) * (p_incam[0] - t_world_to_cam)
+t = p_world - R * p_f1[0]
+p_F2[f] = R * p_F1[f] + t
+```
+
+Only the Hips local rotation is multiplied by `R`; child local rotations are
+unchanged. All positional channels get the same SE(3). No GT roots, floor
+alignment, heading search, scale search or Procrustes fit enters F2. Camera
+JSON must be static and a proper rigid OpenCV transform. Its `worldToCamera`
+(y down, z forward), not the Three/OpenGL matrix, is inverted. Camera evidence
+intrinsics must agree with the known focal.
+
+## Deliberate conversion deviations
+
+- F0/F1 are untouched production archives: `smplToCskel27Motion`,
+  `stabilizeMotion`, and `guardTrajectoryFloor` have already run in T2.
+- F2 is cumulative on **that F1**, not a fresh conversion of the additional
+  inference. The new inference supplies camera evidence only. Its first
+  pelvis replaces production's arbitrary initial floor datum; re-grounding
+  here would undo camera placement. Static registration uses one frame and
+  inherits that frame's monocular depth/orientation uncertainty.
+- F3 keeps F2's root in metres and `personScale=1`; it does not scale the
+  camera translation to compensate for changed body proportions. It rebuilds
+  positions by FK, avoiding production's independently smoothed joint arrays
+  when those disagree with constant bone lengths. There is no second
+  stabilization, foot anchoring or percentile-floor pass.
+- Character factors default to canonical cskel27 (all ones), not a fresh
+  measurement of the rendered y-bot mesh. `--body body.json` accepts the known
+  character's 27 positive per-bone factors. This follows the issue's
+  `boneScale:1` option and leaves playback's own rig mapping intact.
+- F4 preserves F3 bone lengths and uses source NPZ first/last poses exactly as
+  requested. The last source frame is pinned even when rate conversion puts
+  the last rendered sample slightly before it (180@30 vs 144@24).
+- F5 is a **skeletal**, not skinned-mesh, constraint pass. One support point at
+  a time is locked by rigid root translation, preserving rotations and bone
+  vectors. Eligible feet/toes are within 4 cm of a known surface and move at
+  <=0.18 m/s for >=0.08 s. A hand can support on a known box face; no box means
+  no invented hand contact. Smoothstep bridges carry offsets between runs.
+  Simultaneous two-foot or hand/foot contacts are not a multi-effector IK solve.
+- Box collision tests include open-interior bone segments, not just joints.
+  On collision a conservative root shift clears the whole skeleton along a
+  separating axis, preserving lengths. No skin radius, self-collision or
+  collision-free swept trajectory between frames is claimed. Boxes can force
+  substantial displacement. Conflicting projections fail rather than silently
+  emit penetrations. Floor/scene safety wins over incompatible locks and A/B
+  pins; `sceneOverrides` and `maxLockResidualM` disclose this.
+
+Scene format (`--scene`):
+
+```json
+{"boxes":[{"min":[-0.5,0,-0.5],"max":[0.5,1,0.5]}]}
+```
+
+## GPU ownership and caches
+
+Wait until other T2 sweeps have finished. The CLI refuses any other GVHMR
+Python process, including an idle persistent worker, and checks `nvidia-smi`
+compute memory before upload and again immediately before inference. This is
+a safety check, not a lock respected by independently launched jobs; callers
+must coordinate those launches. No other process is killed. The bench runs
+serially and uses only `/tmp/cclay-fit-*` on the box; the run directory is
+removed in success/failure paths, and cleanup failure is an error. Abrupt
+process termination or a broken SSH connection can require manual cleanup.
+
+Local camera caches bind the video, focal/flags and deployed code hashes. The
+box runner SHA is recorded. The runner is externally managed: if it changes,
+use `--force-incam`. `--incam-root` supplies already extracted
+`<root>/<motion>/incam.npz` without touching the GPU (also the CPU integration
+test path).
+
+## Verification and sanity metric
+
+```sh
+node test/verify-fit-bench.mjs
+npm run build                  # dist is required by an existing suite
+node tools/run-tests.mjs
+```
+
+Tests cover camera inverse and proper-rotation validation, rigid trajectory
+registration, body/FK preservation, endpoint slerp and antipodes, short clips,
+falloff boundaries, floor and stance locking, segment/box crossings, bone
+length preservation, archive round trips, byte-identical F0/F1, and the real
+CLI with poisoned intermediate GT data. No timing waits or external GPU are
+needed by tests.
+
+`fit-sanity.mjs` compares output cskel27 `posed_joints` with source NPZ
+`posed_joints` at matching seconds (linear interpolation of reference
+positions). Root-relative error averages joints 1..26; root error is Hips.
+There is **no alignment**. It writes per-motion/per-stage and aggregate tables
+in millimetres. These are not official rendered-rig errors: Studio playback
+applies rig scale and bind offsets, F2 is scene metres, and the requested F4
+source endpoints are native cskel27. Official grading by #431 remains separate.

package/tools/bench/fit/camera.mjs

@@ -0,0 +1,59 @@
+import { matMul, matTranspose, quatToMat } from "../../../src/ardy/convert.js";
+import { add, cloneMotion, matVec, member, readMat, sub, vec } from "./motion.mjs";
+
+export function axisAngleMatrix(v) {
+	const angle = Math.hypot(...v), scale = angle < 1e-12 ? 0.5 : Math.sin(angle / 2) / angle;
+	return quatToMat([Math.cos(angle / 2), ...v.map(x => x * scale)]);
+}
+
+/** OpenCV x-right/y-down/z-forward, NOT the OpenGL camera rotation. */
+export function cameraToWorld(camera) {
+	const t = camera.worldToCamera;
+	if (!camera.static || !Array.isArray(t) || t.length !== 4 || !t.every(row => Array.isArray(row) && row.length === 4 && row.every(Number.isFinite))) {
+		throw new Error("camera: expected static OpenCV worldToCamera [4,4]");
+	}
+	const r = t.slice(0, 3).map(row => row.slice(0, 3)), rt = matTranspose(r);
+	const identity = matMul(r, rt);
+	const det = r[0][0] * (r[1][1] * r[2][2] - r[1][2] * r[2][1]) - r[0][1] * (r[1][0] * r[2][2] - r[1][2] * r[2][0]) + r[0][2] * (r[1][0] * r[2][1] - r[1][1] * r[2][0]);
+	if (identity.some((row, i) => row.some((x, j) => Math.abs(x - Number(i === j)) > 1e-5)) || Math.abs(det - 1) > 1e-5 || t[3].some((x, i) => Math.abs(x - Number(i === 3)) > 1e-6)) {
+		throw new Error("camera: worldToCamera must be a rigid proper transform");
+	}
+	return { rotation: rt, translation: matVec(rt, t.slice(0, 3).map(row => -row[3])) };
+}
+
+export function transformMotion(motion, { rotation, translation }) {
+	const out = cloneMotion(motion);
+	for (let f = 0; f < motion.frames; f++) {
+		out.rootPos.set(add(matVec(rotation, vec(motion.rootPos, f * 3)), translation), f * 3);
+		out.rotMats.set(matMul(rotation, readMat(motion.rotMats, f * 243)).flat(), f * 243);
+		for (let j = 0; j < 27; j++) {
+			const o = (f * 27 + j) * 3;
+			out.posedJoints.set(add(matVec(rotation, vec(motion.posedJoints, o)), translation), o);
+		}
+	}
+	return out;
+}
+
+/** F2: static registration, never a trajectory fit to GT. The new box run
+ * supplies the camera-space pelvis and orientation. F1 supplies the SAME
+ * production-smoothed ayfz root orientation. Register their first frames,
+ * then apply ONE rigid transform to all of F1. This removes the arbitrary
+ * initial heading/origin/floor datum while preserving production trajectory,
+ * body, stabilisation and trajectory-floor safety relative to that datum.
+ * Per-frame world->camera transforms are saved as diagnostics, not used as
+ * a moving camera: their drift includes monocular depth/velocity disagreement.
+ */
+export function registerCamera(motion, incam, camera) {
+	const n = incam.incam_pelvis?.shape[0];
+	if (n !== motion.frames) throw new Error("incam and F1 frame counts disagree");
+	const pelvis = member(incam, "incam_pelvis", [n, 3]);
+	const orient = member(incam, "incam_global_orient", [n, 3]);
+	if (Math.abs(member(incam, "fps", [])[0] - motion.fps) > 1e-6) throw new Error("incam and F1 fps disagree");
+	const c2w = cameraToWorld(camera);
+	const f1ToCamera = matMul(axisAngleMatrix(vec(orient)), matTranspose(readMat(motion.rotMats)));
+	const rotation = matMul(c2w.rotation, f1ToCamera);
+	const worldPelvis = add(matVec(c2w.rotation, vec(pelvis)), c2w.translation);
+	const translation = sub(worldPelvis, matVec(rotation, vec(motion.rootPos)));
+	return { motion: transformMotion(motion, { rotation, translation }),
+		diagnostics: { rotation, translation, worldPelvis, anchorFrame: 0, registration: "static-predicted-pelvis", preservesF1RelativeTrajectory: true } };
+}