This repository contains an unofficial implementation of the Simple Online and Realtime Tracking with Motion Features (MF-SORT) algorithm, as it was presented in (Fu et al, 2019). It is an extension of the original SORT algorithm using Mahalanobis distance and a matching cascade similar to that of DeepSORT.
I am not the original author of MF-SORT, though this repository represents a close implementation based on the description given in the original publication. See Fu et al, 2019 for further details on the algorithm.
This code was developed and tested on Python 3.6, though it should run on any recent version of Python (3+). The following dependencies are needed to run the tracker:
- Numpy
- Scipy
- Filterpy
In addition, in order to run the demos contained in the examples folder and the built-in detection framework, specify the yolo optional dependency when installing with pip.
To install MF-SORT, clone the repository and install the package using pip.
git clone https://github.com/kbvatral/MF-SORT.git
cd MF-SORT
pip install .[yolo]
The repository contains one minimum working example using a video file and an associated CSV file of object detections found in the examples folder. The object detections were generated through YoloV5 using the Detector interface, though any object detector could be used.
To re-generate the provided detections, simply run examples/detect.py. To run tracking on the demo video with the provided detections, simply run examples/track.py, which will produce a CSV file containing the generated tracks in the example data directory. To visualize the generated tracks, simply run examples/visualize_track.py, which will produce and AVI video file which shows the original video with tracking bounding boxes overlaid.
All detections and generated tracks conform to the formatting of the MOT16/17/20 Challenge Benchmark.
The API is divided into three main classes: Detector, Detection, and MF_SORT. Detector is a wrapper around YoloV5 which allows for simple object detection for use in the rest of the tracking pipeline. Note that it is not required to use this detector for the pipeline; it is only included as a convenience. Detection is a wrapper to contain the information (bounding box and class score) for the detections generated by Detector or any other object detection framework. MF_SORT is the actual multiple object tracker which takes in these detections frame by frame and produces the tracks. MF-SORT has a predict/update loop interface that should be familiar to anyone who has worked with Kalman filters in the past. In addition, there is also a step method which wraps the predict/update functions which is recommended for most use cases. For a complete worked use case including detection, tracking, and visualization, see the scripts in the examples folder.
- All credit for the MF-SORT algorithm goes to the original authors. Please see their publication Fu et al, 2019 for further details
- Parts of this repository were inspired by or taken directly from the repositories for SORT and DeepSORT, both licensed under GPL-3.0
- This repository is also licensed under GPL-3.0