feat(tracking): add recursive lifecycle updates and quality diagnostics

Implement the next tracker tranche around a recursive articulated state rather than per-frame ad hoc updates.

Track state now propagates full pose/velocity/shape covariance, uses process noise during prediction, and drives active-to-lost transitions from both miss counts and recursive score thresholds. The multiview update path replaces the generic SciPy least_squares call with a bounded LM/GN loop that returns parameter and beta covariance blocks, accepted-joint counts, mean reprojection error, and iteration diagnostics.

Lost-track handling is stricter and safer: proposal-based reacquisition now requires same-frame 2D support and articulated refinement before a track can return to active. Proposal clusters retain contributing detection indices, the tracker searches broadly within contributing views, and proposal-compatible lost frames are surfaced explicitly instead of silently reviving a track. Old scene JSONs with imgpaths now default to the RPT camera-pose convention so proposal reprojection gating works on the sample scenes.

Add ActualTest support diagnostics that summarize event counts, accepted support, reprojection quality, and tracker diagnostics, plus focused regressions for camera conventions, score-driven demotion, covariance behavior, proposal-compatible lost handling, and broader proposal-backed matching.

tests/support/actual_test.py

@@ -1,3 +1,5 @@
+from collections import Counter
+from dataclasses import dataclass
 from pathlib import Path
 
 import click
@@ -8,12 +10,92 @@ from beartype import beartype
 from loguru import logger
 
 from pose_tracking_exp.common.normalization import infer_bbox_from_keypoints, normalize_rtmpose_body20
-from pose_tracking_exp.schema import CameraCalibration, CameraFrame, FrameBundle, PoseDetection, SceneConfig, TrackerConfig
+from pose_tracking_exp.schema import (
+    CameraCalibration,
+    CameraFrame,
+    FrameBundle,
+    PoseDetection,
+    SceneConfig,
+    TrackerConfig,
+    TrackerDiagnostics,
+    TrackedFrameResult,
+)
 from pose_tracking_exp.tracking import PoseTracker
 
 _NOMINAL_FRAME_PERIOD_NS = 33_333_333
 
 
+@dataclass(slots=True)
+class ActualTestTrackingSummary:
+    bundle_count: int
+    active_frames: int
+    proposal_frames: int
+    max_active_tracks: int
+    max_lost_tracks: int
+    update_action_counts: dict[str, int]
+    mean_accepted_views: float
+    mean_accepted_joints: float
+    mean_reprojection_error: float
+    diagnostics: TrackerDiagnostics
+
+
+def _finite_mean(values: list[float]) -> float:
+    finite = [value for value in values if np.isfinite(value)]
+    if not finite:
+        return np.inf
+    return float(np.mean(np.asarray(finite, dtype=np.float64)))
+
+
+@beartype
+def summarize_tracking_results(
+    results: list[TrackedFrameResult],
+    diagnostics: TrackerDiagnostics,
+) -> ActualTestTrackingSummary:
+    update_events = [event for result in results for event in result.update_events]
+    action_counts = Counter(event.action for event in update_events)
+    accepted_view_samples = [float(event.accepted_view_count) for event in update_events if event.accepted_view_count > 0]
+    accepted_joint_samples = [float(event.accepted_joint_count) for event in update_events if event.accepted_joint_count > 0]
+    reprojection_samples = [float(event.mean_reprojection_error) for event in update_events]
+    return ActualTestTrackingSummary(
+        bundle_count=len(results),
+        active_frames=sum(1 for result in results if result.active_tracks),
+        proposal_frames=sum(1 for result in results if result.proposals),
+        max_active_tracks=max((len(result.active_tracks) for result in results), default=0),
+        max_lost_tracks=max((len(result.lost_tracks) for result in results), default=0),
+        update_action_counts=dict(action_counts),
+        mean_accepted_views=_finite_mean(accepted_view_samples),
+        mean_accepted_joints=_finite_mean(accepted_joint_samples),
+        mean_reprojection_error=_finite_mean(reprojection_samples),
+        diagnostics=diagnostics,
+    )
+
+
+@beartype
+def format_frame_summary_lines(results: list[TrackedFrameResult]) -> tuple[str, ...]:
+    lines: list[str] = []
+    for result in results:
+        action_counts = Counter(event.action for event in result.update_events)
+        finite_reprojection_errors = [
+            float(event.mean_reprojection_error)
+            for event in result.update_events
+            if np.isfinite(event.mean_reprojection_error)
+        ]
+        lines.append(
+            "bundle={} proposals={} active_ids={} lost_ids={} tentative_ids={} actions={} mean_event_reproj={}".format(
+                result.bundle_index,
+                len(result.proposals),
+                [track.track_id for track in result.active_tracks],
+                [track.track_id for track in result.lost_tracks],
+                [track.track_id for track in result.tentative_tracks],
+                dict(action_counts),
+                "{:.2f}".format(float(np.mean(np.asarray(finite_reprojection_errors, dtype=np.float64))))
+                if finite_reprojection_errors
+                else "nan",
+            )
+        )
+    return tuple(lines)
+
+
 @beartype
 def load_actual_test_scene(root: Path) -> SceneConfig:
     # ActualTest parquet comes from the ChArUco/OpenCV side, so `rvec` / `tvec`
@@ -148,6 +230,7 @@ def load_actual_test_segment_bundles(
 @click.option("--max-frames", type=click.IntRange(min=1))
 @click.option("--min-camera-rows", default=1, type=click.IntRange(min=1), show_default=True)
 @click.option("--max-active-tracks", default=1, type=click.IntRange(min=1), show_default=True)
+@click.option("--verbose-frames/--no-verbose-frames", default=False, show_default=True)
 def main(
     root_path: Path,
     segment_name: str,
@@ -156,6 +239,7 @@ def main(
     max_frames: int | None,
     min_camera_rows: int,
     max_active_tracks: int,
+    verbose_frames: bool,
 ) -> None:
     logger.remove()
     logger.add(
@@ -174,12 +258,34 @@ def main(
     )
     tracker = PoseTracker(scene, TrackerConfig(max_active_tracks=max_active_tracks))
     results = tracker.run(bundles)
+    summary = summarize_tracking_results(results, tracker.diagnostics_snapshot())
     logger.info(
-        "actual_test bundles={} active_frames={} proposal_frames={}",
-        len(results),
-        sum(1 for result in results if result.active_tracks),
-        sum(1 for result in results if result.proposals),
+        "actual_test bundles={} active_frames={} proposal_frames={} max_active_tracks={} max_lost_tracks={} "
+        "mean_accepted_views={} mean_accepted_joints={} mean_reprojection_error={}",
+        summary.bundle_count,
+        summary.active_frames,
+        summary.proposal_frames,
+        summary.max_active_tracks,
+        summary.max_lost_tracks,
+        "{:.2f}".format(summary.mean_accepted_views) if np.isfinite(summary.mean_accepted_views) else "nan",
+        "{:.2f}".format(summary.mean_accepted_joints) if np.isfinite(summary.mean_accepted_joints) else "nan",
+        "{:.2f}".format(summary.mean_reprojection_error) if np.isfinite(summary.mean_reprojection_error) else "nan",
     )
+    logger.info(
+        "actual_test actions={} promotions={} reacquisitions={} predict_only_updates={} proposal_reacquisition_attempts={} "
+        "proposal_compatible_lost_frames={} nonlinear_refinements={} lm_iterations={}",
+        summary.update_action_counts,
+        summary.diagnostics.promotions,
+        summary.diagnostics.reacquisitions,
+        summary.diagnostics.predict_only_updates,
+        summary.diagnostics.proposal_reacquisition_attempts,
+        summary.diagnostics.proposal_compatible_lost_frames,
+        summary.diagnostics.nonlinear_refinements,
+        summary.diagnostics.lm_iterations,
+    )
+    if verbose_frames:
+        for line in format_frame_summary_lines(results):
+            logger.info("actual_test_frame {}", line)
 
 
 if __name__ == "__main__":