Feat/core/bytetrack

.github/workflows/mypy-test.yml

@@ -0,0 +1,33 @@
+name: 🔧 MyPy Test Workflow
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  run-tests:
+    name: MyPy Run Tests
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: 📥 Checkout the repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: 🐍 Install uv and set Python version ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@0c5e2b8115b80b4c7c5ddf6ffdd634974642d182 # v5.4.1
+        with:
+          python-version: ${{ matrix.python-version }}
+          # TODO(https://github.com/astral-sh/setup-uv/issues/226): Remove this.
+          prune-cache: ${{ matrix.os != 'windows-latest' }}
+
+      - name: 🚀 Install Packages
+        run: uv pip install -r pyproject.toml --group dev --group docs --group mypy-types --extra cpu --extra reid --extra metrics
+
+      - name: 🧪 Run MyPy Test
+        run: uv run mypy --config-file mypy.ini --exclude "test|docs" .

.pre-commit-config.yaml

@@ -36,9 +36,3 @@ repos:
           args: [--fix, --exit-non-zero-on-fix]
       -   id: ruff-format
           types_or: [ python, pyi, jupyter]
-
-  -   repo: https://github.com/pre-commit/mirrors-mypy
-      rev: 'v1.15.0'
-      hooks:
-      -   id: mypy
-          additional_dependencies: [numpy,types-aiofiles]

docs/trackers/core/bytetrack/tracker.md

@@ -0,0 +1,263 @@
+---
+comments: true
+---
+
+# ByteTrack
+
+[![arXiv](https://img.shields.io/badge/arXiv-2110.06864-b31b1b.svg)](https://arxiv.org/pdf/2110.06864)
+[![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1C7XyJV8_V6HJwx20E838oQ03F5DLauuC?usp=sharing) <!-- Change the URL to custom Roboflow one before merging -->
+
+## Overview
+
+ByteTrack presents a simple and generic association method which associates almost every detection box instead of only the high probability ones. Low score boxes are typically occluded object, so leaving out this objects of the tracking will result in a fatal failure, but because they aren't clearly seen in the image we cannot trust on it's appearance.
+
+That's why the proposed method consists in 2 key steps. The first step will associate the high score detections to the existing tracks using a chosen similarity metric that can be either IoU or based in appearance features. The second step will associate the low score detections to the trackers that didn't match in the previous step using IoU distance. In addition to this, we added parametrized thresholds for accepting the matches only if the similarity is higher to the corresponding threshold. Finally it starts new tracks with the high score detections that didn't match in step 1. Just like [SORT](../sort/tracker.md) and [DeepSORT](../deepsort/tracker.md) this method combines Kalman Filters for having a motion model in order to match low score boxes and the Hungarian algorithm for calculating the optimal associations.
+
+While calculating the appearance features with a Convolutional Neural Network might be slower than only comparing IoU, it makes it possible to track unpredictable trajectories and objects that dissapear and reappear in the scene, while also being suitable for real time tracking.
+
+BytTrack is independent on the object detector and feature extractor network so it can be used for any tracking task as long as the user provides the adequate model.
+
+
+## Examples
+=== "No Feature Extractor"
+    === "rf-detr"
+
+        ```python hl_lines="3 7 13"
+        import supervision as sv
+        from rfdetr import RFDETRBase
+        from trackers import ByteTrackTracker
+
+        model = RFDETRBase(device ="cuda")
+
+        tracker = ByteTrackTracker(reid_model = None)
+
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            detections = model.predict(frame, threshold=0.5)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+    === "inference"
+
+        ```python hl_lines="2 5 12"
+        import supervision as sv
+        from trackers import ByteTrackTracker
+        from inference import get_model
+
+        tracker = ByteTrackTracker(reid_model = None)
+        model = get_model(model_id="yolov11m-640")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            result = model.infer(frame)[0]
+            detections = sv.Detections.from_inference(result)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+    === "ultralytics"
+
+        ```python hl_lines="2 5 12"
+        import supervision as sv
+        from trackers import ByteTrackTracker
+        from ultralytics import YOLO
+
+        tracker = ByteTrackTracker(reid_model = None)
+        model = YOLO("yolo11m.pt")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            result = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(result)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+    === "transformers"
+
+        ```python hl_lines="3 6 28"
+        import torch
+        import supervision as sv
+        from trackers import ByteTrackTracker
+        from transformers import RTDetrV2ForObjectDetection, RTDetrImageProcessor
+
+        tracker = ByteTrackTracker(reid_model = None)
+        processor = RTDetrImageProcessor.from_pretrained("PekingU/rtdetr_v2_r18vd")
+        model = RTDetrV2ForObjectDetection.from_pretrained("PekingU/rtdetr_v2_r18vd")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            inputs = processor(images=frame, return_tensors="pt")
+            with torch.no_grad():
+                outputs = model(**inputs)
+
+            h, w, _ = frame.shape
+            results = processor.post_process_object_detection(
+                outputs,
+                target_sizes=torch.tensor([(h, w)]),
+                threshold=0.5
+            )[0]
+
+            detections = sv.Detections.from_transformers(
+                transformers_results=results,
+                id2label=model.config.id2label
+            )
+
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+=== "With Feature Extractor"
+    === "rf-detr"
+
+        ```python hl_lines="3 6-8 9 14"
+        import supervision as sv
+        from rfdetr import RFDETRBase
+        from trackers import ByteTrackTracker, ReIDModel
+
+        model = RFDETRBase(device = "cuda")
+        reid_model = ReIDModel.from_timm(
+            "mobilenetv4_conv_small.e1200_r224_in1k",
+        )
+        tracker = ByteTrackTracker(reid_model = reid_model)
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            detections = model.predict(frame, threshold=0.5)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+    === "inference"
+
+        ```python hl_lines="2 5-7 9 16"
+        import supervision as sv
+        from trackers import ByteTrackTracker, ReIDModel
+        from inference import get_model
+
+        reid_model = ReIDModel.from_timm(
+            "mobilenetv4_conv_small.e1200_r224_in1k"
+        )
+
+        tracker = ByteTrackTracker(reid_model = reid_model)
+        model = get_model(model_id="yolov11m-640")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            result = model.infer(frame)[0]
+            detections = sv.Detections.from_inference(result)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+
+    === "ultralytics"
+
+        ```python hl_lines="2 6-9 16"
+        import supervision as sv
+        from trackers import ByteTrackTracker, ReIDModel
+
+        from ultralytics import YOLO
+
+        reid_model = ReIDModel.from_timm(
+            "mobilenetv4_conv_small.e1200_r224_in1k"
+        )
+        tracker = ByteTrackTracker(reid_model = reid_model)
+        model = YOLO("yolo11m.pt")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            result = model(frame)[0]
+            detections = sv.Detections.from_ultralytics(result)
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+    === "transformers"
+
+        ```python hl_lines="3 6-9 31"
+        import torch
+        import supervision as sv
+        from trackers import ByteTrackTracker, ReIDModel
+        from transformers import RTDetrV2ForObjectDetection, RTDetrImageProcessor
+
+        reid_model = ReIDModel.from_timm(
+            "mobilenetv4_conv_small.e1200_r224_in1k"
+        )
+        tracker = ByteTrackTracker(reid_model = reid_model)
+        processor = RTDetrImageProcessor.from_pretrained("PekingU/rtdetr_v2_r18vd")
+        model = RTDetrV2ForObjectDetection.from_pretrained("PekingU/rtdetr_v2_r18vd")
+        annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
+
+        def callback(frame, _):
+            inputs = processor(images=frame, return_tensors="pt")
+            with torch.no_grad():
+                outputs = model(**inputs)
+
+            h, w, _ = frame.shape
+            results = processor.post_process_object_detection(
+                outputs,
+                target_sizes=torch.tensor([(h, w)]),
+                threshold=0.5
+            )[0]
+
+            detections = sv.Detections.from_transformers(
+                transformers_results=results,
+                id2label=model.config.id2label
+            )
+
+            detections = tracker.update(detections, frame)
+            return annotator.annotate(frame, detections, labels=detections.tracker_id)
+
+        sv.process_video(
+            source_path="input.mp4",
+            target_path="output.mp4",
+            callback=callback,
+        )
+        ```
+
+## Usage
+
+::: trackers.core.bytetrack.tracker.ByteTrackTracker

mkdocs.yml

@@ -110,4 +110,5 @@ nav:
   - Trackers:
     - SORT: trackers/core/sort/tracker.md
     - DeepSORT: trackers/core/deepsort/tracker.md
+    - ByteTrack: trackers/core/bytetrack/tracker.md
   - ReID: trackers/core/reid/reid.md

mypy.ini

@@ -2,6 +2,7 @@
 python_version = 3.9
 plugins = numpy.typing.mypy_plugin
 
+
 [mypy-requests]
 ignore_missing_imports = True
 
@@ -16,3 +17,9 @@ ignore_missing_imports = True
 
 [mypy-firerequests]
 ignore_missing_imports = True
+
+[mypy-scipy.optimize]
+ignore_missing_imports = True
+
+[mypy-scipy.spatial.distance]
+ignore_missing_imports = True

pyproject.toml

@@ -31,13 +31,14 @@ classifiers = [
     "Operating System :: MacOS",
     "Operating System :: Microsoft :: Windows",
 ]
-keywords = ["tracking","mot","sort","deepsort", "machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "DETR", "YOLO", "Roboflow"]
+keywords = ["tracking", "mot", "sort", "deepsort", "bytetrack", "machine-learning", "deep-learning", "vision", "ML", "DL", "AI", "DETR", "YOLO", "Roboflow"]
 
 dependencies = [
     "aiofiles>=24.1.0",
     "aiohttp>=3.11.16",
     "numpy>=2.0.2",
     "supervision>=0.26.0rc7",
+    "scipy>=1.13.1",
     "tqdm>=4.67.1",
     "validators>=0.34.0",
     "scipy>=1.13.1",

trackers/__init__.py

@@ -16,3 +16,14 @@
         "Please run `pip install trackers[reid]` and try again."
     )
     pass
+
+try:
+    from trackers.core.bytetrack.tracker import ByteTrackTracker
+
+    __all__.extend(["ByteTrackTracker"])
+except ImportError:
+    logger.warning(
+        "ByteTrack dependencies not installed. "
+        "ByteTrack features will not be available. "
+        "Please run `pip install trackers[bytetrack]` and try again."
+    )