add minimum_consecutive_frames to bytetrack

[rolson24]

Description

This PR fixes https://github.com/roboflow/supervision/issues/1044. It replaces this PR https://github.com/roboflow/supervision/pull/1050 which caused only one track to be initialized per frame (see the comment) I decided to re-implement this by instead of setting the tracker_id to -1, I used the existing is_activated property of STrack to mark whether the detection is valid or not. This does not affect the functionality of ByteTrack because every unconfirmed track will get added to the self.tracked_stracks list every time it is matched with a new detection.

Type of change

• [x] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [x] This change requires a documentation update

How has this change been tested, please provide a testcase or example of how you tested the change?

I tested this by running writing pytests for ByteTrack and using them in a colab notebook. I will submit another PR with these tests added to supervision. They cover several cases, including all of the edge cases that I have run into.

Any specific deployment considerations

This might require updating the documentation for ByteTrack, which I am willing to do if this is approved.

Docs

• [ ] Docs updated?

[LinasKo]

@SkalskiP, handing it over to you - happy to merge.

With self.minimum_consecutive_frames=1 this causes no adverse effects, but otherwise increases the chance that neither tracking nor detections will be shown to the user.

This is related to #943, and would be solved when tracker_id is used consistently throughout the codebase - I'll open an issue.

[SkalskiP]

Hi, @rolson24 and @LinasKo 👋🏻 I tested the code included in this PR and have some comments.

• test with minimum_consecutive_frames = 0

https://github.com/roboflow/supervision/assets/26109316/f731bcb5-a990-449e-b608-3f76362a6b2f

• test with minimum_consecutive_frames = 10

https://github.com/roboflow/supervision/assets/26109316/52dd83db-73f7-44cd-ad99-61a4e8460085

I focused primarily on two aspects: tracker ID stability and the overall number of generated tracker IDs.

• If we focus our attention on the group of people standing on the left side, we see that with minimum_consecutive_frames = 0, the following IDs appear: #20, #21, #39, #79, #119, #186, and #292. When we change minimum_consecutive_frames = 10, the following IDs appear: #20, #21, #185, and #316. It works!

• On the other hand, I see that we are generating tons of tracker IDs. In the configuration with minimum_consecutive_frames = 10, we even reached #452. I think the problem lies in the fact that even tracks that are only candidates and ultimately not used are assigned an ID.

  

I think we could solve this problem by initializing the track tracker ID as None and only assigning it when the track is activated.

[rolson24]

Ok I believe I have fixed the issue. The problem was that each track was being re-assigned a new id when it was found after being lost. There also was an issue with the default case of minimum_consective_frames = 1 producing slightly fewer tracks than the current release version because it would only return tracks that had already existed for 1 frame before it got assigned an external id. I fixed this so now it produces the exact same output as the release version. This is the end of the test video from the release version of ByteTrack. You can see that the track_ids are lower than what I originally had:

And this is the new version with minimum_consecutive_frames = 1. You can see that the track_ids are exactly the same:

And finally here is the new version with minimum_consecutive_frames = 10. You can see that the track_ids are much lower because the short tracks have been filtered out. The track_ids are also lower than the previous version due to fixing the re-assigning of track_ids every time a track is found after being lost. Additionally, the bottom middle person is not tracked yet because the track has not reached 10 frames long.

[rolson24]

Just wanted to bump this. I think I fixed the issues we were running into.

[SkalskiP]

Hi @rolson24 👋🏻 I just tested the code, and it looks AWESOME! Thanks a lot for your contribution. 🙏🏻 Unfortunately, we already closed supervision-0.20.0 release, so this feature will need to wait till May/June to get released.

[rolson24]

Good to hear!