# nwojke/deep_sort architecture

> Architecture diagram of the GitHub repository nwojke/deep_sort, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nwojke/deep_sort
- Repository: https://github.com/nwojke/deep_sort

## Overview

Deep SORT is a multi-object tracker that combines motion estimates with deep appearance descriptors to associate detections across video frames. The primary workflow consumes MOTChallenge sequences and detection-feature files, tracks objects frame by frame, and writes tracking results. A separate feature-generation workflow extracts descriptors for detections; evaluation and result visualization are additional documented capabilities. The graph follows the README and sampled entry points; several tracker internals and evaluation behavior are represented only at the module level because their implementations were not sampled.

Main entry points: [`deep_sort/tracker.py`](https://github.com/nwojke/deep_sort/blob/master/deep_sort/tracker.py) (Multi-target tracker), [`deep_sort_app.py`](https://github.com/nwojke/deep_sort/blob/master/deep_sort_app.py) (Tracking application), [`show_results.py`](https://github.com/nwojke/deep_sort/blob/master/show_results.py) (Result viewer), [`tools/generate_detections.py`](https://github.com/nwojke/deep_sort/blob/master/tools/generate_detections.py) (Feature generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_features["Feature preparation"]
  node_featuregen["Feature generator"]
  node_freezer["Model freezer<br/>[freeze_model.py]"]
end

subgraph group_tracking["Tracking core"]
  node_tracker["Multi-target tracker<br/>[tracker.py]"]
  node_detection["Detection records<br/>[detection.py]"]
  node_track["Track state<br/>[track.py]"]
  node_kalman["Kalman filter<br/>[kalman_filter.py]"]
  node_assignment["Matching assignment"]
  node_appearance["Appearance metric<br/>[nn_matching.py]"]
  node_iou["IoU matching<br/>[iou_matching.py]"]
end

subgraph group_applications["Applications"]
  node_app["Tracking application<br/>[deep_sort_app.py]"]
  node_preprocess["Detection suppression<br/>[preprocessing.py]"]
  node_evaluator["MOT evaluator"]
end

subgraph group_presentation["Results and display"]
  node_resultviewer["Result viewer<br/>[show_results.py]"]
  node_visualization["Tracking visualization<br/>[visualization.py]"]
  node_viewer["Image viewer<br/>[image_viewer.py]"]
  node_videogenerator["Video generator<br/>[generate_videos.py]"]
end

node_user(("Researcher"))
node_motdata["MOT data"]
node_model["CNN model"]
node_featurefiles["Detection features"]
node_results["Tracking results"]
node_video["Rendered video"]

node_user -->|"requests descriptors"| node_featuregen
node_motdata -->|"provides frames and detections"| node_featuregen
node_model -->|"encodes crops"| node_featuregen
node_featuregen -->|"writes descriptors"| node_featurefiles
node_user -->|"starts tracking"| node_app
node_motdata -->|"provides sequence frames"| node_app
node_featurefiles -->|"provides detections and features"| node_app
node_app -->|"creates detections"| node_detection
node_app -->|"suppresses overlaps"| node_preprocess
node_app -->|"updates each frame"| node_tracker
node_tracker -->|"predicts and corrects"| node_kalman
node_tracker -->|"assigns matches"| node_assignment
node_tracker -->|"measures appearance distance"| node_appearance
node_tracker -->|"uses IoU matching"| node_iou
node_tracker -->|"maintains tracks"| node_track
node_tracker -->|"produces trajectories"| node_results
node_app -->|"writes MOT output"| node_results
node_results -->|"supplies trajectories"| node_evaluator
node_motdata -->|"supplies benchmark data"| node_evaluator
node_user -->|"requests visualization"| node_resultviewer
node_results -->|"supplies trajectories"| node_resultviewer
node_motdata -->|"supplies sequence frames"| node_resultviewer
node_resultviewer -->|"renders results"| node_visualization
node_visualization -->|"draws frames"| node_viewer
node_user -->|"requests video"| node_videogenerator
node_videogenerator -->|"renders sequences"| node_resultviewer
node_resultviewer -->|"writes video"| node_video
node_user -.->|"requests graph export"| node_freezer
node_freezer -.->|"exports inference graph"| node_model

click node_featuregen "https://github.com/nwojke/deep_sort/blob/master/tools/generate_detections.py"
click node_freezer "https://github.com/nwojke/deep_sort/blob/master/tools/freeze_model.py"
click node_app "https://github.com/nwojke/deep_sort/blob/master/deep_sort_app.py"
click node_tracker "https://github.com/nwojke/deep_sort/blob/master/deep_sort/tracker.py"
click node_detection "https://github.com/nwojke/deep_sort/blob/master/deep_sort/detection.py"
click node_track "https://github.com/nwojke/deep_sort/blob/master/deep_sort/track.py"
click node_kalman "https://github.com/nwojke/deep_sort/blob/master/deep_sort/kalman_filter.py"
click node_assignment "https://github.com/nwojke/deep_sort/blob/master/deep_sort/linear_assignment.py"
click node_appearance "https://github.com/nwojke/deep_sort/blob/master/deep_sort/nn_matching.py"
click node_iou "https://github.com/nwojke/deep_sort/blob/master/deep_sort/iou_matching.py"
click node_preprocess "https://github.com/nwojke/deep_sort/blob/master/application_util/preprocessing.py"
click node_evaluator "https://github.com/nwojke/deep_sort/blob/master/evaluate_motchallenge.py"
click node_resultviewer "https://github.com/nwojke/deep_sort/blob/master/show_results.py"
click node_visualization "https://github.com/nwojke/deep_sort/blob/master/application_util/visualization.py"
click node_viewer "https://github.com/nwojke/deep_sort/blob/master/application_util/image_viewer.py"
click node_videogenerator "https://github.com/nwojke/deep_sort/blob/master/generate_videos.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_featuregen,node_freezer toneBlue
class node_tracker,node_detection,node_track,node_kalman,node_assignment,node_appearance,node_iou toneAmber
class node_app,node_preprocess,node_evaluator toneMint
class node_resultviewer,node_visualization,node_viewer,node_videogenerator toneRose
class node_user,node_motdata,node_model,node_featurefiles,node_results,node_video toneIndigo
```

## Components

### Feature preparation

- [Feature generator](https://github.com/nwojke/deep_sort/blob/master/tools/generate_detections.py): `tools/generate_detections.py`
- [Model freezer](https://github.com/nwojke/deep_sort/blob/master/tools/freeze_model.py): `tools/freeze_model.py`

### Tracking core

- [Multi-target tracker](https://github.com/nwojke/deep_sort/blob/master/deep_sort/tracker.py): `deep_sort/tracker.py`
- [Detection records](https://github.com/nwojke/deep_sort/blob/master/deep_sort/detection.py): `deep_sort/detection.py`
- [Track state](https://github.com/nwojke/deep_sort/blob/master/deep_sort/track.py): `deep_sort/track.py`
- [Kalman filter](https://github.com/nwojke/deep_sort/blob/master/deep_sort/kalman_filter.py): `deep_sort/kalman_filter.py`
- [Matching assignment](https://github.com/nwojke/deep_sort/blob/master/deep_sort/linear_assignment.py): `deep_sort/linear_assignment.py`
- [Appearance metric](https://github.com/nwojke/deep_sort/blob/master/deep_sort/nn_matching.py): `deep_sort/nn_matching.py`
- [IoU matching](https://github.com/nwojke/deep_sort/blob/master/deep_sort/iou_matching.py): `deep_sort/iou_matching.py`

### Applications

- [Tracking application](https://github.com/nwojke/deep_sort/blob/master/deep_sort_app.py): `deep_sort_app.py`
- [Detection suppression](https://github.com/nwojke/deep_sort/blob/master/application_util/preprocessing.py): `application_util/preprocessing.py`
- [MOT evaluator](https://github.com/nwojke/deep_sort/blob/master/evaluate_motchallenge.py): `evaluate_motchallenge.py`

### Results and display

- [Result viewer](https://github.com/nwojke/deep_sort/blob/master/show_results.py): `show_results.py`
- [Tracking visualization](https://github.com/nwojke/deep_sort/blob/master/application_util/visualization.py): `application_util/visualization.py`
- [Image viewer](https://github.com/nwojke/deep_sort/blob/master/application_util/image_viewer.py): `application_util/image_viewer.py`
- [Video generator](https://github.com/nwojke/deep_sort/blob/master/generate_videos.py): `generate_videos.py`

### Other components

- **Researcher**
- **MOT data**
- **CNN model**
- **Detection features**
- **Tracking results**
- **Rendered video**

## Connections

- Researcher → Feature generator: requests descriptors
- MOT data → Feature generator: provides frames and detections
- CNN model → Feature generator: encodes crops
- Feature generator → Detection features: writes descriptors
- Researcher → Tracking application: starts tracking
- MOT data → Tracking application: provides sequence frames
- Detection features → Tracking application: provides detections and features
- Tracking application → Detection records: creates detections
- Tracking application → Detection suppression: suppresses overlaps
- Tracking application → Multi-target tracker: updates each frame
- Multi-target tracker → Kalman filter: predicts and corrects
- Multi-target tracker → Matching assignment: assigns matches
- Multi-target tracker → Appearance metric: measures appearance distance
- Multi-target tracker → IoU matching: uses IoU matching
- Multi-target tracker → Track state: maintains tracks
- Multi-target tracker → Tracking results: produces trajectories
- Tracking application → Tracking results: writes MOT output
- Tracking results → MOT evaluator: supplies trajectories
- MOT data → MOT evaluator: supplies benchmark data
- Researcher → Result viewer: requests visualization
- Tracking results → Result viewer: supplies trajectories
- MOT data → Result viewer: supplies sequence frames
- Result viewer → Tracking visualization: renders results
- Tracking visualization → Image viewer: draws frames
- Researcher → Video generator: requests video
- Video generator → Result viewer: renders sequences
- Result viewer → Rendered video: writes video
- Researcher → Model freezer: requests graph export
- Model freezer → CNN model: exports inference graph