cozyclay 1.9.0 → 2.0.0

package/tools/bench/metrics.mjs

@@ -0,0 +1,313 @@
+/**
+ * Pure scoring math for the mocap bench (#431): rigid/similarity alignment,
+ * pose and trajectory errors, mask IoU, box contact and timeline resampling.
+ * No DOM, no Three, no I/O; unit-tested by test/verify-bench-metrics.mjs.
+ *
+ * Conventions: points are [x, y, z] in the Studio scene (metres, +Y up).
+ * A yaw is a rotation about +Y with the same sign as src/ardy/motion-
+ * calibration.js: x' = cos*x + sin*z, z' = -sin*x + cos*z.
+ */
+
+export const DEG = Math.PI / 180;
+
+export function rotateYaw([x, y, z], yawRad) {
+	const c = Math.cos(yawRad);
+	const s = Math.sin(yawRad);
+	return [c * x + s * z, y, -s * x + c * z];
+}
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+function centroid(points) {
+	const c = [0, 0, 0];
+	for (const p of points) {
+		c[0] += p[0];
+		c[1] += p[1];
+		c[2] += p[2];
+	}
+	return c.map((value) => value / points.length);
+}
+
+/**
+ * Least-squares yaw (about +Y) and ground-plane translation mapping `src`
+ * onto `dst` (paired points): dst ~ rotateYaw(src, yaw) + [tx, 0, tz].
+ * Height is neither rotated nor translated: both takes stand on the same
+ * floor, so a height error stays an error.
+ */
+export function fitYawTranslation(src, dst) {
+	if (src.length !== dst.length || !src.length) throw new Error("fitYawTranslation needs paired, non-empty point sets");
+	const cs = centroid(src);
+	const cd = centroid(dst);
+	// Maximise sum b . R(a) over theta: C = sum(ax bx + az bz), S = sum(az bx - ax bz).
+	let C = 0;
+	let S = 0;
+	for (let i = 0; i < src.length; i += 1) {
+		const ax = src[i][0] - cs[0];
+		const az = src[i][2] - cs[2];
+		const bx = dst[i][0] - cd[0];
+		const bz = dst[i][2] - cd[2];
+		C += ax * bx + az * bz;
+		S += az * bx - ax * bz;
+	}
+	const yawRad = C === 0 && S === 0 ? 0 : Math.atan2(S, C);
+	const rc = rotateYaw(cs, yawRad);
+	return { yawRad, yawDeg: yawRad / DEG, tx: cd[0] - rc[0], tz: cd[2] - rc[2] };
+}
+
+export function applyYawTranslation(point, { yawRad, tx, tz }) {
+	const r = rotateYaw(point, yawRad);
+	return [r[0] + tx, r[1], r[2] + tz];
+}
+
+/** Eigenvector of the largest eigenvalue of a symmetric 4x4 (cyclic Jacobi). */
+function dominantEigenvector4(input) {
+	const a = input.map((row) => row.slice());
+	const v = [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]];
+	for (let sweep = 0; sweep < 64; sweep += 1) {
+		let off = 0;
+		for (let p = 0; p < 4; p += 1) for (let q = p + 1; q < 4; q += 1) off += a[p][q] * a[p][q];
+		if (off < 1e-30) break;
+		for (let p = 0; p < 4; p += 1) {
+			for (let q = p + 1; q < 4; q += 1) {
+				if (Math.abs(a[p][q]) < 1e-300) continue;
+				const theta = (a[q][q] - a[p][p]) / (2 * a[p][q]);
+				const t = Math.sign(theta || 1) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+				const c = 1 / Math.sqrt(t * t + 1);
+				const s = t * c;
+				for (let k = 0; k < 4; k += 1) {
+					const akp = a[k][p];
+					const akq = a[k][q];
+					a[k][p] = c * akp - s * akq;
+					a[k][q] = s * akp + c * akq;
+				}
+				for (let k = 0; k < 4; k += 1) {
+					const apk = a[p][k];
+					const aqk = a[q][k];
+					a[p][k] = c * apk - s * aqk;
+					a[q][k] = s * apk + c * aqk;
+				}
+				for (let k = 0; k < 4; k += 1) {
+					const vkp = v[k][p];
+					const vkq = v[k][q];
+					v[k][p] = c * vkp - s * vkq;
+					v[k][q] = s * vkp + c * vkq;
+				}
+			}
+		}
+	}
+	let best = 0;
+	for (let i = 1; i < 4; i += 1) if (a[i][i] > a[best][best]) best = i;
+	return [v[0][best], v[1][best], v[2][best], v[3][best]];
+}
+
+/**
+ * Similarity Procrustes (Horn's quaternion method, proper rotation only):
+ * scale, R, t minimising sum |s R src_i + t - dst_i|^2.
+ * Returns { scale, R (row-major 3x3), t, aligned }.
+ */
+export function similarityAlign(src, dst, { allowScale = true } = {}) {
+	if (src.length !== dst.length || !src.length) throw new Error("similarityAlign needs paired, non-empty point sets");
+	const cs = centroid(src);
+	const cd = centroid(dst);
+	const S = [[0, 0, 0], [0, 0, 0], [0, 0, 0]];
+	let srcNorm = 0;
+	for (let i = 0; i < src.length; i += 1) {
+		const a = sub(src[i], cs);
+		const b = sub(dst[i], cd);
+		srcNorm += a[0] * a[0] + a[1] * a[1] + a[2] * a[2];
+		for (let r = 0; r < 3; r += 1) for (let c = 0; c < 3; c += 1) S[r][c] += a[r] * b[c];
+	}
+	const [[xx, xy, xz], [yx, yy, yz], [zx, zy, zz]] = S;
+	const N = [
+		[xx + yy + zz, yz - zy, zx - xz, xy - yx],
+		[yz - zy, xx - yy - zz, xy + yx, zx + xz],
+		[zx - xz, xy + yx, -xx + yy - zz, yz + zy],
+		[xy - yx, zx + xz, yz + zy, -xx - yy + zz],
+	];
+	const [w, x, y, z] = dominantEigenvector4(N);
+	const n = Math.hypot(w, x, y, z) || 1;
+	const q = [w / n, x / n, y / n, z / n];
+	const R = [
+		1 - 2 * (q[2] * q[2] + q[3] * q[3]), 2 * (q[1] * q[2] - q[0] * q[3]), 2 * (q[1] * q[3] + q[0] * q[2]),
+		2 * (q[1] * q[2] + q[0] * q[3]), 1 - 2 * (q[1] * q[1] + q[3] * q[3]), 2 * (q[2] * q[3] - q[0] * q[1]),
+		2 * (q[1] * q[3] - q[0] * q[2]), 2 * (q[2] * q[3] + q[0] * q[1]), 1 - 2 * (q[1] * q[1] + q[2] * q[2]),
+	];
+	const rot = (p) => [R[0] * p[0] + R[1] * p[1] + R[2] * p[2], R[3] * p[0] + R[4] * p[1] + R[5] * p[2], R[6] * p[0] + R[7] * p[1] + R[8] * p[2]];
+	let dot = 0;
+	for (let i = 0; i < src.length; i += 1) {
+		const ra = rot(sub(src[i], cs));
+		const b = sub(dst[i], cd);
+		dot += ra[0] * b[0] + ra[1] * b[1] + ra[2] * b[2];
+	}
+	const scale = allowScale && srcNorm > 0 ? dot / srcNorm : 1;
+	const rcs = rot(cs);
+	const t = [cd[0] - scale * rcs[0], cd[1] - scale * rcs[1], cd[2] - scale * rcs[2]];
+	const aligned = src.map((p) => {
+		const r = rot(p);
+		return [scale * r[0] + t[0], scale * r[1] + t[1], scale * r[2] + t[2]];
+	});
+	return { scale, R, t, aligned };
+}
+
+/** Mean per-joint Euclidean error of two paired joint sets. */
+export function meanJointError(pred, gt) {
+	if (pred.length !== gt.length || !pred.length) throw new Error("meanJointError needs paired, non-empty joint sets");
+	let total = 0;
+	for (let i = 0; i < pred.length; i += 1) total += dist(pred[i], gt[i]);
+	return total / pred.length;
+}
+
+/** MPJPE after subtracting each set's own root joint. */
+export function rootRelativeError(pred, gt, rootIndex = 0) {
+	const pr = pred[rootIndex];
+	const gr = gt[rootIndex];
+	return meanJointError(pred.map((p) => sub(p, pr)), gt.map((g) => sub(g, gr)));
+}
+
+/** MPJPE after per-frame similarity Procrustes of pred onto gt. */
+export function procrustesError(pred, gt) {
+	return meanJointError(similarityAlign(pred, gt).aligned, gt);
+}
+
+/** Per-frame position errors of two paired trajectories, summarised. */
+export function trajectoryError(pred, gt) {
+	if (pred.length !== gt.length || !pred.length) throw new Error("trajectoryError needs paired, non-empty trajectories");
+	const errors = pred.map((p, i) => dist(p, gt[i]));
+	const mean = errors.reduce((a, b) => a + b, 0) / errors.length;
+	const rmse = Math.sqrt(errors.reduce((a, b) => a + b * b, 0) / errors.length);
+	return { errors, mean, rmse, max: Math.max(...errors), final: errors[errors.length - 1] };
+}
+
+/** Summed ground-plane (XZ) step length of a trajectory. */
+export function pathLengthXZ(points) {
+	let total = 0;
+	for (let i = 1; i < points.length; i += 1) total += Math.hypot(points[i][0] - points[i - 1][0], points[i][2] - points[i - 1][2]);
+	return total;
+}
+
+/** Ground-plane (XZ) distance from the first to the last point. */
+export function displacementXZ(points) {
+	const a = points[0];
+	const b = points[points.length - 1];
+	return Math.hypot(b[0] - a[0], b[2] - a[2]);
+}
+
+/** pred / gt, or null when gt is 0 (a ratio of nothing is not a number). */
+export function ratio(pred, gt) {
+	return gt > 0 ? pred / gt : null;
+}
+
+/**
+ * Intersection over union of two 8-bit masks (pixel set where value >=
+ * threshold). Two empty masks agree perfectly: IoU 1.
+ */
+export function maskIoU(a, b, threshold = 128) {
+	if (a.length !== b.length) throw new Error(`maskIoU: mask sizes differ (${a.length} vs ${b.length})`);
+	let intersection = 0;
+	let union = 0;
+	for (let i = 0; i < a.length; i += 1) {
+		const x = a[i] >= threshold;
+		const y = b[i] >= threshold;
+		if (x && y) intersection += 1;
+		if (x || y) union += 1;
+	}
+	return { iou: union ? intersection / union : 1, intersection, union };
+}
+
+/**
+ * Signed distance of every point of a flat [x0, y0, z0, ...] array to an
+ * axis-aligned box { min: [x, y, z], max: [x, y, z] }: positive outside
+ * (Euclidean distance to the box), negative inside (minus the distance to
+ * the nearest face). Reduced to the minimum and the count inside.
+ *
+ * Self-contained on purpose (no outer references): render.mjs injects its
+ * source into the Studio page with Function.prototype.toString.
+ */
+export function boxContactValues(points, box) {
+	const [x0, y0, z0] = box.min;
+	const [x1, y1, z1] = box.max;
+	let minSigned = Infinity;
+	let closest = -1;
+	let inside = 0;
+	const count = Math.floor(points.length / 3);
+	for (let i = 0; i < count; i += 1) {
+		const x = points[i * 3];
+		const y = points[i * 3 + 1];
+		const z = points[i * 3 + 2];
+		const dx = Math.max(x0 - x, x - x1);
+		const dy = Math.max(y0 - y, y - y1);
+		const dz = Math.max(z0 - z, z - z1);
+		let signed;
+		if (dx <= 0 && dy <= 0 && dz <= 0) {
+			signed = Math.max(dx, dy, dz);
+			inside += 1;
+		} else {
+			signed = Math.hypot(Math.max(dx, 0), Math.max(dy, 0), Math.max(dz, 0));
+		}
+		if (signed < minSigned) {
+			minSigned = signed;
+			closest = i;
+		}
+	}
+	return { minSignedDistance: minSigned, closestIndex: closest, insideCount: inside, count };
+}
+
+/** Contact summary of one frame: closest approach (0 when touching or
+ * inside) and deepest penetration (0 when nothing is inside). */
+export function contactFromSigned(minSignedDistance) {
+	return { minDistanceM: Math.max(0, minSignedDistance), maxPenetrationM: Math.max(0, -minSignedDistance) };
+}
+
+/** Validate a box given as { min: [x,y,z], max: [x,y,z] }. */
+export function parseBox(value) {
+	const box = typeof value === "string" ? JSON.parse(value) : value;
+	const ok = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+	if (!box || !ok(box.min) || !ok(box.max)) throw new Error("box must be {\"min\":[x,y,z],\"max\":[x,y,z]} in scene metres");
+	if (box.min.some((v, i) => v > box.max[i])) throw new Error("box min must not exceed max on any axis");
+	return { min: box.min.slice(), max: box.max.slice() };
+}
+
+/**
+ * Map every GT timeline frame to the nearest-in-time pred frame. A GT frame
+ * whose time lies past the pred's last frame (by more than half a pred frame)
+ * is not scored. Returns { predIndex: (number|null)[], scored, dropped }.
+ */
+export function resampleToTimeline({ gtFrames, gtFps, predFrames, predFps }) {
+	if (!(gtFps > 0) || !(predFps > 0)) throw new Error("resampleToTimeline needs positive frame rates");
+	const predIndex = [];
+	let scored = 0;
+	for (let i = 0; i < gtFrames; i += 1) {
+		const k = Math.round((i / gtFps) * predFps);
+		if (k <= predFrames - 1) {
+			predIndex.push(k);
+			scored += 1;
+		} else {
+			predIndex.push(null);
+		}
+	}
+	return { predIndex, scored, dropped: gtFrames - scored, exact: gtFps === predFps && gtFrames === predFrames };
+}
+
+/**
+ * The scene calibration (Studio sceneCalibration semantics: yaw about the
+ * take's anchor A, then offset) that equals applying G(p) = rotateYaw(p, g.yaw)
+ * + [g.tx, 0, g.tz] after an existing calibration { yawDeg, offsetX, offsetZ }:
+ *   G(A + o + Ry(psi)(U - A)) = A + o' + Ry(psi + theta)(U - A),
+ *   o' = Ry(theta)(A + o) + t - A.
+ */
+export function composeCalibration(calibration, anchor, g) {
+	const base = [anchor.x + (calibration.offsetX ?? 0), 0, anchor.z + (calibration.offsetZ ?? 0)];
+	const moved = applyYawTranslation(base, g);
+	return {
+		...calibration,
+		yawDeg: (calibration.yawDeg ?? 0) + g.yawDeg,
+		offsetX: moved[0] - anchor.x,
+		offsetZ: moved[2] - anchor.z,
+	};
+}
+
+export function mean(values) {
+	const finite = values.filter((v) => v !== null && Number.isFinite(v));
+	return finite.length ? finite.reduce((a, b) => a + b, 0) / finite.length : null;
+}

package/tools/bench/obs/depth.mjs

@@ -0,0 +1,258 @@
+const COCO_TO_SMPL = [
+	[5, 16], [6, 17], [7, 18], [8, 19], [9, 20], [10, 21],
+	[11, 1], [12, 2], [13, 4], [14, 5], [15, 7], [16, 8],
+];
+
+const DEFAULT_MIN_CONF = 0.3;
+const DEFAULT_SIGMA = 2;
+const EPSILON = 1e-10;
+
+function valuesOf(value) {
+	return value?.data ?? value;
+}
+
+function shapeOf(value) {
+	return value?.shape ? Array.from(value.shape) : null;
+}
+
+function flatValues(value, name) {
+	const data = valuesOf(value);
+	if (ArrayBuffer.isView(data) || Array.isArray(data)) return data;
+	throw new TypeError(`${name}: expected an array or a shaped array`);
+}
+
+function frameRows(value, frames, width, components, name) {
+	const shape = shapeOf(value);
+	const data = flatValues(value, name);
+	if (shape) {
+		const expected = [frames, width, components];
+		if (shape.length !== 3 || shape.some((n, i) => n !== expected[i])) {
+			throw new Error(`${name}: expected shape [${expected.join(", ")}]`);
+		}
+	}
+	if (Array.isArray(data) && data.length === frames && data.every(row => Array.isArray(row))) {
+		return data.map((row, frame) => {
+			if (row.length !== width || row.some(point => !Array.isArray(point) && !ArrayBuffer.isView(point))) {
+				throw new Error(`${name}[${frame}]: expected [${width}, ${components}]`);
+			}
+			return row.map((point, index) => {
+				if (point.length !== components) throw new Error(`${name}[${frame}][${index}]: expected ${components} values`);
+				return Array.from(point, Number);
+			});
+		});
+	}
+	if (data.length !== frames * width * components) {
+		throw new Error(`${name}: expected ${frames * width * components} values`);
+	}
+	return Array.from({ length: frames }, (_, frame) => Array.from({ length: width }, (_, index) => {
+			const offset = (frame * width + index) * components;
+			return Array.from(data.slice(offset, offset + components), Number);
+		}));
+}
+
+function vectorFrames(value, frames, width, name) {
+	const shape = shapeOf(value);
+	const data = flatValues(value, name);
+	if (shape) {
+		const expected = [frames, width];
+		if (shape.length !== 2 || shape.some((n, i) => n !== expected[i])) {
+			throw new Error(`${name}: expected shape [${expected.join(", ")}]`);
+		}
+	}
+	if (Array.isArray(data) && data.length === frames && data.every(row => Array.isArray(row) || ArrayBuffer.isView(row))) {
+		return data.map((row, frame) => {
+			if (row.length !== width) throw new Error(`${name}[${frame}]: expected ${width} values`);
+			return Array.from(row, Number);
+		});
+	}
+	if (data.length !== frames * width) throw new Error(`${name}: expected ${frames * width} values`);
+	return Array.from({ length: frames }, (_, frame) => Array.from(data.slice(frame * width, (frame + 1) * width), Number));
+}
+
+function matrix3(K) {
+	const data = valuesOf(K);
+	const shape = shapeOf(K);
+	if (shape && (shape.length !== 2 || shape[0] !== 3 || shape[1] !== 3)) throw new Error("K: expected shape [3, 3]");
+	const matrix = Array.isArray(data) && data.length === 3 && data.every(row => Array.isArray(row) || ArrayBuffer.isView(row))
+		? data.map(row => Array.from(row, Number))
+		: data?.length === 9 ? Array.from({ length: 3 }, (_, row) => Array.from(data.slice(row * 3, row * 3 + 3), Number)) : null;
+	if (!matrix || matrix.some(row => row.length !== 3 || row.some(value => !Number.isFinite(value)))) throw new Error("K: expected a finite 3x3 matrix");
+	if (!(Math.abs(matrix[0][0]) > EPSILON) || !(Math.abs(matrix[1][1]) > EPSILON)) throw new Error("K: fx and fy must be nonzero");
+	return matrix;
+}
+
+function finiteVector(value, fallback = [0, 0, 0]) {
+	return (Array.isArray(value) || ArrayBuffer.isView(value)) && value.length === 3 && Array.from(value).every(Number.isFinite)
+		? Array.from(value, Number) : fallback.slice();
+}
+
+function addNormal(normal, rhs, row, target, weight) {
+	for (let i = 0; i < 3; i++) {
+		for (let j = 0; j < 3; j++) normal[i][j] += weight * row[i] * row[j];
+		rhs[i] += weight * row[i] * target;
+	}
+}
+
+function solve3(normal, rhs) {
+	const a = normal.map((row, i) => [...row, rhs[i]]);
+	for (let column = 0; column < 3; column++) {
+		let pivot = column;
+		for (let row = column + 1; row < 3; row++) {
+			if (Math.abs(a[row][column]) > Math.abs(a[pivot][column])) pivot = row;
+		}
+		if (Math.abs(a[pivot][column]) <= EPSILON) return null;
+		[a[column], a[pivot]] = [a[pivot], a[column]];
+		for (let row = column + 1; row < 3; row++) {
+			const scale = a[row][column] / a[column][column];
+			for (let col = column; col < 4; col++) a[row][col] -= scale * a[column][col];
+		}
+	}
+	const answer = [0, 0, 0];
+	for (let row = 2; row >= 0; row--) {
+		let value = a[row][3];
+		for (let col = row + 1; col < 3; col++) value -= a[row][col] * answer[col];
+		answer[row] = value / a[row][row];
+	}
+	return answer.every(Number.isFinite) ? answer : null;
+}
+
+function observations(joints, keypoints, K, minConf) {
+	const fx = K[0][0], fy = K[1][1], cx = K[0][2], cy = K[1][2];
+	return COCO_TO_SMPL.flatMap(([coco, smpl]) => {
+		const point = keypoints[coco], joint = joints[smpl];
+		if (!point || !joint || point.length < 3 || joint.length < 3) return [];
+		const confidence = Number(point[2]);
+		if (!(confidence >= minConf) || !joint.every(Number.isFinite) || !point.slice(0, 2).every(Number.isFinite)) return [];
+		return [{ X: joint[0], Y: joint[1], Z: joint[2], u: point[0], v: point[1], confidence }];
+	});
+}
+
+function linearTranslation(items, K) {
+	const fx = K[0][0], fy = K[1][1], cx = K[0][2], cy = K[1][2];
+	const normal = Array.from({ length: 3 }, () => [0, 0, 0]);
+	const rhs = [0, 0, 0];
+	for (const item of items) {
+		const weight = item.confidence;
+		// fx*(X+tx) + (cx-u)*(Z+tz) = 0, and the equivalent y equation.
+		addNormal(normal, rhs, [fx, 0, cx - item.u], item.u * item.Z - fx * item.X, weight);
+		addNormal(normal, rhs, [0, fy, cy - item.v], item.v * item.Z - fy * item.Y, weight);
+	}
+	return solve3(normal, rhs);
+}
+
+function refineTranslation(start, items, K, iterations = 5) {
+	const fx = K[0][0], fy = K[1][1];
+	const translation = start.slice();
+	for (let iteration = 0; iteration < iterations; iteration++) {
+		const normal = Array.from({ length: 3 }, () => [0, 0, 0]);
+		const rhs = [0, 0, 0];
+		let rows = 0;
+		for (const item of items) {
+			const x = item.X + translation[0], y = item.Y + translation[1], z = item.Z + translation[2];
+			if (!(z > EPSILON)) continue;
+			const u = fx * x / z + K[0][2], v = fy * y / z + K[1][2];
+			const du = u - item.u, dv = v - item.v;
+			const ju = [fx / z, 0, -fx * x / (z * z)];
+			const jv = [0, fy / z, -fy * y / (z * z)];
+			addNormal(normal, rhs, ju, -du, item.confidence);
+			addNormal(normal, rhs, jv, -dv, item.confidence);
+			rows += 2;
+		}
+		if (rows < 3) break;
+		const delta = solve3(normal, rhs);
+		if (!delta) break;
+		translation[0] += delta[0];
+		translation[1] += delta[1];
+		translation[2] += delta[2];
+		if (Math.hypot(...delta) < 1e-8) break;
+	}
+	return translation;
+}
+
+function residual(translation, items, K) {
+	let error = 0;
+	let weight = 0;
+	for (const item of items) {
+		const z = item.Z + translation[2];
+		if (!(z > EPSILON)) continue;
+		const u = K[0][0] * (item.X + translation[0]) / z + K[0][2];
+		const v = K[1][1] * (item.Y + translation[1]) / z + K[1][2];
+		error += item.confidence * ((u - item.u) ** 2 + (v - item.v) ** 2);
+		weight += item.confidence;
+	}
+	return weight > 0 ? Math.sqrt(error / weight) : Infinity;
+}
+
+function gaussianSmooth(translations, sigma) {
+	if (!(sigma > 0) || translations.length < 2) return translations.map(translation => translation.slice());
+	const radius = Math.ceil(3 * sigma);
+	return translations.map((_, frame) => {
+		const out = [0, 0, 0];
+		let total = 0;
+		for (let other = Math.max(0, frame - radius); other <= Math.min(translations.length - 1, frame + radius); other++) {
+			const distance = other - frame;
+			const weight = Math.exp(-(distance * distance) / (2 * sigma * sigma));
+			total += weight;
+			for (let axis = 0; axis < 3; axis++) out[axis] += weight * translations[other][axis];
+		}
+		return out.map(value => value / total);
+	});
+}
+
+function guardJumps(translations, maxJump) {
+	if (!(maxJump > 0) || !Number.isFinite(maxJump)) return translations;
+	const guarded = [];
+	for (const translation of translations) {
+		if (!guarded.length) {
+			guarded.push(translation.slice());
+			continue;
+		}
+		const previous = guarded.at(-1);
+		const delta = translation.map((value, axis) => value - previous[axis]);
+		const distance = Math.hypot(...delta);
+		if (distance <= maxJump) guarded.push(translation.slice());
+		else {
+			const scale = maxJump / distance;
+			guarded.push(previous.map((value, axis) => value + delta[axis] * scale));
+		}
+	}
+	return guarded;
+}
+
+/**
+ * Recover per-frame camera translation from known-size, root-relative SMPL-X
+ * joints and COCO-17 observations. `incamTransl` is accepted as the fallback
+ * translation because the root-relative joints alone do not contain one.
+ */
+export function solveTranslations({ jointsRel, kp2d, K, minConf = DEFAULT_MIN_CONF, sigma = DEFAULT_SIGMA, incamTransl, maxJump = Infinity } = {}) {
+	const keypointData = flatValues(kp2d, "kp2d");
+	const keypointShape = shapeOf(kp2d);
+	const frames = keypointShape?.[0] ?? (Array.isArray(keypointData) && keypointData.every(row => Array.isArray(row) || ArrayBuffer.isView(row)) ? keypointData.length : Math.floor(keypointData.length / (17 * 3)));
+	if (!Number.isInteger(frames) || frames < 1) throw new Error("kp2d: expected at least one frame");
+	const joints = frameRows(jointsRel, frames, 22, 3, "jointsRel");
+	const keypoints = frameRows(kp2d, frames, 17, 3, "kp2d");
+	const intrinsics = matrix3(K);
+	if (!(Number.isFinite(minConf) && minConf >= 0)) throw new Error("minConf: expected a nonnegative number");
+	if (!(Number.isFinite(sigma) && sigma >= 0)) throw new Error("sigma: expected a nonnegative number");
+	const fallback = incamTransl === undefined
+		? Array.from({ length: frames }, () => [0, 0, 0])
+		: vectorFrames(incamTransl, frames, 3, "incamTransl");
+	const rawTranslations = [];
+	const flags = [];
+	const frameItems = [];
+	for (let frame = 0; frame < frames; frame++) {
+		const items = observations(joints[frame], keypoints[frame], intrinsics, minConf);
+		let translation = items.length >= 4 ? linearTranslation(items, intrinsics) : null;
+		const usedFallback = items.length < 4 || !translation;
+		if (usedFallback) translation = finiteVector(fallback[frame]);
+		else translation = refineTranslation(translation, items, intrinsics);
+		rawTranslations.push(translation);
+		flags.push(usedFallback);
+		frameItems.push(items);
+	}
+	const translations = guardJumps(gaussianSmooth(rawTranslations, sigma), maxJump);
+	const residualPx = translations.map((translation, frame) => residual(translation, frameItems[frame], intrinsics));
+	return { transl: translations, flags, residualPx };
+}
+
+export { COCO_TO_SMPL };