Sportsball game-recognition models
Sportsball uses a phone camera to identify a baseball or basketball broadcast
on a television. This repository contains the five model roles used by the
camera pipeline.
A scorebug is the on-screen graphic that shows the score and teams.
Model roles
sport-router selects baseball, basketball, or neither from the complete
camera frame.mlb-scorebug-locator finds a Major League Baseball scorebug.nba-scorebug-locator finds a National Basketball Association scorebug.mlb-team-detector identifies Major League Baseball team marks in the
high-resolution scorebug crop.nba-team-detector identifies National Basketball Association team marks
in the high-resolution scorebug crop.
The team pair is selected before schedule data is checked. A schedule can add
an official game identifier, but it does not change the recognized teams.
Source code
The application, training tools, evaluation tools, and deployment examples are
available in the
public Sportsball source repository.
Files
Each model folder includes these files when the format applies:
model.pt: PyTorch weights for Ultralytics YOLO.model.onnx: a portable Open Neural Network Exchange model.hailo-source.onnx: the exact output form used for Hailo compilation.model.hef: a Hailo Execution Format model for Hailo-10H devices.labels.json: class order, input size, and output details.
SHA256SUMS contains a SHA-256 checksum for every release file. A checksum is
a file fingerprint that detects an incomplete or changed download.
Download and test
Install the Hugging Face and Ultralytics command-line tools, then download the
complete model set:
1python -m pip install huggingface_hub ultralytics
2hf download richardpenner/sportsball-game-recognition \
3 --local-dir sportsball-game-recognition
This short Python example runs the sport router on one camera frame:
1from ultralytics import YOLO
2
3router = YOLO("sportsball-game-recognition/sport-router/model.pt")
4result = router.predict("camera-frame.jpg", imgsz=384)[0]
5print(result.names[result.probs.top1], float(result.probs.top1conf))
The scorebug locators accept a complete camera frame at 768 input pixels. The
team detectors accept the native-resolution scorebug crop at 960 input pixels.
The full application must use the router, the selected locator, and the
matching team detector in that order.
Measured results
Measurements below use fixed test sets that were not used for training.
Sport router
- Permanent test: 1,056 of 1,069 frames correct, or 98.78%.
- Visible real-phone scorebugs: 13 of 13 routed correctly.
- Hailo top-choice agreement with PyTorch: 1,067 of 1,069, or 99.81%.
- Hailo accelerator-only rate: 659.49 frames per second.
Routed scorebug search
This result uses the sport router, both sport-specific locators, and the
fallback that tries the other locator after a miss.
- Scorebugs found: 95 of 96, or 98.96%.
- No-scorebug frames with an incorrect detection: 3 of 60, or 5.00%.
- Major League Baseball phone scorebugs found: 12 of 13.
- Major League Baseball phone no-scorebug frames with an incorrect detection:
0 of 43.
- National Basketball Association scorebugs found: 83 of 83.
- National Basketball Association no-scorebug frames with an incorrect
detection: 3 of 17.
Major League Baseball scorebug locator
- Clean-broadcast scorebugs found: 83 of 91, or 91.21%.
- Clean-broadcast no-scorebug frames with an incorrect detection: 2 of 22, or
9.09%.
- Median shared-area score: 0.868. This measures the overlap between the
predicted and human rectangles. A value of 1.0 is perfect.
- Median predicted-area ratio: 1.137. The predicted rectangle was typically
13.7% larger than the human rectangle.
Major League Baseball team detector
The training validation set produced 0.937 precision, 0.936 recall, 0.961
mean average precision at the 50% overlap check, and 0.754 mean average
precision averaged across the 50% through 95% overlap checks. Precision is
the share of reported marks that are correct. Recall is the share of expected
marks that are found. These training validation values do not replace the
saved-phone tests used for product decisions.
National Basketball Association team detector
At the 0.50 confidence cutoff:
- Fixed clean-broadcast test: at least one expected team in 75 of 82 crops, or
91.5%; both teams in 56 of 80 two-team crops, or 70.0%.
- Fixed 328-image phone-to-television test: at least one expected team in 318
of 328 crops, or 97.0%; both teams in 232 of 320 two-team crops, or 72.5%.
- Training validation: 0.919 precision, 0.845 recall, 0.913 mean average
precision at the 50% overlap check, and 0.773 mean average precision averaged
across the 50% through 95% overlap checks.
Limits
- The product targets a phone camera aimed at a television. Results on clean
broadcast frames do not prove phone-to-television performance.
- A scorebug that is partly outside the camera frame might not show both teams.
- The National Basketball Association team model covers regular-season
graphics. A retained Summer League test did not recognize both teams because
that scorebug style was absent from training.
- Broadcast graphic styles can change by network, event, and season.
- These models identify the broadcast and its teams. They do not supply game
facts or summaries.
Training data
The training data includes reviewed broadcast frames and generated
phone-to-television scenes. The data is not included in this repository.
Users must obtain their own lawful training and test data.
License
The models and release files use the GNU Affero General Public License version
3.0. The models were trained with Ultralytics YOLO, which applies that license
to trained models by default.
Major League Baseball, National Basketball Association, team names, and team
marks belong to their respective owners. This project is not endorsed by the
leagues or teams.
