Skip to main content

sightloom_tracking/
track.rs

1//! Single-object track state for `ByteTrack`.
2
3use crate::kalman::KalmanState;
4use sightloom_core::{ClassId, Rect, TrackId};
5
6/// Lifecycle state of a track.
7#[derive(Clone, Copy, Debug, Eq, PartialEq)]
8pub enum TrackState {
9    /// Newly created; not yet confirmed.
10    New,
11    /// Actively matched in recent frames.
12    Tracked,
13    /// Temporarily unmatched; retained for re-association.
14    Lost,
15    /// Expired and eligible for removal.
16    Removed,
17}
18
19/// One tracked object with Kalman state and metadata.
20#[derive(Clone, Copy, Debug, PartialEq)]
21pub struct Track {
22    /// Stable track identifier.
23    pub id: TrackId,
24    /// Current lifecycle state.
25    pub state: TrackState,
26    /// Optional class label carried from the activating detection.
27    pub class_id: Option<ClassId>,
28    /// Kalman filter state.
29    pub kalman: KalmanState,
30    /// Last associated detection score.
31    pub score: f32,
32    /// Frames since the last successful match.
33    pub time_since_update: u32,
34    /// Total frames this track has been observed.
35    pub hits: u32,
36    /// Frame index when the track was created.
37    pub start_frame: u64,
38    /// Frame index of the latest update.
39    pub frame_id: u64,
40}
41
42impl Track {
43    /// Creates a new track from a detection box.
44    #[must_use]
45    pub fn new(
46        id: TrackId,
47        rect: Rect,
48        score: f32,
49        class_id: Option<ClassId>,
50        frame_id: u64,
51    ) -> Self {
52        Self {
53            id,
54            state: TrackState::New,
55            class_id,
56            kalman: KalmanState::initiate(rect),
57            score,
58            time_since_update: 0,
59            hits: 1,
60            start_frame: frame_id,
61            frame_id,
62        }
63    }
64
65    /// Predicted bounding box.
66    #[must_use]
67    pub fn predicted_bbox(self) -> Rect {
68        self.kalman.to_rect()
69    }
70
71    /// Runs the Kalman predict step.
72    pub fn predict(&mut self) {
73        self.kalman.predict();
74        self.time_since_update = self.time_since_update.saturating_add(1);
75    }
76
77    /// Associates a detection and marks the track as tracked.
78    pub fn update(&mut self, rect: Rect, score: f32, class_id: Option<ClassId>, frame_id: u64) {
79        self.kalman.update(rect);
80        self.score = score;
81        if class_id.is_some() {
82            self.class_id = class_id;
83        }
84        self.time_since_update = 0;
85        self.hits = self.hits.saturating_add(1);
86        self.frame_id = frame_id;
87        self.state = if self.hits >= 2 {
88            TrackState::Tracked
89        } else {
90            TrackState::New
91        };
92    }
93
94    /// Marks the track as lost.
95    pub fn mark_lost(&mut self) {
96        self.state = TrackState::Lost;
97    }
98
99    /// Marks the track as removed.
100    pub fn mark_removed(&mut self) {
101        self.state = TrackState::Removed;
102    }
103}