Skip to main content

sightloom_tracking/
metrics.rs

1//! Baseline multi-object tracking metrics for synthetic regression and smoke benches.
2//!
3//! These are **CLEAR-style baseline** helpers, not a full TrackEval/HOTA stack.
4//! Until MOT17/MOT20/DanceTrack numbers are published, call the tracker a
5//! **baseline** association tracker rather than a complete `ByteTrack` port.
6#![allow(clippy::cast_possible_truncation, clippy::too_many_lines)]
7
8#[cfg(feature = "alloc")]
9extern crate alloc;
10
11#[cfg(feature = "alloc")]
12use alloc::vec;
13#[cfg(feature = "alloc")]
14use alloc::vec::Vec;
15
16use sightloom_core::{Rect, TrackId, iou};
17
18/// One ground-truth or hypothesis box in a frame.
19#[derive(Clone, Copy, Debug, PartialEq)]
20pub struct MotObject {
21    /// Stable identity (GT id or predicted track id).
22    pub id: u32,
23    /// Axis-aligned box.
24    pub bbox: Rect,
25}
26
27/// One frame of GT and hypotheses.
28#[derive(Clone, Debug, PartialEq)]
29pub struct MotFrame {
30    /// Ground-truth objects.
31    pub gt: Vec<MotObject>,
32    /// Tracker hypotheses.
33    pub hyp: Vec<MotObject>,
34}
35
36/// Aggregate baseline MOT metrics over a sequence.
37#[derive(Clone, Copy, Debug, Default, PartialEq)]
38pub struct BaselineMotMetrics {
39    /// Frames evaluated.
40    pub frames: u32,
41    /// True positives (matched pairs).
42    pub true_positives: u32,
43    /// False positives.
44    pub false_positives: u32,
45    /// False negatives (missed GT).
46    pub false_negatives: u32,
47    /// Identity switches (matched GT whose hyp id changed vs previous frame).
48    pub id_switches: u32,
49    /// Fragmentations (GT reappears after a gap under a new hyp id).
50    pub fragmentations: u32,
51    /// CLEAR MOTA in approximately `(-inf, 1]`.
52    pub mota: f32,
53    /// Precision `TP / (TP + FP)`.
54    pub precision: f32,
55    /// Recall `TP / (TP + FN)`.
56    pub recall: f32,
57    /// Simple IDF1 approximation: `2 * IDTP / (2 * IDTP + IDFP + IDFN)`.
58    pub idf1: f32,
59}
60
61/// Evaluates baseline CLEAR metrics with greedy `IoU` matching per frame.
62///
63/// Matching threshold is applied as minimum `IoU` for a valid association.
64#[must_use]
65pub fn evaluate_baseline_mot(frames: &[MotFrame], iou_threshold: f32) -> BaselineMotMetrics {
66    let mut tp = 0_u32;
67    let mut fp = 0_u32;
68    let mut fn_ = 0_u32;
69    let mut id_switches = 0_u32;
70    let mut fragmentations = 0_u32;
71    let mut idtp = 0_u32;
72    let mut idfp = 0_u32;
73    let mut idfn = 0_u32;
74
75    // Last hyp id matched to each GT id.
76    let mut last_match: Vec<(u32, u32)> = Vec::new(); // (gt_id, hyp_id)
77    // GT ids seen as unmatched in the previous frame (for fragmentation).
78    let mut prev_unmatched_gt: Vec<u32> = Vec::new();
79
80    for frame in frames {
81        let mut used_gt = vec![false; frame.gt.len()];
82        let mut used_hyp = vec![false; frame.hyp.len()];
83        let mut pairs: Vec<(usize, usize, f32)> = Vec::new();
84        for (gi, g) in frame.gt.iter().enumerate() {
85            for (hi, h) in frame.hyp.iter().enumerate() {
86                let score = iou(g.bbox, h.bbox);
87                if score >= iou_threshold {
88                    pairs.push((gi, hi, score));
89                }
90            }
91        }
92        pairs.sort_by(|a, b| b.2.partial_cmp(&a.2).unwrap_or(core::cmp::Ordering::Equal));
93
94        let mut frame_matches: Vec<(u32, u32)> = Vec::new();
95        for (gi, hi, _) in pairs {
96            if used_gt[gi] || used_hyp[hi] {
97                continue;
98            }
99            used_gt[gi] = true;
100            used_hyp[hi] = true;
101            tp = tp.saturating_add(1);
102            let gt_id = frame.gt[gi].id;
103            let hyp_id = frame.hyp[hi].id;
104            frame_matches.push((gt_id, hyp_id));
105            if let Some((_, prev_hyp)) = last_match.iter().find(|(g, _)| *g == gt_id)
106                && *prev_hyp != hyp_id
107            {
108                id_switches = id_switches.saturating_add(1);
109            }
110            // Identity-aware TP when the same hyp id stays with the GT.
111            if last_match.iter().any(|(g, h)| *g == gt_id && *h == hyp_id)
112                || last_match.iter().all(|(g, _)| *g != gt_id)
113            {
114                idtp = idtp.saturating_add(1);
115            }
116            if prev_unmatched_gt.contains(&gt_id)
117                && last_match
118                    .iter()
119                    .find(|(g, _)| *g == gt_id)
120                    .is_some_and(|(_, h)| *h != hyp_id)
121            {
122                fragmentations = fragmentations.saturating_add(1);
123            }
124        }
125
126        for (gi, g) in frame.gt.iter().enumerate() {
127            if !used_gt[gi] {
128                fn_ = fn_.saturating_add(1);
129                idfn = idfn.saturating_add(1);
130            }
131            let _ = g;
132        }
133        for (hi, _) in frame.hyp.iter().enumerate() {
134            if !used_hyp[hi] {
135                fp = fp.saturating_add(1);
136                idfp = idfp.saturating_add(1);
137            }
138        }
139
140        // Update last_match for matched GTs; drop GTs not present this frame.
141        let present_gt: Vec<u32> = frame.gt.iter().map(|g| g.id).collect();
142        last_match.retain(|(g, _)| present_gt.contains(g));
143        for (gt_id, hyp_id) in &frame_matches {
144            if let Some(slot) = last_match.iter_mut().find(|(g, _)| g == gt_id) {
145                slot.1 = *hyp_id;
146            } else {
147                last_match.push((*gt_id, *hyp_id));
148            }
149        }
150        prev_unmatched_gt = frame
151            .gt
152            .iter()
153            .enumerate()
154            .filter(|(i, _)| !used_gt[*i])
155            .map(|(_, g)| g.id)
156            .collect();
157    }
158
159    let frames_n = u32::try_from(frames.len()).unwrap_or(u32::MAX);
160    let denom = tp.saturating_add(fn_);
161    let mota = if denom == 0 {
162        0.0
163    } else {
164        1.0 - ((fn_.saturating_add(fp).saturating_add(id_switches) as f32) / (denom as f32))
165    };
166    let precision = if tp.saturating_add(fp) == 0 {
167        0.0
168    } else {
169        (tp as f32) / (tp.saturating_add(fp) as f32)
170    };
171    let recall = if denom == 0 {
172        0.0
173    } else {
174        (tp as f32) / (denom as f32)
175    };
176    let id_denom = (2 * idtp).saturating_add(idfp).saturating_add(idfn);
177    let idf1 = if id_denom == 0 {
178        0.0
179    } else {
180        (2.0 * (idtp as f32)) / (id_denom as f32)
181    };
182
183    BaselineMotMetrics {
184        frames: frames_n,
185        true_positives: tp,
186        false_positives: fp,
187        false_negatives: fn_,
188        id_switches,
189        fragmentations,
190        mota,
191        precision,
192        recall,
193        idf1,
194    }
195}
196
197/// Helper: wraps a track id + rect as a MOT object.
198#[must_use]
199pub fn mot_from_track(track_id: TrackId, bbox: Rect) -> MotObject {
200    MotObject {
201        id: track_id.0,
202        bbox,
203    }
204}
205
206#[cfg(test)]
207mod tests {
208    use super::*;
209    use sightloom_core::Rect;
210
211    #[test]
212    fn perfect_tracking_scores_high_mota() {
213        let box_a = Rect::new(0.0, 0.0, 10.0, 20.0).unwrap();
214        let frames = [
215            MotFrame {
216                gt: vec![MotObject { id: 1, bbox: box_a }],
217                hyp: vec![MotObject { id: 7, bbox: box_a }],
218            },
219            MotFrame {
220                gt: vec![MotObject { id: 1, bbox: box_a }],
221                hyp: vec![MotObject { id: 7, bbox: box_a }],
222            },
223        ];
224        let m = evaluate_baseline_mot(&frames, 0.5);
225        assert_eq!(m.true_positives, 2);
226        assert_eq!(m.false_positives, 0);
227        assert_eq!(m.false_negatives, 0);
228        assert_eq!(m.id_switches, 0);
229        assert!((m.mota - 1.0).abs() < 1e-5);
230        assert!((m.precision - 1.0).abs() < 1e-5);
231        assert!((m.recall - 1.0).abs() < 1e-5);
232    }
233
234    #[test]
235    fn id_switch_is_counted() {
236        let box_a = Rect::new(0.0, 0.0, 10.0, 20.0).unwrap();
237        let frames = [
238            MotFrame {
239                gt: vec![MotObject { id: 1, bbox: box_a }],
240                hyp: vec![MotObject { id: 7, bbox: box_a }],
241            },
242            MotFrame {
243                gt: vec![MotObject { id: 1, bbox: box_a }],
244                hyp: vec![MotObject { id: 9, bbox: box_a }],
245            },
246        ];
247        let m = evaluate_baseline_mot(&frames, 0.5);
248        assert_eq!(m.id_switches, 1);
249        assert!(m.mota < 1.0);
250    }
251}