🏌️ PuttSim — AI-Powered Putting Simulator

Real-time golf putting simulator using computer vision (YOLOv8) and physics prediction. Place a real golf ball, putt it, and watch the predicted trajectory animate on a 2D canvas dashboard.

🎯 How It Works

1. Place the ball in the start circle → system shows READY with a beep
2. Putt the ball → system enters TRACKING mode
3. Ball crosses the detection line → system predicts the trajectory using physics
4. Animated result appears on the 2D canvas with speed, angle, and distance

┌─────────────────────────┐
│   PREDICTION ZONE       │  ← Physics engine predicts here
│   (above yellow line)   │
├─────────────────────────┤  ← Yellow midline (30% from top)
│                         │
│   DETECTION ZONE        │  ← YOLO tracks the ball here
│   (below yellow line)   │
│                         │
│        ⚪ ← START       │  ← Ball placement circle (82% down)
│                         │
└─────────────────────────┘

🏗️ Architecture

┌──────────┐    WebSocket     ┌──────────┐    HTTP/WS    ┌──────────┐
│  Phone   │ ──────────────→  │  Server  │ ←──────────→  │ Browser  │
│  Camera  │   MJPEG frames   │ FastAPI  │   Telemetry   │Dashboard │
└──────────┘                  └────┬─────┘               └──────────┘
                                   │
                          ┌────────┴────────┐
                          │                 │
                    ┌─────┴─────┐    ┌──────┴──────┐
                    │  Vision   │    │  Physics    │
                    │  Engine   │    │  Engine     │
                    │ (YOLOv8)  │    │ (Kinematics)│
                    └───────────┘    └─────────────┘

Components

File	Description
server.py	FastAPI server with WebSocket, camera streaming, shot broadcasting
vision.py	YOLOv8 ball detection, Kalman filter tracking, state machine (IDLE→READY→TRACKING→COOLDOWN)
physics.py	Stimpmeter-based physics, velocity→distance prediction, deceleration model
config.py	Configuration constants (camera, physics, detection thresholds)
static/app.js	Canvas renderer, shot animation, WebSocket client, scorecard
static/style.css	Premium dark dashboard theme
static/index.html	Dashboard layout with sidebar, scorecard, shot analysis, telemetry
static/mobile.html	Phone camera streaming page

🚀 Quick Start

Prerequisites

• Python 3.10+
• A phone camera (or webcam)
• Both devices on the same WiFi network

Installation

git clone https://github.com/yourusername/PuttSim.git
cd PuttSim

# Create virtual environment
python -m venv venv
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

Generate SSL Certificates (required for phone camera)

mkdir -p certs
openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem \
  -days 365 -nodes -subj '/CN=localhost'

Run

python server.py

Open https://localhost:8000 in your browser (accept the self-signed certificate warning).

Connect Phone Camera

1. Click 📱 Celular on the dashboard
2. Scan the QR code with your phone
3. Accept the camera permission on your phone
4. The phone camera feed will appear in the dashboard

📐 Physics Model

The simulator uses a Stimpmeter-based deceleration model:

Stimp Rating (ft) → Deceleration (m/s²)
────────────────────────────────────────
decel = (2 × g) / (stimp_ft × 0.3048)

Stimp 10 → decel ≈ 0.549 m/s²

Kinematics:

• distance = v² / (2 × decel)
• time_to_stop = v / decel
• Direction from Kalman filter velocity vector

🎮 State Machine

IDLE ──→ READY ──→ TRACKING ──→ COOLDOWN ──→ IDLE
  │        │          │            │
  │    Ball in      Ball hit    Ball lost     3s timer
  │    circle       (leaves     (crosses      resets
  │    10 frames    circle)     line, 3       everything
  │    + beep                   frames)

🔧 Configuration

Edit config.py to adjust:

Setting	Default	Description
STIMP_RATING	10.0	Green speed (6-14 ft)
CAMERA_INDEX	0	Local webcam index
PIXELS_PER_METER	500	Calibration factor
YOLO_CONFIDENCE	0.35	Ball detection threshold

📱 Supported Setups

• Phone camera (recommended): Vertical/portrait mode, pointed down at the putting surface
• Webcam: Any USB webcam mounted above the putting area
• IP camera: Any MJPEG-compatible stream

📄 License

MIT License — feel free to use, modify, and distribute.