cozyclay 1.9.0 → 2.0.0

package/tools/track/py/check_env.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Small, real CUDA/SAM2 smoke test for the CozyFit box environment."""
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+import os
+import sys
+
+
+def version(module_name: str, distribution: str) -> str:
+    importlib.import_module(module_name)
+    return importlib.metadata.version(distribution)
+
+
+def main() -> int:
+    import numpy as np
+    import torch
+
+    print(f"python {sys.version.split()[0]}")
+    print(f"torch {version('torch', 'torch')}")
+    print(f"torchvision {version('torchvision', 'torchvision')}")
+    print(f"numpy {version('numpy', 'numpy')}")
+    print(f"scipy {version('scipy', 'scipy')}")
+    print(f"opencv {version('cv2', 'opencv-python-headless')}")
+    print(f"sam2 {version('sam2', 'SAM-2')}")
+    print(f"fast-simplification {version('fast_simplification', 'fast-simplification')}")
+    print(f"pytest {version('pytest', 'pytest')}")
+    cuda = bool(torch.cuda.is_available())
+    print(f"torch.cuda.is_available() {cuda}")
+    if not cuda:
+        raise RuntimeError("CUDA is unavailable")
+
+    from sam2.build_sam import build_sam2
+    from sam2.sam2_image_predictor import SAM2ImagePredictor
+
+    root = os.path.expanduser("~/cclay-ingest/cozyfit")
+    checkpoint = os.path.join(root, "checkpoints", "sam2.1_hiera_small.pt")
+    config = "configs/sam2.1/sam2.1_hiera_s.yaml"
+    torch.cuda.reset_peak_memory_stats()
+    model = build_sam2(config, checkpoint, device="cuda")
+    predictor = SAM2ImagePredictor(model)
+    frame = np.zeros((480, 832, 3), dtype=np.uint8)
+    predictor.set_image(frame)
+    predictor.predict(
+        point_coords=np.array([[416.0, 240.0]], dtype=np.float32),
+        point_labels=np.array([1], dtype=np.int32),
+        box=np.array([208.0, 120.0, 624.0, 360.0], dtype=np.float32),
+        multimask_output=False,
+    )
+    torch.cuda.synchronize()
+    peak_mb = torch.cuda.max_memory_reserved() / (1024 * 1024)
+    print(f"SAM2 peak VRAM {peak_mb:.1f} MB")
+    if peak_mb >= 3000:
+        raise RuntimeError(f"SAM2 peak VRAM too high: {peak_mb:.1f} MB")
+    print("sam2 ok")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/track/py/eval_lr.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Evaluate Viterbi assignments against the Gate-0 truth-projected labels."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from lr_viterbi import ARM_PAIRS, LEG_PAIRS, solve_lr_viterbi, state_permutation
+
+COCO_TO_RIG = {
+    5: "LeftArm", 6: "RightArm", 7: "LeftForeArm", 8: "RightForeArm",
+    9: "LeftHand", 10: "RightHand", 11: "LeftUpLeg", 12: "RightUpLeg",
+    13: "LeftLeg", 14: "RightLeg", 15: "LeftFoot", 16: "RightFoot",
+}
+BODY = tuple(COCO_TO_RIG)
+
+
+def read_npz(path: Path) -> np.ndarray:
+    with np.load(path, allow_pickle=False) as data:
+        if "kp2d" not in data:
+            raise ValueError(f"{path}: missing kp2d")
+        return np.asarray(data["kp2d"], dtype=np.float64)
+
+
+def _box(scene: dict[str, Any]) -> tuple[np.ndarray, np.ndarray, float]:
+    centre = np.asarray(scene.get("centre", scene.get("center")), dtype=np.float64)
+    half = np.asarray(scene.get("halfExtents"), dtype=np.float64)
+    if centre.shape != (3,) or half.shape != (3,):
+        if "min" not in scene or "max" not in scene:
+            raise ValueError("scene box needs centre/halfExtents or min/max")
+        lo, hi = np.asarray(scene["min"], dtype=np.float64), np.asarray(scene["max"], dtype=np.float64)
+        centre, half = (lo + hi) / 2, (hi - lo) / 2
+    yaw = float(scene.get("yawDeg", 0.0)) * np.pi / 180.0
+    if not np.isfinite(centre).all() or not np.isfinite(half).all() or (half <= 0).any():
+        raise ValueError("scene box has invalid dimensions")
+    return centre, half, yaw
+
+
+def segment_hits_box(origin: np.ndarray, point: np.ndarray, scene: dict[str, Any]) -> bool:
+    centre, half, yaw = _box(scene)
+    c, s = np.cos(yaw), np.sin(yaw)
+
+    def local(p: np.ndarray) -> np.ndarray:
+        q = p - centre
+        return np.array([c * q[0] - s * q[2], q[1], s * q[0] + c * q[2]])
+
+    o, q = local(origin), local(point)
+    enter, exit = -np.inf, np.inf
+    for axis in range(3):
+        d = q[axis] - o[axis]
+        if abs(d) < 1e-12:
+            if abs(o[axis]) > half[axis]:
+                return False
+            continue
+        a, b = (-half[axis] - o[axis]) / d, (half[axis] - o[axis]) / d
+        enter, exit = max(enter, min(a, b)), min(exit, max(a, b))
+    return enter <= exit and exit > 1e-9 and enter < 1 - 1e-9
+
+
+def truth_reference_error(study_item: Any, label: str) -> str | None:
+    """Require todo-4's explicit truth-preferred arm/leg labels."""
+    if not isinstance(study_item, dict):
+        return f"{label}: missing study-2d item"
+    if study_item.get("status") != "ok":
+        return f"{label}: study-2d status is {study_item.get('status')!r}"
+    swaps = study_item.get("swaps")
+    frames = swaps.get("frames") if isinstance(swaps, dict) else None
+    if not isinstance(frames, dict) or not isinstance(frames.get("arms"), list) or not isinstance(frames.get("legs"), list):
+        return f"{label}: missing explicit swaps.frames.arms/legs truth labels"
+    if any(not isinstance(frame, int) or frame < 0 for group in ("arms", "legs") for frame in frames[group]):
+        return f"{label}: malformed truth swap frame labels"
+    return None
+
+
+def expected_assignments(study_item: dict[str, Any], frames: int) -> np.ndarray:
+    """Convert todo-4's per-group truth-preferred swap frames to permutations."""
+    arms = set(study_item.get("swaps", {}).get("frames", {}).get("arms", []))
+    legs = set(study_item.get("swaps", {}).get("frames", {}).get("legs", []))
+    out = np.empty((frames, 17), dtype=np.int64)
+    identity = state_permutation("identity")
+    arm_perm = state_permutation("arms_swap")
+    leg_perm = state_permutation("legs_swap")
+    full_perm = state_permutation("full_swap")
+    for t in range(frames):
+        if t in arms and t in legs:
+            out[t] = full_perm
+        elif t in arms:
+            out[t] = arm_perm
+        elif t in legs:
+            out[t] = leg_perm
+        else:
+            out[t] = identity
+    return out
+
+
+def truth_visibility(item: dict[str, Any], frames: int, joints: dict[str, Any]) -> np.ndarray:
+    visible = np.ones((frames, 17), dtype=bool)
+    if not item.get("scene"):
+        return visible
+    scene = json.loads(Path(item["scene"]).read_text())
+    origin = np.asarray(joints.get("cameraPosition", [0, 0, 0]), dtype=np.float64)
+    if not np.isfinite(origin).all() or np.linalg.norm(origin) == 0:
+        camera_path = Path(item["dir"]) / item["variant"] / "camera.json"
+        camera = json.loads(camera_path.read_text())
+        pos = camera.get("position")
+        if isinstance(pos, dict):
+            origin = np.array([pos["x"], pos["y"], pos["z"]], dtype=np.float64)
+        else:
+            origin = np.asarray(pos, dtype=np.float64)
+    names = [joint["name"] if isinstance(joint, dict) else joint for joint in joints["joints"]]
+    index = {name: i for i, name in enumerate(names)}
+    world = np.asarray(joints["world"], dtype=np.float64)
+    for coco, rig_name in COCO_TO_RIG.items():
+        points = world[:frames, index[rig_name], :]
+        for t, point in enumerate(points):
+            visible[t, coco] = not segment_hits_box(origin, point, scene)
+    return visible
+
+
+def evaluate_item(item: dict[str, Any], study_by_item: dict[str, Any], obs_root: Path, delta_px: float) -> dict[str, Any]:
+    label = f"{item['set']}/{item['name']}"
+    reference = study_by_item.get(label)
+    reference_error = truth_reference_error(reference, label)
+    if reference_error:
+        return {"item": label, "status": "missing-truth-reference", "error": reference_error}
+    obs_path = obs_root / item["set"] / item["name"] / "g5" / "obs.npz"
+    if not obs_path.exists():
+        return {"item": label, "status": "missing-obs", "obsPath": str(obs_path)}
+    variant_dir = Path(item["dir"]) / item["variant"]
+    joints = json.loads((variant_dir / "joints.json").read_text())
+    obs = read_npz(obs_path)
+    if obs.ndim != 3 or obs.shape[1] != 17 or obs.shape[2] < 2:
+        raise ValueError(f"{label}: kp2d has invalid shape {obs.shape}")
+    names = [joint["name"] if isinstance(joint, dict) else joint for joint in joints["joints"]]
+    index = {name: i for i, name in enumerate(names)}
+    uv = np.full((len(joints["world"]), 17, 2), np.nan, dtype=np.float64)
+    for coco, rig_name in COCO_TO_RIG.items():
+        uv[:, coco] = np.asarray(joints["uv"], dtype=np.float64)[: uv.shape[0], index[rig_name], :2]
+    frames = min(obs.shape[0], uv.shape[0])
+    obs, projected = obs[:frames], uv[:frames]
+    visible = truth_visibility(item, frames, joints)
+    result = solve_lr_viterbi(obs, projected, visibility=visible, deltaPx=delta_px)
+    expected = expected_assignments(reference, frames)
+    valid = np.isfinite(obs[..., :2]).all(axis=2) & (obs[..., 2] > 0 if obs.shape[2] >= 3 else True)
+    correct = raw_correct = total = 0
+    # Agreement is deliberately measured only on visible bilateral observations,
+    # never on box-occluded joints or absent detector points.
+    for t in range(frames):
+        for left, right in ARM_PAIRS + LEG_PAIRS:
+            if not (visible[t, left] and visible[t, right]):
+                continue
+            if not (valid[t, left] and valid[t, right]):
+                continue
+            for joint in (left, right):
+                total += 1
+                correct += int(result["assignments"][t, joint] == expected[t, joint])
+                raw_correct += int(joint == expected[t, joint])
+    return {
+        "item": label,
+        "status": "ok",
+        "frames": frames,
+        "deltaPx": delta_px,
+        "agreement": correct / total if total else None,
+        "correct": correct,
+        "rawAgreement": raw_correct / total if total else None,
+        "rawCorrect": raw_correct,
+        "visibleBilateralPairs": total // 2,
+        "visibleBilateralJointLabels": total,
+        "switches": result["switches"],
+        "stateCounts": result["state_counts"],
+        "ambiguousFrames": int(np.count_nonzero(result["ambiguous"])),
+        "medianMargin": float(np.median(result["margins"])) if frames else None,
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    here = Path(__file__).resolve()
+    root = next((parent for parent in here.parents if (parent / "evidence/obs/approved.json").exists()), Path.cwd())
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--summary", type=Path, default=root / "evidence/obs/study-2d/summary.json")
+    parser.add_argument("--approved", type=Path, default=root / "evidence/obs/approved.json")
+    parser.add_argument("--obs-root", type=Path, default=root / "evidence/obs/cache")
+    parser.add_argument("--delta-px", type=float, default=None)
+    parser.add_argument("--out", type=Path, default=None)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    summary = json.loads(args.summary.read_text())
+    delta_px = args.delta_px if args.delta_px is not None else summary.get("deltaPx")
+    if not isinstance(delta_px, (int, float)) or not np.isfinite(delta_px) or delta_px <= 0:
+        raise SystemExit("eval_lr: summary must provide a finite positive deltaPx (or pass --delta-px)")
+    approved = json.loads(args.approved.read_text())
+    study_items = (summary.get("study2d") or {}).get("items", [])
+    study_by_item = {row.get("item"): row for row in study_items if isinstance(row, dict)}
+    truth_items = [item for item in approved["items"] if item.get("set") in {"gt", "cube"}]
+    results = [evaluate_item(item, study_by_item, args.obs_root, float(delta_px)) for item in truth_items]
+    valid = [row for row in results if row["status"] == "ok" and row["agreement"] is not None]
+    total = sum(row["visibleBilateralJointLabels"] for row in valid)
+    correct = sum(row["correct"] for row in valid)
+    raw_correct = sum(row["rawCorrect"] for row in valid)
+    output = {
+        "tool": "tools/track/py/eval_lr.py",
+        "summary": str(args.summary),
+        "deltaPx": float(delta_px),
+        "items": results,
+        "agreement": correct / total if total else None,
+        "correct": correct,
+        "rawAgreement": raw_correct / total if total else None,
+        "rawCorrect": raw_correct,
+        "visibleBilateralJointLabels": total,
+        "itemsOk": len(valid),
+        "itemsTotal": len(results),
+        "pass": bool(len(valid) == len(results) and total and correct / total >= 0.95),
+    }
+    out = args.out or args.summary.with_name("eval-lr.json")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(output, indent=2) + "\n")
+    print(json.dumps(output, indent=2))
+    return 0 if output["pass"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/tools/track/py/lr_viterbi.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""Temporal left/right assignment for COCO-17 observations.
+
+The detector's left/right labels are latent.  This module intentionally knows
+only geometry, confidence, and time; it has no appearance or colour inputs.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+import numpy as np
+
+COCO_NAMES = (
+    "nose", "leftEye", "rightEye", "leftEar", "rightEar",
+    "leftShoulder", "rightShoulder", "leftElbow", "rightElbow",
+    "leftWrist", "rightWrist", "leftHip", "rightHip", "leftKnee",
+    "rightKnee", "leftAnkle", "rightAnkle",
+)
+
+# Pairs are COCO indices.  Face pairs are changed only by the full-swap state.
+ARM_PAIRS = ((5, 6), (7, 8), (9, 10))
+LEG_PAIRS = ((11, 12), (13, 14), (15, 16))
+FACE_PAIRS = ((1, 2), (3, 4))
+BILATERAL_PAIRS = ARM_PAIRS + LEG_PAIRS
+BODY_INDICES = tuple(i for pair in BILATERAL_PAIRS for i in pair)
+
+STATE_NAMES = ("identity", "full_swap", "arms_swap", "legs_swap")
+# The third bit is face-only.  It is tied to both body swaps for full_swap.
+STATE_BITS = {
+    "identity": (0, 0, 0),
+    "full_swap": (1, 1, 1),
+    "arms_swap": (1, 0, 0),
+    "legs_swap": (0, 1, 0),
+}
+
+
+def state_permutation(state: str | int) -> np.ndarray:
+    """Return anatomical -> detector COCO indices for one permitted state."""
+    if isinstance(state, (int, np.integer)):
+        state = STATE_NAMES[int(state)]
+    if state not in STATE_BITS:
+        raise ValueError(f"unknown L/R state: {state!r}")
+    arm, leg, face = STATE_BITS[state]
+    out = np.arange(17, dtype=np.int64)
+    if arm:
+        for left, right in ARM_PAIRS:
+            out[left], out[right] = right, left
+    if leg:
+        for left, right in LEG_PAIRS:
+            out[left], out[right] = right, left
+    if face:
+        for left, right in FACE_PAIRS:
+            out[left], out[right] = right, left
+    return out
+
+
+PERMUTATIONS = np.stack([state_permutation(name) for name in STATE_NAMES])
+
+
+def huber(value: float | np.ndarray, delta: float) -> float | np.ndarray:
+    """Huber rho, applied to a non-negative residual magnitude."""
+    if not np.isfinite(delta) or delta <= 0:
+        raise ValueError("deltaPx must be a finite positive number")
+    value = np.asarray(value, dtype=np.float64)
+    result = np.where(value <= delta, 0.5 * value * value, delta * (value - 0.5 * delta))
+    return float(result) if result.ndim == 0 else result
+
+
+def _observations(kp2d: Any, projected: Any, visibility: Any | None) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    kp = np.asarray(kp2d, dtype=np.float64)
+    pred = np.asarray(projected, dtype=np.float64)
+    if kp.size == 0:
+        if pred.size == 0:
+            kp = np.empty((0, 17, 3), dtype=np.float64)
+        else:
+            pred = pred.reshape((-1, 17, 2))
+            kp = np.full((pred.shape[0], 17, 3), np.nan, dtype=np.float64)
+    elif kp.ndim == 2 and kp.shape == (17, 3):
+        kp = kp[None, ...]
+    elif kp.ndim == 1 and kp.size % (17 * 3) == 0:
+        kp = kp.reshape((-1, 17, 3))
+    if kp.ndim != 3 or kp.shape[1] != 17 or kp.shape[2] < 2:
+        raise ValueError("kp2d must have shape [frames, 17, 2+] (or be empty)")
+
+    if pred.size == 0 and kp.shape[0] == 0:
+        pred = np.empty((0, 17, 2), dtype=np.float64)
+    elif pred.ndim == 2 and pred.shape == (17, 2):
+        pred = pred[None, ...]
+    elif pred.ndim == 1 and pred.size % (17 * 2) == 0:
+        pred = pred.reshape((-1, 17, 2))
+    if pred.ndim != 3 or pred.shape[1:] != (17, 2):
+        raise ValueError("projected must have shape [frames, 17, 2]")
+    if kp.shape[0] != pred.shape[0]:
+        raise ValueError(f"kp2d/projected frame mismatch: {kp.shape[0]} vs {pred.shape[0]}")
+
+    conf = kp[..., 2] if kp.shape[2] >= 3 else np.ones(kp.shape[:2], dtype=np.float64)
+    conf = np.where(np.isfinite(conf), np.clip(conf, 0.0, 1.0), 0.0)
+    detector_weight = np.where(np.isfinite(kp[..., :2]).all(axis=-1), conf, 0.0)
+    anatomical_weight = np.isfinite(pred).all(axis=-1).astype(np.float64)
+    if visibility is not None:
+        vis = np.asarray(visibility, dtype=bool)
+        if vis.shape != anatomical_weight.shape:
+            raise ValueError(f"visibility must have shape {anatomical_weight.shape}, got {vis.shape}")
+        anatomical_weight *= vis
+    # Visibility belongs to the rendered anatomical joint i.  Detector-side
+    # confidence/validity remains indexed by h(i) and is permuted later.
+    return kp, pred, detector_weight, anatomical_weight
+
+
+def _frame_scales(t: int, torso_scale: Any | None) -> np.ndarray:
+    if torso_scale is None:
+        return np.ones(t, dtype=np.float64)
+    scale = np.asarray(torso_scale, dtype=np.float64)
+    if scale.ndim == 0:
+        scale = np.full(t, float(scale), dtype=np.float64)
+    elif scale.ndim == 1 and scale.shape == (t,):
+        scale = scale.copy()
+    else:
+        raise ValueError("torso_scale must be a scalar or one value per frame")
+    if not np.isfinite(scale).all() or (scale <= 0).any():
+        raise ValueError("torso_scale must contain finite positive values")
+    return scale
+
+
+def _emissions(kp: np.ndarray, pred: np.ndarray, detector_weight: np.ndarray, anatomical_weight: np.ndarray, scales: np.ndarray, delta: float, complexity_weight: float) -> tuple[np.ndarray, np.ndarray]:
+    t = kp.shape[0]
+    emissions = np.zeros((t, len(STATE_NAMES)), dtype=np.float64)
+    identity_terms: list[np.ndarray] = []
+    for state_index, permutation in enumerate(PERMUTATIONS):
+        observed = kp[:, permutation, :2]
+        residual = np.linalg.norm(pred - observed, axis=2) / scales[:, None]
+        residual = np.nan_to_num(residual, nan=0.0, posinf=0.0, neginf=0.0)
+        robust = np.asarray(huber(residual, delta))
+        joint_weight = anatomical_weight * detector_weight[:, permutation]
+        weighted = robust * joint_weight
+        emissions[:, state_index] = weighted.sum(axis=1) + complexity_weight * sum(STATE_BITS[STATE_NAMES[state_index]])
+        if state_index == 0:
+            identity_terms.append(robust[joint_weight > 0])
+    return emissions, np.concatenate(identity_terms) if identity_terms else np.empty(0, dtype=np.float64)
+
+
+def _transitions(kp: np.ndarray, pred: np.ndarray, detector_weight: np.ndarray, anatomical_weight: np.ndarray, scales: np.ndarray, delta: float, switch_penalty: float, lambda_cont: float) -> np.ndarray:
+    """Return [frame-1, previous_state, current_state] transition costs."""
+    t = kp.shape[0]
+    out = np.zeros((max(0, t - 1), len(STATE_NAMES), len(STATE_NAMES)), dtype=np.float64)
+    predicted_delta = pred[1:] - pred[:-1]
+    for previous, prev_perm in enumerate(PERMUTATIONS):
+        for current, current_perm in enumerate(PERMUTATIONS):
+            observed_delta = kp[1:, current_perm, :2] - kp[:-1, prev_perm, :2]
+            residual = np.linalg.norm(observed_delta - predicted_delta, axis=2) / scales[1:, None]
+            residual = np.nan_to_num(residual, nan=0.0, posinf=0.0, neginf=0.0)
+            robust = np.asarray(huber(residual, delta))
+            detector_pair_weights = np.minimum(detector_weight[1:, current_perm], detector_weight[:-1, prev_perm])
+            anatomical_pair_weights = np.minimum(anatomical_weight[1:], anatomical_weight[:-1])
+            continuous = (robust * detector_pair_weights * anatomical_pair_weights).sum(axis=1)
+            changed = sum(a != b for a, b in zip(STATE_BITS[STATE_NAMES[previous]], STATE_BITS[STATE_NAMES[current]]))
+            out[:, previous, current] = switch_penalty * changed + lambda_cont * continuous
+    return out
+
+
+def solve_lr_viterbi(
+    kp2d: Any,
+    projected: Any,
+    *,
+    visibility: Any | None = None,
+    torso_scale: Any | None = None,
+    deltaPx: float = 1.0,
+    switch_penalty: float | None = None,
+    lambda_cont: float = 1.0,
+    hysteresis: float = 0.1,
+    complexity_weight: float | None = None,
+) -> dict[str, Any]:
+    """Solve the permitted COCO left/right assignment states over a clip.
+
+    ``path[t]`` is an integer in ``STATE_NAMES`` order.  ``assignment[t, i]``
+    is the detector index to use for anatomical joint ``i``.  Invalid/NaN
+    observations simply have zero weight; this makes an all-zero-confidence
+    clip deterministic (identity, all ambiguous) rather than exceptional.
+    """
+    if not np.isfinite(deltaPx) or deltaPx <= 0:
+        raise ValueError("deltaPx must be a finite positive number")
+    if lambda_cont < 0 or hysteresis < 0:
+        raise ValueError("lambda_cont and hysteresis must be non-negative")
+    kp, pred, detector_weight, anatomical_weight = _observations(kp2d, projected, visibility)
+    t = kp.shape[0]
+    if t == 0:
+        return {
+            "path": np.empty(0, dtype=np.int64), "state_names": STATE_NAMES,
+            "assignments": np.empty((0, 17), dtype=np.int64),
+            "margins": np.empty(0, dtype=np.float64), "ambiguous": np.empty(0, dtype=bool),
+            "emission": np.empty((0, 4), dtype=np.float64), "switch_penalty": 0.0,
+            "state_counts": {name: 0 for name in STATE_NAMES}, "switches": 0,
+        }
+
+    scales = _frame_scales(t, torso_scale)
+    # The plan's switch penalty is four times the median visible emission.  Use
+    # the robust per-joint identity terms, not an aggregate frame cost, so a
+    # short swap run cannot inflate its own penalty.
+    _, identity_terms = _emissions(kp, pred, detector_weight, anatomical_weight, scales, float(deltaPx), 0.0)
+    median_emission = float(np.median(identity_terms)) if identity_terms.size else 0.0
+    penalty = float(4.0 * median_emission if switch_penalty is None else switch_penalty)
+    if not np.isfinite(penalty) or penalty < 0:
+        raise ValueError("switch_penalty must be finite and non-negative")
+    if complexity_weight is None:
+        complexity_weight = 0.01 * median_emission
+    emissions, _ = _emissions(kp, pred, detector_weight, anatomical_weight, scales, float(deltaPx), float(complexity_weight))
+    transitions = _transitions(kp, pred, detector_weight, anatomical_weight, scales, float(deltaPx), penalty, float(lambda_cont))
+
+    states = len(STATE_NAMES)
+    forward = np.full((t, states), np.inf, dtype=np.float64)
+    backpointer = np.zeros((t, states), dtype=np.int64)
+    forward[0] = emissions[0]
+    for frame in range(1, t):
+        for current in range(states):
+            values = forward[frame - 1] + transitions[frame - 1, :, current]
+            previous = int(np.argmin(values))
+            backpointer[frame, current] = previous
+            forward[frame, current] = emissions[frame, current] + values[previous]
+    raw_path = np.empty(t, dtype=np.int64)
+    raw_path[-1] = int(np.argmin(forward[-1]))
+    for frame in range(t - 1, 0, -1):
+        raw_path[frame - 1] = backpointer[frame, raw_path[frame]]
+
+    backward = np.zeros((t, states), dtype=np.float64)
+    for frame in range(t - 2, -1, -1):
+        for previous in range(states):
+            backward[frame, previous] = np.min(transitions[frame, previous] + emissions[frame + 1] + backward[frame + 1])
+    conditioned = forward + backward - np.min(forward[-1])
+
+    def assignment_margin(frame: int, chosen: int) -> float:
+        """Margin against the best state that changes an active assignment."""
+        chosen_perm = PERMUTATIONS[chosen]
+        anatomical_active = anatomical_weight[frame] > 0
+        best = np.inf
+        for alternative, alternative_perm in enumerate(PERMUTATIONS):
+            if alternative == chosen:
+                continue
+            affected = anatomical_active & (alternative_perm != chosen_perm)
+            if not np.any(affected):
+                # Ties in inactive groups are not assignment alternatives.
+                continue
+            detector_active = (detector_weight[frame, chosen_perm] > 0) | (detector_weight[frame, alternative_perm] > 0)
+            affected &= detector_active
+            count = int(np.count_nonzero(affected))
+            if not count:
+                continue
+            best = min(best, float((conditioned[frame, alternative] - conditioned[frame, chosen]) / count))
+        return max(0.0, best) if np.isfinite(best) else 0.0
+
+    # Hysteresis compares the proposed assignment with the assignment it would
+    # retain, not with an unrelated state that ties on inactive groups.
+    path = raw_path.copy()
+    for frame in range(1, t):
+        proposed, retained = int(raw_path[frame]), int(path[frame - 1])
+        if proposed == retained:
+            continue
+        proposed_perm, retained_perm = PERMUTATIONS[proposed], PERMUTATIONS[retained]
+        active = anatomical_weight[frame] > 0
+        active &= (detector_weight[frame, proposed_perm] > 0) | (detector_weight[frame, retained_perm] > 0)
+        affected = active & (proposed_perm != retained_perm)
+        count = int(np.count_nonzero(affected))
+        if not count:
+            path[frame] = retained
+            continue
+        improvement_per_joint = float((conditioned[frame, retained] - conditioned[frame, proposed]) / count)
+        if improvement_per_joint < hysteresis:
+            path[frame] = retained
+
+    margins = np.asarray([assignment_margin(frame, int(path[frame])) for frame in range(t)], dtype=np.float64)
+    ambiguous = margins < 0.05
+    assignments = PERMUTATIONS[path]
+    counts = {name: int(np.count_nonzero(path == index)) for index, name in enumerate(STATE_NAMES)}
+    return {
+        "path": path,
+        "raw_path": raw_path,
+        "state_names": STATE_NAMES,
+        "assignments": assignments,
+        "margins": margins,
+        "ambiguous": ambiguous,
+        "emission": emissions,
+        "switch_penalty": penalty,
+        "median_visible_emission": median_emission,
+        "state_counts": counts,
+        "switches": int(np.count_nonzero(path[1:] != path[:-1])),
+    }
+
+
+# Short aliases make the pure function convenient for callers and tests.
+viterbi_lr = solve_lr_viterbi
+solve_viterbi = solve_lr_viterbi
+
+
+if __name__ == "__main__":
+    raise SystemExit("lr_viterbi.py is a library; use eval_lr.py for file evaluation")