rhill051/gsproremote
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gsproremote/PRD.md

229 lines
No EOL
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
1. **Deliver a clean, intuitive remote-control interface** optimized for tablets/phones.
2. **Support all GSPro keyboard shortcuts** via touch-friendly buttons.
3. **Provide low-latency streaming of the GSPro map/mini-map** (\~200ms or less).
4. **Persist user settings/configuration** locally on the GSPro PC between sessions.
5. **Make installation simple** for non-technical users (one installer, auto-start server).
6. **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 `pydirectinput` to 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 |
Reference in a new issue View git blame Copy permalink