| --- |
| license: agpl-3.0 |
| library_name: coreml |
| tags: |
| - pose-estimation |
| - keypoint-detection |
| - fitness |
| - coreml |
| - onnx |
| base_model: Ultralytics/YOLOv8 |
| --- |
| |
| # Spotter models |
|
|
| Models for **Spotter**, a quiet AI spotter for new gym-goers and people returning from injury |
| (Knight Hacks IX). The iPhone app runs the pose model on-device; the form model scores reps. |
| The app reads `manifest.json` on launch and downloads any model that changed. |
|
|
| Manifest version **2**, published 2026-10-10T17:03:35+00:00. |
|
|
| | Model | Format | Path | Size | |
| |---|---|---|---| |
| | `form-quality-label-onnx` | onnx | `form/form_quality_label.onnx` | 0.9 MB | |
| | `form-quality-score-onnx` | onnx | `form/form_quality_score.onnx` | 0.2 MB | |
| | `pose-256-coreml` | coreml | `pose/yolov8n-pose-256.mlpackage` | 6.7 MB | |
| | `pose-320-coreml` | coreml | `pose/yolov8n-pose-320.mlpackage` | 6.7 MB | |
| | `pose-320-onnx` | onnx | `pose/yolov8n-pose-320.onnx` | 13.3 MB | |
|
|
| ## Pose: YOLOv8n-pose |
|
|
| - Ultralytics YOLOv8n-pose (COCO keypoints), exported at 320 and 256 px to Core ML (FP16, no NMS) |
| and at 320 px to ONNX. |
| - Output: one tensor `[1, 56, N]` of raw candidates: 4 box values, person confidence, then |
| 17 joints x (x, y, visibility), with sigmoid already applied. Decoding and orientation rules: |
| `docs/pose/how-it-works.md` and `docs/pose/pose-result-contract.md` in the Spotter repo. |
| - Video never leaves the phone; only joint positions are sent to the cloud. |
|
|
| ## Form quality |
|
|
| - `spotter.ml.form_quality` version 4 |
| from Databricks Unity Catalog, as two ONNX graphs: `label` (clean, partial_range, knees_in, |
| forward_lean, fast_lowering, other) and `score` (quality, clip to 0-1). |
| - Inputs, one row per rep: `exercise_id`, `range_deg`, `weight_kg`. |
| `exercise_id` is a string; unseen exercises are ignored. Numeric inputs may be missing (NaN). |
| - Held-out metrics: label_accuracy 0.188, label_macro_f1 0.2427, quality_mae 0.0807, quality_r2 0.153, test_lifters 40.0, test_reps 35816.0. |
| - **Limitations:** a baseline gradient-boosted model trained on labels derived from the phone's |
| rule flags and synthetic sessions, not hand-labelled clips. Expect it to be replaced. |
| |
| ## Intended use |
| |
| Real-time rep counting and form feedback for recreational lifting. **Not a medical device** and |
| not for diagnosing injuries. |
| |
| ## License |
| |
| The pose model is derived from Ultralytics YOLOv8 and is released under **AGPL-3.0**, the license |
| of the original weights. |
| |
