Unitrack

Getting Started

Getting Started

unitrack requires Python 3.13 and PyTorch 2.7 or newer.

Installation

From PyPI

pip install unitrack

Optional dependencies

Solvers (built-in)

All solvers ship in-tree and need no extras: unitrack.assignment.Hungarian, unitrack.assignment.Greedy, unitrack.assignment.Auction, unitrack.assignment.lap.LAP, and the C++ Jonker-Volgenant family unitrack.assignment.Jonker / unitrack.assignment.LAPJVS / unitrack.assignment.LAPJVX. Jonker is an alias for the AVX2-vectorized in-tree LAPJVX solver. See the API reference for the full signature of each.

Benchmark comparisons

To include the external lapx reference solver when running benchmarks:

pip install "unitrack[bench]"
# or, from source:
uv sync --extra bench

From source

git clone https://github.com/tue-p8n/unitrack
cd unitrack
uv sync

torch.utils.cpp_extension JIT-compiles the CPU assignment extensions (lapjv, lapjvx) on first import. The build needs a C++17-capable compiler and reads AVX2/FMA flags from /proc/cpuinfo automatically.

Development workflow

just serves as the task runner. Common recipes:

just test            # full test suite (parallel)
just coverage        # tests + HTML coverage report
just bench           # both assignment benchmarks, refreshes assets/benchmarks/
just bench-batched   # batched benchmark only
just lint            # ruff + clang-format check
just format          # ruff + clang-format fix
just docs            # build the docyard documentation site
just info            # print CUDA availability and nvcc version
just clangd          # regenerate compile_flags.txt for clangd

Install pre-commit hooks via prek:

prek install

Quick example

The project README contains a runnable three-frame example that wires Detections, Pipe, the Jonker solver, and a single position state into a Tracker and a MultiStream wrapper. Run it first to confirm the install before reaching for the more elaborate recipes.

Tracker recipes

Self-contained recipes live under docs/6.recipes/. Two port 1.x trackers:

  • recipes/sort — SORT (Bewley et al., 2016) as one Pipe with BoxIoU cost and a KalmanBBox state. Shows how to combine an IoU cost on bbox_xyxy with a bbox_xyah Kalman update via a projection state.
  • recipes/overlap_tracker — the 1.x models.overlap tracker: class- and score-gated IoU matching with Gated and Sequential.

Four more assemble appearance and motion trackers from the same primitives (these mirror the HOTA benchmark's tracker registry):

Read the recipes as the canonical worked examples of "stage tree plus state dictionary plus lifecycle policy".

Tutorial notebooks

The seven-notebook tour covers the library at a higher resolution than the recipes:

  1. Quickstart — build and run a minimal tracker; visualize trajectories.
  2. Data model — the typed records and the Gate algebra.
  3. Costs and gates — the cost zoo (Cosine, CDist, BiSoftmax, RBF, IoU family, Mahalanobis) and the gate zoo (Class, Score, Spatial, Motion).
  4. Pipeline tree — Pipe, Sequential, Parallel, Gated, Filter, Iterate; cascaded versus parallel fusion.
  5. States and lifecycle — Process × Observation, Kalman, EMA; Tentative → Active → Lost → Removed.
  6. Cascaded and parallel — K=2 configurations compared end-to-end on synthetic data with known ground truth.
  7. Migration — migrate a 1.x tracker to 2.0 and showcase the new possibilities (parallel fusion, cascaded matching, lifecycle, differentiable matching), driven by a real lightweight Hugging Face detector.

Each notebook is self-contained; read in order if new to the library, or jump straight to the topic you need.

API reference

The API reference lists every public symbol grouped by subpackage. Use it as the lookup surface once the recipes and tutorials have made the shape of the library familiar.

Recipe: two-stage cascade tracker