This README is a guide to install and build the Sports-tracking project. For interesting project details, check here.
Table of Contents
The Sports-tracking project is a code challenge provided by Swiss Timing. It aims to build an efficient and fit-for-purpose solution to process short sports videos with moving athletes and extract information about the athletes. The development environment is maintained using Docker, and the project is built using CMake. OpenCV is the primary library used in this project.
As this project was completed in a short time, there might be some bugs or issues. Feel free to suggest changes or report issues by opening an issue.
This section provides instructions for setting up the project on a Windows system. Users on other platforms should follow similar steps with differences in setting GUI applications communication between the Docker container and the host.
To run this project, you need to have the following:
- Docker - Download and install Docker.
- VcXsrv Windows X Server - Install the X Server for GUI communication. For more details, read the documentation.
- A short sport video clip for testing.
Follow these steps to set up the project:
- Pull the Docker image with OpenCV version 4.5.4:
docker pull adnrv/opencv:latest
- Run the Docker container with mounted volumes:
docker run -t -d
--name sports-tracking
--mount type=bind,source=$YOUR_PROJECT_PATH$,target=/home/sports-tracking
-e DISPLAY=$YOUR_IP_ADDRESS$:0.0 adnrv/opencv
- Obtain the pretrained YOLOv5 model and convert it to the ONNX format:
git clone https://github.com/ultralytics/yolov5
wget https://github.com/ultralytics/YOLOv5/releases/download/v6.1/YOLOv5s.pt
python export.py --weights YOLOv5s.pt --simplify --opset 12 --include onnx
- Download this repository and build it:
git clone https://github.com/ChauChorHim/Sports-tracking.git
mkdir build && cd build
cmake .. && make -j4
Edit the configuration file config/badminton.json with the following parameters:
- path_to_video: relative path to the video for processing
- path_to_onnx: relative path to the onnx weights of YOLOv5 model
- path_to_save_video: relative path to the processed video and .avi is the only supported format for now
- path_to_save_bbs: relative path to the extracted bounding box information in text format
- diable_gui: diable the real time display function, which requires GUI
- enable_bev: enable the bird's eye view (BEV) alongside with the athlete detection and tracking
- bev_map_size_w: the width of BEV map
- bev_map_size_h: the height of BEV map
- others - input_width_, input_height_, score_threshold_, nms_threshold_, confidence_threshold_ are parameters of YOLOv5. Please check the documentation of YOLOv5 for more details
Edit the configuration file config/badminton_bev_map.json to describe the points and connections in the BEV map. For detailed description, please check here.
Before running the executable file, ensure that the GUI communication between the Docker container and the host is set up correctly. If GUI communication is not possible, enable the "disable_gui" option in the config file.
// Run the main executable file with argument indicating the path to the json file
cd $YOUR_PROJECT_PATH$/bin
main /home/sports-tracking/config/badminton.json
For more detailed documentation and information about the project, refer to doc/documentation.md.