iou-tracker is a Python implementation of the IOU and V-IOU multi-object trackers

Association by overlap, with image information deliberately left out

The IOU tracker, in its original form, decides which detection belongs to which existing track using geometry alone. That is the point of the 2017 paper it implements, High-Speed Tracking-by-Detection Without Using Image Information, presented at the International Workshop on Traffic and Street Surveillance for Safety and Security at IEEE AVSS 2017.

Working without image information is the interesting constraint. A tracker that never looks at pixels cannot re-identify a target that disappeared behind an obstruction and came back, and it cannot tell two similar-looking vehicles apart when their boxes barely overlap. What it can do is run very fast, which is why a tracker of this kind is still a useful baseline rather than a historical curiosity.

The repository also contains the second generation, described in Extending IOU Based Multi-Object Tracking by Visual Information, presented at IEEE AVSS in 2018 and published in the proceedings of the conference on Advanced Video and Signals-based Surveillance with the identifier pages 441 to 446. The V-IOU tracker takes the geometric association and adds a visual tracker to the pipeline for the cases geometry cannot resolve.

Both are MIT licensed, and the README asks that the work be cited if it is used in research, providing BibTeX entries for the two papers.

V-IOU wires in a visual tracker for the cases overlap cannot settle

The V-IOU pipeline is configured through the demo script's visual tracker option, and the README lists the supported implementations: BOOSTING, MIL, KCF, KCF2, TLD, MEDIANFLOW, GOTURN and NONE, with NONE disabling the visual stage.

Two parameters control how much of the object the visual tracker is allowed to look at. The keep_upper_height_ratio option sets the ratio of the height of the object to track to the total height of the object for visual tracking, and the documentation gives upper 30 percent as the example. A time to live parameter, ttl, is described as the v-iou time to live parameter, which is the window during which a track can be kept alive without a matching detection.

The choice of visual tracker is not cosmetic. Two implementations of the KCF tracker exist: one supplied by OpenCV-Contrib, and a second, called KCF2, which is a Cython based wrapper of the original KCF code and is the one needed to reproduce the reported results. The documentation is direct about why: that implementation works better and much faster than the one provided by OpenCV-Contrib, and installing OpenCV from scratch rather than from the PyPI package is recommended so that the necessary headers and libraries are available.

If the KCF2 module is missing, the tracker falls back to the OpenCV implementation and prints a warning. The fallback is silent in effect even though it is loud in output, because the documentation notes that tracking performance will be affected.

The install is a virtual environment and five packages

The dependency split is simple. The IOU tracker depends only on numpy, while V-IOU additionally requires OpenCV-Contrib and some other dependencies. The project recommends a virtual environment, and the three commands below are the documented starting point for running most of the scripts in the repository.

virtualenv -p python3 env
source env/bin/activate
pip install numpy lapsolver tqdm opencv-contrib-python

The four packages map onto the roles they play. numpy is the IOU tracker's only dependency, while the other packages are additional dependencies the README lists without documenting their individual roles. opencv-contrib-python brings the video and tracking code that the V-IOU path and the OpenCV-provided KCF implementation need.

One caveat sits on top of that list. The README recommends building OpenCV from source instead of using the PyPI package, precisely so that the headers and libraries needed by the KCF2 wrapper are present. That turns a one line install into a source build for anyone who wants the published results, and it is the single largest practical obstacle in this repository.

demo.py consumes a detection CSV and writes MOT format output

The main entry point is demo.py, and the README presents it as a basic demo script that is not dataset specific and can be used for other applications. The usage text in the documentation shows the full flag set.

usage: demo.py [-h] [-v VISUAL] [-hr KEEP_UPPER_HEIGHT_RATIO] [-f FRAMES_PATH]

The inputs are a path to sequence frames, given as a format string with a zero padded frame id, and a full path to a CSV file containing the detections. The output path stores the tracking results in the MOT challenge and VisDrone devkit compatible format. The detection format itself is selected with the format option, whose documented values are motchallenge and visdrone.

The remaining flags are thresholds rather than inputs. sigma_l and sigma_h are the low and high detection thresholds, sigma_iou is the intersection-over-union threshold, t_min is the minimum track length, and nms is the non-maximum suppression setting used when loading multi-class detections. Reading them together, the script is essentially a configurable pipeline: a thresholded detection set, an assignment rule, an optional visual stage, and a filter for tracks that are too short to be real.

A concrete run on a MOT17 sequence looks like this, with the detection file as input and a result file per tracker variant in the output directory.

./demo.py -d ../mot17/train/MOT17-04-SDP/det/det.txt -o res/iou-tracker/MOT17-04-SDP.txt

Benchmark scripts per dataset, and a full argument example

Beyond the generic demo, the repository carries per-benchmark entry points. The top level holds mot16.py, mot17.py, a cvpr19.sh shell script and a visdrone-mot.sh shell script, alongside the tracker implementations iou_tracker.py, viou_tracker.py, vis_tracker.py and a shared util.py.

The VisDrone example in the documentation shows what a fully specified invocation looks like, with the visual tracker, both detection thresholds, the IoU threshold, the minimum track length, the time to live and the detection format all set explicitly.

demo.py -f '/path/to/VisDrone2018-MOT-val/sequences/uav0000137_00458_v/{:07d}.jpg' -d /path/to/VisDrone2018-MOT-val/detections/uav0000137_00458_v.txt -o results/VisDrone2018-MOT-val/uav0000137_00458_v.txt -v MEDIANFLOW -sl 0.9 -sh 0.98 -si 0.1 -tm 23 --ttl 8 --nms 0.6 -fmt visdrone

Two patterns are visible in that line. The frame path uses a seven digit format string, and the output directory is organised by dataset and sequence so that a sweep over many sequences does not overwrite itself. There is also a seqmaps/ directory at the top level, which is where such per-sequence maps live.

For DETRAC the workflow is different, and it is the one part of this repository that is not Python. The instructions say to download and extract the DETRAC toolkit and the detections to evaluate, then clone this repository into the trackers directory of that toolkit, configure the toolkit for tracking evaluation, and set the tracker name in the experiment file.

tracker.trackerName = 'iou-tracker';

A MATLAB script, run_tracker.m, and a saveStateInfo.m helper are included for that path, and the DETRAC section notes that the tracker can be switched between the IOU and V-IOU variants and the parameters selected there.

The comparison point: geometry only against appearance first

The natural alternative to a tracker like this is an appearance based multi-object tracker that matches detections to tracks using features of the object itself, and the difference in approach is the whole design.

An appearance first tracker tolerates occlusion and identity switches better, because it can recognise a target that reappears with a different box. It also costs more per frame, because features have to be extracted, and it fails in its own way when two objects look alike, which is common in traffic footage with similar vehicles.

The IOU approach inverts that. It leans on position and velocity, it is cheap, and it is legible: you can read the thresholds in the command line and understand what the tracker will do. Its weakness is the one the 2017 title advertises, and the reason the 2018 paper exists. V-IOU is a hybrid that keeps the cheap geometric stage for the common case and spends visual computation only where it is needed, which is a reasonable compromise and also the reason the KCF2 implementation and its speed matter.

For a reader choosing a baseline for a new dataset, that trade is the useful takeaway. This repository is a transparent, parameter-driven implementation of one side of that trade, with the other side available as a pluggable visual tracker.

Documentation from 2020, code pushed in 2026, and an MIT licence

The repository is released under the MIT License, with the details in the LICENSE file. That is a permissive grant with no obligation on downstream users beyond keeping the notice, which matters for a research tool that other groups build on.

The maintenance picture needs reading carefully. The last push to the master branch was on 2026-06-14, so the code is not abandoned, but the repository has no GitHub releases, so there is no tagged version to pin and no changelog to read. The README carries its own update notes instead, and the most recent one is dated January 2020, recording that the V-IOU code was added and the README was updated. The note before that, from December 2018, added the V-IOU results from the second paper, Mask R-CNN detections for UA-DETRAC, and improved CompACT parameters.

In other words, the narrative documentation trails the code by several years while the branch itself is still receiving pushes. Nobody has written a release note explaining what the 2026 commits changed, so if you are upgrading a working copy, the diff itself is the only record of what moved.

The homepage is a group page rather than a project site, and the project topics list detrac, ua-detrac, mot, tracking-by-detection and demo-script, which tells you the intended audience is a research replication attempt rather than a general engineering audience.

Editorial conclusion

iou-tracker suits a researcher who needs a transparent, geometry-driven baseline tracker that runs on a CSV of detections, and it does not suit a team that needs the paper numbers reproduced exactly without building OpenCV and the KCF wrapper from source. Before using it, install the KCF2 wrapper if you intend to reproduce the published results, since the OpenCV fallback changes tracking performance, and expect the surrounding tooling to be MATLAB rather than Python for the DETRAC evaluation.

Frequently asked questions

Official sources

1. bochinski/iou-tracker on GitHub
2. Issues
3. License: MIT
4. Project website
5. README