---
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.