cozyclay 2.1.0 → 3.0.0

package/tools/track/py/track.py

@@ -1,411 +0,0 @@
-#!/usr/bin/env python3
-"""Known-character whole-clip fit in the initializer's Studio world frame.
-
-Calibration travels with camera.json as tracker.{deltaPx,cameraFixed,endpoints}.
-Endpoints, when supplied, are {a:{rotMats,rootPos}, b:{rotMats,rootPos}} in that
-same frame. No re-anchoring or endpoint fabrication occurs at this boundary.
-Exit 0: motion and diagnostics; exit 3: failed fit, diagnostics only;
-exit 2: malformed input, diagnostics only. --iterations 0 is an exact NPZ
-round-trip for coordinate-contract QA, not an optimized-fit acceptance test.
-"""
-from __future__ import annotations
-
-import os
-os.environ.setdefault('CUBLAS_WORKSPACE_CONFIG', ':4096:8')
-
-import argparse
-import json
-from pathlib import Path
-import random
-import sys
-import time
-
-import cv2
-import numpy as np
-import torch
-
-from lr_viterbi import STATE_NAMES, solve_lr_viterbi
-from objective import (ABLATIONS, COCO_JOINTS, ClipObjective, MaskEvidence,
-                       project, slice_boxes)
-from rig import RigError, State, cskel27_fk, load_rig
-from scene import (SceneError, box_tensors, foot_points, load_scene,
-                   penetration_stats, ray_occlusion, stance_hmm)
-
-SCHEDULE = (('root', 150, 1e-2, 10), ('pose', 300, 5e-3, 10), ('refine', 200, 1e-3, 30))
-MAX_RESERVED_MIB = 5632
-
-
-class TrackError(ValueError):
-    def __init__(self, code, detail):
-        super().__init__(f'{code}: {detail}')
-        self.code = code
-
-
-def finite_array(value, shape, label):
-    a = np.asarray(value, dtype=np.float32)
-    if a.shape != shape or not np.isfinite(a).all():
-        raise TrackError('bad-input', f'{label}: expected finite {shape}, got {a.shape}')
-    return a
-
-
-def read_inputs(args):
-    with np.load(args.obs, allow_pickle=False) as z:
-        kp = np.asarray(z['kp2d'], dtype=np.float32)
-        if kp.ndim != 3 or kp.shape[1:] != (17, 3) or len(kp) < 1:
-            raise TrackError('bad-input', 'kp2d must be nonempty T x 17 x 3')
-        frames = len(kp)
-        finite_array(kp[..., :2], (frames, 17, 2), 'kp2d coordinates')
-        # ViTPose confidence is the raw (flip-averaged) heatmap peak, a Gaussian
-        # regression target of height 1, not a probability: it can overshoot 1.
-        # Only the weight is repaired; coordinates stay strictly validated.
-        conf = kp[..., 2]
-        finite = np.isfinite(conf)
-        sanitized = {'input.confidenceNonFinite': int((~finite).sum()),
-                     'input.confidenceAboveOne': int((finite & (conf > 1)).sum()),
-                     'input.confidenceBelowZero': int((finite & (conf < 0)).sum())}
-        kp[..., 2] = np.clip(np.where(finite, conf, 0), 0, 1)
-        fps = float(np.asarray(z['fps']).item())
-        if not np.isfinite(fps) or fps <= 0 or not fps.is_integer():
-            raise TrackError('bad-input', 'fps must be a positive integer')
-        finite_array(z['K'], (3, 3), 'obs.K')
-        bbx = finite_array(z['bbx_xys'], (frames, 3), 'bbx_xys')
-        if (bbx[:, 2] <= 0).any():
-            raise TrackError('bad-input', 'bbx size must be positive')
-    with np.load(args.init, allow_pickle=False) as z:
-        motion = {k: z[k].copy() for k in z.files}
-    finite_array(motion['local_rot_mats'], (frames, 27, 3, 3), 'local_rot_mats')
-    finite_array(motion['root_positions'], (frames, 3), 'root_positions')
-    finite_array(motion['posed_joints'], (frames, 27, 3), 'posed_joints')
-    rot = motion['local_rot_mats']
-    if not np.allclose(rot.swapaxes(-1, -2) @ rot, np.eye(3), atol=1e-3) or (np.linalg.det(rot) < 0.99).any():
-        raise TrackError('bad-input', 'local_rot_mats must lie on SO(3)')
-    bone_scale = motion.get('bone_scale')
-    if bone_scale is not None:
-        finite_array(bone_scale, (27,), 'bone_scale')
-        if (bone_scale <= 0).any():
-            raise TrackError('bad-input', 'bone_scale must be positive')
-    camera = json.loads(Path(args.camera).read_text())
-    K = finite_array(camera['K'], (3, 3), 'camera.K')
-    w = finite_array(camera['worldToCamera'], (4, 4), 'worldToCamera')
-    if not np.allclose(w[3], [0, 0, 0, 1]) or not np.allclose(w[:3, :3].T @ w[:3, :3], np.eye(3), atol=1e-5):
-        raise TrackError('bad-input', 'camera extrinsics must be rigid')
-    if K[0, 0] <= 0 or K[1, 1] <= 0:
-        raise TrackError('bad-input', 'camera focal length must be positive')
-    width, height = camera['width'], camera['height']
-    if not isinstance(width, int) or not isinstance(height, int) or min(width, height) < 4:
-        raise TrackError('bad-input', 'camera dimensions must be positive integers >=4')
-    config = camera.get('tracker', {})
-    delta = args.delta_px if args.delta_px is not None else config.get('deltaPx', 5.708)
-    if not isinstance(delta, (int, float)) or not np.isfinite(delta) or delta <= 0:
-        raise TrackError('bad-input', 'deltaPx must be finite and positive')
-    fixed = config.get('cameraFixed', True)
-    if not isinstance(fixed, bool):
-        raise TrackError('bad-input', 'cameraFixed must be boolean')
-    with np.load(args.masks, allow_pickle=False) as z:
-        prob = finite_array(z['prob'], (frames, height // 2, width // 2), 'prob')
-    if ((prob < 0) | (prob > 1)).any():
-        raise TrackError('bad-input', 'mask probabilities must lie in [0,1]')
-    if not Path(args.video).is_file():
-        raise TrackError('bad-input', 'video file does not exist')
-    endpoints = {}
-    ep = config.get('endpoints', {})
-    if not isinstance(ep, dict):
-        raise TrackError('bad-input', 'endpoints must be an object with a and/or b')
-    for name, frame in [('a', 0), ('b', frames - 1)]:
-        if name in ep:
-            e = ep[name]
-            endpoints[frame] = (finite_array(e['rootPos'], (3,), f'{name}.rootPos'),
-                                finite_array(np.asarray(e['rotMats']).reshape(27, 3, 3), (27, 3, 3), f'{name}.rotMats'))
-    kp[:, :5, 2] = 0
-    return kp, fps, motion, bone_scale, camera, prob, delta, fixed, endpoints, sanitized
-
-
-def blank_diagnostics(frames=1, fps=24):
-    return dict(version=1, frames=frames, fps=fps,
-                occluded=[[False] * 27 for _ in range(frames)],
-                lrState=['identity'] * frames, lrMargin=[0.0] * frames,
-                ambiguous=[True] * frames,
-                stance=dict(left=[False] * frames, right=[False] * frames),
-                penetration=dict(maxBoxCm=0.0, maxFloorCm=0.0, frames=[]),
-                nuisance=dict(scale=1.0, cameraDeltaDeg=[0.0, 0.0], fovDeltaPct=0.0),
-                stageLosses={}, runtime=dict(trackerSeconds=0.0, peakReservedMiB=0.0), failure=None)
-
-
-def windows(frames):
-    if frames <= 240:
-        return [(0, frames)]
-    out, start = [], 0
-    while start < frames:
-        end = min(start + 120, frames)
-        out.append((start, end))
-        if end == frames:
-            break
-        start = end - 16
-    return out
-
-
-def schedule(iterations):
-    if iterations is None:
-        return SCHEDULE
-    counts = [iterations * 150 // 650, iterations * 450 // 650]
-    lengths = [counts[0], counts[1] - counts[0], iterations - counts[1]]
-    return tuple((name, n, lr, pen) for (name, _, lr, pen), n in zip(SCHEDULE, lengths))
-
-
-def identity_labels(frames):
-    """The detector's own left/right labelling, used when Viterbi is ablated."""
-    return dict(path=np.full(frames, STATE_NAMES.index('identity')),
-                assignments=np.tile(np.arange(17), (frames, 1)),
-                margins=np.zeros(frames), ambiguous=np.zeros(frames, dtype=bool))
-
-
-@torch.no_grad()
-def labels(objective, state, nuisance, kp, start, end):
-    joints, _ = cskel27_fk(state, objective.bone_scale, objective.rig)
-    joints = state.transl[:, None] + (joints - state.transl[:, None]) * (1 + nuisance[0])
-    uv, depth = project(joints[:, COCO_JOINTS], objective.camera, nuisance)
-    # Geometric box occlusion is always reported; the fit uses it only when
-    # the 'occlusion' component is enabled.
-    hidden = ray_occlusion(joints, objective.camera_pos, slice_boxes(objective.boxes, start, end))
-    visible = depth > 0
-    if 'occlusion' in objective.components:
-        visible = ~hidden[:, COCO_JOINTS] & visible
-    if 'viterbi' in objective.components:
-        result = solve_lr_viterbi(kp, uv.cpu().numpy(), visibility=visible.cpu().numpy(), deltaPx=objective.delta)
-    else:
-        result = identity_labels(end - start)
-    assigned = kp[np.arange(end - start)[:, None], result['assignments']]
-    stance = stance_hmm(foot_points(joints).cpu(), objective.fps, slice_boxes(objective.boxes, start, end))
-    return (torch.as_tensor(assigned, device=joints.device),
-            torch.as_tensor(stance, device=joints.device), result, hidden)
-
-
-def optimize(objective, state, nuisance, kp, masks, fixed, iterations, diagnostics, started):
-    frames = len(kp)
-    for stage, steps, lr, pen in schedule(iterations):
-        if not steps:
-            continue
-        # One shared per-clip nuisance tensor, even when trajectories use windows.
-        # A complete stage visits all windows before the next discrete update.
-        chunks = windows(frames)
-        total_steps = steps * len(chunks)
-        print(f'[track] stage {stage} 0/{total_steps}', flush=True)
-        assigned_all, stance_all, _, hidden = labels(objective, state, nuisance, kp, 0, frames)
-        articulation_all = None if stage == 'root' else objective.articulation_observation(
-            state, nuisance, assigned_all)
-        support_all = None
-        if stage != 'root' and 'contacts' in objective.components:
-            support_all = objective.support_observation(state, nuisance, assigned_all, stance_all, hidden)
-            diagnostics['stageLosses'][f'{stage}.supportFootFramesTotal'] = float(support_all[1].sum())
-        for window_index, (start, end) in enumerate(chunks):
-            local = State(*(getattr(state, name)[start:end].detach().clone().requires_grad_(True)
-                            for name in ('transl', 'root6d', 'local6d')))
-            local.local6d.requires_grad_(stage != 'root')
-            objective.masks = masks.window(start, end, state.transl.device)
-            assigned, stance = assigned_all[start:end], stance_all[start:end]
-            support = None if support_all is None else tuple(x[start:end] for x in support_all)
-            articulation = None if articulation_all is None else tuple(x[start:end] for x in articulation_all)
-            params = [local.transl, local.root6d]
-            if stage != 'root':
-                params.append(local.local6d)
-            if not fixed:
-                params.append(nuisance)
-            optimizer = torch.optim.Adam(params, lr=lr)
-            for iteration in range(steps):
-                optimizer.zero_grad(set_to_none=True)
-                trust_weight = 0.0 if stage == 'root' else 0.1
-                if stage == 'refine':
-                    trust_weight *= 1 - iteration / max(1, steps - 1)
-                loss, terms = objective(local, nuisance, start, end, assigned, stance, pen,
-                                        trust_weight, support=support, articulation=articulation)
-                if not torch.isfinite(loss):
-                    raise TrackError('non-finite', 'objective is not finite')
-                loss.backward()
-                if not all(p.grad is not None and torch.isfinite(p.grad).all() for p in params):
-                    raise TrackError('non-finite', 'gradient is not finite')
-                optimizer.step()
-                with torch.no_grad():
-                    nuisance.clamp_(nuisance.new_tensor([-0.1, -2, -2, -2]), nuisance.new_tensor([0.1, 2, 2, 2]))
-                done = window_index * steps + iteration + 1
-                if done % 50 == 0 or iteration == steps - 1:
-                    print(f'[track] stage {stage} {done}/{total_steps}', flush=True)
-                    if time.monotonic() - started > max(300, 1.5 * frames + 120):
-                        raise TrackError('runtime-budget', 'tracker time budget exhausted')
-                    if state.transl.is_cuda and torch.cuda.max_memory_reserved() > MAX_RESERVED_MIB * 1024 ** 2:
-                        raise TrackError('memory-budget', 'reserved memory exceeded 5632 MiB')
-            diagnostics['stageLosses'].update({f'{stage}.{k}': float(v.detach()) for k, v in terms.items()})
-            with torch.no_grad():
-                for name in ('transl', 'root6d', 'local6d'):
-                    destination, source = getattr(state, name), getattr(local, name)
-                    if window_index:
-                        ramp = torch.arange(1, 17, device=source.device, dtype=source.dtype) / 17
-                        ramp = ramp.reshape((16,) + (1,) * (source.ndim - 1))
-                        destination[start:start + 16].lerp_(source[:16], ramp)
-                        destination[start + 16:end].copy_(source[16:])
-                    else:
-                        destination[start:end].copy_(source)
-            print(f'[track] {end} / {frames}', flush=True)
-
-
-def sample_iou(uv, visible, mask):
-    """Non-rendering occupancy estimate for rejection only, not a fitted loss.
-
-    Dense surface point splats with a one-pixel footprint approximate the
-    half-resolution occupied region; this statistic is explicitly named in
-    stageLosses and is not the independent benchmark silhouette score.
-    """
-    h, w = mask.shape
-    image = np.zeros((h, w), np.uint8)
-    xy = np.floor(uv[visible]).astype(np.int64)
-    inside = (xy[:, 0] >= 0) & (xy[:, 0] < w) & (xy[:, 1] >= 0) & (xy[:, 1] < h)
-    xy = xy[inside]
-    image[xy[:, 1], xy[:, 0]] = 1
-    image = cv2.dilate(image, np.ones((3, 3), np.uint8)).astype(bool)
-    union = (image | mask).sum()
-    return float((image & mask).sum() / union) if union else 0.0
-
-
-@torch.no_grad()
-def finish(objective, state, nuisance, kp, masks, diagnostics):
-    joints_out, errors, ious, max_box, max_floor, pen_frames = [], [], [], 0.0, 0.0, []
-    assigned_all, stance, lr, hidden_all = labels(objective, state, nuisance, kp, 0, len(kp))
-    diagnostics['occluded'] = hidden_all.cpu().tolist()
-    diagnostics['lrState'] = [STATE_NAMES[i] for i in lr['path']]
-    diagnostics['lrMargin'] = lr['margins'].tolist()
-    diagnostics['ambiguous'] = lr['ambiguous'].tolist()
-    diagnostics['stance']['left'] = stance[:, 0].cpu().tolist()
-    diagnostics['stance']['right'] = stance[:, 1].cpu().tolist()
-    for start, end in windows(len(kp)):
-        local = State(*(getattr(state, name)[start:end] for name in ('transl', 'root6d', 'local6d')))
-        joints, verts = objective.geometry(local, nuisance)
-        assigned, hidden = assigned_all[start:end], hidden_all[start:end]
-        uv, depth = project(joints[:, COCO_JOINTS], objective.camera, nuisance)
-        active = (~hidden[:, COCO_JOINTS] & (depth > 0) & (assigned[..., 2] > 0)).cpu().numpy()
-        errors.extend((uv - assigned[..., :2]).norm(dim=-1).cpu().numpy()[active].tolist())
-        samples = (verts[:, objective.faces] * objective.bary[None, :, :, None]).sum(-2)
-        pixels, depth = project(samples, objective.camera, nuisance)
-        visible = (~ray_occlusion(samples, objective.camera_pos, slice_boxes(objective.boxes, start, end)) & (depth > 0)).cpu().numpy()
-        pixels = pixels.cpu().numpy() * masks.ratio
-        offset = 0 if start == 0 else 16
-        ious.extend(sample_iou(pixels[t], visible[t], masks.binary[start + t]) for t in range(offset, end - start))
-        joints_out.append(joints[offset:].cpu().numpy())
-        stats = penetration_stats(verts, slice_boxes(objective.boxes, start, end))
-        max_box, max_floor = max(max_box, stats['maxBoxCm']), max(max_floor, stats['maxFloorCm'])
-        pen_frames.extend(start + i for i in stats['frames'])
-    diagnostics['penetration'] = dict(maxBoxCm=max_box, maxFloorCm=max_floor, frames=sorted(set(pen_frames)))
-    diagnostics['stageLosses']['visibleKeypointMedianPx'] = float(np.median(errors)) if errors else 0.0
-    diagnostics['stageLosses']['sampleMaskIoUMean'] = float(np.mean(ious))
-    diagnostics['nuisance'] = dict(scale=1 + float(nuisance[0]), cameraDeltaDeg=nuisance[1:3].cpu().tolist(), fovDeltaPct=float(nuisance[3]))
-    if not errors:
-        diagnostics['failure'] = 'no-evidence'
-    elif np.median(errors) > 3 * objective.delta:
-        diagnostics['failure'] = 'keypoint-residual'
-    elif np.mean(ious) < 0.5:
-        diagnostics['failure'] = 'mask-mismatch'
-    return np.concatenate(joints_out)
-
-
-def run(args):
-    started = time.monotonic()
-    out = Path(args.out)
-    out.mkdir(parents=True, exist_ok=True)
-    # A failed request cannot leave a previous successful motion behind.
-    (out / 'motion.npz').unlink(missing_ok=True)
-    diagnostics = blank_diagnostics()
-    ablation = {f'ablation.{args.track_ablate}': 1.0}
-    diagnostics['stageLosses'].update(ablation)
-    code = 0
-    try:
-        random.seed(0)
-        np.random.seed(0)
-        torch.manual_seed(0)
-        torch.use_deterministic_algorithms(True, warn_only=True)
-        torch.set_num_threads(4)
-        torch.backends.cuda.matmul.allow_tf32 = False
-        torch.backends.cudnn.allow_tf32 = False
-        torch.backends.cudnn.benchmark = False
-        kp, fps, motion, bone_scale, camera, prob, delta, fixed, endpoints, sanitized = read_inputs(args)
-        diagnostics = blank_diagnostics(len(kp), fps)
-        diagnostics['stageLosses'].update(ablation, **sanitized)
-        if any(sanitized.values()):
-            print('[track] sanitized keypoint confidences ' + json.dumps(sanitized), flush=True)
-        if not (kp[..., 2] > 0).any():
-            raise TrackError('no-evidence', 'no confident body observations')
-        device = 'cuda' if torch.cuda.is_available() and args.device != 'cpu' else 'cpu'
-        if args.device == 'cuda' and device != 'cuda':
-            raise TrackError('device-unavailable', 'CUDA requested but unavailable')
-        if device == 'cuda':
-            torch.cuda.empty_cache()
-            torch.cuda.reset_peak_memory_stats()
-            torch.cuda.set_per_process_memory_fraction(MAX_RESERVED_MIB * 1024 ** 2 / torch.cuda.get_device_properties(0).total_memory)
-        rig = load_rig(args.rig, device=device)
-        state = State.from_motion(motion['local_rot_mats'], motion['root_positions'], device=device)
-        boxes = box_tensors(load_scene(args.scene), len(kp), device=device)
-        masks = MaskEvidence(prob, camera['width'], camera['height'])
-        endpoints = {t: tuple(torch.as_tensor(p, device=device) for p in pose) for t, pose in endpoints.items()}
-        nuisance = torch.zeros(4, device=device, requires_grad=not fixed)
-        objective = ClipObjective(rig, bone_scale, camera, boxes, None, kp, fps, delta, endpoints, state,
-                                  components=ABLATIONS[args.track_ablate])
-        optimize(objective, state, nuisance, kp, masks, fixed, args.iterations, diagnostics, started)
-        posed = finish(objective, state, nuisance, kp, masks, diagnostics)
-        if args.iterations == 0:
-            diagnostics['failure'] = None
-        elif not diagnostics['failure']:
-            motion['local_rot_mats'] = state.local_rot_mats().detach().cpu().numpy().astype(np.float32)
-            motion['root_positions'] = state.transl.cpu().numpy().astype(np.float32)
-            motion['posed_joints'] = posed.astype(np.float32)
-            if float(nuisance[0]) != 0:
-                motion['bone_scale'] = np.asarray(bone_scale if bone_scale is not None else np.ones(27), np.float32) * (1 + float(nuisance[0]))
-        motion['fps'] = np.asarray(int(fps), dtype=np.int32)
-        if not diagnostics['failure']:
-            np.savez(out / 'motion.npz', **motion)
-        else:
-            code = 3
-    except (TrackError, RigError, SceneError) as error:
-        diagnostics['failure'] = error.code
-        code = 3 if error.code in ('no-evidence', 'non-finite', 'runtime-budget', 'memory-budget', 'device-unavailable') else 2
-        print(f'[track] {error}', file=sys.stderr, flush=True)
-    except (OSError, ValueError, KeyError, TypeError) as error:
-        diagnostics['failure'] = 'bad-input'
-        code = 2
-        print(f'[track] bad-input: {error}', file=sys.stderr, flush=True)
-    except torch.cuda.OutOfMemoryError as error:
-        diagnostics['failure'] = 'memory-budget'
-        code = 3
-        print(f'[track] memory-budget: {error}', file=sys.stderr, flush=True)
-    except Exception:
-        # Preserve a failed transaction even for an unexpected dependency bug;
-        # the traceback is surfaced, never converted into a successful report.
-        import traceback
-        diagnostics['failure'] = 'internal-error'
-        code = 3
-        traceback.print_exc()
-    finally:
-        if code:
-            (out / 'motion.npz').unlink(missing_ok=True)
-        if torch.cuda.is_initialized():
-            torch.cuda.synchronize()
-            diagnostics['runtime']['peakReservedMiB'] = torch.cuda.max_memory_reserved() / 1024 ** 2
-        diagnostics['runtime']['trackerSeconds'] = time.monotonic() - started
-        (out / 'diagnostics.json').write_text(json.dumps(diagnostics, allow_nan=False, indent=2) + '\n')
-        print('[track] result ' + json.dumps(dict(failure=diagnostics['failure'], **diagnostics['runtime'])), flush=True)
-    return code
-
-
-def parse_args(argv=None):
-    parser = argparse.ArgumentParser(description=__doc__)
-    for name in ('video', 'obs', 'masks', 'init', 'camera', 'scene', 'rig', 'out'):
-        parser.add_argument('--' + name, required=True)
-    parser.add_argument('--iterations', type=int, default=None)
-    parser.add_argument('--delta-px', type=float)
-    parser.add_argument('--device', choices=('auto', 'cpu', 'cuda'), default='auto')
-    parser.add_argument('--track-ablate', choices=tuple(ABLATIONS), default='full',
-                        help='fit components: kp-only < silhouette < viterbi < contacts < full')
-    args = parser.parse_args(argv)
-    if args.iterations is not None and args.iterations < 0:
-        parser.error('--iterations must be nonnegative')
-    return args
-
-
-if __name__ == '__main__':
-    raise SystemExit(run(parse_args()))

package/tools/track/remote.mjs

@@ -1,140 +0,0 @@
-#!/usr/bin/env node
-/** Remote execution boundary for the known-character tracker. */
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { runBox } from "./run-box.mjs";
-import { trackerBudgetMs } from "./budget.mjs";
-
-/** Parse the two progress formats emitted by track.py. */
-export function parseProgressLine(line) {
-	const text = String(line).trim();
-	let match = /^\[track\]\s+stage\s+(\S+)\s+(\d+)\/(\d+)\s*$/.exec(text);
-	if (match) {
-		const current = Number(match[2]), total = Number(match[3]);
-		return { kind: "stage", stage: match[1], current, total, fraction: total > 0 ? current / total : 0 };
-	}
-	match = /^\[track\]\s+(\d+)\s*\/\s*(\d+)\s*$/.exec(text);
-	if (match) {
-		const current = Number(match[1]), total = Number(match[2]);
-		return { kind: "frame", current, total, fraction: total > 0 ? current / total : 0 };
-	}
-	return null;
-}
-
-/** track.py --track-ablate levels, cumulative from kp-only to full (the default fit). */
-export const TRACK_ABLATIONS = Object.freeze(["kp-only", "silhouette", "viterbi", "contacts", "full"]);
-
-export const trackerInputNames = Object.freeze(["video", "obs", "masks", "init", "camera", "scene", "rig"]);
-export function trackerUploadPlan({ video, obsPath, masksPath, initMotionPath, cameraPath, scenePath, rigPath } = {}) {
-	return Object.fromEntries(Object.entries({ video, obs: obsPath, masks: masksPath, init: initMotionPath, camera: cameraPath, scene: scenePath, rig: rigPath }));
-}
-
-function requiredFile(path, name) {
-	if (typeof path !== "string" || !path) throw new Error(`${name}: path is required`);
-	return path;
-}
-function lineParser(onLine, progress) {
-	return (text) => {
-		const parsed = parseProgressLine(text);
-		if (parsed) progress.push(parsed);
-		onLine?.(text, parsed);
-	};
-}
-function withTimeout(promise, timeoutMs) {
-	let timer;
-	const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`tracker timeout after ${timeoutMs} ms`)), timeoutMs); });
-	return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-/**
- * Delegate all transfer and remote execution to run-box.mjs. The only
- * caller-owned data transfer entries are the seven declared tracker inputs;
- * run-box separately uploads the Python implementation.
- */
-export async function runTracker({ host, video, obsPath, masksPath, initMotionPath, cameraPath, scenePath, rigPath, outDir, onLine, transport, ablate } = {}) {
-	if (typeof host !== "string" || !host.trim()) throw new Error("host is required");
-	if (ablate !== undefined && !TRACK_ABLATIONS.includes(ablate)) throw new Error(`ablate must be one of ${TRACK_ABLATIONS.join(",")}`);
-	const files = trackerUploadPlan({ video, obsPath, masksPath, initMotionPath, cameraPath, scenePath, rigPath });
-	for (const [name, path] of Object.entries(files)) requiredFile(path, name);
-	if (typeof outDir !== "string" || !outDir) throw new Error("outDir is required");
-	mkdirSync(outDir, { recursive: true });
-	const motionPath = `${outDir}/motion.npz`, diagnosticsPath = `${outDir}/diagnostics.json`;
-	for (const path of [motionPath, diagnosticsPath]) rmSync(path, { force: true });
-	const progress = [];
-	const runner = transport?.runBox ?? runBox;
-	const upload = Object.entries(files).map(([name, localPath]) => ({ localPath, remoteRelPath: name }));
-	const fetch = [
-		{ remoteRelPath: "motion.npz", localPath: motionPath },
-		{ remoteRelPath: "diagnostics.json", localPath: diagnosticsPath },
-	];
-	const frames = await inferFrames(obsPath);
-	const args = [
-		"--video", "video", "--obs", "obs", "--masks", "masks", "--init", "init", "--camera", "camera", "--scene", "scene", "--rig", "rig", "--out", ".",
-		...(ablate === undefined ? [] : ["--track-ablate", ablate]),
-	];
-	try {
-		await withTimeout(Promise.resolve(runner({ entry: "track.py", args, hostName: host, onLine: lineParser(onLine, progress), upload, fetch })), trackerBudgetMs(frames));
-	} catch (error) {
-		// track.py exits 2/3 with diagnostics only; hand them to the caller on the
-		// original error. Unreadable diagnostics never replace that error.
-		if (existsSync(diagnosticsPath)) {
-			try {
-				error.diagnostics = validateDiagnostics(JSON.parse(readFileSync(diagnosticsPath, "utf8")));
-				error.diagnosticsPath = diagnosticsPath;
-			} catch (diagnosticsError) {
-				error.diagnosticsError = diagnosticsError.message;
-			}
-		}
-		error.progress = progress;
-		throw error;
-	}
-	const diagnostics = JSON.parse(readFileSync(diagnosticsPath, "utf8"));
-	validateDiagnostics(diagnostics);
-	return { motionPath, diagnosticsPath, diagnostics, progress };
-}
-
-function finite(value, label) {
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`diagnostics: ${label} must be finite`);
-}
-
-/** Structural validation kept dependency-free because the bench has no schema package. */
-export function validateDiagnostics(value) {
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("diagnostics: expected an object");
-	const required = ["version", "frames", "fps", "occluded", "lrState", "lrMargin", "ambiguous", "stance", "penetration", "nuisance", "stageLosses", "runtime", "failure"];
-	const rootKeys = new Set(required);
-	for (const key of required) if (!(key in value)) throw new Error(`diagnostics: missing ${key}`);
-	for (const key of Object.keys(value)) if (!rootKeys.has(key)) throw new Error(`diagnostics: unknown property ${key}`);
-	if (value.version !== 1 || !Number.isInteger(value.frames) || value.frames < 1) throw new Error("diagnostics: invalid version or frames");
-	finite(value.fps, "fps");
-	if (!(value.fps > 0)) throw new Error("diagnostics: fps must be positive");
-	const arrays = [["occluded", value.occluded], ["lrState", value.lrState], ["lrMargin", value.lrMargin], ["ambiguous", value.ambiguous], ["stance.left", value.stance?.left], ["stance.right", value.stance?.right]];
-	for (const [name, array] of arrays) if (!Array.isArray(array) || array.length !== value.frames) throw new Error(`diagnostics: ${name} must have ${value.frames} frames`);
-	value.occluded.forEach((row, t) => { if (!Array.isArray(row) || row.length !== 27 || row.some(v => typeof v !== "boolean")) throw new Error(`diagnostics: occluded[${t}] must contain 27 booleans`); });
-	value.lrState.forEach((v, t) => { if (typeof v !== "string") throw new Error(`diagnostics: lrState[${t}] must be a string`); });
-	value.lrMargin.forEach((v, t) => finite(v, `lrMargin[${t}]`));
-	value.ambiguous.forEach((v, t) => { if (typeof v !== "boolean") throw new Error(`diagnostics: ambiguous[${t}] must be boolean`); });
-	if (!value.stance || typeof value.stance !== "object" || Object.keys(value.stance).some(key => !["left", "right"].includes(key))) throw new Error("diagnostics: invalid stance");
-	for (const side of ["left", "right"]) value.stance[side].forEach((v, t) => { if (typeof v !== "boolean") throw new Error(`diagnostics: stance.${side}[${t}] must be boolean at ${t}`); });
-	if (!value.penetration || typeof value.penetration !== "object" || Object.keys(value.penetration).some(key => !["maxBoxCm", "maxFloorCm", "frames"].includes(key)) || !Array.isArray(value.penetration.frames)) throw new Error("diagnostics: invalid penetration");
-	finite(value.penetration.maxBoxCm, "penetration.maxBoxCm"); finite(value.penetration.maxFloorCm, "penetration.maxFloorCm");
-	if (value.penetration.maxBoxCm < 0 || value.penetration.maxFloorCm < 0 || value.penetration.frames.some(v => !Number.isInteger(v) || v < 0)) throw new Error("diagnostics: invalid penetration values");
-	if (!value.nuisance || typeof value.nuisance !== "object" || Object.keys(value.nuisance).some(key => !["scale", "cameraDeltaDeg", "fovDeltaPct"].includes(key)) || !Number.isFinite(value.nuisance.scale) || !(value.nuisance.scale > 0) || !Array.isArray(value.nuisance.cameraDeltaDeg) || value.nuisance.cameraDeltaDeg.length !== 2 || value.nuisance.cameraDeltaDeg.some(v => !Number.isFinite(v)) || !Number.isFinite(value.nuisance.fovDeltaPct)) throw new Error("diagnostics: invalid nuisance");
-	if (!value.stageLosses || typeof value.stageLosses !== "object" || Array.isArray(value.stageLosses) || Object.values(value.stageLosses).some(v => !Number.isFinite(v))) throw new Error("diagnostics: invalid stageLosses");
-	if (!value.runtime || typeof value.runtime !== "object" || Object.keys(value.runtime).some(key => !["trackerSeconds", "peakReservedMiB"].includes(key)) || !Number.isFinite(value.runtime.trackerSeconds) || value.runtime.trackerSeconds < 0 || !Number.isFinite(value.runtime.peakReservedMiB) || value.runtime.peakReservedMiB < 0) throw new Error("diagnostics: invalid runtime");
-	if (value.failure !== null && typeof value.failure !== "string") throw new Error("diagnostics: failure must be null or string");
-	return value;
-}
-
-async function inferFrames(path) {
-	try {
-		const { readNpz } = await import("../kimodo/read-npz.mjs");
-		const shape = readNpz(path).kp2d?.shape;
-		if (shape && Number.isInteger(shape[0]) && shape[0] > 0) return shape[0];
-	} catch { /* track.py reports malformed input; retain the safe minimum */ }
-	return 1;
-}
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-	console.error("remote.mjs exports runTracker; call it from the bench or bridge runner");
-	process.exitCode = 2;
-}