add sfsort tracker (#2225)

Author: mikel-brostrom

.github/workflows/benchmark.yml

@@ -20,7 +20,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ['3.12']
-        tracker: ["ocsort", "bytetrack", "botsort", "deepocsort", "hybridsort", "strongsort", "boosttrack"]
+        tracker: ["ocsort", "bytetrack", "botsort", "deepocsort", "hybridsort", "strongsort", "boosttrack", "sfsort"]
     timeout-minutes: 50
 
     steps:
@@ -84,12 +84,13 @@ jobs:
           else
             declare -A tracker_fps
             tracker_fps["deepocsort"]=12
-            tracker_fps["bytetrack"]=1265
-            tracker_fps["ocsort"]=1483
-            tracker_fps["strongsort"]=17
-            tracker_fps["botsort"]=46
+            tracker_fps["bytetrack"]=720
+            tracker_fps["ocsort"]=890
+            tracker_fps["strongsort"]=11
+            tracker_fps["botsort"]=12
             tracker_fps["hybridsort"]=25
-            tracker_fps["boosttrack"]=25
+            tracker_fps["boosttrack"]=13
+            tracker_fps["sfsort"]="6000"
             fps=${tracker_fps[$TRACKER_NAME]}
           fi
 
@@ -154,6 +155,7 @@ jobs:
           paper_links["strongsort"]="https://arxiv.org/abs/2202.13514"
           paper_links["botsort"]="https://arxiv.org/abs/2206.14651"
           paper_links["hybridsort"]="https://arxiv.org/abs/2308.00783"
+          paper_links["sfsort"]="https://arxiv.org/pdf/2404.07553"
 
           new_table="| Tracker | Status  | HOTA↑ | MOTA↑ | IDF1↑ | FPS |\n"
           new_table+="| :-----: | :-----: | :---: | :---: | :---: | :---: |\n"

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
         os: [ubuntu-latest, macos-14]   # skip windows-latest for
         python-version: ['3.12']
     env:
-      TRACKERS: "ocsort bytetrack botsort deepocsort strongsort boosttrack hybridsort"
+      TRACKERS: "ocsort bytetrack botsort deepocsort strongsort boosttrack hybridsort sfsort"
       IMG: ./assets/MOT17-mini/train/MOT17-02-FRCNN/img1/000001.jpg
 
     # Timeout: https://stackoverflow.com/a/59076067/4521646
@@ -89,7 +89,7 @@ jobs:
     outputs:
       status: ${{ job.status }}
     env:
-      TRACKERS: "ocsort bytetrack botsort deepocsort strongsort boosttrack hybridsort"
+      TRACKERS: "ocsort bytetrack botsort deepocsort strongsort boosttrack hybridsort sfsort"
 
     # Timeout: https://stackoverflow.com/a/59076067/4521646
     timeout-minutes: 50

AGENTS.md

@@ -186,3 +186,31 @@ Sometimes the provided environment is missing GPUs, large datasets, or external
 - Where practical:
   - Use deterministic or seeded behavior for tests/examples.
   - Avoid unnecessary heavy computation in unit tests.
+
+## 9. Integrating a New Tracker (Checklist)
+
+1) Implement the tracker
+  - Add a new module under `boxmot/trackers/<name>/` (e.g., `sfsort.py`).
+  - Implement a tracker class that subclasses `BaseTracker` and defines `update()`.
+
+2) Register the tracker
+  - Add the tracker to `TRACKER_MAPPING` in `boxmot/trackers/tracker_zoo.py`.
+  - Export it in `boxmot/trackers/__init__.py` and `boxmot/__init__.py`.
+  - Add the tracker name to the `TRACKERS` list in `boxmot/__init__.py`.
+
+3) Add default configuration
+  - Create `boxmot/configs/trackers/<name>.yaml` with default parameters and tuning ranges.
+
+4) Update docs
+  - Add a tracker doc page in `docs/trackers/<name>.md`.
+  - Add the tracker to `mkdocs.yml` nav.
+  - Mention it in `docs/index.md` and `README.md` where trackers are listed.
+
+5) Update tests
+  - Register the tracker in `tests/test_config.py` lists so it’s covered by unit tests.
+
+6) Update CI/benchmarks
+  - Add the tracker name to workflow matrices/lists in `.github/workflows/`.
+
+7) Commit new files
+  - Ensure new tracker code, config, and docs are staged and pushed.

README.md

@@ -56,6 +56,7 @@
 | [bytetrack](https://arxiv.org/abs/2110.06864) | ✅ | 67.68 | 78.039 | 79.157 | 1265 |
 | [hybridsort](https://arxiv.org/abs/2308.00783) | ✅ | 67.39 | 74.127 | 79.105 | 25 |
 | [ocsort](https://arxiv.org/abs/2203.14360) | ✅ | 66.441 | 74.548 | 77.899 | 1483 |
+| sfsort | ✅ | — | — | — | — |
 
 <!-- END TRACKER TABLE -->
 
@@ -87,7 +88,7 @@ Where:
   MODE      (required) one of [track, eval, tune, generate, export]
   DETECTOR  (optional) YOLO model like yolov8n, yolov9c, yolo11m, yolox_x
   REID      (optional) ReID model like osnet_x0_25_msmt17, mobilenetv2_x1_4
-  TRACKER   (optional) one of [deepocsort, botsort, bytetrack, strongsort, ocsort, hybridsort, boosttrack]
+  TRACKER   (optional) one of [deepocsort, botsort, bytetrack, strongsort, ocsort, hybridsort, boosttrack, sfsort]
   ARGS      (optional) 'arg=value' pairs that override defaults
 ```
 
@@ -212,6 +213,7 @@ boxmot track yolov8n osnet_x0_25_msmt17 bytetrack
 boxmot track yolov8n osnet_x0_25_msmt17 botsort
 boxmot track yolov8n osnet_x0_25_msmt17 boosttrack
 boxmot track yolov8n osnet_x0_25_msmt17 hybridsort
+boxmot track yolov8n osnet_x0_25_msmt17 sfsort
 ```
 
 </details>

boxmot/__init__.py

@@ -10,6 +10,7 @@
 from boxmot.trackers.deepocsort.deepocsort import DeepOcSort
 from boxmot.trackers.hybridsort.hybridsort import HybridSort
 from boxmot.trackers.ocsort.ocsort import OcSort
+from boxmot.trackers.sfsort.sfsort import SFSORT
 from boxmot.trackers.strongsort.strongsort import StrongSort
 from boxmot.trackers.tracker_zoo import create_tracker, get_tracker_config
 
@@ -21,6 +22,7 @@
     "deepocsort",
     "hybridsort",
     "boosttrack",
+    "sfsort",
 ]
 
 __all__ = (
@@ -32,6 +34,7 @@
     "DeepOcSort",
     "HybridSort",
     "BoostTrack",
+    "SFSORT",
     "create_tracker",
     "get_tracker_config",
     "gsi",

boxmot/configs/trackers/sfsort.yaml

@@ -0,0 +1,69 @@
+high_th:
+  type: uniform
+  default: 0.6
+  range: [0.4, 0.9]
+
+match_th_first:
+  type: uniform
+  default: 0.67
+  range: [0.4, 0.67]
+
+new_track_th:
+  type: uniform
+  default: 0.7
+  range: [0.6, 0.95]
+
+low_th:
+  type: uniform
+  default: 0.1
+  range: [0.05, 0.4]
+
+match_th_second:
+  type: uniform
+  default: 0.3
+  range: [0.1, 0.6]
+
+dynamic_tuning:
+  type: choice
+  default: false
+  options: [true, false]
+
+cth:
+  type: uniform
+  default: 0.5
+  range: [0.2, 0.8]
+
+high_th_m:
+  type: uniform
+  default: 0.0
+  range: [0.02, 0.1]
+
+new_track_th_m:
+  type: uniform
+  default: 0.0
+  range: [0.02, 0.08]
+
+match_th_first_m:
+  type: uniform
+  default: 0.0
+  range: [0.02, 0.08]
+
+marginal_timeout:
+  type: qrandint
+  default: 0
+  range: [0, 501, 50]
+
+central_timeout:
+  type: qrandint
+  default: 0
+  range: [0, 1001, 100]
+
+horizontal_margin:
+  type: qrandint
+  default: 0
+  range: [0, 641, 50]
+
+vertical_margin:
+  type: qrandint
+  default: 0
+  range: [0, 641, 50]

boxmot/trackers/__init__.py

@@ -4,4 +4,5 @@
 from boxmot.trackers.deepocsort.deepocsort import DeepOcSort
 from boxmot.trackers.hybridsort.hybridsort import HybridSort
 from boxmot.trackers.ocsort.ocsort import OcSort
+from boxmot.trackers.sfsort.sfsort import SFSORT
 from boxmot.trackers.strongsort.strongsort import StrongSort

boxmot/trackers/sfsort/__init__.py

@@ -0,0 +1 @@
+# Mikel Broström 🔥 BoxMOT 🧾 AGPL-3.0 license