pool-ar

Projector-camera augmented reality system for a home pool table. An overhead projector draws onto the cloth; an overhead camera tracks the balls (and, optionally, the cue). Two capability tiers share one foundation:

1. Aim assist — project trajectory lines, ghost-ball contact points, and cushion rebounds based on detected cue angle and ball positions.
2. Arcade modes — themed "living felt", target/zone games, time trials, portal/teleport effects, and collision FX projected onto the table.

Both tiers rest on the same two primitives: a projector warped to the table rectangle and overhead ball tracking. Build that once; everything else is software drawing on top.

Why this architecture

• Reversible. Nothing touches the cloth or slate. Normal play is unaffected when the system is off.
• Incremental payoff. A zero-tracking themed felt works on day one and validates the projector mount + warp before any computer vision exists.
• Stack-native. TouchDesigner is the real-time visual engine and projection warp; OpenCV (Python) does the vision; state can be published over MQTT into the existing Grafana/InfluxDB telemetry world for match stats.

Repository layout

pool-ar/
├── README.md                  # this file
├── docs/
│   ├── PLAN.md                # full phased build plan + milestones
│   ├── HARDWARE.md            # sensor/projector selection + mounting
│   ├── CALIBRATION.md         # homography: camera <-> table <-> projector
│   ├── VISION.md              # ball + cue detection pipeline
│   ├── PHYSICS.md             # trajectory / ghost ball / cushion math
│   └── GAMES.md               # arcade mode catalogue + difficulty tiers
├── vision/                    # Python OpenCV pipeline
│   ├── requirements.txt
│   ├── config.example.yaml
│   ├── capture.py             # camera abstraction (RGB or RealSense)
│   ├── calibrate.py           # interactive homography capture tool
│   ├── detect_balls.py        # color/blob ball detection
│   ├── detect_cue.py          # cue line detection
│   ├── physics.py             # shot prediction
│   └── publish.py             # MQTT/OSC state publisher
├── touchdesigner/
│   └── README.md              # TD project structure (the .toe is binary)
├── config/
│   └── table.example.yaml     # table dimensions, pocket positions
└── scripts/
    └── setup.sh               # venv + deps bootstrap

Quickstart

git clone <this-repo> && cd pool-ar
./scripts/setup.sh             # creates venv, installs vision deps
cp vision/config.example.yaml vision/config.yaml
python vision/calibrate.py     # capture the 4 table corners -> homography
python vision/detect_balls.py  # verify ball tracking on a live feed

See docs/PLAN.md for the full build sequence.

Status

Scaffold / planning. No working pipeline yet — start at Phase 0 in the plan.