Skip to content

trackforge / trackers / deepsort

Module deepsort

DeepSORT (Simple Online and Realtime Tracking with a Deep Association Metric) implementation.

This module provides a DeepSORT tracker that uses appearance features for more robust tracking.

Quick Reference

Item Kind Description
DeepSortParams struct Settings for DeepSort.

Types

NearestNeighborDistanceMetric

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

A nearest neighbor distance metric for deep association.

Keeps a history of features (samples) for each target (track) and computes the minimum distance between a new feature and the stored history.

Implementations

fn new(metric: Metric, matching_threshold: f32, budget: Option<usize>) -> Self

Create a new distance metric.

# Arguments

Argument Description
metric The distance metric to use (Euclidean or Cosine).
matching_threshold Threshold for matching.
budget Optional maximum number of samples to keep per track. 

fn partial_fit(&mut self, features: &[(u64, Vec<f32>)], active_targets: &[u64])

Update the sample gallery with new features.

# Arguments

Argument Description
features Map from track_id to a list of new features.
active_targets List of track IDs that are currently active (confirmed). Sample galleries for inactive targets will be removed. 

fn distance(&self, features: &[Vec<f32>], targets: &[u64]) -> Vec<Vec<f32>>

Compute the distance matrix between tracks and detections.

# Arguments

Argument Description
features A map of detection indices to their feature vectors (usually we pass a list of features corresponding to detections).
targets List of track IDs to compare against.

# Returns

An n_targets x n_features matrix of distances.

fn matching_threshold(&self) -> f32

Trait Implementations

impl Clone for NearestNeighborDistanceMetric


fn clone(&self) -> NearestNeighborDistanceMetric


impl Debug for NearestNeighborDistanceMetric


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

Track

struct Track {
    pub track_id: u64,
    pub class_id: i64,
    pub hits: usize,
    pub age: usize,
    pub time_since_update: usize,
    pub state: TrackState,
    pub mean: crate::utils::kalman::StateVector,
    pub covariance: crate::utils::kalman::CovarianceMatrix,
    pub score: f32,
    pub features: Vec<Vec<f32>>,
    pub det_ind: Option<usize>,
    // [REDACTED: Private Fields]
}

A single object track maintained by the DeepSORT tracker.

Fields

Name Type Description
track_id u64 Unique track identifier.
class_id i64 Class label of the tracked object.
hits usize Number of times this track has been matched to a detection.
age usize Total frames since the track was created.
time_since_update usize Frames elapsed since the last successful detection match.
state TrackState Current life-cycle state.
mean crate::utils::kalman::StateVector Kalman filter mean state [x, y, a, h, vx, vy, va, vh].
covariance crate::utils::kalman::CovarianceMatrix Kalman filter covariance matrix.
score f32 Detection confidence of the last matched detection.
features Vec<Vec<f32>> Appearance embeddings accumulated since the last metric-gallery flush.
det_ind Option<usize> Index of the last detection this track was matched to (None if never matched).

Implementations

fn new(mean: StateVector, covariance: CovarianceMatrix, track_id: u64, class_id: i64, n_init: usize, max_age: usize, score: f32, feature: Vec<f32>) -> Self


fn tlwh_to_xyah(tlwh: &[f32; 4]) -> MeasurementVector

Convert TLWH to (x, y, a, h)

fn xyah_to_tlwh(state: &StateVector) -> [f32; 4]

Convert (x, y, a, h) to TLWH

fn to_tlwh(&self) -> [f32; 4]


fn predict(&mut self, kf: &KalmanFilter)


fn update(&mut self, kf: &KalmanFilter, detection: &MeasurementVector, score: f32, class_id: i64, feature: Vec<f32>)


fn mark_missed(&mut self)


fn is_confirmed(&self) -> bool


fn is_tentative(&self) -> bool


fn is_deleted(&self) -> bool

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

DeepSortTracker

struct DeepSortTracker {
    pub metric: crate::trackers::deepsort::nn_matching::NearestNeighborDistanceMetric,
    pub max_age: usize,
    pub n_init: usize,
    pub tracks: Vec<crate::trackers::deepsort::track::Track>,
    pub kf: crate::utils::kalman::KalmanFilter,
    pub max_iou_distance: f32,
    pub next_id: u64,
}

Implementations

fn new(metric: NearestNeighborDistanceMetric, max_age: usize, n_init: usize, max_iou_distance: f32) -> Self


fn predict(&mut self)


fn update(&mut self, detections: &[(crate::types::BoundingBox, f32, i64)], embeddings: &[Vec<f32>])


fn initiate_track(&mut self, tlwh: &[f32; 4], score: f32, class_id: i64, embedding: Vec<f32>)

Trait Implementations

impl Clone for DeepSortTracker


fn clone(&self) -> DeepSortTracker


impl Debug for DeepSortTracker


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

DeepSortParams

struct DeepSortParams {
    pub common: crate::trackers::common::CommonParams,
    pub max_iou_distance: f32,
    pub max_cosine_distance: f32,
    pub nn_budget: usize,
}

Settings for DeepSort.

Shared lifecycle fields live in CommonParams; DeepSORT reads its confirmation count from common.min_hits, what it calls n_init. The rest are DeepSORT specific. Build it with default.

Fields

Name Type Description
common crate::trackers::common::CommonParams Shared lifecycle settings. common.min_hits is DeepSORT's n_init.
max_iou_distance f32 Match cutoff for the IoU fallback stage, given as a maximum IoU distance of one minus IoU. A pair matches when its IoU distance is at or below this, so 0.7 means the boxes only need an IoU of 0.3. Lower is stricter.
max_cosine_distance f32 How different two appearance embeddings may be and still count as the same object, measured as cosine distance from zero to two. Lower demands a closer appearance match and cuts id switches, at the cost of more lost tracks.
nn_budget usize How many past appearance embeddings to keep per track for Re-ID. When the gallery is full the oldest is dropped. Larger remembers more of how the object looked over time but uses more memory and compute.

Trait Implementations

impl Clone for DeepSortParams


fn clone(&self) -> DeepSortParams


impl Copy for DeepSortParams

impl Debug for DeepSortParams


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


impl Default for DeepSortParams


fn default() -> Self


impl PartialEq for DeepSortParams


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

Metric

enum Metric {
    Euclidean,
    Cosine,
}

Trait Implementations

impl Clone for Metric


fn clone(&self) -> Metric


impl Copy for Metric

impl Debug for Metric


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


impl Eq for Metric

impl PartialEq for Metric


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

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