Game Analytics Platform Computer Vision

# Game Analytics Platform - Computer Vision Fitness Tracker

> Skill by [ara.so](https://ara.so) — Data Skills collection.

## What This Project Does

Game Analytics Platform is a local-first, real-time computer vision system that tracks user movements across 16 fitness exercises using webcam input. It combines:

- **YOLO v8** for object detection and tracking (balls, cones, people)
- **MediaPipe** for skeletal pose estimation and form validation
- **Spring Boot** (Java 17) backend for process orchestration
- **React + Vite** frontend dashboard for game control
- **Python AI scripts** that export workout metrics to CSV
- **pyttsx3** for real-time audio coaching

The architecture runs entirely locally with a 3-tier design: React UI → Spring Boot API → Python AI processes.

## Installation

### Prerequisites

Install these first:
- **Python 3.10+** (ensure "Add to PATH" is checked)
- **Java 17** (from Adoptium)
- **Node.js LTS**

### Auto-Install

```bash
# Windows
python install.py

# Mac/Linux
python3 install.py
```

This creates a Python virtual environment, installs dependencies, downloads YOLO models, and builds the frontend.

### Manual Setup (if auto-install fails)

```bash
# 1. Create Python virtual environment
python -m venv venv

# 2. Activate it
# Windows:
venv\Scripts\activate
# Mac/Linux:
source venv/bin/activate

# 3. Install Python dependencies
pip install ultralytics mediapipe opencv-python pandas pyttsx3

# 4. Build frontend
cd frontend
npm install
npm run build
cd ..

# 5. Build backend
cd backend
mvn clean package
cd ..
```

## Starting the Platform

```bash
# Windows
start.bat

# Mac/Linux
./start.sh
```

Access dashboard at `http://localhost:8080`

## Architecture Components

### 1. Spring Boot Backend (Java)

The backend orchestrates Python AI processes via REST API.

**Key Files:**
- `backend/src/main/java/com/gameanalytics/controller/GameController.java`
- `backend/src/main/java/com/gameanalytics/service/ProcessService.java`

**REST API Endpoints:**

```java
// Start a game
POST /api/games/{id}/start
// Response: 200 OK or 400 if game already running

// Stop a game
POST /api/games/{id}/stop
// Response: 200 OK

// Get available CSV data files
GET /api/games/data
// Response: ["workout_20260601_143022.csv", ...]

// Get list of all games
GET /api/games
// Response: [{"id": 1, "name": "YOLO Ball Counter", ...}, ...]
```

**Process Management Pattern:**

```java
// ProcessService.java
public class ProcessService {
    private Process currentProcess;
    private final Object lock = new Object();

    public boolean startGame(int gameId) {
        synchronized (lock) {
            if (currentProcess != null && currentProcess.isAlive()) {
                return false; // Game already running
            }
            
            String pythonPath = System.getProperty("os.name").toLowerCase().contains("win")
                ? "venv\\Scripts\\python.exe"
                : "venv/bin/python";
            
            String scriptPath = "games/exe_" + gameId + ".py";
            
            ProcessBuilder pb = new ProcessBuilder(pythonPath, scriptPath);
            pb.directory(new File(System.getProperty("user.dir")));
            pb.redirectErrorStream(true);
            
            try {
                currentProcess = pb.start();
                
                // Stream logs asynchronously