ultimate-radar
Turn one possession of broadcast Ultimate Frisbee footage into two synchronized views — an
overlay on the video and an overhead field view — that let a coach see how a defence
organises, moves and breaks, and correct the system when it is wrong.
See it
| |
|---|
| p0001 — midfield possession | 24 s, 4th quarter. 88 % tracker recall, 13 of 14 players in shot at the open. |
| p0003 — endzone possession | 37 s, 1st quarter, ending in a goal. Harder: only 53 % of frames clear the calibration confidence floor, and the viewer says so. |
| The synthetic fixture | Invented throughout. Built so the hard cases are visible on demand — players leaving the camera, estimates drifting, a planted identity swap, and the correction flow that repairs it. Not published: it is a development target, and offering it beside real footage invites the two being read as the same kind of thing. Open viewer/index.html with no working directory to see it. |
Scrub the timeline and watch the coverage number. Every readout carries a chip saying whether
it was measured, partial or inferred, and an inferred one names what it could not
see. That is the point of the project rather than a disclaimer on it.
About the footage. The two real pages carry 24 and 37 second excerpts of a publicly posted
UFA broadcast — Austin Sol vs Minnesota Wind Chill, 27 August 2026 — used here to demonstrate
video analysis. Source and provenance are in docs/10-getting-the-footage.md. This project is
not affiliated with or endorsed by the UFA or either club, and the footage is theirs, not mine.
Everything else — code, documents, tracking output, the fixture — is MIT, see LICENSE.
Two commitments shape the whole design, and everything else follows from them:
- Never pretend to know. A single broadcast camera sees roughly 10 of 14 players at a
time, and the ones it misses skew toward the deep defenders who decide whether a huck is on.
So the overhead view draws the camera's real field of view, anything outside it is explicitly
inferred, and a tactical readout refuses to present itself as measured when its inputs were
not observed.
- Always be fixable. Same-team identity swaps are what every appearance model does to
players in identical jerseys. The system detects its own, repairs them in one click, and
keeps corrections in an append-only layer that never touches the raw output.
Licence: MIT, see LICENSE. Model and dependency licences are audited per component in
docs/07-licenses.md — no AGPL, which rules out Ultralytics YOLO and boxmot.
Turn one possession of broadcast Ultimate footage into two synchronized views — an
overlay on the video and an overhead field view — that let a coach see how a defence
organises, moves and breaks, and correct the system when it is wrong.
Round one target footage: UFA 2026 semifinal, Austin Sol vs Minnesota Wind Chill,
27 Aug 2026, Breese Stevens Field, Madison WI. https://www.youtube.com/watch?v=IDnoyd4cKfM
— 2:22:27, downloaded as 1920×1080 avc1, 59.94 fps (format 299+140, 5.95 GB). The AV1
compromise the early docs anticipated is not needed; a 1080p60 H.264 stream is offered.
Constraints that are not negotiable
- Free. Open weights, permissive licences, no paid APIs, no cloud inference.
- Runs on one desktop with a consumer NVIDIA GPU (8–12 GB VRAM assumed).
- No AGPL. Ultralytics YOLO (all versions) and
boxmot are AGPL-3.0 and are out.
See docs/07-licenses.md before adding any dependency.
- Offline and serverless. The viewer is a static page reading JSON from disk.
- This is personal film study. Do not redistribute the video or the extracted frames.
Try it in ten seconds
Open viewer/index.html in a browser. No server, no build step, no install. With no
working directory present it renders the committed synthetic fixture and says so at the top;
with one, it renders the real possession.
Start here
| Read | For |
|---|
HANDOFF.md | Resuming work. Current state (M0–M6 built), the three results that are not clean, and what to do next. Read this first. |
docs/09-decision-record.md | One page: the commitments, the decisions, the state |
docs/00-footage-report.md | What the real footage actually looks like, measured. It corrected several figures in the docs below; its foot lists every change. |
docs/01-brief.md | What success means, and what this is not |
docs/02-architecture.md | The pipeline diagram and the stage notes |
docs/adr/ | The ten decisions, AD-1 to AD-10, one file each |
docs/03-data-contracts.md | Every file the stages exchange |
docs/04-milestones.md | The build order, with acceptance tests. Work from this. |
docs/05-uncertainty.md | Evidence states and the correction model — the heart of the product |
docs/06-viewer.md | Viewer spec, derived from a working prototype |
docs/07-licenses.md | Licence register. Check before pip install. |
docs/08-risks.md | What might not work, what has not been verified, and the open questions |
docs/10-getting-the-footage.md | Downloading the game and cutting a possession |
docs/11-m0-review.md | An independent review of M0 — found a real M1 hazard, and a claim that had to be withdrawn |
docs/12-m1-calibration.md | M1: how calibration works here, its numbers, and the five bugs worth keeping |
docs/13-m2-detection.md | M2: detection, why its false-positive gate had to be deferred, and what the misses are |
docs/14-m3.md | M3: team assignment, the referee test that is not the one predicted, and a sigma that was 46 % honest |
What already exists
M0–M6 are built. M0–M4 are gated and pass, with one threshold left deliberately unset. M5
passes three of four criteria — the jersey gate fails at 3 of 7 against a gate of 5. M6's page
is built and works; its file:// criterion and its comprehension test both need a human and
are unrun. HANDOFF.md is the cold-start document and carries all of that in one place.
Pipeline
ur/ingest.py, ur/ffprobe.py — M0. Cuts a possession, emits 15 fps frames plus the
native clip, writes clip.json. Deterministic, byte-identical across runs. source.start_s
is measured against the source frames, not assumed.ur/calibrate/ — M1. A fixed camera centre with per-frame pan/tilt/roll/focal, fitted
to the soccer centre circle and halfway line. Writes calibration.json with a residual and
a confidence per frame. Mean held-out reprojection error 0.0996 yd.
ur.calibrate.verify renders the line overlay; ur.calibrate.accept runs the gate.ur/detect/ — M2. D-FINE (Apache-2.0 code and weights), person class only, whole
frame, no fine-tune, no SAHI. Writes detections.json with field positions, a per-detection
sigma, and an explicit in/out-of-bounds decision. Recall 0.9873. Its sigma_yd is built
on a measured 5.83 px of foot error, not M2's assumed 3.ur/team.py — M3. Fits the two kits per possession by deterministic 2-means on torso
L*, then rejects referees on stripe periodicity and camera crew on position and
appearance. Team accuracy 0.9957; false positives 1.15 → 0.30 per frame with zero
real players lost, which closes the gate M2 had to defer.ur/track/ — M4. A Kalman filter in field yards (AD-1), 14 slots never created or
destroyed (AD-2), per-team gated Hungarian association (AD-3), and the docs/05 evidence
state machine. Writes tracks.json. Its motion model is an integrated Ornstein-Uhlenbeck
velocity whose one free constant is measured by tools/m4_speed.py rather than chosen.
Per-player recall 0.8846; position error 0.3698 yd median; sigma containment 80 %.ur/possess.py — M4. Reshapes tracks.json into the columnar possession.json the
viewer reads. Never mutates tracks.json (AD-6), and carries the measured gates in the
file so nothing downstream can quote a position without the recall beside it.ur/issues.py — M5. The "needs a human" queue. Four detectors, one of which fires zero
times on real data and is kept in the code with the reason, because it is the more
instructive of the two: a detector built on is blind to exactly the errors
a tracker makes. The one that works asks whether the choice was .
Possessions on disk (all gitignored; regenerate per HANDOFF.md)
work/p0001/ — the working possession. 24.0 s, 360 frames, one camera shot. clip.json +
calibration.json + detections.json + tracks.json + possession.json + issues.json +
identities.json + events.json.work/p0002/ — the pull before p0001, cut as calibration reconnaissance.work/p0003/ — endzone-framed, 26.0 s. Cut to settle the 120-vs-110 yd question and to be
M7's second possession. Its calibration is deliberately near-useless (confidence ≥ 0.5
on 1 % of frames) because the honesty guards correctly refuse to fit a shot with no
exactly-specified geometry in view. That is the intended behaviour, not a regression.
Evidence and labels — eval/m0/ … eval/m5/, all committed. Includes the acceptance JSON
for each gate, the verification videos, and the hand-label sets
(eval/m0/visibility_counts.json, eval/m2/labels.json, eval/m3/team_labels.json,
eval/m3/foot_labels.json, eval/m4/foot_labels_fresh.json, eval/m4/jersey_labels.json),
which are the most expensive artefacts here and the hardest to regenerate.
Measurement tools — tools/: seeded still extraction, paint detection, whole-game
scene-change scan, contact sheets, gridded crops, plus two checks worth knowing about.
tools/regcheck.py demonstrates why registration must run on a mask; tools/pancheck.py
cross-checks the calibration's camera motion against an independent measurement that shares
no code with it.
For the viewer — viewer/index.html is the product. viewer/prototype.html is the design
reference docs/06-viewer.md was written from and is kept for comparison.
fixtures/possession_demo.json is a synthetic 7v7 possession in the real schema, with a camera
that sees ~10 of 14 players, ghosts that drift, and a deliberate identity swap;
tools/make_demo_possession.py generates it and is the easiest way to learn the schema by
example. See viewer/README.md.
Layout
ultimate-radar/
docs/ specs and per-milestone results
fixtures/ synthetic + hand-labelled ground truth
eval/ committed evidence for every gate
tools/ measurement scripts and label harnesses
ur/ the package
ingest.py video -> frames + clip metadata [built]
calibrate/ world model, camera, mask, paint, fit, venue, verify [built]
detect/ detector wrapper + bounds and size filters [built]
team.py kit-colour team assignment, plus the referee test [built]
track/ field-space Kalman + slot-locked association [built]
possess.py tracks.json -> possession.json [built]
issues.py the "needs a human" queue [built]
resolve.py applies corrections.json over tracks.json [built]
identify/ jersey OCR, tracklet voting [built]
events.py human event tagging [built]
derive.py tactical metrics with provenance propagation [in the viewer]
viewer/ static page, no build step, no framework
work/ per-possession working dirs (gitignored)
derive.py does not exist as a module: the six readouts are computed in the viewer, because
they change with every correction and a precomputed file would be stale the moment a coach
dragged a marker. If M7 needs them exported, that is the time to lift them out.
Running
Run everything through the venv: .\.venv\Scripts\python.exe -m <module>.
python -m ur.ingest --source raw/sol-vs-windchill-2026-semi.mp4 \
--id p0001 --start 7264.0 --duration 24.0 --offense sol --defense chill
python -m ur.calibrate.run work/p0001 # -> calibration.json
python -m ur.calibrate.verify work/p0001 --video # the line-overlay render
python -m ur.calibrate.accept work/p0001 # the M1 gate
python -m ur.detect.run work/p0001 # -> detections.json
python -m ur.detect.overlay work/p0001 # boxes burned onto the clip
python -m tools.m2_label score work/p0001 # the M2 recall gate
python -m ur.team work/p0001 # fills team / team_score in detections.json
python -m tools.m3_label score work/p0001 # the team gate, and M2's deferred FP gate
python -m tools.m3_foot score work/p0001 # the foot-point gate
python -m ur.track.run work/p0001 # -> tracks.json
python -m ur.possess work/p0001 # -> possession.json
python -m tools.m4_render work/p0001 # the tracker video — watch it before measuring
python -m tools.m4_recall work/p0001 # the re-specified observed gate
python -m tools.m4_structure work/p0001 # slot structure + position + sigma gates
python -m ur.issues work/p0001 # -> issues.json
python -m ur.identify.vote work/p0001 # -> identities.json (~4 min, GPU)
python -m tools.m5_identity work/p0001 # the jersey gate
python -m tools.m5_resolve work/p0001 # the anchor + revert gates
python -m ur.events work/p0001 suggest # -> events.json
python -m ur.resolve work/p0001 # applies corrections.json, if any
python -m tools.make_view work/p0001 # -> viewer/live-data.js
Then open viewer/index.html directly. If you would rather serve it, use a server that
supports range requests — Python's http.server does not, and the video will not seek.
