Repository: roboflow/supervision

Issue:
[ByteTrack] - change the names  and documenting input arguments
### Description

Change the names of [input arguments](https://github.com/roboflow/supervision/blob/3024ddca83ad837651e59d040e2a5ac5b2b4f00f/supervision/tracker/byte_tracker/core.py#L182) to be more intuitive and better document them so that users can easily use them while optimizing ByteTrack. Let's also consider exposing more parameters. Especially those that are available in the original implementation.

Document how changes in the values of individual arguments affect the behavior of ByteTrack.

### Reference

   - [ByteTrack paper](https://arxiv.org/pdf/2110.06864.pdf)
   - [ByteTrack code](https://github.com/ifzhang/ByteTrack)

### Additional

- Note: Please share a Google Colab with minimal code to test the new feature. We know it's additional work, but it will speed up the review process. The reviewer must test each change. Setting up a local environment to do this is time-consuming. Please ensure that Google Colab can be accessed without any issues (make it public). Thank you! 🙏🏻 


Discussion:
Hi, I am interesting with this task. Can you assign me? 
@Kadermiyanyedi task is yours, good luck and have fun 🚀 
Hi @Kadermiyanyedi 👋🏻 Did you manage to get started with this task?
Hi, I started this task and I will open a PR as soon as possible :)

Hi @Kadermiyanyedi 👋🏻 Awesome. Thanks a lot for the update. 

Resolving patch:
diff --git a/supervision/tracker/byte_tracker/core.py b/supervision/tracker/byte_tracker/core.py
--- a/supervision/tracker/byte_tracker/core.py
+++ b/supervision/tracker/byte_tracker/core.py
@@ -6,6 +6,7 @@
 from supervision.tracker.byte_tracker import matching
 from supervision.tracker.byte_tracker.basetrack import BaseTrack, TrackState
 from supervision.tracker.byte_tracker.kalman_filter import KalmanFilter
+from supervision.utils.internal import deprecated_parameter
 
 
 class STrack(BaseTrack):
@@ -172,26 +173,57 @@ class ByteTrack:
     </video>
 
     Parameters:
-        track_thresh (float, optional): Detection confidence threshold
-            for track activation.
-        track_buffer (int, optional): Number of frames to buffer when a track is lost.
-        match_thresh (float, optional): Threshold for matching tracks with detections.
+        track_activation_threshold (float, optional): Detection confidence threshold
+            for track activation. Increasing track_activation_threshold improves accuracy
+            and stability but might miss true detections. Decreasing it increases
+            completeness but risks introducing noise and instability.
+        lost_track_buffer (int, optional): Number of frames to buffer when a track is lost.
+            Increasing lost_track_buffer enhances occlusion handling, significantly
+            reducing the likelihood of track fragmentation or disappearance caused
+            by brief detection gaps.
+        minimum_matching_threshold (float, optional): Threshold for matching tracks with detections.
+            Increasing minimum_matching_threshold improves accuracy but risks fragmentation.
+            Decreasing it improves completeness but risks false positives and drift.
         frame_rate (int, optional): The frame rate of the video.
     """  # noqa: E501 // docs
 
+    @deprecated_parameter(
+        old_parameter="track_buffer",
+        new_parameter="lost_track_buffer",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
+    @deprecated_parameter(
+        old_parameter="track_thresh",
+        new_parameter="track_activation_threshold",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
+    @deprecated_parameter(
+        old_parameter="match_thresh",
+        new_parameter="minimum_matching_threshold",
+        map_function=lambda x: x,
+        warning_message="`{old_parameter}` in `{function_name}` is deprecated and will "
+        "be remove in `supervision-0.23.0`. Use '{new_parameter}' "
+        "instead.",
+    )
     def __init__(
         self,
-        track_thresh: float = 0.25,
-        track_buffer: int = 30,
-        match_thresh: float = 0.8,
+        track_activation_threshold: float = 0.25,
+        lost_track_buffer: int = 30,
+        minimum_matching_threshold: float = 0.8,
         frame_rate: int = 30,
     ):
-        self.track_thresh = track_thresh
-        self.match_thresh = match_thresh
+        self.track_activation_threshold = track_activation_threshold
+        self.minimum_matching_threshold = minimum_matching_threshold
 
         self.frame_id = 0
-        self.det_thresh = self.track_thresh + 0.1
-        self.max_time_lost = int(frame_rate / 30.0 * track_buffer)
+        self.det_thresh = self.track_activation_threshold + 0.1
+        self.max_time_lost = int(frame_rate / 30.0 * lost_track_buffer)
         self.kalman_filter = KalmanFilter()
 
         self.tracked_tracks: List[STrack] = []
@@ -295,9 +327,9 @@ def update_with_tensors(self, tensors: np.ndarray) -> List[STrack]:
         scores = tensors[:, 4]
         bboxes = tensors[:, :4]
 
-        remain_inds = scores > self.track_thresh
+        remain_inds = scores > self.track_activation_threshold
         inds_low = scores > 0.1
-        inds_high = scores < self.track_thresh
+        inds_high = scores < self.track_activation_threshold
 
         inds_second = np.logical_and(inds_low, inds_high)
         dets_second = bboxes[inds_second]
@@ -335,7 +367,7 @@ def update_with_tensors(self, tensors: np.ndarray) -> List[STrack]:
 
         dists = matching.fuse_score(dists, detections)
         matches, u_track, u_detection = matching.linear_assignment(
-            dists, thresh=self.match_thresh
+            dists, thresh=self.minimum_matching_threshold
         )
 
         for itracked, idet in matches:
diff --git a/supervision/utils/internal.py b/supervision/utils/internal.py
--- a/supervision/utils/internal.py
+++ b/supervision/utils/internal.py
@@ -2,6 +2,8 @@
 import warnings
 from typing import Callable
 
+warnings.simplefilter("always", DeprecationWarning)
+
 
 def deprecated_parameter(
     old_parameter: str,


Test patch: