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
DeepSort struct Deep SORT tracker implementation.

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


impl Read<Exclusive, BecauseExclusive> for NearestNeighborDistanceMetric


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>>,
    // [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.

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


impl Read<Exclusive, BecauseExclusive> for Track


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


impl Read<Exclusive, BecauseExclusive> for DeepSortTracker


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


fn is_in_subset(&self) -> bool


fn to_subset_unchecked(&self) -> SS


fn from_subset(element: &SS) -> SP

DeepSort<E: AppearanceExtractor>

struct DeepSort<E: AppearanceExtractor> {
    // [REDACTED: Private Fields]
}

Deep SORT tracker implementation.

Wraps the tracker logic and appearance feature extraction.

Implementations

fn new(extractor: E, max_age: usize, n_init: usize, max_iou_distance: f32, max_cosine_distance: f32, nn_budget: usize) -> Self

Create a new Deep SORT tracker.

# Arguments

Argument Description
extractor The appearance feature extractor.
max_age Maximum frames to keep a track without detection. Default: 70.
n_init Minimum hits to confirm a track. Default: 3.
max_iou_distance Threshold for IoU matching. Default: 0.7.
max_cosine_distance Threshold for cosine distance matching. Default: 0.2.
nn_budget Maximum library size for appearance features. Default: 100. 

fn update(&mut self, image: &DynamicImage, detections: Vec<(BoundingBox, f32, i64)>) -> Result<Vec<Track>, Box<dyn Error>>

Update the tracker with new frame and detections.

# Arguments

Argument Description
image The current video frame.
detections List of (BoundingBox, Score, ClassID).

# Returns

List of confirmed tracks.

fn new_default(extractor: E) -> Self

Trait Implementations

impl Read<Exclusive, BecauseExclusive> for DeepSort<E>


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


impl Read<Exclusive, BecauseExclusive> for Metric


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


impl Read<Exclusive, BecauseExclusive> for TrackState


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


fn is_in_subset(&self) -> bool


fn to_subset_unchecked(&self) -> SS


fn from_subset(element: &SS) -> SP