cozyclay 1.9.0 → 2.0.0

package/tools/track/masks.mjs

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * masks.mjs — SAM2 video masks for the known-character tracker (#500).
+ *
+ * Runs tools/track/py/masks.py on the GPU box for one clip (video + GVHMR obs)
+ * and caches the result at <cache-root>/<set>/<name>/masks/{masks.npz,masks.json,manifest.json}.
+ * The cache key is sha256 over the video bytes, the obs bytes, the masks.py
+ * bytes and the run parameters: changing any of them recomputes. A cache hit
+ * also requires masks.npz / masks.json to match the sha256 recorded in the
+ * manifest, so a corrupt or truncated file is recomputed, never served. Only the
+ * video and the obs reach the box; no plate, truth mask or colour cue.
+ *
+ * Provenance: the masks must be computed from the video the obs was extracted
+ * from. The obs manifest chain is followed (copy manifests via `source`, checked
+ * against `sourceSha256`) to the original obs; when that records `videoSha256`
+ * the video used here must have exactly that sha (else `obs-video-mismatch`),
+ * and the masks manifest carries the origin's own label unchanged: "recorded"
+ * (hashed at extraction; the default when the origin has no label) or
+ * "backfilled-path" (hashed later by tools/track/backfill-provenance.mjs).
+ * Sweep obs without a manifest (tools' serial sweep) record nothing: the item's
+ * sweep input path is used (fal: the approved clip `item.video`) and a video
+ * written after the obs is rejected (`obs-video-newer`); such manifests say
+ * `provenance: "path-only"`.
+ *
+ *   node tools/track/masks.mjs --approved evidence/obs/approved.json [--items gt/walk,cube/bump]
+ *   node tools/track/masks.mjs --video clip.mp4 --obs obs.npz --out <dir>
+ */
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+import { readNpz } from "../kimodo/read-npz.mjs";
+import { buildRemoteCommand, quote } from "./run-box.mjs";
+
+const HERE = fileURLToPath(new URL(".", import.meta.url));
+export const MASKS_SCRIPT = join(HERE, "py", "masks.py");
+export const DEFAULT_CACHE_ROOT = process.env.COZYCLAY_OBS_ROOT ?? "evidence/obs/cache";
+const DEFAULT_HOST = process.env.COZYFIT_HOST || "ubuntu-baremetal";
+const sshBase = ["-o", "BatchMode=yes", "-o", "ConnectTimeout=15", "-o", "ServerAliveInterval=15", "-o", "ServerAliveCountMax=3"];
+const port = process.env.CCLAY_EXTRACT_SSH_PORT;
+const sshFlags = port ? [...sshBase, "-p", port] : sshBase;
+const scpFlags = port ? [...sshBase, "-P", port] : sshBase;
+
+export const USAGE = `usage: node tools/track/masks.mjs --approved <approved.json> [options]
+       node tools/track/masks.mjs --video <clip.mp4> --obs <obs.npz> --out <dir> [options]
+
+  --items a,b            set/name or name filter (default: every approved item)
+  --obs-root <dir>       obs from <dir>/<set>/<name>/g5/obs.npz (default ${DEFAULT_CACHE_ROOT})
+  --cache-root <dir>     masks to <dir>/<set>/<name>/masks/ (default: --obs-root)
+  --chunk-frames 180     SAM2 frames per propagation chunk
+  --prompt <mode>        centre | box | torso | upper | joints | all (default: masks.py's joints)
+  --host <ssh-dest>      GPU box (default ${DEFAULT_HOST})
+  --gpu-wait-min 30      wait this long for a busy GPU (never kills the other job)
+  --force                recompute even when the cache key matches`;
+
+const sha256 = (...parts) => { const h = createHash("sha256"); for (const p of parts) h.update(p); return h.digest("hex"); };
+const fileSha = (path) => sha256(readFileSync(path));
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
+
+/** The cache key: content of every input that can change the masks. */
+export function masksCacheKey({ videoSha256, obsSha256, scriptSha256, params = {} }) {
+	for (const [name, value] of Object.entries({ videoSha256, obsSha256, scriptSha256 })) {
+		if (!/^[0-9a-f]{64}$/.test(value ?? "")) throw new Error(`masksCacheKey: ${name} must be a sha256 hex digest`);
+	}
+	const sorted = Object.fromEntries(Object.entries(params).sort(([a], [b]) => a.localeCompare(b)));
+	return sha256(JSON.stringify({ video: videoSha256, obs: obsSha256, script: scriptSha256, params: sorted }));
+}
+
+/**
+ * "cached" only when the manifest names this key and both outputs exist with
+ * the sha256 the manifest recorded. `files` = { npz, json } shas or null.
+ */
+export function cacheState(manifest, key, files) {
+	if (!manifest) return files ? "stale-unmanifested" : "missing";
+	if (manifest.key !== key) return "stale-key";
+	if (!files) return "missing";
+	if (!manifest.masksSha256 || !manifest.masksJsonSha256) return "unverifiable";
+	return files.npz === manifest.masksSha256 && files.json === manifest.masksJsonSha256 ? "cached" : "corrupt";
+}
+
+/**
+ * Check the video against what the obs records about its own extraction video.
+ * `origin` = the original obs manifest (after following copies) or null.
+ */
+export const HASHED_PROVENANCE = ["recorded", "backfilled-path"];
+export function checkObsVideo({ origin, videoSha256, obsSha256, videoPath, videoMtimeMs, obsMtimeMs }) {
+	const label = origin?.provenance;
+	if (label !== undefined && label !== "path-only" && !HASHED_PROVENANCE.includes(label)) throw new Error(`obs-provenance-unknown: obs manifest provenance ${JSON.stringify(label)} is not ${[...HASHED_PROVENANCE, "path-only"].join("|")}`);
+	if (HASHED_PROVENANCE.includes(label) && !origin.videoSha256) throw new Error(`obs-provenance-invalid: obs manifest says ${label} but records no videoSha256`);
+	if (origin?.videoSha256) {
+		if (label === "path-only") throw new Error("obs-provenance-invalid: obs manifest says path-only but records a videoSha256");
+		if (origin.videoSha256 !== videoSha256) throw new Error(`obs-video-mismatch: the obs was extracted from video sha256 ${origin.videoSha256} (${origin.video ?? "?"}), not ${videoSha256} (${videoPath})`);
+		if (origin.obsSha256 && origin.obsSha256 !== obsSha256) throw new Error(`obs-sha-mismatch: obs sha256 ${obsSha256} differs from its manifest's ${origin.obsSha256}`);
+		return { provenance: label ?? "recorded", recordedVideoSha256: origin.videoSha256, recordedVideo: origin.video ?? null };
+	}
+	if (videoMtimeMs > obsMtimeMs) throw new Error(`obs-video-newer: ${videoPath} was written after the obs it would pair with; it cannot be the extraction video`);
+	return { provenance: "path-only", recordedVideoSha256: null, recordedVideo: origin?.video ?? null };
+}
+
+/** Follow copy manifests (`source` + `sourceSha256`) to the original obs and its manifest. */
+export function resolveObsOrigin(obs) {
+	let path = resolve(obs);
+	const copies = [];
+	for (let hop = 0; hop < 4; hop += 1) {
+		const manifest = readJson(join(dirname(path), "manifest.json"));
+		if (!manifest?.source || resolve(manifest.source) === path) return { obs: path, manifest, copies };
+		if (manifest.sourceSha256 && fileSha(path) !== manifest.sourceSha256) throw new Error(`obs-copy-mismatch: ${path} is not the ${manifest.source} its manifest names`);
+		copies.push(path);
+		path = resolve(manifest.source);
+		if (!existsSync(path)) throw new Error(`obs-copy-mismatch: source ${path} is missing`);
+	}
+	throw new Error(`obs-copy-mismatch: manifest chain from ${obs} is too long`);
+}
+
+/** Structural check of a fetched masks.npz before it is committed to the cache. */
+export function validateMasksNpz(path, frames) {
+	const members = readNpz(path);
+	const prob = members.prob?.shape, area = members.area?.shape;
+	if (!prob || prob.length !== 3 || prob[0] !== frames || !(prob[1] > 0 && prob[2] > 0) || members.prob.dtype !== "<f2") throw new Error(`masks-invalid: prob ${JSON.stringify(prob ?? null)} ${members.prob?.dtype ?? ""} for ${frames} frames`);
+	if (!area || area[0] !== frames || !members.reprompted) throw new Error(`masks-invalid: area/reprompted missing or wrong length in ${path}`);
+	return prob;
+}
+
+/** Remote budget: model load + ~0.25 s/frame on the RTX 3070, 3x headroom, bounded. */
+export function remoteTimeoutS(frames) {
+	return Math.min(1800, Math.ceil(60 + 0.75 * Math.max(1, frames)));
+}
+
+/** The clip and obs a bench item's masks are computed from (same files the obs sweep used). */
+export function itemMaskInputs(item, { obsRoot = DEFAULT_CACHE_ROOT, cacheRoot = obsRoot } = {}) {
+	// The obs sweep extracted every item from item.video ?? <dir>/<variant>/video.mp4 (fal: the approved clip itself).
+	const video = item.video ?? join(item.dir, item.variant, "video.mp4");
+	return { video, obs: join(obsRoot, item.set, item.name, "g5", "obs.npz"), outDir: join(cacheRoot, item.set, item.name, "masks") };
+}
+
+function exec(program, args, { onLine, timeoutMs } = {}) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(program, args, { stdio: ["ignore", "pipe", "pipe"] });
+		let output = "", pending = "", timer;
+		const emit = (chunk) => {
+			output += chunk; pending += chunk;
+			const lines = pending.split(/[\r\n]+/); // tqdm redraws with \r
+			pending = lines.pop() ?? "";
+			for (const line of lines) if (line) onLine?.(line);
+		};
+		child.stdout.on("data", emit); child.stderr.on("data", emit);
+		if (timeoutMs > 0) timer = setTimeout(() => child.kill("SIGTERM"), timeoutMs);
+		child.once("error", (error) => { clearTimeout(timer); reject(error); });
+		child.once("close", (code, signal) => {
+			clearTimeout(timer);
+			if (pending) onLine?.(pending);
+			if (code === 0) resolvePromise(output);
+			else reject(Object.assign(new Error(`${program} exited ${code ?? signal}: ${output.slice(-3000)}`), { code, output }));
+		});
+	});
+}
+
+async function runRemote({ host, video, obs, outDir, chunkFrames, prompt, frames, onLine }) {
+	const remote = `/tmp/cozyfit-masks-${Date.now()}-${randomBytes(5).toString("hex")}`;
+	const ssh = (command, options) => exec("ssh", [...sshFlags, host, command], options);
+	const scp = (from, to) => exec("scp", [...scpFlags, from, to]);
+	const staging = `${outDir}.tmp-${process.pid}`;
+	let failure;
+	try {
+		await ssh(`umask 077 && mkdir ${quote(remote)}`);
+		await scp(MASKS_SCRIPT, `${host}:${remote}/masks.py`);
+		await scp(video, `${host}:${remote}/video.mp4`);
+		await scp(obs, `${host}:${remote}/obs.npz`);
+		const inner = buildRemoteCommand(remote, "masks.py", ["--video", `${remote}/video.mp4`, "--obs", `${remote}/obs.npz`, "--out", `${remote}/out`, "--chunk-frames", String(chunkFrames), ...(prompt ? ["--prompt", prompt] : [])]);
+		const limit = remoteTimeoutS(frames);
+		// The box enforces the bound itself so a dropped ssh never leaves SAM2 running.
+		await ssh(`timeout -k 15 ${limit} bash -c ${quote(inner)}`, { onLine, timeoutMs: (limit + 60) * 1000 });
+		rmSync(staging, { recursive: true, force: true });
+		mkdirSync(staging, { recursive: true });
+		await scp(`${host}:${remote}/out/masks.npz`, join(staging, "masks.npz"));
+		await scp(`${host}:${remote}/out/masks.json`, join(staging, "masks.json"));
+		return staging;
+	} catch (error) {
+		failure = error;
+		rmSync(staging, { recursive: true, force: true });
+		throw error;
+	} finally {
+		try { await ssh(`rm -rf ${quote(remote)}`); }
+		catch (cleanupError) { if (!failure) throw cleanupError; }
+	}
+}
+
+/** Row count of the obs person boxes; empty obs fails here, before any box work. */
+function obsFrames(obsPath) {
+	const shape = readNpz(obsPath).bbx_xys?.shape;
+	if (!shape || shape.length !== 2 || shape[0] === 0 || shape[1] !== 3) throw new Error(`no-person-prompt: ${obsPath} has no person boxes (bbx_xys shape ${JSON.stringify(shape ?? null)})`);
+	return shape[0];
+}
+
+/**
+ * Masks for one clip, computed on the box unless the cache key matches.
+ * Returns { path, jsonPath, manifest, cached }.
+ */
+export async function ensureMasks({ video, obs, outDir, host = DEFAULT_HOST, chunkFrames = 180, prompt, force = false, gpuWaitMin = 30, log = console.log } = {}) {
+	for (const [name, path] of Object.entries({ video, obs })) if (!path || !existsSync(path)) throw new Error(`masks: missing ${name} ${path}`);
+	const frames = obsFrames(obs);
+	const params = { chunkFrames, prompt: prompt ?? "script-default" };
+	const record = { videoSha256: fileSha(video), obsSha256: fileSha(obs), scriptSha256: fileSha(MASKS_SCRIPT), params };
+	const origin = resolveObsOrigin(obs);
+	const provenance = { ...checkObsVideo({ origin: origin.manifest, videoSha256: record.videoSha256, obsSha256: fileSha(origin.obs), videoPath: resolve(video), videoMtimeMs: statSync(video).mtimeMs, obsMtimeMs: statSync(origin.obs).mtimeMs }), originObs: origin.obs, obsCopies: origin.copies };
+	const key = masksCacheKey(record);
+	const path = join(outDir, "masks.npz"), jsonPath = join(outDir, "masks.json"), manifestPath = join(outDir, "manifest.json");
+	const files = existsSync(path) && existsSync(jsonPath) ? { npz: fileSha(path), json: fileSha(jsonPath) } : null;
+	const state = cacheState(readJson(manifestPath), key, files);
+	if (state === "cached" && !force) return { path, jsonPath, manifest: readJson(manifestPath), cached: true, state };
+	log(`masks: ${force ? "forced" : state}; computing on ${host}`);
+	const deadline = Date.now() + gpuWaitMin * 60000;
+	let staging;
+	for (;;) {
+		try {
+			staging = await runRemote({ host, video, obs, outDir, chunkFrames, prompt, frames, onLine: (line) => { if (/^\[masks\]|no-person-prompt|Error|error:/.test(line)) log(line); } });
+			break;
+		} catch (error) {
+			const message = String(error.message);
+			if (/no-person-prompt/.test(message)) throw new Error(`no-person-prompt: ${obs} has no usable person box`);
+			if (!/gpu-busy/.test(message) || Date.now() > deadline) throw error;
+			log(`masks: GPU busy; waiting 30 s (${message.split("\n").find((l) => /gpu-busy/.test(l))?.trim().slice(0, 200)})`);
+			await sleep(30000);
+		}
+	}
+	let summary;
+	try {
+		summary = JSON.parse(readFileSync(join(staging, "masks.json"), "utf8"));
+		if (summary.frames !== frames) throw new Error(`masks-invalid: masks.json frames ${summary.frames}, obs ${frames}`);
+		validateMasksNpz(join(staging, "masks.npz"), frames);
+	} catch (error) {
+		rmSync(staging, { recursive: true, force: true });
+		throw error;
+	}
+	const manifest = {
+		key, ...record, video: resolve(video), obs: resolve(obs), script: MASKS_SCRIPT, ...provenance,
+		masksSha256: fileSha(join(staging, "masks.npz")), masksJsonSha256: fileSha(join(staging, "masks.json")),
+		host, frames: summary.frames, seconds: summary.seconds, peakReservedMiB: summary.peakReservedMiB, reprompted: summary.reprompted, anchor: summary.anchor, previousState: force ? "forced" : state, createdAt: new Date().toISOString(),
+	};
+	mkdirSync(outDir, { recursive: true });
+	rmSync(manifestPath, { force: true }); // no window where a manifest vouches for half-renamed files
+	for (const name of ["masks.npz", "masks.json"]) renameSync(join(staging, name), join(outDir, name));
+	rmSync(staging, { recursive: true, force: true });
+	writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 1)}\n`);
+	return { path, jsonPath, manifest, cached: false, state };
+}
+
+export function parseArgs(argv) {
+	const options = { obsRoot: DEFAULT_CACHE_ROOT, chunkFrames: 180, host: DEFAULT_HOST, gpuWaitMin: 30, force: false };
+	const value = (i) => { if (i + 1 >= argv.length) throw new Error(`${argv[i]} needs a value`); return argv[i + 1]; };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (arg === "--help" || arg === "-h") options.help = true;
+		else if (arg === "--force") options.force = true;
+		else if (arg === "--approved") options.approved = value(i++);
+		else if (arg === "--items") options.items = value(i++).split(",").filter(Boolean);
+		else if (arg === "--obs-root") options.obsRoot = value(i++);
+		else if (arg === "--cache-root") options.cacheRoot = value(i++);
+		else if (arg === "--video") options.video = value(i++);
+		else if (arg === "--obs") options.obs = value(i++);
+		else if (arg === "--out") options.out = value(i++);
+		else if (arg === "--host") options.host = value(i++);
+		else if (arg === "--chunk-frames") options.chunkFrames = Number(value(i++));
+		else if (arg === "--prompt") options.prompt = value(i++);
+		else if (arg === "--gpu-wait-min") options.gpuWaitMin = Number(value(i++));
+		else throw new Error(`unknown argument ${arg}`);
+	}
+	options.cacheRoot ??= options.obsRoot;
+	if (!options.help) {
+		const single = options.video || options.obs || options.out;
+		if (single ? !(options.video && options.obs && options.out) || options.approved : !options.approved) throw new Error(USAGE);
+		if (!(Number.isInteger(options.chunkFrames) && options.chunkFrames >= 2)) throw new Error("--chunk-frames must be an integer >= 2");
+	}
+	return options;
+}
+
+export function selectMaskItems(approved, filter) {
+	const items = approved.items ?? [];
+	if (!filter) return items;
+	const chosen = filter.map((key) => {
+		const hit = items.filter((item) => key === `${item.set}/${item.name}` || key === item.name);
+		if (hit.length !== 1) throw new Error(`--items ${key}: ${hit.length ? "ambiguous" : "not in the approved list"}`);
+		return hit[0];
+	});
+	return chosen;
+}
+
+async function main(argv = process.argv.slice(2)) {
+	const options = parseArgs(argv);
+	if (options.help) { console.log(USAGE); return; }
+	const common = { host: options.host, chunkFrames: options.chunkFrames, prompt: options.prompt, force: options.force, gpuWaitMin: options.gpuWaitMin };
+	if (options.video) {
+		const result = await ensureMasks({ ...common, video: options.video, obs: options.obs, outDir: options.out });
+		console.log(`${options.out}: ${result.cached ? "cached" : "computed"} frames=${result.manifest.frames} seconds=${result.manifest.seconds} peakReservedMiB=${result.manifest.peakReservedMiB} reprompted=${result.manifest.reprompted.length}`);
+		return;
+	}
+	const items = selectMaskItems(JSON.parse(readFileSync(options.approved, "utf8")), options.items);
+	let failed = 0;
+	for (const item of items) {
+		const label = `${item.set}/${item.name}`;
+		try {
+			const inputs = itemMaskInputs(item, options);
+			const result = await ensureMasks({ ...common, ...inputs, log: (line) => console.log(`${label}: ${line}`) });
+			console.log(`${label}: ${result.cached ? "cached" : `computed (was ${result.state})`} frames=${result.manifest.frames} seconds=${result.manifest.seconds} peakReservedMiB=${result.manifest.peakReservedMiB} reprompted=${result.manifest.reprompted.length} provenance=${result.manifest.provenance} video=${result.manifest.video} sha=${result.manifest.videoSha256.slice(0, 12)} -> ${result.path}`);
+		} catch (error) {
+			failed += 1;
+			console.error(`${label}: FAILED ${error.message.split("\n")[0]}`);
+		}
+	}
+	console.log(`masks: ${items.length - failed}/${items.length} ok`);
+	if (failed) process.exitCode = 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+	main().catch((error) => { console.error(error.message); process.exitCode = error.message === USAGE ? 2 : 1; });
+}

package/tools/track/metrics.mjs

@@ -0,0 +1,201 @@
+/**
+ * metrics.mjs - pure quality metrics for the known-character tracker gate
+ * (#500, plan todo 4). No I/O: callers load motions and pass arrays.
+ *
+ * Motions are `{ frames, fps, posedJoints }` with posedJoints a flat
+ * frames x 27 x 3 array (cskel27 order, metres), exactly what
+ * src/ardy/npz.js decodeMotionNpz and tools/kimodo/read-npz.mjs give.
+ * rotMats are flat frames x 27 x 9 (row-major local rotations; the root's
+ * local rotation is its world rotation).
+ */
+import { CSKEL27_JOINTS } from "../../src/ardy/cskel27.js";
+
+/** cskel27 foot joints whose truth speed defines stance (same set as the
+ * truth-analysis evaluate(): RightFoot, RightToeBase, LeftFoot, LeftToeBase). */
+export const STANCE_FEET = ["RightFoot", "RightToeBase", "LeftFoot", "LeftToeBase"].map((name) => CSKEL27_JOINTS.indexOf(name));
+/** A truth foot joint moving slower than this (3D, m/s) is in stance. */
+export const STANCE_SPEED_MPS = 0.1;
+
+const DEG = 180 / Math.PI;
+
+/** Geodesic angle (degrees) between consecutive root rotations: frames - 1 values. */
+export function pelvisStepsDeg(rotMats, frames = rotMats.length / (27 * 9)) {
+	if (!(Number.isInteger(frames) && frames > 0) || rotMats.length % frames) throw new Error(`pelvisStepsDeg: ${rotMats.length} values do not split into ${frames} frames`);
+	const stride = rotMats.length / frames;
+	if (stride < 9) throw new Error("pelvisStepsDeg: fewer than 9 values per frame");
+	const out = new Float64Array(Math.max(0, frames - 1));
+	for (let t = 0; t + 1 < frames; t += 1) {
+		const a = t * stride, b = (t + 1) * stride;
+		// trace(A^T B) = sum_ij A_ij B_ij
+		let trace = 0;
+		for (let k = 0; k < 9; k += 1) trace += rotMats[a + k] * rotMats[b + k];
+		out[t] = Math.acos(Math.min(1, Math.max(-1, (trace - 1) / 2))) * DEG;
+	}
+	return out;
+}
+
+/** Solve A X = B in place (dense, partial pivoting). A: n x n rows, B: n x m rows. */
+function solveDense(A, B) {
+	const n = A.length, m = B[0].length;
+	for (let c = 0; c < n; c += 1) {
+		let p = c;
+		for (let r = c + 1; r < n; r += 1) if (Math.abs(A[r][c]) > Math.abs(A[p][c])) p = r;
+		if (!(Math.abs(A[p][c]) > 1e-300)) throw new Error("spline: singular system");
+		[A[c], A[p]] = [A[p], A[c]];
+		[B[c], B[p]] = [B[p], B[c]];
+		for (let r = c + 1; r < n; r += 1) {
+			const f = A[r][c] / A[c][c];
+			if (f === 0) continue;
+			for (let k = c; k < n; k += 1) A[r][k] -= f * A[c][k];
+			for (let k = 0; k < m; k += 1) B[r][k] -= f * B[c][k];
+		}
+	}
+	for (let r = n - 1; r >= 0; r -= 1) {
+		for (let k = 0; k < m; k += 1) {
+			let s = B[r][k];
+			for (let c = r + 1; c < n; c += 1) s -= A[r][c] * B[c][k];
+			B[r][k] = s / A[r][r];
+		}
+	}
+	return B;
+}
+
+/**
+ * Cubic spline with not-a-knot ends (scipy.interpolate.CubicSpline's
+ * default) through `values[i][k]` at strictly increasing `times[i]`, evaluated
+ * at `queries` (clamped to the knot range). Fewer than 4 knots: linear.
+ * Returns queries.length rows of m values.
+ */
+export function splineResample(times, values, queries) {
+	const n = times.length, m = values[0]?.length ?? 0;
+	if (n < 2 || values.length !== n) throw new Error("splineResample: need >= 2 knots with one value row each");
+	for (let i = 1; i < n; i += 1) if (!(times[i] > times[i - 1])) throw new Error("splineResample: times must increase");
+	const h = Array.from({ length: n - 1 }, (_, i) => times[i + 1] - times[i]);
+	let M = null; // second derivatives
+	if (n >= 4) {
+		const A = Array.from({ length: n }, () => new Float64Array(n));
+		const B = Array.from({ length: n }, () => new Float64Array(m));
+		A[0][0] = h[1]; A[0][1] = -(h[0] + h[1]); A[0][2] = h[0];
+		A[n - 1][n - 3] = h[n - 2]; A[n - 1][n - 2] = -(h[n - 3] + h[n - 2]); A[n - 1][n - 1] = h[n - 3];
+		for (let i = 1; i < n - 1; i += 1) {
+			A[i][i - 1] = h[i - 1]; A[i][i] = 2 * (h[i - 1] + h[i]); A[i][i + 1] = h[i];
+			for (let k = 0; k < m; k += 1) B[i][k] = 6 * ((values[i + 1][k] - values[i][k]) / h[i] - (values[i][k] - values[i - 1][k]) / h[i - 1]);
+		}
+		M = solveDense(A, B);
+	}
+	return Array.from(queries, (q0) => {
+		const q = Math.min(times[n - 1], Math.max(times[0], q0));
+		let i = 0, hi = n - 2;
+		while (i < hi) { const mid = (i + hi + 1) >> 1; if (times[mid] <= q) i = mid; else hi = mid - 1; }
+		const x0 = times[i], x1 = times[i + 1], hh = h[i], a = x1 - q, b = q - x0;
+		const row = new Float64Array(m);
+		for (let k = 0; k < m; k += 1) {
+			const y0 = values[i][k], y1 = values[i + 1][k];
+			row[k] = M
+				? (M[i][k] * a ** 3 + M[i + 1][k] * b ** 3) / (6 * hh) + (y0 / hh - (M[i][k] * hh) / 6) * a + (y1 / hh - (M[i + 1][k] * hh) / 6) * b
+				: (y0 * a + y1 * b) / hh;
+		}
+		return row;
+	});
+}
+
+function jointCountOf(motion) {
+	const count = motion.posedJoints.length / (motion.frames * 3);
+	if (!Number.isInteger(count) || count < 1) throw new Error(`motion: ${motion.posedJoints.length} posedJoints values do not split into ${motion.frames} frames`);
+	return count;
+}
+
+/** posedJoints of `motion` spline-resampled to `frames` frames at `fps` (times k / fps, clamped to the clip). */
+export function resampleMotion(motion, fps, frames) {
+	const joints = jointCountOf(motion), width = joints * 3;
+	const times = Array.from({ length: motion.frames }, (_, i) => i / motion.fps);
+	const rows = Array.from({ length: motion.frames }, (_, i) => motion.posedJoints.subarray ? motion.posedJoints.subarray(i * width, (i + 1) * width) : motion.posedJoints.slice(i * width, (i + 1) * width));
+	const out = splineResample(times, rows, Array.from({ length: frames }, (_, k) => k / fps));
+	const posedJoints = new Float64Array(frames * width);
+	out.forEach((row, k) => posedJoints.set(row, k * width));
+	return { frames, fps, posedJoints };
+}
+
+/**
+ * Foot slide on truth-stance frames (cm/s). The truth is resampled (not-a-knot
+ * cubic spline) to the prediction's timeline t_k = k / pred.fps; a foot joint
+ * is in stance between k and k+1 when its truth 3D speed is below 0.10 m/s,
+ * and the prediction's horizontal (XZ) speed there is pooled over the four
+ * foot joints. Speeds are invariant to the rigid yaw/translation alignment
+ * the prediction may need, so none is applied.
+ */
+export function truthStanceSlideCmPerS(pred, truth, { feet = STANCE_FEET, stanceSpeedMps = STANCE_SPEED_MPS } = {}) {
+	const pj = jointCountOf(pred), tj = jointCountOf(truth);
+	for (const j of feet) if (!(j < pj && j < tj)) throw new Error(`foot joint ${j} is outside the motions' joint count`);
+	const n = pred.frames;
+	const truthTimes = Array.from({ length: truth.frames }, (_, i) => i / truth.fps);
+	const queries = Array.from({ length: n }, (_, k) => k / pred.fps);
+	const truthRows = Array.from({ length: truth.frames }, (_, i) => feet.flatMap((j) => [0, 1, 2].map((c) => truth.posedJoints[(i * tj + j) * 3 + c])));
+	const G = splineResample(truthTimes, truthRows, queries);
+	const slides = [];
+	for (let f = 0; f < feet.length; f += 1) {
+		const j = feet[f];
+		for (let k = 0; k + 1 < n; k += 1) {
+			const gv = Math.hypot(G[k + 1][f * 3] - G[k][f * 3], G[k + 1][f * 3 + 1] - G[k][f * 3 + 1], G[k + 1][f * 3 + 2] - G[k][f * 3 + 2]) * pred.fps;
+			if (!(gv < stanceSpeedMps)) continue;
+			const a = (k * pj + j) * 3, b = ((k + 1) * pj + j) * 3;
+			slides.push(Math.hypot(pred.posedJoints[b] - pred.posedJoints[a], pred.posedJoints[b + 2] - pred.posedJoints[a + 2]) * pred.fps);
+		}
+	}
+	const total = feet.length * Math.max(0, n - 1);
+	return {
+		meanCmPerS: slides.length ? (slides.reduce((s, v) => s + v, 0) / slides.length) * 100 : null,
+		stanceSamples: slides.length,
+		stanceFraction: total ? slides.length / total : 0,
+		rule: `truth foot 3D speed < ${stanceSpeedMps} m/s (truth spline-resampled to the prediction's ${pred.fps} fps); prediction XZ speed pooled over cskel27 joints ${feet.join(",")}`,
+	};
+}
+
+function sameShape(a, b, what) {
+	if (a.length !== b.length) throw new Error(`${what}: ${a.length} vs ${b.length} frames`);
+	a.forEach((row, t) => { if (row.length !== b[t].length) throw new Error(`${what}: frame ${t} has ${row.length} vs ${b[t].length} joints`); });
+}
+
+/**
+ * Agreement of per-frame, per-joint occlusion flags (true = hidden) with the
+ * truth visibility (true = visible): the fraction of (frame, joint) pairs
+ * where flagged === !visible, plus the confusion counts.
+ */
+export function occlusionAgreement(flags, truthVisibility) {
+	sameShape(flags, truthVisibility, "occlusionAgreement");
+	let pairs = 0, agree = 0, truthHidden = 0, flagged = 0, bothHidden = 0;
+	flags.forEach((row, t) => row.forEach((flag, j) => {
+		const hidden = !truthVisibility[t][j];
+		pairs += 1;
+		if (Boolean(flag) === hidden) agree += 1;
+		if (hidden) truthHidden += 1;
+		if (flag) flagged += 1;
+		if (flag && hidden) bothHidden += 1;
+	}));
+	return {
+		agreement: pairs ? agree / pairs : null,
+		pairs,
+		truthHidden,
+		flagged,
+		hiddenRecall: truthHidden ? bothHidden / truthHidden : null,
+		flaggedPrecision: flagged ? bothHidden / flagged : null,
+	};
+}
+
+/**
+ * Mean Euclidean error (metres, Studio world frame, no alignment: the camera
+ * is known) over exactly the (frame, joint) pairs flagged hidden.
+ * pred / truth: [T][J][3]; flags: [T][J] booleans.
+ */
+export function hiddenJointError(pred, truth, flags) {
+	sameShape(pred, truth, "hiddenJointError pred/truth");
+	sameShape(pred, flags, "hiddenJointError pred/flags");
+	let sum = 0, pairs = 0;
+	flags.forEach((row, t) => row.forEach((flag, j) => {
+		if (!flag) return;
+		const p = pred[t][j], g = truth[t][j];
+		sum += Math.hypot(p[0] - g[0], p[1] - g[1], p[2] - g[2]);
+		pairs += 1;
+	}));
+	return { meanM: pairs ? sum / pairs : null, pairs };
+}

package/tools/track/publish-obs.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * publish-obs.mjs - publish the mannequin observations an `obs-bench --extract`
+ * run produced into the shared obs root that later runs read
+ * (tools/bench/obs-bench.mjs ensureObs: <obsRoot>/<set>/<name>/g5/obs.npz).
+ *
+ *   node tools/track/publish-obs.mjs --run <obs-bench out dir> --obs-root <dir> [--dry-run]
+ *
+ * For every <run>/<set>/<name>/obs-mannequin/{obs.npz,manifest.json,extract.log}:
+ *   - the manifest must describe a genuine extraction (no `source`: not itself
+ *     a copy from an obs root) whose signature still matches the video on disk
+ *     (sha256(video sha, K, betas, wrapper sha, detector, keypoints), the
+ *     formula obs-bench signs extractions with), so the obs belong to that video;
+ *   - obs.npz and extract.log are copied; manifest.json is the run's manifest
+ *     plus videoSha256, obsSha256 and publishedFrom (deterministic content);
+ *   - an existing target file with different bytes is never replaced: the item
+ *     is refused and nothing of it is written. Identical files are left alone.
+ * Writes <run>/publish.json and exits 1 when any item is refused or incomplete.
+ */
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sha = (...parts) => { const h = createHash("sha256"); for (const p of parts) h.update(p); return h.digest("hex"); };
+const fileSha = (path) => sha(readFileSync(path));
+const FILES = ["obs.npz", "extract.log", "manifest.json"];
+
+export const USAGE = "usage: node tools/track/publish-obs.mjs --run <obs-bench out dir> --obs-root <dir> [--dry-run]";
+
+export function parseArgs(argv) {
+	const o = { dryRun: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const flag = argv[i];
+		if (flag === "--dry-run") { o.dryRun = true; continue; }
+		if (flag === "--help" || flag === "-h") { o.help = true; continue; }
+		if (flag !== "--run" && flag !== "--obs-root") throw new Error(`unknown option ${flag}`);
+		const value = argv[++i];
+		if (value === undefined || value.startsWith("--")) throw new Error(`${flag} needs a value`);
+		o[flag === "--run" ? "run" : "obsRoot"] = resolve(value);
+	}
+	if (!o.help && (!o.run || !o.obsRoot)) throw new Error("--run and --obs-root are required");
+	return o;
+}
+
+/** <run>/<set>/<name>/obs-mannequin dirs. */
+export function runItems(run) {
+	const dirs = (p) => readdirSync(p).filter((n) => statSync(join(p, n)).isDirectory());
+	const out = [];
+	for (const set of dirs(run)) for (const name of dirs(join(run, set))) if (existsSync(join(run, set, name, "obs-mannequin"))) out.push({ set, name, dir: join(run, set, name, "obs-mannequin") });
+	return out;
+}
+
+/** The files to publish for one item, or a reason it cannot be published. */
+export function plan({ set, name, dir }, obsRoot) {
+	const label = `${set}/${name}`;
+	const missing = FILES.filter((f) => !existsSync(join(dir, f)));
+	if (missing.length) return { item: label, status: "incomplete", missing };
+	let manifest;
+	try { manifest = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8")); } catch (error) { return { item: label, status: "refused", reason: `unreadable manifest.json: ${error.message}` }; }
+	if (!manifest || typeof manifest !== "object") return { item: label, status: "refused", reason: "manifest.json is not an object" };
+	if (manifest.source) return { item: label, status: "refused", reason: `manifest records source ${manifest.source}: a copy from an obs root, not an extraction` };
+	for (const key of ["signature", "video", "K", "betas", "detector", "keypoints", "wrapperSha256"]) if (manifest[key] === undefined) return { item: label, status: "refused", reason: `manifest has no ${key}` };
+	if (!existsSync(manifest.video)) return { item: label, status: "refused", reason: `video ${manifest.video} is gone` };
+	const videoSha256 = fileSha(manifest.video);
+	const signature = sha(videoSha256, JSON.stringify(manifest.K), JSON.stringify(manifest.betas), manifest.wrapperSha256, manifest.detector, manifest.keypoints);
+	if (signature !== manifest.signature) return { item: label, status: "refused", reason: `signature mismatch: ${manifest.video} (sha256 ${videoSha256}) is not the video these obs were extracted from` };
+	const obsSha256 = fileSha(join(dir, "obs.npz"));
+	const published = `${JSON.stringify({ ...manifest, videoSha256, obsSha256, publishedFrom: dir }, null, "\t")}\n`;
+	const target = join(obsRoot, set, name, "g5");
+	const files = [
+		{ name: "obs.npz", bytes: readFileSync(join(dir, "obs.npz")), from: join(dir, "obs.npz") },
+		{ name: "extract.log", bytes: readFileSync(join(dir, "extract.log")), from: join(dir, "extract.log") },
+		{ name: "manifest.json", bytes: Buffer.from(published) },
+	].map((f) => ({ ...f, to: join(target, f.name), state: !existsSync(join(target, f.name)) ? "new" : readFileSync(join(target, f.name)).equals(f.bytes) ? "same" : "different" }));
+	const clash = files.filter((f) => f.state === "different");
+	if (clash.length) return { item: label, status: "refused", reason: `existing different file(s) not overwritten: ${clash.map((f) => f.to).join(", ")}`, target };
+	return { item: label, status: files.every((f) => f.state === "same") ? "same" : "publish", target, videoSha256, obsSha256, detector: manifest.detector, files };
+}
+
+export function publish(options) {
+	const results = runItems(options.run).map((item) => {
+		const p = plan(item, options.obsRoot);
+		if (p.status === "publish" && !options.dryRun) {
+			mkdirSync(p.target, { recursive: true });
+			for (const f of p.files) if (f.state === "new") (f.from ? copyFileSync(f.from, f.to) : writeFileSync(f.to, f.bytes));
+			// Read back: what is on disk is what was planned.
+			for (const f of p.files) if (!readFileSync(f.to).equals(f.bytes)) throw new Error(`${f.to}: read-back differs after publishing`);
+			p.status = "published";
+		}
+		const { files, ...rest } = p;
+		return { ...rest, ...(files ? { files: files.map((f) => ({ name: f.name, state: f.state })) } : {}) };
+	});
+	return { run: options.run, obsRoot: options.obsRoot, dryRun: options.dryRun, createdAt: new Date().toISOString(), results, ok: results.length > 0 && results.every((r) => ["published", "same", "publish"].includes(r.status)) };
+}
+
+export function main(argv = process.argv.slice(2)) {
+	let options;
+	try { options = parseArgs(argv); } catch (error) { console.error(`publish-obs: ${error.message}\n${USAGE}`); return 2; }
+	if (options.help) { console.log(USAGE); return 0; }
+	const report = publish(options);
+	for (const r of report.results) console.log(`${r.item}: ${r.status}${r.reason ? ` - ${r.reason}` : ""}${r.missing ? ` - missing ${r.missing.join(", ")}` : ""}`);
+	if (!report.results.length) console.error(`publish-obs: no <set>/<name>/obs-mannequin under ${options.run}`);
+	if (!options.dryRun) writeFileSync(join(options.run, "publish.json"), `${JSON.stringify(report, null, "\t")}\n`);
+	return report.ok ? 0 : 1;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = main();