# SimpleTrack Deep-Dive Tutorial Series

A hands-on, math-anchored walkthrough of **SimpleTrack** (Pang et al., 2021,
[arXiv:2111.09621](https://arxiv.org/abs/2111.09621)) - the 3D multi-object
tracker we run **after** BEVFusion in `perception/`. Every concept is derived
and then demonstrated with a runnable, self-contained numpy/matplotlib cell; the
final notebook runs the modules on the **real BEVFusion detection JSON**.

## Notebooks

| # | Notebook | What you learn |
|---|----------|----------------|
| 01 | [`01_mot_problem_and_pipeline.ipynb`](01_mot_problem_and_pipeline.ipynb) | The online 3D-MOT problem, notation (FP/FN/IDS/FRAG), and the 4-module tracking-by-detection pipeline SimpleTrack ablates. |
| 02 | [`02_kalman_filter_motion_models.ipynb`](02_kalman_filter_motion_models.ipynb) | Motion models + the **Kalman filter**: full predict/update equations, a from-scratch 10-D constant-velocity 3D-box KF, CV vs CA, and the yaw wrap-around fix. |
| 03 | [`03_data_association_iou_giou_hungarian.ipynb`](03_data_association_iou_giou_hungarian.ipynb) | Association affinities - L2, 3D **IoU**, and **GIoU** (why SimpleTrack picks GIoU) - plus the **Hungarian** solver and Mahalanobis gating. |
| 04 | [`04_two_stage_association_and_lifecycle.ipynb`](04_two_stage_association_and_lifecycle.ipynb) | SimpleTrack's **two-stage association**, score-threshold + **3D NMS** pre-processing, the confirmed/tentative **life-cycle**, id assignment, and motion-based **re-identification** across occlusions. |
| 05 | [`05_amota_metrics_and_end_to_end.ipynb`](05_amota_metrics_and_end_to_end.ipynb) | **AMOTA/AMOTP** (and CLEAR-MOT MOTA/MOTP) metrics, and running the tracker on the **real BEVFusion `results_nusc.json`** end-to-end. |
| 06 | [`06_failure_modes_and_analysis.ipynb`](06_failure_modes_and_analysis.ipynb) | In-depth **failure-mode analysis**: detector FP/FN, state **initialization**, **filter divergence**, **assignment** failures, **wrong associations / ID switches**, **occlusion** & **re-identification**, yaw/size geometry pitfalls; each reproduced + tied to IDS/FRAG and the controlling knob, plus a failure probe on the real BEVFusion detections. |

## Design of these notebooks

Like the BEVFusion series, every notebook is robust to a partially-built
environment: heavy deps (`shapely`, `scipy`, `nuscenes-devkit`, the vendored
`simpletrack`) are imported inside `try/except` with pure-numpy fallbacks, so the
math, equations, and visualizations always run. The "real tracker / real metric"
paths light up automatically when the deps and the detection JSON are present.

## Running (in the reproducible container)

From the repo root, using the shared launcher:

```bash
perception/docker/run_notebooks.sh simpletrack lab        # interactive JupyterLab
perception/docker/run_notebooks.sh simpletrack execute    # headless: run all 5 in place
perception/docker/run_notebooks.sh all execute            # run BOTH the BEVFusion and SimpleTrack suites
perception/docker/run_notebooks.sh simpletrack regen      # regenerate the .ipynb from _build_notebooks*.py
```

## Prerequisites for the end-to-end cell (NB05)

* The BEVFusion detection JSON at `/results/bevfusion_det/results_nusc.json`
  (produced by `perception/docker/run_pipeline.sh`); NB05 falls back to a
  synthetic scene if it is absent.
* Optional: `nuscenes-devkit` for official AMOTA/AMOTP, and the vendored
  `perception/simpletrack` for the reference implementation.

## Regenerating

```bash
cd perception/notebooks/SimpleTrack && python _build_notebooks.py
```