Merge pull request #1611 from mikel-brostrom/trackers-args

added args description to all trackers

boxmot/trackers/botsort/bot_sort.py

@@ -1,6 +1,8 @@
 # Mikel Broström 🔥 Yolo Tracking 🧾 AGPL-3.0 license
 
+import torch
 import numpy as np
+from pathlib import Path
 from collections import deque
 
 from boxmot.appearance.reid_auto_backend import ReidAutoBackend
@@ -186,12 +188,32 @@ def xyxy(self):
 
 
 class BoTSORT(BaseTracker):
+    """
+    BoTSORT Tracker: A tracking algorithm that utilizes a combination of appearance and motion-based tracking.
+
+    Args:
+        model_weights (str): Path to the model weights for ReID (Re-Identification).
+        device (str): Device on which to run the model (e.g., 'cpu' or 'cuda').
+        fp16 (bool): Whether to use half-precision (fp16) for faster inference on compatible devices.
+        per_class (bool, optional): Whether to perform per-class tracking
+        track_high_thresh (float, optional): High threshold for detection confidence. Detections above this threshold are used in the first association round.
+        track_low_thresh (float, optional): Low threshold for detection confidence. Detections below this threshold are ignored.
+        new_track_thresh (float, optional): Threshold for creating a new track. Detections above this threshold will be considered as potential new tracks.
+        track_buffer (int, optional): Number of frames to keep a track alive after it was last detected.
+        match_thresh (float, optional): Threshold for the matching step in data association.
+        proximity_thresh (float, optional): Threshold for IoU (Intersection over Union) distance in first-round association.
+        appearance_thresh (float, optional): Threshold for appearance embedding distance in the ReID module.
+        cmc_method (str, optional): Method for correcting camera motion. Options include "sof" (simple optical flow).
+        frame_rate (int, optional): Frame rate of the video being processed. Used to scale the track buffer size.
+        fuse_first_associate (bool, optional): Whether to fuse appearance and motion information during the first association step.
+        with_reid (bool, optional): Whether to use ReID (Re-Identification) features for association.
+    """
     def __init__(
         self,
-        model_weights,
-        device,
-        fp16,
-        per_class=False,
+        model_weights: Path,
+        device: torch.device,
+        fp16: bool,
+        per_class: bool = False,
         track_high_thresh: float = 0.5,
         track_low_thresh: float = 0.1,
         new_track_thresh: float = 0.6,

boxmot/trackers/bytetrack/byte_tracker.py

@@ -116,13 +116,23 @@ def xyxy(self):
 
 
 class BYTETracker(BaseTracker):
+    """
+    BYTETracker: A tracking algorithm based on ByteTrack, which utilizes motion-based tracking.
+
+    Args:
+        track_thresh (float, optional): Threshold for detection confidence. Detections above this threshold are considered for tracking in the first association round.
+        match_thresh (float, optional): Threshold for the matching step in data association. Controls the maximum distance allowed between tracklets and detections for a match.
+        track_buffer (int, optional): Number of frames to keep a track alive after it was last detected. A longer buffer allows for more robust tracking but may increase identity switches.
+        frame_rate (int, optional): Frame rate of the video being processed. Used to scale the track buffer size.
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+    """
     def __init__(
         self,
-        track_thresh=0.45,
-        match_thresh=0.8,
-        track_buffer=25,
-        frame_rate=30,
-        per_class=False,
+        track_thresh: float = 0.45,
+        match_thresh: float = 0.8,
+        track_buffer: int = 25,
+        frame_rate: int = 30,
+        per_class: bool = False,
     ):
         super().__init__(per_class=per_class)
         self.active_tracks = []  # type: list[STrack]

boxmot/trackers/deepocsort/deep_ocsort.py

@@ -1,6 +1,8 @@
 # Mikel Broström 🔥 Yolo Tracking 🧾 AGPL-3.0 license
 
 import numpy as np
+import torch
+from pathlib import Path
 from collections import deque
 
 from boxmot.appearance.reid_auto_backend import ReidAutoBackend
@@ -222,28 +224,53 @@ def mahalanobis(self, bbox):
 
 
 class DeepOCSort(BaseTracker):
+    """
+    DeepOCSort Tracker: A tracking algorithm that utilizes a combination of appearance and motion-based tracking.
+
+    Args:
+        model_weights (str): Path to the model weights for ReID (Re-Identification).
+        device (str): Device on which to run the model (e.g., 'cpu' or 'cuda').
+        fp16 (bool): Whether to use half-precision (fp16) for faster inference on compatible devices.
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+        det_thresh (float, optional): Detection confidence threshold. Detections below this threshold will be ignored.
+        max_age (int, optional): Maximum number of frames to keep a track alive without any detections.
+        min_hits (int, optional): Minimum number of hits required to confirm a track.
+        iou_threshold (float, optional): Intersection over Union (IoU) threshold for data association.
+        delta_t (int, optional): Time delta for velocity estimation in Kalman Filter.
+        asso_func (str, optional): Association function to use for data association. Options include "iou" for IoU-based association.
+        inertia (float, optional): Weight for inertia in motion modeling. Higher values make tracks less responsive to changes.
+        w_association_emb (float, optional): Weight for the embedding-based association score.
+        alpha_fixed_emb (float, optional): Fixed alpha for updating embeddings. Controls the contribution of new and old embeddings in the ReID model.
+        aw_param (float, optional): Parameter for adaptive weighting between association costs.
+        embedding_off (bool, optional): Whether to turn off the embedding-based association.
+        cmc_off (bool, optional): Whether to turn off camera motion compensation (CMC).
+        aw_off (bool, optional): Whether to turn off adaptive weighting.
+        Q_xy_scaling (float, optional): Scaling factor for the process noise covariance in the Kalman Filter for position coordinates.
+        Q_s_scaling (float, optional): Scaling factor for the process noise covariance in the Kalman Filter for scale coordinates.
+        **kwargs: Additional arguments for future extensions or parameters.
+    """
     def __init__(
         self,
-        model_weights,
-        device,
-        fp16,
-        per_class=False,
-        det_thresh=0.3,
-        max_age=30,
-        min_hits=3,
-        iou_threshold=0.3,
-        delta_t=3,
-        asso_func="iou",
-        inertia=0.2,
-        w_association_emb=0.5,
-        alpha_fixed_emb=0.95,
-        aw_param=0.5,
-        embedding_off=False,
-        cmc_off=False,
-        aw_off=False,
-        Q_xy_scaling=0.01,
-        Q_s_scaling=0.0001,
-        **kwargs
+        model_weights: Path,
+        device: torch.device,
+        fp16: bool,
+        per_class: bool = False,
+        det_thresh: float = 0.3,
+        max_age: int = 30,
+        min_hits: int = 3,
+        iou_threshold: float = 0.3,
+        delta_t: int = 3,
+        asso_func: str = "iou",
+        inertia: float = 0.2,
+        w_association_emb: float = 0.5,
+        alpha_fixed_emb: float = 0.95,
+        aw_param: float = 0.5,
+        embedding_off: bool = False,
+        cmc_off: bool = False,
+        aw_off: bool = False,
+        Q_xy_scaling: float = 0.01,
+        Q_s_scaling: float = 0.0001,
+        **kwargs: dict
     ):
         super().__init__(max_age=max_age, per_class=per_class)
         """

boxmot/trackers/hybridsort/hybridsort.py

@@ -331,38 +331,58 @@ def get_state(self):
 
 
 class HybridSORT(BaseTracker):
+    """
+    HybridSORT Tracker: A tracking algorithm that utilizes a combination of appearance and motion-based tracking
+    and temporal consistency models (TCM) for improved tracking accuracy and robustness.
+
+    Args:
+        reid_weights (str): Path to the model weights for ReID (Re-Identification).
+        device (str): Device on which to run the model (e.g., 'cpu' or 'cuda').
+        half (bool): Whether to use half-precision (fp16) for faster inference on compatible devices.
+        det_thresh (float): Detection confidence threshold. Detections below this threshold will be ignored in the first association step.
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+        max_age (int, optional): Maximum number of frames to keep a track alive without any detections.
+        min_hits (int, optional): Minimum number of hits required to confirm a track.
+        iou_threshold (float, optional): Intersection over Union (IoU) threshold for data association.
+        delta_t (int, optional): Time delta for velocity estimation in Kalman Filter.
+        asso_func (str, optional): Association function to use for data association. Options include "iou" for IoU-based association.
+        inertia (float, optional): Weight for inertia in motion modeling. Higher values make tracks less responsive to changes.
+        longterm_reid_weight (float, optional): Weight for the long-term ReID feature in the association process.
+        TCM_first_step_weight (float, optional): Weight for the Temporal Consistency Model (TCM) in the first association step.
+        use_byte (bool, optional): Whether to use BYTE association in the second association step.
+    """
     def __init__(self, reid_weights, device, half, det_thresh, per_class=False, max_age=30, min_hits=3,
                  iou_threshold=0.3, delta_t=3, asso_func="iou", inertia=0.2, longterm_reid_weight=0, TCM_first_step_weight=0, use_byte=False):
         super().__init__(max_age=max_age, per_class=per_class)
 
         """
         Sets key parameters for SORT
         """
-        self.max_age = max_age
-        self.min_hits = min_hits
-        self.iou_threshold = iou_threshold
-        self.per_class = per_class
-        self.frame_count = 0
-        self.det_thresh = det_thresh
-        self.delta_t = delta_t
-        self.asso_func = get_asso_func(asso_func)
-        self.inertia = inertia
-        self.use_byte = use_byte
-        self.low_thresh = 0.1
-        self.EG_weight_high_score = 1.3
-        self.EG_weight_low_score = 1.2
-        self.TCM_first_step = True
-        self.with_longterm_reid = True
-        self.with_longterm_reid_correction = True
-        self.longterm_reid_weight = longterm_reid_weight
-        self.TCM_first_step_weight = TCM_first_step_weight
-        self.high_score_matching_thresh = 0.8
-        self.longterm_reid_correction_thresh = 0.4
-        self.longterm_reid_correction_thresh_low = 0.4
-        self.TCM_byte_step = True
-        self.TCM_byte_step_weight = 1.0
-        self.dataset = 'dancetrack'
-        self.ECC = False
+        self.max_age: int = max_age
+        self.min_hits: int = min_hits
+        self.iou_threshold: float = iou_threshold
+        self.per_class: bool = per_class
+        self.frame_count: int = 0
+        self.det_thresh: float = det_thresh
+        self.delta_t: int = delta_t
+        self.asso_func: str = get_asso_func(asso_func)  # assuming get_asso_func returns a callable function
+        self.inertia: float = inertia
+        self.use_byte: bool = use_byte
+        self.low_thresh: float = 0.1
+        self.EG_weight_high_score: float = 1.3
+        self.EG_weight_low_score: float = 1.2
+        self.TCM_first_step: bool = True
+        self.with_longterm_reid: bool = True
+        self.with_longterm_reid_correction: bool = True
+        self.longterm_reid_weight: float = longterm_reid_weight
+        self.TCM_first_step_weight: float = TCM_first_step_weight
+        self.high_score_matching_thresh: float = 0.8
+        self.longterm_reid_correction_thresh: float = 0.4
+        self.longterm_reid_correction_thresh_low: float = 0.4
+        self.TCM_byte_step: bool = True
+        self.TCM_byte_step_weight: float = 1.0
+        self.dataset: str = 'dancetrack'
+        self.ECC: bool = False
         KalmanBoxTracker.count = 0
 
         self.model = ReidAutoBackend(

boxmot/trackers/imprassoc/impr_assoc_tracker.py

@@ -2,6 +2,8 @@
 
 import numpy as np
 from collections import deque
+from pathlib import Path
+from torch import device
 
 from boxmot.appearance.reid_auto_backend import ReidAutoBackend
 from boxmot.motion.cmc.sof import SOF
@@ -186,12 +188,34 @@ def xyxy(self):
 
 
 class ImprAssocTrack(BaseTracker):
+    """
+    ImprAssocTrack Tracker: A tracking algorithm that utilizes a combination of appearance and motion-based tracking.
+
+    Args:
+        model_weights (str): Path to the model weights for ReID (Re-Identification).
+        device (str): Device on which to run the model (e.g., 'cpu' or 'cuda').
+        fp16 (bool): Whether to use half-precision (fp16) for faster inference on compatible devices.
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+        track_high_thresh (float, optional): High threshold for detection confidence. Detections above this threshold are used in the first association round.
+        track_low_thresh (float, optional): Low threshold for detection confidence. Detections below this threshold are ignored.
+        new_track_thresh (float, optional): Threshold for creating a new track. Detections above this threshold will be considered as potential new tracks.
+        match_thresh (float, optional): Threshold for the matching step in data association. Controls the maximum distance allowed between tracklets and detections for a match.
+        second_match_thresh (float, optional): Threshold for the second round of matching, used to associate low confidence detections.
+        overlap_thresh (float, optional): Threshold for discarding overlapping detections after association.
+        lambda_ (float, optional): Weighting factor for combining different association costs (e.g., IoU and ReID distance).
+        track_buffer (int, optional): Number of frames to keep a track alive after it was last detected. A longer buffer allows for more robust tracking but may increase identity switches.
+        proximity_thresh (float, optional): Threshold for IoU (Intersection over Union) distance in first-round association.
+        appearance_thresh (float, optional): Threshold for appearance embedding distance in the ReID module.
+        cmc_method (str, optional): Method for correcting camera motion. Options include "sparseOptFlow" (Sparse Optical Flow).
+        frame_rate (int, optional): Frame rate of the video being processed. Used to scale the track buffer size.
+        with_reid (bool, optional): Whether to use ReID (Re-Identification) features for association.
+    """
     def __init__(
         self,
-        model_weights,
-        device,
-        fp16,
-        per_class=False,
+        model_weights: Path,
+        device: device,
+        fp16: bool,
+        per_class: bool = False,
         track_high_thresh: float = 0.6,
         track_low_thresh: float = 0.1,
         new_track_thresh: float = 0.7,

boxmot/trackers/ocsort/ocsort.py

@@ -182,19 +182,35 @@ def get_state(self):
 
 
 class OCSort(BaseTracker):
+    """
+    OCSort Tracker: A tracking algorithm that utilizes motion-based tracking.
+
+    Args:
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+        det_thresh (float, optional): Detection confidence threshold. Detections below this threshold are ignored in the first association step.
+        max_age (int, optional): Maximum number of frames to keep a track alive without any detections.
+        min_hits (int, optional): Minimum number of hits required to confirm a track.
+        asso_threshold (float, optional): Threshold for the association step in data association. Controls the maximum distance allowed between tracklets and detections for a match.
+        delta_t (int, optional): Time delta for velocity estimation in Kalman Filter.
+        asso_func (str, optional): Association function to use for data association. Options include "iou" for IoU-based association.
+        inertia (float, optional): Weight for inertia in motion modeling. Higher values make tracks less responsive to changes.
+        use_byte (bool, optional): Whether to use BYTE association in the second association step.
+        Q_xy_scaling (float, optional): Scaling factor for the process noise covariance in the Kalman Filter for position coordinates.
+        Q_s_scaling (float, optional): Scaling factor for the process noise covariance in the Kalman Filter for scale coordinates.
+    """
     def __init__(
         self,
-        per_class=False,
-        det_thresh=0.2,
-        max_age=30,
-        min_hits=3,
-        asso_threshold=0.3,
-        delta_t=3,
-        asso_func="iou",
-        inertia=0.2,
-        use_byte=False,
-        Q_xy_scaling=0.01,
-        Q_s_scaling=0.0001
+        per_class: bool = False,
+        det_thresh: float = 0.2,
+        max_age: int = 30,
+        min_hits: int = 3,
+        asso_threshold: float = 0.3,
+        delta_t: int = 3,
+        asso_func: str = "iou",
+        inertia: float = 0.2,
+        use_byte: bool = False,
+        Q_xy_scaling: float = 0.01,
+        Q_s_scaling: float = 0.0001
     ):
         super().__init__(max_age=max_age, per_class=per_class)
         """

boxmot/trackers/strongsort/strong_sort.py

@@ -1,6 +1,8 @@
 # Mikel Broström 🔥 Yolo Tracking 🧾 AGPL-3.0 license
 
 import numpy as np
+from torch import device
+from pathlib import Path
 
 from boxmot.appearance.reid_auto_backend import ReidAutoBackend
 from boxmot.motion.cmc import get_cmc_method
@@ -12,12 +14,28 @@
 
 
 class StrongSORT(object):
+    """
+    StrongSORT Tracker: A tracking algorithm that utilizes a combination of appearance and motion-based tracking.
+
+    Args:
+        model_weights (str): Path to the model weights for ReID (Re-Identification).
+        device (str): Device on which to run the model (e.g., 'cpu' or 'cuda').
+        fp16 (bool): Whether to use half-precision (fp16) for faster inference on compatible devices.
+        per_class (bool, optional): Whether to perform per-class tracking. If True, tracks are maintained separately for each object class.
+        max_dist (float, optional): Maximum cosine distance for ReID feature matching in Nearest Neighbor Distance Metric.
+        max_iou_dist (float, optional): Maximum Intersection over Union (IoU) distance for data association. Controls the maximum allowed distance between tracklets and detections for a match.
+        max_age (int, optional): Maximum number of frames to keep a track alive without any detections.
+        n_init (int, optional): Number of consecutive frames required to confirm a track.
+        nn_budget (int, optional): Maximum size of the feature library for Nearest Neighbor Distance Metric. If the library size exceeds this value, the oldest features are removed.
+        mc_lambda (float, optional): Weight for motion consistency in the track state estimation. Higher values give more weight to motion information.
+        ema_alpha (float, optional): Alpha value for exponential moving average (EMA) update of appearance features. Controls the contribution of new and old embeddings in the ReID model.
+    """
     def __init__(
         self,
-        model_weights,
-        device,
-        fp16,
-        per_class=False,
+        model_weights: Path,
+        device: device,
+        fp16: bool,
+        per_class: bool = False,
         max_dist=0.2,
         max_iou_dist=0.7,
         max_age=30,