refactor (#2202)

Author: mikel-brostrom

README.md

@@ -93,20 +93,20 @@ Where:
 
 **Quick Examples:**
 ```bash
-# Track with webcam
-boxmot track yolov8n osnet_x0_25_msmt17 deepocsort --source 0 --show
+# Track with webcam, save results, show basic results
+boxmot track yolov8n osnet_x0_25_msmt17 deepocsort --source 0 --show --save
 
-# Track a video file
-boxmot track yolov8n osnet_x0_25_msmt17 botsort --source video.mp4 --save
+# Track a video file, save results, show trajectories + lost tracks
+boxmot track yolov8n osnet_x0_25_msmt17 botsort --source video.mp4 --save --show-trajectories --show-lost
 
 # Evaluate on MOT dataset
-boxmot eval yolox_x_MOT17_ablation lmbn_n_duke botsort --source MOT17-ablation --classes 0,2 --source MOT17-ablation
+boxmot eval yolox_x_MOT17_ablation lmbn_n_duke botsort --source MOT17-ablation
 
-# Tune tracker hyperparameters
-boxmot eval yolox_x_dancetrack_ablation lmbn_n_duke botsort --source MOT17-ablation --classes 0,2 --source dancetrack-ablation --n-trials 1000
+# Tune ocsort's hyperparameters for dancetrack
+boxmot tune yolox_x_dancetrack_ablation lmbn_n_duke ocsort --source dancetrack-ablation --n-trials 10
 
-# Export ReID model
-boxmot export --weights osnet_x0_25_msmt17.pt --include onnx --include openvino --dynamic
+# Export ReID model with dynamic sized input
+boxmot export --weights osnet_x0_25_msmt17.pt --include onnx --include engine dynamic
 ```
 
 ## 🐍 PYTHON

boxmot/engine/cli.py

@@ -91,7 +91,7 @@ def core_options(func):
         click.option('--show-trajectories', is_flag=True,
                      help='overlay past trajectories'),
         click.option('--show-lost', is_flag=True,
-                     help='show lost and removed tracks'),
+                     help='show lost tracks'),
         click.option('--save-txt', is_flag=True,
                      help='save results to a .txt file'),
         click.option('--save-crop', is_flag=True,

boxmot/trackers/basetracker.py

@@ -10,7 +10,7 @@
 from boxmot.utils.visualization import VisualizationMixin
 
 
-class BaseTracker(ABC, VisualizationMixin):
+class BaseTracker(VisualizationMixin):
     def __init__(
         self,
         det_thresh: float = 0.3,

boxmot/utils/visualization.py

@@ -1,11 +1,14 @@
 import colorsys
 import hashlib
+from abc import ABC, abstractmethod
+
 import cv2 as cv
 import numpy as np
 
-class VisualizationMixin:
+
+class BaseVisualization(ABC):
     """
-    Mixin class for visualization methods in BaseTracker.
+    Abstract base class for visualization methods in BaseTracker.
     """
 
     def id_to_color(
@@ -176,67 +179,9 @@ def _infer_state(self, a):
 
         return "confirmed"
 
+    @abstractmethod
     def _display_groups(self):
-        """
-        Yield groups of (tracks, forced_state, style) ready for drawing.
-        If ByteTrack-style lists exist, use them with styles and TTLs.
-        Otherwise, fall back to all active tracks and per-track inferred state.
-        """
-        lost_list = getattr(self, "lost_stracks", None)
-        removed_list = getattr(self, "removed_stracks", None)
-
-        # Maintain internal frame index for TTL accounting
-        self._plot_frame_idx += 1
-        now = self._plot_frame_idx
-
-        ttl = int(max(0, getattr(self, "removed_display_frames", self.removed_display_frames)))
-
-        if (lost_list is not None) or (removed_list is not None):
-            # Active
-            yield (self._all_active_tracks(), "confirmed", "solid")
-
-            # Lost (dashed, orange)
-            if lost_list:
-                yield (list(lost_list), "predicted", "dashed")
-
-            # Removed (gray, solid), with TTL + tombstone
-            if removed_list and ttl > 0:
-                filtered_removed = []
-                for a in removed_list:
-                    if not getattr(a, "history_observations", None):
-                        continue
-                    sf = int(getattr(a, "start_frame", getattr(a, "birth_frame", -1)))
-                    rid = int(getattr(a, "id"))
-                    key = (rid, sf) if sf >= 0 else rid
-
-                    if key in self._removed_expired:
-                        continue
-
-                    if key not in self._removed_first_seen:
-                        self._removed_first_seen[key] = now
-
-                    if (now - self._removed_first_seen[key]) < ttl:
-                        filtered_removed.append(a)
-                    else:
-                        self._removed_expired.add(key)
-
-                if filtered_removed:
-                    yield (filtered_removed, "removed", "solid")
-
-            # Optional: simple memory cap
-            if len(self._removed_expired) > 10000:
-                horizon = getattr(self, "removed_tombstone_horizon", 10000)
-                cutoff = now - max(ttl, 1) - horizon
-                to_drop = [k for k, t0 in self._removed_first_seen.items() if t0 < cutoff]
-                for k in to_drop:
-                    self._removed_first_seen.pop(k, None)
-                    self._removed_expired.discard(k)
-
-        else:
-            # Generic fallback: only active tracks; state per track
-            active_tracks = self._all_active_tracks()
-            if active_tracks:
-                yield (active_tracks, None, "dashed")
+        pass
 
     def _draw_track(self, img, a, forced_state, style, thickness, fontscale, show_trajectories):
         if not getattr(a, "history_observations", None):
@@ -286,7 +231,7 @@ def plot_results(
         show_trajectories: bool,
         thickness: int = 2,
         fontscale: float = 0.5,
-        show_lost: bool = True,
+        show_lost: bool = False,
     ) -> np.ndarray:
         """
         Visualizes the trajectories of all active tracks on the image.
@@ -311,3 +256,89 @@ def plot_results(
                     show_trajectories=show_trajectories,
                 )
         return img
+
+
+class ExplicitStateVisualization(BaseVisualization):
+    """
+    Visualization for trackers that maintain explicit lists for lost and removed tracks.
+    """
+
+    def _display_groups(self):
+        lost_list = getattr(self, "lost_stracks", None)
+        removed_list = getattr(self, "removed_stracks", None)
+
+        # Maintain internal frame index for TTL accounting
+        self._plot_frame_idx += 1
+        now = self._plot_frame_idx
+
+        ttl = int(max(0, getattr(self, "removed_display_frames", self.removed_display_frames)))
+
+        # Active
+        yield (self._all_active_tracks(), "confirmed", "solid")
+
+        # Lost (dashed, orange)
+        if lost_list:
+            yield (list(lost_list), "predicted", "dashed")
+
+        # Removed (gray, solid), with TTL + tombstone
+        if removed_list and ttl > 0:
+            filtered_removed = []
+            for a in removed_list:
+                if not getattr(a, "history_observations", None):
+                    continue
+                sf = int(getattr(a, "start_frame", getattr(a, "birth_frame", -1)))
+                rid = int(getattr(a, "id"))
+                key = (rid, sf) if sf >= 0 else rid
+
+                if key in self._removed_expired:
+                    continue
+
+                if key not in self._removed_first_seen:
+                    self._removed_first_seen[key] = now
+
+                if (now - self._removed_first_seen[key]) < ttl:
+                    filtered_removed.append(a)
+                else:
+                    self._removed_expired.add(key)
+
+            if filtered_removed:
+                yield (filtered_removed, "removed", "solid")
+
+        # Optional: simple memory cap
+        if len(self._removed_expired) > 10000:
+            horizon = getattr(self, "removed_tombstone_horizon", 10000)
+            cutoff = now - max(ttl, 1) - horizon
+            to_drop = [k for k, t0 in self._removed_first_seen.items() if t0 < cutoff]
+            for k in to_drop:
+                self._removed_first_seen.pop(k, None)
+                self._removed_expired.discard(k)
+
+
+class InferredStateVisualization(BaseVisualization):
+    """
+    Visualization for trackers that only expose active tracks and state is inferred.
+    """
+
+    def _display_groups(self):
+        # Maintain internal frame index for TTL accounting
+        self._plot_frame_idx += 1
+        
+        # Generic fallback: only active tracks; state per track
+        active_tracks = self._all_active_tracks()
+        if active_tracks:
+            yield (active_tracks, None, "dashed")
+
+
+class VisualizationMixin(BaseVisualization):
+    """
+    Mixin class for visualization methods in BaseTracker.
+    """
+    
+    def _display_groups(self):
+        lost_list = getattr(self, "lost_stracks", None)
+        removed_list = getattr(self, "removed_stracks", None)
+        
+        if (lost_list is not None) or (removed_list is not None):
+            return ExplicitStateVisualization._display_groups(self)
+        else:
+            return InferredStateVisualization._display_groups(self)