Basketball Video Analytics is my computer-vision project for analyzing basketball game footage. It processes a video to detect and track players and the ball, assign players to teams, estimate ball possession, identify passes and interceptions, calculate player speed and distance, and generate an annotated video with a top-down tactical court view.
The project is maintained in this repository by Manish Maurya.
This is my basketball video analytics project, maintained by Manish Maurya. I am improving the repository's reliability, setup, and documentation while bringing detection, tracking, team assignment, possession and event estimation, court mapping, and movement analysis into one workflow.
The codebase builds on related open-source basketball analytics work. See the Credits section for attribution; reused code, model weights, and datasets remain subject to their original licenses.
- Player and ball detection: Uses fine-tuned Ultralytics YOLO models.
- Player tracking: Uses ByteTrack through the
supervisionlibrary to maintain player IDs across frames. - Team assignment: Uses a zero-shot Fashion-CLIP model to group players by jersey appearance.
- Ball possession: Estimates which player is in possession of the ball.
- Passes and interceptions: Tracks changes in possession to estimate passes between teammates and interceptions by the opposing team.
- Tactical court view: Detects court keypoints and uses a homography to project player positions onto a top-down court.
- Speed and distance: Estimates player movement in km/h and metres using the court mapping.
- Annotated output: Combines detections, tracks, possession information, events, movement statistics, and the tactical view in an output video.
- Python 3.11 is recommended (the Docker image uses Python 3.11).
- Dependencies listed in
requirements.txt. - Three model weight files in a
models/directory:models/player_detector.ptmodels/ball_detector_model.ptmodels/court_keypoint_detector.pt
- An input basketball video supported by OpenCV.
The model weight files are not included in this repository by default. Add compatible weights that you have trained or are authorized to use, or train models using the notebooks in training_notebooks/. The filenames must match the list above. Before using third-party weights or datasets, check their license and usage terms.
Clone the repository and install its dependencies:
git clone https://github.com/Manishmaurya89/Basketball-Analytics-Estimation-Using-Object-Segmentation-.git
cd Basketball-Analytics-Estimation-Using-Object-Segmentation-
python -m venv .venv
# macOS/Linux
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txtPlace the three model files listed above in models/, then run:
python main.py path/to/game.mp4 --output_video output_videos/output_video.aviThe annotated video is written to output_videos/output_video.avi unless you specify another path. You can see all command-line options with:
python main.py --helpPlace the model files in models/ before building the image:
docker build -t basketball-analytics .
docker run --rm \
-v "$(pwd)/input_videos:/app/input_videos" \
-v "$(pwd)/output_videos:/app/output_videos" \
basketball-analytics input_videos/game.mp4 \
--output_video output_videos/output_video.aviThe output video will be available in the local output_videos/ directory.
Input video
|
v
YOLO detection: players, ball, and court keypoints
|
v
ByteTrack player tracking
|
v
Fashion-CLIP team assignment
|
v
Ball possession estimation
|
+--> Pass and interception estimates
|
v
Court homography and top-down player positions
|
v
Speed and distance estimates
|
v
Annotated video with tactical view and statistics
The current possession logic estimates possession from the ball's proximity to player bounding boxes. Passes and interceptions are inferred from changes in possession and team assignment; they are estimates, not guaranteed ground-truth event labels.
The tactical view uses the court image at images/basketball_court.png.
The movement calculation uses a nominal court size of 28 m × 15 m. The keypoint mapping and this court-size assumption affect the accuracy of speed and distance estimates.
Court diagrams are credited to The Hoops Geek.
├── main.py Runs the complete pipeline
├── configs/ Model and output paths
├── trackers/ Player and ball detection/tracking
├── team_assigner/ Team assignment
├── ball_aquisition/ Ball-possession estimation
├── pass_and_interception_detector/ Pass and interception estimates
├── court_keypoint_detector/ Court keypoint detection
├── tactical_view_converter/ Homography and top-down projection
├── speed_and_distance_calculator/ Player speed and distance estimates
├── drawers/ Video overlays and annotations
├── utils/ Video I/O, bounding boxes, and caching
├── training_notebooks/ Model-training notebooks
├── images/ Court images and reference diagrams
├── stubs/ Cached intermediate results
├── Dockerfile
└── requirements.txt
Python, Ultralytics YOLO, ByteTrack (supervision), Fashion-CLIP, Hugging Face Transformers, OpenCV, PyTorch, Pandas, and NumPy. The training workflow uses datasets managed through Roboflow.
- Detection and tracking quality depends on video quality, camera angle, occlusion, and the trained weights.
- Team assignment based on jersey appearance may be unreliable when teams wear similar colors.
- Possession, passes, and interceptions are inferred heuristically and should be validated against manually labeled footage before being used for formal performance evaluation.
- Speed and distance are estimates that depend on court-keypoint accuracy and the homography calibration.
- Upstream open-source codebase: abdullahtarek/basketball_analysis.
- Court dimensions reference: The Hoops Geek.
- Project repository and maintenance: Manish Maurya.
Please check the relevant upstream licenses and dataset/model terms before redistributing inherited code, weights, or data.
Questions: manish.maurya0408@gmail.com