How it works · Quickstart · Results · Data · Model card · Citation
ArmAngleCV estimates a pitcher's release arm angle from a single video frame. Pick the release frame, click five points, and get a Statcast-style angle in degrees — about 2.65° RMSE against Statcast on pitchers the model never saw.
Important
Validated scope: MLB center-field broadcast footage. College, high-school, side-view, and recruiting-reel accuracy is unverified. See the model card.
- Find release. Scrub the clip with the timeline, arrow keys, and neighboring frames, then lock the release frame.
- Mark five points. The view zooms to the pitcher automatically. Click throwing shoulder, opposite shoulder, elbow, wrist, then ball.
- Estimate. The app shows the raw shoulder-to-ball angle and the model estimate. The model is a standardized ridge regression on 12 features from all five points, with coordinates rescaled to 720 px height so resizing the video doesn't change the result.
- Save and export. Each saved pitch becomes a CSV row; export a whole session at once.
| Step | Where | Writes |
|---|---|---|
| Fetch MLB examples (optional) | scripts/fetchUiTestBatch.py |
pitches/ |
| Label and analyze | armangle/labelServer.py + web/ |
analysisLabels.csv |
| Predict | armangle/angleInputs.py + model/armAngleModelResolutionSafe.joblib |
in-app estimate |
| Export | Export session CSV / scripts/predictLabels.py |
session CSV |
| Retrain and evaluate | scripts/evaluateAngleInputs.py |
reports/ |
| Verify release | tools/checkRelease.py |
— |
Use Python 3.12. No GPU or neural-network weights are needed.
python3.12 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m armangleOpen http://127.0.0.1:8777/index.html and choose Upload a video or Try MLB examples.
To download one fixed MLB example clip first (omit --limit 1 for all 12):
python -m pip install -r requirements-fetch.txt
python scripts/fetchUiTestBatch.py --limit 1Upload limits and labeling controls
- MP4 up to 100 MB, 60 s, 1920 × 1080, 60 fps, and 3,600 frames. Uploads are copied
to
uploads/on your computer; nothing leaves your machine. - Drag a point to adjust it. Scroll to zoom at the cursor, shift-drag to pan, and
press
Zto toggle between the pitcher crop and the full frame. - If the ball is hidden, mark it unavailable. It saves as an occluded annotation but produces no model estimate.
- Quality notes record uncertainty; they are not a confidence score.
- Use short clips: frames are decoded into memory.
Eight outer folds grouped by pitcher, so no pitcher appears in both training and test:
| Method | RMSE | MAE |
|---|---|---|
| Raw shoulder-to-ball angle (no model) | 3.227° | 2.592° |
ArmAngleCV manual-v1 |
2.653° | 2.137° |
These are development cross-validation results on 180 pitches from 98 pitchers
across all 30 parks, not an external benchmark. tools/checkRelease.py reproduces
them exactly and verifies the shipped model's checksums.
Limits: the extreme low-slot tail (below −30°) has 12 pitches from one pitcher, and there is no calibrated per-pitch confidence interval. Details are in the model card.
| File | Contents |
|---|---|
data/manual-v1/labels.csv |
Frozen 184-row snapshot the shipped model was trained on. Do not edit. |
data/labels.csv |
Current development labels (192 complete, 103 pitchers). |
data/savant_data.csv |
Baseball Savant export, Aug 10–16, 2026, used to select pitches. |
data/uiTestBatch.json |
Identifiers for the 12 MLB example clips. |
analysisLabels.csv |
Yours, created locally. Saved analyses; git-ignored. |
Arm-angle targets and pitch metadata come from Baseball Savant. No broadcast video is included. See DATA_SOURCES.md for attribution and the V1 CSV contract for export fields. This project is not affiliated with or endorsed by MLB.
ArmAngleCV/
├── armangle/ # core package — `python -m armangle` starts the local app
│ ├── labelServer.py # local server and API
│ ├── angleInputs.py, features.py, AnglePredictor.py # model inputs and estimator
│ └── analysisExport.py, videoUploads.py, savantUtils.py, releaseTiming.py
├── web/ # browser UI: labelTool.html, labelTool.js, workspace.css
├── scripts/ # command-line tools: fetch clips, predict, evaluate
├── model/ # shipped ridge models + checksummed manifest
├── data/ # labels, frozen manual-v1 snapshot, Statcast export
├── hosted/ deploy/ # optional AWS web app and its deployment config
├── phase4/ # experimental automatic keypoints
├── tools/ tests/ # release checks, bundle builders, test suite
├── docs/ # model card, data sources, guides
└── assets/ reports/ # README images, validation outputs
python -m unittest discover -s tests -v # includes a real first-run server test
node --test tests/labelTool.test.cjs # browser workflow logic (Node 22)
python tools/checkRelease.py # model/data checksums and grouped score| Status | Features |
|---|---|
| ✅ Supported | Manual release selection, five-point labeling, angle prediction, CSV export |
| 🧪 Experimental | Automatic keypoints (phase4/) and release detection |
| 🗓️ Planned | Independent validation batch; college footage validation |
See research workflows and the research history.
Hosted deployment (AWS)
A separate Flask/Gunicorn runtime in hosted/ serves the analysis workspace with
per-visitor isolation, SQLite saves, private frame storage, upload limits, and
expiry/deletion. The local app is unaffected.
- Elastic Beanstalk guide · build with
tools/prepareBeanstalk.py - Lightsail guide
- Optional S3 original storage
- Privacy and storage
- Public release checklist
Code is released under the MIT license. Statcast data remains subject to MLB's terms. If you use ArmAngleCV in your work, cite it with GitHub's Cite this repository button or:
@software{capretta_armanglecv_2026,
author = {Capretta, Charlie},
title = {ArmAngleCV: Pitcher release arm angle from broadcast video},
year = {2026},
url = {https://github.com/charliecapretta/ArmAngleCV}
}