richardpenner/sportsball-game-recognition

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

1. 1.sport-router selects baseball, basketball, or neither from the complete camera frame.
2. 2.mlb-scorebug-locator finds a Major League Baseball scorebug.
3. 3.nba-scorebug-locator finds a National Basketball Association scorebug.
4. 4.mlb-team-detector identifies Major League Baseball team marks in the high-resolution scorebug crop.
5. 5.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:

python -m pip install huggingface_hub ultralytics
hf download richardpenner/sportsball-game-recognition \
  --local-dir sportsball-game-recognition

This short Python example runs the sport router on one camera frame:

from ultralytics import YOLO

router = YOLO("sportsball-game-recognition/sport-router/model.pt")
result = router.predict("camera-frame.jpg", imgsz=384)[0]
print(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.