ngperception/tracking: SORT baseline, evaluator and a dataset-free harness

[egeboy35]

ngperception/README.md lists Tracking (MOT) as planned, with SORT as the basic tier and DeepSORT → ByteTrack → OC-SORT above it. The folder does not exist yet. This adds it.

It follows the three-layer shape the rest of the suite uses (trackers / datasets / evaluator) and consumes ngdet.Detection rather than detecting anything itself — so a sequence can be re-tracked under a different detector without touching the tracker, which is what keeps the ablation about association rather than detection.

Layout

tracking/
├── trackers/base.py    TrackResult + BaseTracker + TRACKER_REGISTRY + build_tracker + iou_matrix
├── trackers/sort.py    @register("sort") — Kalman (cx,cy,area,aspect) + Hungarian on IoU
├── datasets.py         MOTChallenge csv reader + a dataset-free synthetic generator
├── evaluator.py        CLEAR-MOT: MOTA / MOTP / IDF1 / ID-switches
├── run_eval.py         CLI, same shape as depth/run_eval.py
└── tests/              37 tests, ~1.2 s

numpy and scipy only — no network, no weights, no GPU, nothing to download. That is deliberate: the tracking arm stays reproducible by anyone, and a later appearance-based backend gets a like-for-like reference to beat.

Runs with no dataset

python -m DeepDataMiningLearning.ngperception.tracking.run_eval \
    --trackers sort --synthetic --min-hits 1

  tracker           MOTA    MOTP    IDF1   IDSW      FP      FN
  sort           +1.0000  1.0000  1.0000      0       0       0

Dial in the failure the tracker is supposed to survive (2 × 30 frames × 4 objects, --min-hits 1 --max-age 3):

condition	MOTA	MOTP	IDF1	IDSW	FN
clean	+1.0000	1.0000	1.0000	0	0
6 px detector jitter	+1.0000	0.9187	1.0000	0	0
10 % missed detections	+0.9000	1.0000	0.9474	0	24
15 % missed + 8 px jitter	+0.8583	0.8914	0.7175	0	34

Jitter costs MOTP and leaves MOTA's detection terms alone; missed detections cost MOTA in proportion. Reporting both keeps those separable.

On a MOTChallenge dataset

python -m DeepDataMiningLearning.ngperception.tracking.run_eval \
    --trackers sort --root /data/MOT17 --sequences MOT17-02 MOT17-04

datasets.py does the two conversions that format needs, in one place, tested: frames are 1-indexed on disk, 0-indexed in the API, and boxes are xywh on disk, xyxy everywhere in ngdet/ngperception (x2 = left + width, not left + width − 1). Rows whose conf is 0 are MOTChallenge's ignore flag and are dropped by default.

Algorithm

A constant-velocity Kalman filter per track over [cx, cy, area, aspect] with aspect held constant — SORT's own simplification, kept so this is the published baseline and not a private variant — plus Hungarian assignment on IoU between each track's predicted box and each detection. Matches below the gate are rejected after the assignment, not before: filtering first would let a leftover pair win an assignment the optimal solution had given to a better one.

Tests

37 tests, ~1.2 s, no GPU and no dataset. Line coverage is 100 % of the importable code in all four modules — the only uncovered lines are the if __name__ self-test blocks, and each of those runs under python -m.

They were checked against 18 seeded mutations: gate removal, assignment sign, id reuse, area/aspect swap, the area clamp, the IoU union term, the ID-switch counter, MOTA's terms, and both MOTChallenge conversions. All 18 turn the suite red.

Two of those started out undetected and the tests were strengthened until they were not — removing the association gate, and removing the area clamp. The first needed a case where a far-away detection must not claim an existing track; the second needed a box collapsing fast enough that the predicted area passes through zero (with the clamp it stays ~240 px wide, without it every corner lands on the same point).

What this baseline does not do

Stated in the README rather than left implicit: SORT has no re-identification, so an object that leaves and returns gets a new id and the sequence takes an ID-switch; it has no occlusion reasoning beyond coasting for max_age frames; and it inherits every miss of the detector it is given.

The README task-table row moves from planned to ✅ baseline, with the three appearance/association backends above it still marked planned.

🤖 Generated with Claude Code