videoToOCF

Computer-vision pipeline that turns basketball video into Open Coaching Format (OCF) JSON.

Status: early planning / pre-alpha. No pipeline code yet — this README documents the architecture and roadmap before implementation starts.

---

What this is

OCF is a JSON standard for representing basketball plays, drills, and playbooks — real-world court coordinates, named positions, and semantic actions (screen, cut, dribble, pass, shoot, …). See opencoachingformat/spec for the schema and full specification.

videoToOCF extracts that structured data automatically from video: detect players and the ball, calibrate the court, track possession, recognize events, and emit a valid .ocf.json file.

Scope for v0.1 (MVP)

Deliberately narrow to start:

• Input: a single half-court or full-court clip, static camera
• Output: a valid .ocf.json with entities, balls, and frames covering only dribble, pass, and shoot (incl. result: make/miss)
• Explicitly out of scope for v0.1: screen, cut, defend, pickup — these need real action classification, which doesn't exist cleanly anywhere yet (targeted for v0.2+)

Pipeline architecture

Video
  │
  ├─ 1. Detection & Tracking      → player/ball boxes per frame + persistent IDs
  ├─ 2. Team Assignment           → offense/defense (derived from possession, not just jersey color)
  ├─ 3. Court Calibration         → pixel → OCF real-world coordinates (m/ft, midcourt origin)
  ├─ 4. Event Detection           → pass / shot (+ make/miss) / dribble from trajectories
  ├─ 5. Frame Segmentation        → continuous tracking → discrete OCF frames with start/end_state
  └─ 6. OCF Serializer            → JSON export + validation against opencoachingformat/spec's schema/v1.json

Building blocks

Each stage draws on a different piece of prior art. None of this is copy-pasted wholesale — licenses and provenance are tracked explicitly:

Stage	Source of inspiration / code	Notes
1. Detection/Tracking	abdullahtarek/basketball_analysis (MIT)	MIT-licensed, freely reusable as a starting point for YOLO detection + team clustering + keypoints
3. Court Calibration	Roboflow's basketball court-keypoint dataset (Roboflow Universe) for training; homography approach informed by abdullahtarek / HanaFEKI/AI_BasketBall_Analysis_v1	Biggest effort sink otherwise — pre-labeled data saves weeks
Tracking primitives	roboflow/supervision (MIT, actively maintained)	Preferred over ad-hoc trackers (e.g. Norfair) for stability and ecosystem support
4. Shot/pass heuristics	vinod-polinati/basketball-vision-analytics as a methodology reference (release/peak/descent trajectory analysis, direction-change pass detection)	No license on that repo — approach reimplemented from scratch, not copied
Action vocabulary	Warmvne/Basketball_ComputerVision as conceptual reference	Its 7-class action taxonomy overlaps closely with OCF's action set; pick-and-roll detection is a useful reference for v0.2
5–6. Frame segmentation, OCF serializer	Original work	No existing project does this — it's the actual OCF-specific core only this repo builds

Repository layout (planned)

videoToOCF/
├── pipeline/
│   ├── detection.py          # YOLO wrapper
│   ├── tracking.py           # supervision/ByteTrack wrapper
│   ├── calibration.py        # homography, court-keypoint inference
│   ├── possession.py         # ball carried_by / at / dead state machine
│   ├── events.py             # pass/shot/dribble detection
│   └── segmentation.py       # continuous tracking → OCF frames
├── ocf_export/
│   └── serializer.py         # builds the .ocf.json, validates against the spec schema
├── models/                   # trained weights (court keypoints etc.)
├── examples/
│   └── sample_clip → sample.ocf.json   # end-to-end proof
├── tests/
├── README.md
├── CONTRIBUTING.md
└── LICENSE

Roadmap

1. M0 — Proof of concept: a single pick-and-roll clip → a correctly validated .ocf.json with only pass+shoot, coarse coordinates (calibration not required yet)
2. M1 — Court calibration: real homography module trained on the Roboflow dataset, real-world coordinates in meters
3. M2 — Possession/team logic: offense/defense reliably assigned, carried_by/at/dead correct across a full sequence
4. M3 — Robust frame segmentation: works across multiple different clips, not just the test video
5. M4 (stretch) — Screen/cut detection: custom classification, informed by Warmvne's taxonomy

License

Apache License 2.0 — see LICENSE. Commercial use, closed derivatives, and building products on top are all explicitly permitted.

This is separate from the OCF specification itself (opencoachingformat/spec), which is licensed CC BY 4.0 — that separation is deliberate: the format stays maximally permissive so anyone can implement it, while this tool can evolve its licensing independently as the project's direction (hobby vs. commercial) becomes clearer.

Contributions require signing a CLA (see CONTRIBUTING.md) — this keeps relicensing options open later without needing to track down every past contributor.