Skip to main content

sightloom_tracking/
bytetrack.rs

1//! ByteTrack-compatible multi-object tracker.
2
3#[cfg(feature = "alloc")]
4extern crate alloc;
5
6#[cfg(feature = "alloc")]
7use alloc::{vec, vec::Vec};
8
9use crate::{
10    ByteTrackConfig, Track, TrackError, TrackState,
11    matching::{AssignScratch, MatchCandidate, greedy_iou_assign},
12};
13use sightloom_core::{ClassId, Detection, Rect, TrackId};
14
15/// Serializable snapshot of a single-source tracker runtime.
16#[derive(Clone, Debug, PartialEq)]
17pub struct TrackerSnapshot {
18    /// Internal frame counter.
19    pub frame_id: u64,
20    /// Next local track id.
21    pub next_id: u32,
22    /// Active and lost tracks.
23    pub tracks: Vec<Track>,
24}
25
26/// `ByteTrack` multi-object tracker with stable IDs.
27///
28/// Accepts external detections each frame and returns the active tracked set.
29/// Does not run inference or decode video.
30#[cfg(feature = "alloc")]
31#[derive(Clone, Debug)]
32pub struct ByteTracker {
33    config: ByteTrackConfig,
34    frame_id: u64,
35    next_id: u32,
36    tracks: Vec<Track>,
37}
38
39#[cfg(feature = "alloc")]
40impl ByteTracker {
41    /// Creates a tracker from a validated configuration.
42    ///
43    /// # Errors
44    ///
45    /// Returns [`TrackError::InvalidConfig`] when thresholds are invalid.
46    pub fn new(config: ByteTrackConfig) -> Result<Self, TrackError> {
47        let config = config.validate()?;
48        Ok(Self {
49            config,
50            frame_id: 0,
51            next_id: 1,
52            tracks: Vec::new(),
53        })
54    }
55
56    /// Returns the current configuration.
57    #[must_use]
58    pub const fn config(&self) -> ByteTrackConfig {
59        self.config
60    }
61
62    /// Returns all non-removed tracks.
63    #[must_use]
64    pub fn tracks(&self) -> &[Track] {
65        &self.tracks
66    }
67
68    /// Internal frame counter after the last [`Self::update`].
69    #[must_use]
70    pub const fn frame_id(&self) -> u64 {
71        self.frame_id
72    }
73
74    /// Next local track id that will be assigned.
75    #[must_use]
76    pub const fn next_id(&self) -> u32 {
77        self.next_id
78    }
79
80    /// Captures a full runtime snapshot for checkpointing.
81    #[must_use]
82    pub fn snapshot(&self) -> TrackerSnapshot {
83        TrackerSnapshot {
84            frame_id: self.frame_id,
85            next_id: self.next_id,
86            tracks: self.tracks.clone(),
87        }
88    }
89
90    /// Restores counters and track list from a snapshot (config unchanged).
91    pub fn restore(&mut self, snapshot: TrackerSnapshot) {
92        self.frame_id = snapshot.frame_id;
93        self.next_id = snapshot.next_id.max(1);
94        self.tracks = snapshot.tracks;
95    }
96
97    /// Restores a tracker from a snapshot and validated config.
98    ///
99    /// # Errors
100    ///
101    /// Returns config validation errors.
102    pub fn from_snapshot(
103        config: ByteTrackConfig,
104        snapshot: TrackerSnapshot,
105    ) -> Result<Self, TrackError> {
106        let mut tracker = Self::new(config)?;
107        tracker.restore(snapshot);
108        Ok(tracker)
109    }
110
111    /// Updates the tracker with one frame of detections.
112    ///
113    /// Assigns `track_id` on the returned detections for matched/activated
114    /// objects. Input order of returned detections follows the active track
115    /// list (tracked and new), not the original detection order.
116    ///
117    /// # Errors
118    ///
119    /// Returns [`TrackError::NonFinite`] only if internal assumptions break;
120    /// detections are expected to already be validated by `sightloom-core`.
121    pub fn update(&mut self, detections: &[Detection]) -> Result<Vec<Detection>, TrackError> {
122        self.frame_id = self.frame_id.saturating_add(1);
123        let frame_id = self.frame_id;
124
125        for track in &mut self.tracks {
126            track.predict();
127        }
128
129        let mut high = Vec::new();
130        let mut low = Vec::new();
131        for (index, detection) in detections.iter().enumerate() {
132            if detection.score() >= self.config.track_high_thresh {
133                high.push((index, *detection));
134            } else if detection.score() >= self.config.track_low_thresh {
135                low.push((index, *detection));
136            }
137        }
138
139        let mut tracked_indices = Vec::new();
140        let mut lost_indices = Vec::new();
141        let mut new_indices = Vec::new();
142        for (index, track) in self.tracks.iter().enumerate() {
143            match track.state {
144                TrackState::Tracked => tracked_indices.push(index),
145                TrackState::Lost => lost_indices.push(index),
146                TrackState::New => new_indices.push(index),
147                TrackState::Removed => {}
148            }
149        }
150        // Pool for first association: tracked + new + lost
151        let mut pool = Vec::new();
152        pool.extend(tracked_indices.iter().copied());
153        pool.extend(new_indices.iter().copied());
154        pool.extend(lost_indices.iter().copied());
155
156        let (matched_high, unmatched_pool, unmatched_high) =
157            self.associate(&pool, &high, self.config.match_thresh);
158
159        for &(track_i, det_i) in &matched_high {
160            let detection = high[det_i].1;
161            self.tracks[track_i].update(
162                detection.bbox(),
163                detection.score(),
164                detection.class_id(),
165                frame_id,
166            );
167        }
168
169        // Second stage: remaining pool tracks vs low-confidence detections.
170        let (matched_low, still_unmatched_pool, _) =
171            self.associate(&unmatched_pool, &low, self.config.match_thresh);
172
173        for &(track_i, det_i) in &matched_low {
174            let detection = low[det_i].1;
175            self.tracks[track_i].update(
176                detection.bbox(),
177                detection.score(),
178                detection.class_id(),
179                frame_id,
180            );
181        }
182
183        for track_i in still_unmatched_pool {
184            let track = &mut self.tracks[track_i];
185            if track.state == TrackState::Tracked || track.state == TrackState::New {
186                track.mark_lost();
187            }
188        }
189
190        // Activate new tracks from unmatched high-confidence detections.
191        for det_i in unmatched_high {
192            let detection = high[det_i].1;
193            if detection.score() < self.config.track_activation_thresh {
194                continue;
195            }
196            let id = TrackId(self.next_id);
197            self.next_id = self.next_id.saturating_add(1);
198            self.tracks.push(Track::new(
199                id,
200                detection.bbox(),
201                detection.score(),
202                detection.class_id(),
203                frame_id,
204            ));
205        }
206
207        // Expire lost tracks past the buffer.
208        for track in &mut self.tracks {
209            if track.state == TrackState::Lost
210                && track.time_since_update > self.config.max_time_lost
211            {
212                track.mark_removed();
213            }
214        }
215        self.tracks
216            .retain(|track| track.state != TrackState::Removed);
217
218        let mut output = Vec::new();
219        for track in &self.tracks {
220            if track.state != TrackState::Tracked && track.state != TrackState::New {
221                continue;
222            }
223            let detection = Detection::new(
224                track.predicted_bbox(),
225                track.score,
226                track.class_id,
227                Some(track.id),
228            )
229            .map_err(|_| TrackError::NonFinite)?;
230            output.push(detection);
231        }
232        Ok(output)
233    }
234
235    fn associate(
236        &self,
237        track_indices: &[usize],
238        detections: &[(usize, Detection)],
239        iou_threshold: f32,
240    ) -> (Vec<(usize, usize)>, Vec<usize>, Vec<usize>) {
241        if track_indices.is_empty() || detections.is_empty() {
242            return (
243                Vec::new(),
244                track_indices.to_vec(),
245                (0..detections.len()).collect(),
246            );
247        }
248
249        let track_boxes: Vec<Rect> = track_indices
250            .iter()
251            .map(|&i| self.tracks[i].predicted_bbox())
252            .collect();
253        let det_boxes: Vec<Rect> = detections.iter().map(|(_, d)| d.bbox()).collect();
254        let track_classes: Vec<Option<ClassId>> = track_indices
255            .iter()
256            .map(|&i| self.tracks[i].class_id)
257            .collect();
258        let det_classes: Vec<Option<ClassId>> =
259            detections.iter().map(|(_, d)| d.class_id()).collect();
260
261        let cand_cap = track_boxes.len().saturating_mul(det_boxes.len()).max(1);
262        let mut candidates = vec![
263            MatchCandidate {
264                track_index: 0,
265                detection_index: 0,
266                iou: 0.0,
267            };
268            cand_cap
269        ];
270        let mut track_used = vec![false; track_boxes.len()];
271        let mut det_used = vec![false; det_boxes.len()];
272        let mut matches = vec![(0_usize, 0_usize); track_boxes.len().min(det_boxes.len()).max(1)];
273        let mut unmatched_tracks = vec![0_usize; track_boxes.len()];
274        let mut unmatched_dets = vec![0_usize; det_boxes.len()];
275        let mut scratch = AssignScratch {
276            candidates: &mut candidates,
277            track_used: &mut track_used,
278            detection_used: &mut det_used,
279        };
280
281        let result = greedy_iou_assign(
282            &track_boxes,
283            &det_boxes,
284            &track_classes,
285            &det_classes,
286            self.config.class_aware,
287            iou_threshold,
288            &mut scratch,
289            &mut matches,
290            &mut unmatched_tracks,
291            &mut unmatched_dets,
292        );
293
294        let paired = matches[..result.match_count]
295            .iter()
296            .map(|&(ti, di)| (track_indices[ti], di))
297            .collect();
298        let unmatched_pool = unmatched_tracks[..result.unmatched_track_count]
299            .iter()
300            .map(|&ti| track_indices[ti])
301            .collect();
302        let unmatched_high = unmatched_dets[..result.unmatched_detection_count].to_vec();
303        (paired, unmatched_pool, unmatched_high)
304    }
305}