cozyclay 2.1.0 → 3.0.0

package/tools/track/masks.mjs

@@ -1,318 +0,0 @@
-#!/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

@@ -1,201 +0,0 @@
-/**
- * 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

@@ -1,108 +0,0 @@
-#!/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();