ByteTrack Documentation

The two implementations differ in their motion handling:

• TransTrack (tracker.py): Uses motion only.
• TransTrack_BYTE (mot_online/byte_tracker.py): Uses motion combined with a Kalman filter.

You can run FairMOT using two different tracking modes by selecting the appropriate script and setting the --match_thres threshold:

• BYTE tracker (motion only): Use byte_tracker.py and set --match_thres 0.8.
• Standard tracker (motion + reid): Use tracker.py and set --match_thres 0.4.

Example command for running the BYTE tracker:

python3 track_half.py mot --load_model ../exp/mot/mot17_half_dla34/model_last.pth --match_thres 0.8

To set up FairMOT, clone the repository and replace the existing multitracker implementation with the ByteTrack version.

1. Clone the repository: git clone https://github.com/ifzhang/FairMOT.git

2. Replace the file src/lib/tracker/multitracker.py with the ByteTrack version provided in this repository.

To install ByteTrack directly on your host machine, follow these steps to clone the repository, install requirements, and set up the package in development mode. You must also install pycocotools and cython_bbox as dependencies.

# Step 1: Install ByteTrack
git clone https://github.com/ifzhang/ByteTrack.git
cd ByteTrack
pip3 install -r requirements.txt
python3 setup.py develop

# Step 2: Install pycocotools
pip3 install cython; pip3 install 'git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonAPI'

# Step 3: Install cython_bbox
pip3 install cython_bbox

To train on a custom dataset:

1. Prepare your dataset in COCO format (refer to tools/convert_mot17_to_coco.py or tools/convert_crowdhuman_to_coco.py).
2. Create a new Experiment (Exp) file for your dataset (refer to exps/example/mot/yolox_x_ch.py).
3. Modify get_data_loader() and get_eval_loader() in your new Exp file.
4. Run the training script using your custom Exp file.

cd <ByteTrack_HOME>
python3 tools/train.py -f exps/example/mot/your_exp_file.py -d 8 -b 48 --fp16 -o -c pretrained/yolox_x.pth

Use the export_onnx.py tool to convert a PyTorch checkpoint (e.g., .pth.tar) into an ONNX file.

Example for bytetrack_s_mot17.pth.tar:

cd <ByteTrack_HOME>
python3 tools/export_onnx.py -f exps/example/mot/yolox_s_mix_det.py -c pretrained/bytetrack_s_mot17.pth.tar

This generates a bytetrack_s.onnx file in the <ByteTrack_HOME> directory.

To use ByteTrack as a custom low-level tracker in NVIDIA DeepStream, you must first compile the C++ code into a shared object file (libByteTracker.so).

$mkdir build && cd build
$cmake ..
$make ByteTracker

Convert a PyTorch model (e.g., bytetrack_s_mot17) to a TensorRT model using the tools/trt.py script. You need to provide the experiment configuration file and the pretrained checkpoint.

cd <ByteTrack_HOME>
python3 tools/trt.py -f exps/example/mot/yolox_s_mix_det.py -c pretrained/bytetrack_s_mot17.pth.tar

To run inference using a trained CTracker model, replace the existing test.py in the CTracker repository with the version provided in this tutorial. Run the following command to perform testing on the MOT17 dataset:

python3 test.py --dataset_path MOT17 --model_dir ctracker --model_path ctracker/mot17_half_ctracker.pt

To convert the generated ONNX file to ncnn format, place the .onnx file in ncnn/build/tools/onnx and run onnx2ncnn.

Note: You may see a warning Unsupported slice step ! because the Focus module is not natively supported in ncnn. This is expected; the C++ version of the Focus layer is manually implemented in src/bytetrack.cpp.

cd ncnn/build/tools/onnx
./onnx2ncnn bytetrack_s.onnx bytetrack_s.param bytetrack_s.bin

You can use Docker to build and run ByteTrack in a containerized environment. The startup sample includes mounting volumes for pretrained models, datasets, and outputs, as well as configuring X11 for GUI/display support.

# Build the image
docker build -t bytetrack:latest .

# Startup sample
mkdir -p pretrained && \
mkdir -p YOLOX_outputs && \
xhost +local: && \
docker run --gpus all -it --rm \
-v $PWD/pretrained:/workspace/ByteTrack/pretrained \
-v $PWD/datasets:/workspace/ByteTrack/datasets \
-v $PWD/YOLOX_outputs:/workspace/ByteTrack/YOLOX_outputs \
-v /tmp/.X11-unix/:/tmp/.X11-unix:rw \
--device /dev/video0:/dev/video0:mwr \
--net=host \
-e XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR \
-e DISPLAY=$DISPLAY \
--privileged \
bytetrack:latest