Skip to content

trackforge / trackers / tracktrack

Module tracktrack

TrackTrack (CVPR 2025). A track-centric online tracker built on a ByteTrack-style two-stage lifecycle with two contributions.

  • Track-perspective association. Instead of one global assignment, each track picks its own best detection and a pair matches only when the choice is mutual. The loop repeats with a gate that tightens each round. High and low confidence detections share one pass, with low ones carrying a penalty rather than running as a separate stage. The cost fuses a height-modulated IoU, an optional appearance term, a confidence projection, and a velocity-direction term.
  • Track-aware initialization. A leftover detection starts a new track only if it clears an init threshold and does not overlap an existing active track, or a more confident leftover, by too much.

Appearance is optional. Pass embeddings to use the Re-ID term, or an empty slice to track on motion only.

This port keeps the two contributions and the fused cost. It uses the shared 8-dimensional Kalman filter, a simplified velocity-direction term, and does not reproduce the paper's detector-level NMS recovery pool, which needs access to the detector's suppressed boxes.

```rust,ignore use trackforge::trackers::tracktrack::TrackTrack;

let mut tracker = TrackTrack::new();

let detections = vec![([100.0, 100.0, 50.0, 100.0], 0.9, 0)]; let tracks = tracker.update(detections, &[]); for t in &tracks { println!("ID: {}, Box: {:?}", t.track_id, t.tlwh); } 

## Quick Reference

| Item | Kind | Description |
|------|------|-------------|
| [`Track`](#track) | struct | A single object tracked by TrackTrack. |
| [`TrackTrack`](#tracktrack) | struct | TrackTrack tracker. |
| [`TrackTrackParams`](#tracktrackparams) | struct | Settings for [`TrackTrack`]. |

## Types

### `Track`

```rust
struct Track {
    pub tlwh: [f32; 4],
    pub score: f32,
    pub class_id: i64,
    pub track_id: u64,
    pub state: crate::trackers::byte_track::TrackState,
    pub det_ind: Option<usize>,
    // [REDACTED: Private Fields]
}

A single object tracked by TrackTrack.

Fields

Name Type Description
tlwh [f32; 4] Bounding box in TLWH (top-left x, top-left y, width, height) format.
score f32 Detection confidence of the most recent match.
class_id i64 Class label of the most recent match.
track_id u64 Unique track identifier (0 until the track is activated).
state crate::trackers::byte_track::TrackState Lifecycle state.
det_ind Option<usize> Index of the last detection this track was matched to (None if never matched).

Trait Implementations

impl Clone for Track


fn clone(&self) -> Track


impl Debug for Track


fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result


fn to_subset(&self) -> Option<SS>


fn is_in_subset(&self) -> bool


fn to_subset_unchecked(&self) -> SS


fn from_subset(element: &SS) -> SP

TrackTrack

struct TrackTrack {
    // [REDACTED: Private Fields]
}

TrackTrack tracker.

See the module documentation for the algorithm. The two contributions are a track-perspective association and a track-aware initialization. Appearance is used when embeddings are supplied, otherwise the tracker runs on motion only.

Implementations

fn from_params(params: TrackTrackParams) -> Self

Create a TrackTrack tracker from a TrackTrackParams.

fn new() -> Self

Create a TrackTrack tracker with the default parameters.

fn update(&mut self, detections: Vec<([f32; 4], f32, i64)>, embeddings: &[Vec<f32>]) -> Vec<Track>

Update the tracker with the current frame's detections and optional embeddings.

Pass an empty embeddings slice to track on motion only. Returns the confirmed

tracks active in this frame.

fn update_with_camera_motion(&mut self, detections: Vec<([f32; 4], f32, i64)>, embeddings: &[Vec<f32>], camera_motion: &CameraMotion) -> Vec<Track>

Update the tracker, first warping track predictions by camera_motion.

Trait Implementations

impl Default for TrackTrack


fn default() -> Self


fn to_subset(&self) -> Option<SS>


fn is_in_subset(&self) -> bool


fn to_subset_unchecked(&self) -> SS


fn from_subset(element: &SS) -> SP

TrackTrackParams

struct TrackTrackParams {
    pub common: crate::trackers::common::CommonParams,
    pub det_thresh: f32,
    pub match_thresh: f32,
    pub init_thresh: f32,
    pub tai_thresh: f32,
    pub penalty_low: f32,
    pub reduce_step: f32,
}

Settings for TrackTrack.

Shared lifecycle fields live in CommonParams; TrackTrack maps its lost buffer onto common.max_age and its confirmation length onto common.min_hits. The rest are TrackTrack specific. Build it with default.

Fields

Name Type Description
common crate::trackers::common::CommonParams Shared lifecycle settings. common.max_age is the lost buffer, common.min_hits is how many matched frames confirm a new track.
det_thresh f32 Score above which a detection is high confidence and matched first. Lower scores are still offered to tracked tracks in the same pass, carrying a penalty.
match_thresh f32 Association cost gate. A track and a detection match only when their fused cost is below this. Lower is stricter.
init_thresh f32 Smallest score a leftover detection needs before it may start a new track.
tai_thresh f32 Overlap gate for track-aware initialization. A leftover detection is dropped if it overlaps an existing active track, or a more confident leftover, by more than this IoU. This is a maximum IoU.
penalty_low f32 Extra cost added to low confidence detections during association, so they only win a match when nothing better is available.
reduce_step f32 How much the association cost gate tightens on each round of the track-perspective matching loop.

Trait Implementations

impl Clone for TrackTrackParams


fn clone(&self) -> TrackTrackParams


impl Copy for TrackTrackParams

impl Debug for TrackTrackParams


fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result


impl Default for TrackTrackParams


fn default() -> Self


impl PartialEq for TrackTrackParams


fn eq(&self, other: &TrackTrackParams) -> bool


fn to_subset(&self) -> Option<SS>


fn is_in_subset(&self) -> bool


fn to_subset_unchecked(&self) -> SS


fn from_subset(element: &SS) -> SP