85 lines
3.9 KiB
Markdown
85 lines
3.9 KiB
Markdown
|
# 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.
|