PinPoint/README.md

# PinPoint (BowlEye)

An Android application for analyzing a bowler's approach and delivery form using on-device pose detection. The app captures video of a bowler via the phone camera, tracks body landmarks in real time, and surfaces step-count, joint-angle, and phase feedback to help improve technique.

See [`docs/`](docs/) for the project proposal, architecture, and deliverables/ownership breakdown.

## Tech stack

- **Language:** Kotlin (application/feature code), Java (legacy entry point), C++ (native game shell)
- **Platform:** Android (min SDK 24, target/compile SDK 36)
- **Build system:** Gradle (Kotlin DSL version catalog) + CMake 3.22.1 for the native module
- **Key libraries:** CameraX (capture), ML Kit Pose Detection — accurate model (landmark tracking), Kotlin Coroutines, AndroidX Lifecycle/ViewModel

## Prerequisites

- **Android Studio** (current stable channel) — bundles a compatible JDK, so no separate JDK install is required
- **Android SDK** with:
  - Android SDK Platform 36 (and 36.1)
  - NDK (side by side) — a recent version compatible with AGP
  - CMake 3.22.1
  - Android SDK Build-Tools 36.0.0
- A physical Android device with a camera (recommended) or an emulator with a virtual/webcam camera. Real camera input is strongly recommended since pose detection needs an actual moving subject.

> The NDK/CMake/platform components above do **not** need to be installed manually — both Android Studio's "install missing components" prompt and a plain `./gradlew` command-line build will fetch them automatically on first sync/build, provided you have internet access and accept the SDK license prompts.

## Getting started

### Option A — Android Studio

1. `File > Open` and select the repository root.
2. Let Gradle sync; approve any "install missing SDK components" prompts.
3. Connect a device (enable **Developer Options > USB debugging** on the phone) or start an emulator.
4. Click **Run** ▶ with the `app` configuration selected.

### Option B — Command line

```bash
# Windows
.\gradlew.bat assembleDebug
.\gradlew.bat installDebug

# macOS / Linux
./gradlew assembleDebug
./gradlew installDebug
```

Then launch an activity directly, e.g.:

```bash
adb shell am start -n com.example.jnicpp/.MainActivity
adb shell am start -n com.example.jnicpp/.bowling.BowlingCameraActivity
```

### First-time local setup notes

- Gradle needs a `local.properties` file **at the repository root** (not inside `app/`) pointing at your local Android SDK, e.g.:
  ```
  sdk.dir=/Users/you/Library/Android/sdk
  ```
  Android Studio creates/updates this automatically on first sync. This file is machine-specific and is gitignored — never commit it.
- The app requests **Camera** and **Record Audio** permissions at runtime; grant both to use the bowling analysis screen.

## Project structure

```
app/
├── src/main/cpp/            # Native C++ game shell (OpenGL ES menu, JNI bridge), built via CMake
├── src/main/java/.../       # MainActivity (native GL menu host)
└── src/main/java/.../bowling/  # Bowling capture + pose analysis feature (Kotlin, CameraX + ML Kit)
docs/                        # Proposal, architecture, design, and deliverables documentation
```

The native GL menu (`MainActivity`) and the bowling camera/pose-analysis screen (`BowlingCameraActivity`) are currently two independent entry points — see [`docs/architecture.md`](docs/architecture.md) for how they're intended to connect.

## Running tests

```bash
./gradlew test            # JVM unit tests
./gradlew connectedCheck  # Instrumented tests (requires a connected device/emulator)
```

## Cross-platform notes

The native game-state code under `app/src/main/cpp/my_gl_app/` is written behind a `Platform.h` seam with both `PLATFORM_ANDROID` and `PLATFORM_WINDOWS` (GLFW) code paths, so the menu/state-machine logic itself is portable. Only the Android (Gradle/CMake) build is wired up today; there is no standalone desktop build target yet.