Virtual Billiard Coach

Real-time pool coaching system that uses computer vision to detect and track billiard balls, measure shot timing, and record game data for analysis.

Features

• Ball detection & tracking — YOLO11 model with ByteTrack for persistent ball IDs across frames
• Motion trails — visual polyline tails showing recent ball paths
• Speed Pool game mode — detects rack ready state, measures time from break to all balls pocketed
• Shot recording — saves per-frame ball positions, velocities, and confidence to JSON for later analysis
• Collision prediction — highlights balls likely to collide based on proximity

Requirements

• Python 3.11
• CUDA-capable GPU recommended (runs on CPU too, slower)
• Webcam or pre-recorded video file

Setup

git clone https://github.com/fearlessit/pool_coach.git
cd pool_coach
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

source .venv/bin/activate
python src/pool_coach.py

Or use the pool_coach run configuration in VSCode (.vscode/launch.json).

Controls

Key	Action
q	Quit
+	Increase FPS cap
-	Decrease FPS cap

Configuration

All tunable parameters are in src/conf/constants.py:

Parameter	Default	Description
input_video_capture_parameter	0	Webcam index or video file path
DETECTION_THRESHOLD	0.5	Minimum confidence for ball detection
MIN_BALL_COUNT_IN_RACK	9	Balls needed to consider rack ready
SHOT_SETTLE_MIN_FRAMES	25	Frames of stillness to consider shot complete
MODEL_DIR	model/best_weights.pt	Path to YOLO weights

Project Structure

src/
├── pool_coach.py          # Entry point
├── conf/constants.py      # All configuration
├── billiard/
│   ├── ball.py            # Ball entity (position, velocity, confidence)
│   └── inference.py       # YOLO tracking wrapper
├── games/
│   └── speed_pool.py      # Speed Pool game logic
├── ui/
│   ├── billiard_ui.py     # Visualization and frame loop
│   └── collisions.py      # Collision prediction overlay
└── utils/
    ├── last_values.py     # Sliding window averager
    ├── shot_recorder.py   # JSON shot data recorder
    └── stable_change.py   # Debounced state change detector

Shot Data

Completed shots are saved to the directory configured by SHOT_RECORDINGS_DIR, as JSON files organized by game and shot index. Each file contains per-frame ball positions, velocities, and detection confidence.

Demo

• Short demo, camera placement from above (real-time)

Intesting links

• https://pypi.org/project/billiards/ - PyPi Billiards 2d physics and view engine