12 KiB
12 KiB
Product Requirements Document (PRD)
Product: GSPro Remote Version: 0.1.0 (Restart Foundation) Author: [You] Date: [Today’s date]
1. Executive Summary
GSPro Remote is a companion application for GSPro golf simulator users running on Windows. It allows golfers to control GSPro from a secondary device (tablet, phone, or PC) via a web-based interface.
The app’s purpose is to:
- Simplify control of GSPro without needing a physical keyboard nearby.
- Provide intuitive UI for common simulator functions (aim, club selection, mulligans, tee box navigation, shot options, map interaction).
- Enhance immersion and ease-of-use for golf enthusiasts with GSPro setups.
Future versions may incorporate computer vision (OCR/marker detection) to auto-detect and track GSPro UI elements, reducing manual setup and enabling more advanced automation.
2. Goals
- Deliver a clean, intuitive remote-control interface optimized for tablets/phones.
- Support all GSPro keyboard shortcuts via touch-friendly buttons.
- Provide low-latency streaming of the GSPro map/mini-map (~200ms or less).
- Persist user settings/configuration locally on the GSPro PC between sessions.
- Make installation simple for non-technical users (one installer, auto-start server).
- Prepare for future OCR-based automation, but keep it out of MVP.
3. Non-Goals
- Multiplayer sync or cloud-hosted services. (There is zero value in a any cloud related services)
- Mobile native apps (PWA installable from browser is sufficient).
- Full-fledged vision debugging UI for end-users (that stays an advanced/dev option).
4. Target Audience
- Primary: GSPro simulator owners with a launch monitor, seeking more convenient in-round controls.
- Secondary: Enthusiasts who like to customize sim setups (may use advanced OCR features later).
Users are assumed to be non-technical golfers, not developers. Installation and updates must be straightforward.
5. Personas & Use Cases
Persona A: “Weekend Golfer”
- Wants to control GSPro from a tablet while standing on the mat.
- Needs quick access to Aim, Mulligan, Club Selection, Tee Box controls.
- Doesn’t want to touch a keyboard during play.
6. Functional Requirements
6.1 Core Features (MVP)
-
UI Controls
- Directional Pad for Aim (Up/Down/Left/Right/Reset).
- Club Indicator + Detection (manual at first, OCR planned later).
- Mulligan button.
- Tee box navigation (previous/next tee).
- Map panel with expand/collapse. (should stream the map from the GSPro UI)
-
Backend Integration
- WebSocket streaming of GSPro map region.
- API endpoints to send keypresses mapped to GSPro shortcuts.
- Config persistence (JSON stored on host PC).
- mDNS discovery (
gsproapp.local) for easy access.
-
Performance
- Streaming latency under 200ms (720p @ 30fps acceptable).
- Smooth interaction (key commands executed <100ms).
6.2 Advanced / V2 Features
-
OCR & Region Detection
- EasyOCR/Tesseract integration to auto-detect club, map, shot info.
- Auto-configuration of regions (user doesn’t manually define).
-
Custom Monitor Tasks
- Background monitoring of regions for changes (e.g., “detect when putting mode enabled”).
-
Marker Detection
- Visual template matching for advanced element tracking.
-
Extended Controls
- Support for additional GSPro shortcuts (e.g., free look, flyover, lighting).
7. Technical Architecture
-
Frontend: React + TypeScript
DynamicGolfUI= Main consumer UI (touch-friendly, polished).VisionDashboard= Developer/advanced-only UI (OCR testing, markers).
-
Backend: Python + FastAPI
/api/actions/key→ Trigger GSPro keypresses./api/vision/ws/stream→ WebSocket for video streaming./api/vision/ocr,/api/vision/markers,/api/vision/regions→ Vision endpoints (advanced).
-
System Design
- Runs locally on Windows (FastAPI server).
- UI served at
http://gsproapp.local:5005/ui. - Input simulated via
pydirectinputto control GSPro. - Screen captured via
mss+ OpenCV.
8. User Experience
-
Primary UI (DynamicGolfUI) Matches "GSPro App.png" in project root directory:
- Top: App name/version, Mulligan button.
- Left: Club indicator.
- Center: Aim directional pad.
- Right: Map stream (expandable).
- Bottom: Shot Options + Tee controls.
-
Advanced UI (VisionDashboard) Hidden behind advanced toggle. Used by devs to:
- Test OCR engines.
- Define/capture regions.
- Add/verify markers.
- Monitor tasks.
9. Success Metrics
-
MVP launch:
- Users can control 90% of their round without a keyboard.
- Map streaming latency <200ms.
- 1-click installer on Windows.
-
V2:
- Automatic detection of club + map area with >90% reliability.
- Config persistence across restarts without user intervention.
10. Milestones
-
Phase 1 (MVP / Public Beta)
- Polish DynamicGolfUI.
- Ensure all GSPro shortcuts are covered.
- Stable WebSocket streaming.
- Windows installer packaging.
-
Phase 2 (Vision + OCR)
- Add OCR-based auto-detection.
- Background monitor tasks.
- VisionDashboard improvements.
-
Phase 3 (Subscription-ready)
- Licensing/subscription integration.
- Polished UX/UI redesign (visual depth, animations, better icons).
- Documentation & onboarding guide.
11. Risks / Open Questions
- Will OCR performance be good enough at different resolutions (1080p vs 4K)?
- Will average users struggle with network/firewall setup for accessing the web UI?
- Packaging FastAPI + dependencies into an easy Windows installer (PyInstaller vs. MSI vs. Docker)?
12. Feature Mapping Matrix
| UI Control | GSPro Shortcut | API Endpoint | Notes |
|---|---|---|---|
| Reset | A |
POST /api/actions/key |
Reset |
| Aim Pad (Up/Down/Left/Right) | Arrow keys | POST /api/actions/keydown + /keyup |
aim adjust = arrow keys, needs “hold” support |
| Club Selection (Up/Down) | U (club up), K (club down) |
POST /api/actions/key |
Shown as club indicator in UI |
| Mulligan | Ctrl+M |
POST /api/actions/key |
Toggle mulligan |
| Shot Options (Normal/Punch/Flop/Chip) | ' (apostrophe) + context? |
POST /api/actions/key |
Might need mapping to GSPro UI if not explicit |
| Tee Box (Left/Right) | C (tee left), V (tee right) |
POST /api/actions/key |
Navigates tee position |
| Map Expand/Collapse | S |
POST /api/actions/key |
Toggles map size |
| Map Zoom (In/Out) | Q (zoom +), W (zoom -) |
POST /api/actions/key |
Could be UI slider later |
| Map Click (Expanded) | Mouse click | POST /api/actions/key or WS click event |
Normalized coordinates mapped to screen |
| Scorecard | T |
POST /api/actions/key |
Toggle scorecard |
| Range Finder | R |
POST /api/actions/key |
Launch rangefinder |
| Heat Map | Y |
POST /api/actions/key |
Toggle heatmap overlay |
| Putt Toggle | U |
POST /api/actions/key |
Enable/disable putting mode |
| Pin Indicator | P |
POST /api/actions/key |
Show/hide pin indicator |
| Flyover | O |
POST /api/actions/key |
Hole preview |
| Tracer Clear | F1 |
POST /api/actions/key |
Clear ball tracer |
| Aim Point | F3 |
POST /api/actions/key |
Toggle aim point view |
| Free Look | F5 |
POST /api/actions/key |
Unlock camera |
| Console Short/Tall | F8 / F9 |
POST /api/actions/key |
Open GSPro dev consoles |
| Fullscreen | F11 |
POST /api/actions/key |
Toggle fullscreen |
| Camera Go To Ball | 5 |
POST /api/actions/key |
Jump to ball cam |
| Camera Fly To Ball | 6 |
POST /api/actions/key |
Fly cam to ball |
| Go To Ball (practice) | 8 |
POST /api/actions/key |
Only in practice mode |
| Previous/Next Hole | 9 / 0 |
POST /api/actions/key |
Only in practice mode |
| Sound On/Off | + / - |
POST /api/actions/key |
Volume control |
| FPS Display | F |
POST /api/actions/key |
Show/hide FPS |
| Green Grid | G |
POST /api/actions/key |
Show/hide green putting grid |
| Lighting | L |
POST /api/actions/key |
Adjust lighting |
| Shot Camera | J |
POST /api/actions/key |
Switch to shot cam |
| UI Hide/Show | H |
POST /api/actions/key |
Toggle GSPro UI |
| 3D Grass Toggle | Z |
POST /api/actions/key |
Show/hide grass detail |
| Switch Handedness | N |
POST /api/actions/key |
Left/right handed player |
| Shadow Intensity | < / > |
POST /api/actions/key |
Adjust shadows |
| Fast Forward Ball Roll | Hold key (space?) | POST /api/actions/keydown + /keyup |
Needs “hold” support |