Feat/core/CBioU tracker by AlexBodner · Pull Request #417 · roboflow/trackers

AlexBodner · 2026-05-14T19:06:32Z

What does this PR do?

Adding CBIoU tracker as wrapper of IoU variants BIoU and BoTsort without cmc (which would be original bytetrack).

Still missing the metrics

Type of Change

New feature (non-breaking change that adds functionality)

Testing

I have tested this change locally
I have added/updated tests for this change

Test details:

Checklist

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code where necessary, particularly in hard-to-understand areas
My changes generate no new warnings or errors
I have updated the documentation accordingly (if applicable)

Additional Context

- New `CBIoUTracker` subclass of `BoTSORTTracker` registered as "cbiou" - CMC permanently disabled; `buffer_ratio` elevated as first-class param - `update()` emits UserWarning when frame is passed (CMC off) - `search_space` covers all tunable params + buffer_ratio [0.0, 0.5] - 13 dedicated tests in tests/core/test_cbiou_tracker.py - `IOC_TRACKER_IDS` in shared_ids.py excludes CBIoU from iou= injection test - Exported from top-level trackers package Co-authored-by: Cursor <cursoragent@cursor.com>

Plans are working documents and should not be tracked in the repository. Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

Adds a new CBIoU tracker as a BoT-SORT-derived tracker that disables CMC and uses Buffered IoU for association, then exposes it through the package API and shared tracker test coverage.

Changes:

Adds CBIoUTracker implementation and package entry point.
Exports CBIoU from trackers.
Extends tracker registration/shared behavior tests and adds CBIoU-specific tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`src/trackers/core/cbiou/tracker.py`	Implements the CBIoU tracker wrapper around BoT-SORT with BIoU and CMC disabled.
`src/trackers/core/cbiou/__init__.py`	Adds the new CBIoU package.
`src/trackers/__init__.py`	Exposes `CBIoUTracker` from the top-level package.
`tests/core/shared_ids.py`	Adds `cbiou` to shared tracker IDs and separates IoU-configurable trackers.
`tests/core/test_trackers.py`	Excludes CBIoU from the configurable-IoU test.
`tests/core/test_registration.py`	Includes CBIoU in registration/search-space coverage.
`tests/core/test_cbiou_tracker.py`	Adds CBIoU-specific construction, warning, association, and search-space tests.

…/trackers into feat/core/cbiou-tracker

Borda · 2026-05-18T15:20:41Z

Let's mark as resolved the comment which you already addressed, so we know what is left

…/trackers into feat/core/cbiou-tracker

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (2)

docs/trackers/comparison.md:187

The comparison page lists enable_cmc: false under the C-BIoU configuration, but CBIoUTracker.init does not accept an enable_cmc parameter (CMC is always disabled internally). Remove this key from the example config (or reword it as a note) to avoid suggesting an invalid constructor argument.

      high_conf_det_threshold: 0.6
      track_activation_threshold: 0.7
      buffer_ratio_first: 0.3
      buffer_ratio_second: 0.5
      enable_cmc: false

docs/trackers/comparison.md:367

The comparison page lists enable_cmc: false under the C-BIoU configuration, but CBIoUTracker.init does not accept an enable_cmc parameter (CMC is always disabled internally). Remove this key from the example config (or reword it as a note) to avoid suggesting an invalid constructor argument.

      high_conf_det_threshold: 0.36
      track_activation_threshold: 0.83
      buffer_ratio_first: 0.23
      buffer_ratio_second: 0.33
      enable_cmc: false

…/trackers into feat/core/cbiou-tracker

tstanczyk95 · 2026-05-20T12:40:11Z

+---
+title: C-BIoU — Cascaded-Buffered IoU Tracker | Trackers
+comments: true
+description: C-BIoU improves association under fast motion and similar appearances by matching with Buffered IoU instead of plain IoU, using a BoT-SORT-style pipeline without camera motion compensation.


"Similar appearances" doesn't sound right here as C-BIoU doesn't use any re-ID or visual appearance matching.

"BoT-SORT-style pipeline without camera motion compensation" sounds confusing, as the main contribution of the implemented BoT-SORT is exactly camera motion compensation.
I would rather say ByteTrack-style pipeline. I know that state estimator and such are rather the ones as in BoT-SORT, but in the docs the description as provided might be confusing, so we might want to clarify it.

tstanczyk95 · 2026-05-20T12:41:43Z

+
+## What is C-BIoU?
+
+C-BIoU builds on the same tracking pipeline as [ByteTrack](bytetrack.md) and [BoT-SORT](botsort.md) but replaces plain IoU with **Buffered IoU (BIoU)**, expanding boxes before overlap is computed so tracks and detections can still match when motion is fast or boxes barely align. It runs two association passes with a small buffer first and a larger buffer second (`buffer_ratio_first` and `buffer_ratio_second`), and does not use camera motion compensation, so only bounding boxes are required. C-BIoU is a strong fit for sports and dance footage where objects move irregularly and look alike.


"when motion is fast" -> "when motion of the object" or "movement of the objects"

(optionally "entities" instead of "objects")

Further, "where objects [...] and look alike": the same remarks as for "similar appearances" above https://github.com/roboflow/trackers/pull/417/changes#r3273963540

tstanczyk95 · 2026-05-20T12:44:05Z

+
+## How does C-BIoU work?
+
+C-BIoU keeps the [ByteTrack](bytetrack.md)-style association pipeline used in [BoT-SORT](botsort.md) but replaces plain IoU with **cascaded Buffered IoU** at each association step.


Upper case: either "Cascaded Buffered IoU" or "cascaded buffered IoU", not mixing.

tstanczyk95 · 2026-05-20T12:45:25Z

+
+C-BIoU keeps the [ByteTrack](bytetrack.md)-style association pipeline used in [BoT-SORT](botsort.md) but replaces plain IoU with **cascaded Buffered IoU** at each association step.
+
+**First association (b1).** High-confidence detections are matched to confirmed and lost tracks using BIoU with `buffer_ratio_first` (paper **b1**, small buffer). Costs are fused with detection confidence.


If you say "paper b1" here, you might provide the link to the reference section below: ## Reference
Same for "paper b2" below.

tstanczyk95 · 2026-05-20T12:48:52Z

+
+**First association (b1).** High-confidence detections are matched to confirmed and lost tracks using BIoU with `buffer_ratio_first` (paper **b1**, small buffer). Costs are fused with detection confidence.
+
+**Second association (b2).** Remaining *tracked* tracks (not lost) are matched to low-confidence detections using BIoU with `buffer_ratio_second` (paper **b2**, large buffer). Score fusion is not applied here. In the paper, the large buffer is applied to **remaining unmatched track/detection pairs** after the first cascade; here it is wired to ByteTrack's low-confidence recovery stage.


"Score fusion is not applied here" -> It hasn't been mentioned before. Thus either mention it before or remove it from here. I would opt for removing it.

I would change the last sentence into:
"In the paper, the large buffer is applied to remaining unmatched track/unmatched detection pairs after the first cascade; here it is wired to ByteTrack's unmatched track/low-confidence detection recovery stage."

tstanczyk95 · 2026-05-20T13:07:58Z

+            out_tracker_ids.append(-1)
+
+        # Step 3: match unconfirmed tracks with remaining unmatched high-confidence
+        # detections (ByteTrack lifecycle; reuses b1 / iou_first, not a paper parameter).


I would say remove "not a paper parameter" for clarity.

It has been mentioned in the docs within the larger context. Here it might cause extra confusion.

tstanczyk95 · 2026-05-20T13:11:37Z

+        self.iou_first = BIoU(buffer_ratio=buffer_ratio_first)
+        self.iou_second = BIoU(buffer_ratio=buffer_ratio_second)
+        self.buffer_ratio_first = buffer_ratio_first
+        self.buffer_ratio_second = buffer_ratio_second


Should we consider some warning for the user if ultimately self.buffer_ratio_first becomes higher or equal to self.buffer_ratio_second?

dont think so, it is just recommended by paper authors, but like you pointed over Slack, if it works better or the user sees fit using a higher threshold first should be fine

tstanczyk95 · 2026-05-20T13:13:07Z

+class TestCBIoUAssociationTolerance:
+    """BIoU should associate near-miss detections that plain IoU would miss."""
+
+    def test_near_miss_associated_with_buffer(self) -> None:


Nice test to demonstrate, but it actually safe? And not too number/case-specific?

it is very specific, but it tests what we want right? what seems off to you?

tstanczyk95 · 2026-05-20T13:16:21Z



-@pytest.mark.parametrize("tracker_id", ALL_TRACKER_IDS)
+@pytest.mark.parametrize("tracker_id", IOU_TRACKER_IDS)


Why do we do this distinction here? I mean why excluding C-BIoU here?

because its testing that the IoU variants are properly used as the user passed as parameter. This is not an option in CBIoU as its forced to be BIoU

tstanczyk95 · 2026-05-20T13:20:27Z

    assert tracking_iou.compute_calls > 0


-@pytest.mark.parametrize("tracker_id", ALL_TRACKER_IDS)


I might have missed, but where are all these tests now? This is quite a big block of tests being removed. I saw a big addition above https://github.com/roboflow/trackers/pull/417/changes#diff-e03730a206379add4fc7c6e8b37ae01ffc5564cc8ccfdfb3f2917255cef0aee3R1 but it was C-BIoU-specific.

Thus what happens with such tests for the other trackers then?

This is conflicting because we adjusted these tests at https://github.com/roboflow/trackers/pull/415/changes#diff-c4ed0ac20c4d9ad9eb94afd554b45099460a4f85b5edfac4c3eba1f85d04a6cb
Thanks for pointing this out, Im going to merge with these changes that we wanted

handled this in fc66939

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>

…not merged here

…/trackers into feat/core/cbiou-tracker

AlexBodner and others added 2 commits May 14, 2026 13:48

refactor: simplify cbiou __init__.py to header-only

0bcbe35

AlexBodner requested a review from SkalskiP as a code owner May 14, 2026 19:06

pre-commit-ci Bot and others added 2 commits May 14, 2026 19:06

fix(pre_commit): 🎨 auto format pre-commit hooks

e1a6cf6

Remove plan file from version control

a4ab848

Plans are working documents and should not be tracked in the repository. Co-authored-by: Cursor <cursoragent@cursor.com>

Borda requested a review from Copilot May 15, 2026 07:04

Copilot started reviewing on behalf of Borda May 15, 2026 07:05 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

AlexBodner changed the title ~~Feat/core/cbiou tracker~~ Feat/core/CBioU tracker May 15, 2026

AlexBodner and others added 6 commits May 16, 2026 13:52

updated CBioU with 2 buffer rates and docs

7ac4b47

fix(pre_commit): 🎨 auto format pre-commit hooks

dccbbaf

preliminary numbers for cbiou

86c42f8

Merge branch 'feat/core/cbiou-tracker' of https://github.com/roboflow…

56c431c

…/trackers into feat/core/cbiou-tracker

fix(pre_commit): 🎨 auto format pre-commit hooks

8ea2d24

Merge branch 'develop' into feat/core/cbiou-tracker

e492563

AlexBodner and others added 6 commits May 19, 2026 10:27

updated CBIoU numbers

e4ab8c6

updated CBIoU numbers

3f75742

fix(pre_commit): 🎨 auto format pre-commit hooks

7d40f2c

added expected cbiou results

9094128

Merge branch 'feat/core/cbiou-tracker' of https://github.com/roboflow…

e4d9dbb

…/trackers into feat/core/cbiou-tracker

small adjust in tests

baec230

AlexBodner requested a review from Copilot May 19, 2026 18:20

Copilot started reviewing on behalf of AlexBodner May 19, 2026 18:21 View session

Copilot AI reviewed May 19, 2026

View reviewed changes

Comment thread src/trackers/core/cbiou/tracker.py

Comment thread src/trackers/core/cbiou/tracker.py

Comment thread tests/core/test_cbiou_tracker.py Outdated

Comment thread docs/trackers/comparison.md

Comment thread docs/trackers/comparison.md

AlexBodner and others added 5 commits May 19, 2026 15:37

mypy fix

9bc87a6

fix(pre_commit): 🎨 auto format pre-commit hooks

f55b1c5

docs fix

cd33617

Merge branch 'feat/core/cbiou-tracker' of https://github.com/roboflow…

eb92a34

…/trackers into feat/core/cbiou-tracker

handling default confidence with utility

ec23482

AlexBodner requested a review from Borda May 19, 2026 18:43

fix(pre_commit): 🎨 auto format pre-commit hooks

36deef2

Borda requested a review from tstanczyk95 May 20, 2026 09:44

Borda added the enhancement New feature or request label May 20, 2026

Merge branch 'develop' into feat/core/cbiou-tracker

6bb345c

Borda reviewed May 20, 2026

View reviewed changes

Comment thread docs/trackers/cbiou.md Outdated

Borda previously approved these changes May 20, 2026

View reviewed changes

tstanczyk95 reviewed May 20, 2026

View reviewed changes

Borda and others added 2 commits May 20, 2026 18:52

Merge branch 'develop' into feat/core/cbiou-tracker

220391f

Update docs/trackers/cbiou.md

aaa4432

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>

AlexBodner dismissed Borda’s stale review via aaa4432 May 20, 2026 19:37

pre-commit-ci Bot and others added 3 commits May 20, 2026 19:37

fix(pre_commit): 🎨 auto format pre-commit hooks

91865b9

fixed tests pointed out by Tomasz which were modified in PR #415 but …

fc66939

…not merged here

Merge branch 'feat/core/cbiou-tracker' of https://github.com/roboflow…

7b45bb6

…/trackers into feat/core/cbiou-tracker


		## What is C-BIoU?

		C-BIoU builds on the same tracking pipeline as [ByteTrack](bytetrack.md) and [BoT-SORT](botsort.md) but replaces plain IoU with Buffered IoU (BIoU), expanding boxes before overlap is computed so tracks and detections can still match when motion is fast or boxes barely align. It runs two association passes with a small buffer first and a larger buffer second (`buffer_ratio_first` and `buffer_ratio_second`), and does not use camera motion compensation, so only bounding boxes are required. C-BIoU is a strong fit for sports and dance footage where objects move irregularly and look alike.


		## How does C-BIoU work?

		C-BIoU keeps the [ByteTrack](bytetrack.md)-style association pipeline used in [BoT-SORT](botsort.md) but replaces plain IoU with cascaded Buffered IoU at each association step.


		C-BIoU keeps the [ByteTrack](bytetrack.md)-style association pipeline used in [BoT-SORT](botsort.md) but replaces plain IoU with cascaded Buffered IoU at each association step.

		First association (b1). High-confidence detections are matched to confirmed and lost tracks using BIoU with `buffer_ratio_first` (paper b1, small buffer). Costs are fused with detection confidence.


		First association (b1). High-confidence detections are matched to confirmed and lost tracks using BIoU with `buffer_ratio_first` (paper b1, small buffer). Costs are fused with detection confidence.

		Second association (b2). Remaining tracked tracks (not lost) are matched to low-confidence detections using BIoU with `buffer_ratio_second` (paper b2, large buffer). Score fusion is not applied here. In the paper, the large buffer is applied to remaining unmatched track/detection pairs after the first cascade; here it is wired to ByteTrack's low-confidence recovery stage.



		@pytest.mark.parametrize("tracker_id", ALL_TRACKER_IDS)
		@pytest.mark.parametrize("tracker_id", IOU_TRACKER_IDS)

		assert tracking_iou.compute_calls > 0


		@pytest.mark.parametrize("tracker_id", ALL_TRACKER_IDS)

Conversation

AlexBodner commented May 14, 2026

What does this PR do?

Type of Change

Testing

Checklist

Additional Context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Borda commented May 18, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants