🏀 BasketballDetector is a deep-learning based tool that enables automatic ball detection in basketball broadcasting videos.

This repository contains the BasketballDetector implementation using a classification approach instead of a segmentation one. It also contains some of the first attempts to address the problem with simple segmentation models implemented in tensorflow from scratch.

Please note that this work has been discarded in favor of the segmentation approach using SOTA real-time segmentation models, which proved more accurate and way faster.

This project requires tensorflow==2.13.*. Instructions on how to properly set up a working environment can be found on the official page.

Alternatively, you can simply import and use the same conda environment that was used during development. Using the provided conda environment file run:

conda create --name myenv-tf --file tf.environment.yml

Don't forget to set up the required environment variables as well:

CUDNN_PATH=$(dirname $(python -c "import nvidia.cudnn;print(nvidia.cudnn.__file__)"))
export LD_LIBRARY_PATH=$CUDNN_PATH/lib:$CONDA_PREFIX/lib/:$LD_LIBRARY_PATH

You can automatize the process of adding the environment variables to execute automatically each time you activate your conda environment by running the following commands:

mkdir -p $CONDA_PREFIX/etc/conda/activate.d
echo 'CUDNN_PATH=$(dirname $(python -c "import nvidia.cudnn;print(nvidia.cudnn.__file__)"))' >> $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh
echo 'export LD_LIBRARY_PATH=$CUDNN_PATH/lib:$CONDA_PREFIX/lib/:$LD_LIBRARY_PATH' >> $CONDA_PREFIX/etc/conda/activate.d/env_vars.sh

If you're using the provided conda environment, you can ignore these steps. Otherwise, to install all the required dependencies, either run:

python -m pip install -r requirements.txt

Or:

python -m pip install .

If you want to install the project in development mode, instead you can run:

python -m pip install -v -e .

More information about what development mode is can be found here. Please note that if you're not using a conda environment you still need to manually set up the appropriate CUDA runtime API version as detailed here in order to be able to use GPU acceleration.

This repository uses pdoc to build the project's documentation. All credits go to the author.

The model has been largely inspired by the paper Convolutional Neural Networks Based Ball Detection in Tennis Games. All credits go to the authors.