Skip to content

trackforge / trackers / common

Module common

Building blocks shared across the trackers.

TrackState is the common confirm/delete lifecycle used by the IoU and appearance trackers, and KalmanTrack wraps the per-track Kalman state with the predict/update mechanics they all repeat. cmc holds the shared camera motion compensation transform.

Quick Reference

Item Kind Description
association mod Observation-centric association helpers shared by OC-SORT and Deep OC-SORT.
byte_cascade mod Shared two-stage association cascade for the ByteTrack family.
cmc mod Camera motion compensation (CMC) shared across trackers.
obs_track mod Observation-centric Kalman track shared by OC-SORT and Deep OC-SORT.
params mod Parameters shared by every tracker.
KalmanTrack struct Per-track Kalman state plus the predict/update steps every tracker repeats.
TrackState enum Lifecycle state of a track.

Modules

  • association — Observation-centric association helpers shared by OC-SORT and Deep OC-SORT.
  • byte_cascade — Shared two-stage association cascade for the ByteTrack family.
  • cmc — Camera motion compensation (CMC) shared across trackers.
  • obs_track — Observation-centric Kalman track shared by OC-SORT and Deep OC-SORT.
  • params — Parameters shared by every tracker.

Types

CameraMotion

struct CameraMotion {
    pub a: f32,
    pub b: f32,
    pub tx: f32,
    pub c: f32,
    pub d: f32,
    pub ty: f32,
}

A 2x3 affine camera-motion transform [[a, b, tx], [c, d, ty]].

Maps a previous-frame point (x, y) to (a*x + b*y + tx, c*x + d*y + ty). The default is the identity (no camera motion).

Fields

Name Type Description
a f32 Row 0 of the linear part.
tx f32 Horizontal translation.
c f32 Row 1 of the linear part.
ty f32 Vertical translation.

Implementations

fn new(a: f32, b: f32, tx: f32, c: f32, d: f32, ty: f32) -> Self

Build a transform from the six affine coefficients.

fn identity() -> Self

The identity transform (no camera motion).

fn is_identity(&self) -> bool

Whether this transform is the identity, so application can be skipped.

fn apply_state(&self, mean: &mut StateVector, covariance: &mut CovarianceMatrix)

Warp a Kalman mean and covariance in place.

fn apply_observation(&self, obs: &mut MeasurementVector)

Warp an XYAH observation [cx, cy, aspect, height] in place.

Trait Implementations

impl Clone for CameraMotion


fn clone(&self) -> CameraMotion


impl Copy for CameraMotion

impl Debug for CameraMotion


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


impl Default for CameraMotion


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

ObsTrack

struct ObsTrack {
    pub tlwh: [f32; 4],
    pub score: f32,
    pub class_id: i64,
    pub track_id: u64,
    pub state: crate::trackers::common::TrackState,
    pub hits: usize,
    pub hit_streak: usize,
    pub time_since_update: usize,
    pub age: usize,
    pub det_ind: Option<usize>,
    // [REDACTED: Private Fields]
}

A tracked object with an observation history.

Shared by OC-SORT and Deep OC-SORT (each re-exports it under its own name).

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 monotonically increasing track identifier.
state crate::trackers::common::TrackState Current lifecycle state.
hits usize Total number of detection matches over the track lifetime.
hit_streak usize Consecutive detection matches without interruption (resets on a missed frame).
time_since_update usize Frames elapsed since the last detection match.
age usize Total frames since track creation.
det_ind Option<usize> Index of the detection this track was most recently matched to (in the current frame's detection list), or None when unmatched this frame.

Implementations

fn is_confirmed(&self) -> bool

Whether the track has been confirmed and is returned to callers.

Trait Implementations

impl Clone for ObsTrack


fn clone(&self) -> ObsTrack


impl Debug for ObsTrack


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

CommonParams

struct CommonParams {
    pub max_age: usize,
    pub min_hits: usize,
}

Lifecycle settings common to all trackers.

Fields

Name Type Description
max_age usize How many frames a track stays alive after it stops matching any detection. If an object is missed or hidden for up to this many frames, the track keeps its id and can be picked back up when the object returns. Past this the track is dropped. Larger values ride out longer occlusions but risk keeping stale tracks and handing an old id to a different object. Some trackers call this the track buffer; it is the same thing.
min_hits usize How many matched frames in a row a new track needs before it is confirmed and returned to the caller. Larger values suppress flickering false tracks from one-off detections but delay when a real object first shows up in the output. Some trackers call this n_init; it is the same thing.

Implementations

fn new(max_age: usize, min_hits: usize) -> Self

Build the common lifecycle settings directly.

Trait Implementations

impl Clone for CommonParams


fn clone(&self) -> CommonParams


impl Copy for CommonParams

impl Debug for CommonParams


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


impl Default for CommonParams


fn default() -> Self


impl Eq for CommonParams

impl PartialEq for CommonParams


fn eq(&self, other: &CommonParams) -> 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

KalmanTrack

struct KalmanTrack {
    pub mean: crate::utils::kalman::StateVector,
    pub covariance: crate::utils::kalman::CovarianceMatrix,
}

Per-track Kalman state plus the predict/update steps every tracker repeats.

Holds the 8-dimensional mean and covariance and applies the shared KalmanFilter. The owning track keeps its own box, score, and lifecycle fields and delegates the filtering to this type.

Fields

Name Type Description
mean crate::utils::kalman::StateVector Kalman filter state mean ([x, y, a, h, vx, vy, va, vh]).
covariance crate::utils::kalman::CovarianceMatrix Kalman filter state covariance.

Implementations

fn initiate(measurement: &MeasurementVector, kf: &KalmanFilter) -> Self

Initialise the filter from a first measurement in XYAH form.

fn predict(&mut self, kf: &KalmanFilter) -> [f32; 4]

Run one Kalman prediction step and return the refreshed TLWH box.

fn update(&mut self, measurement: &MeasurementVector, kf: &KalmanFilter)

Correct the state with a matched measurement in XYAH form.

fn apply_camera_motion(&mut self, cmc: &CameraMotion) -> [f32; 4]

Warp the Kalman state by a camera motion transform and return the new TLWH box.

Trait Implementations

impl Clone for KalmanTrack


fn clone(&self) -> KalmanTrack


impl Debug for KalmanTrack


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

TrackState

enum TrackState {
    Tentative,
    Confirmed,
    Deleted,
}

Lifecycle state of a track.

A track starts Tentative, becomes Confirmed once it has accumulated enough matches, and is Deleted when it ages out or fails confirmation.

Variants

  • Tentative

Newly created; not yet confirmed by enough matches.

  • Confirmed

Confirmed active track returned to callers.

  • Deleted

Marked for removal.

Trait Implementations

impl Clone for TrackState


fn clone(&self) -> TrackState


impl Copy for TrackState

impl Debug for TrackState


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


impl Eq for TrackState

impl PartialEq for TrackState


fn eq(&self, other: &TrackState) -> 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