Flippd Pinball Vision — Score Extraction

Flippd Score Extraction finds numeric scores on photographed pinball displays and returns confidence-ranked suggestions. The private training corpus is not distributed. Inference runs locally with ONNX Runtime.

Artifacts and architecture

The pipeline is a two-model chain, not an image classifier:

1. detector.onnx is a YOLO11s display-score detector. Runtime preprocessing uses stride-32 letterboxing; detections above 0.25 confidence undergo IoU 0.7 non-maximum suppression.
2. Each retained crop is trimmed 2% on the left, resized to 48 pixels high with preserved aspect ratio, right-padded to 320 pixels, and passed to reader.onnx, an 8.0M-parameter CTC digit reader.
3. Width-8 prefix-beam decoding, digit normalization, plausibility filtering, confidence gating, deduplication, and ranking produce the final suggestions.

The default detector pass uses size 384. If it produces no accepted suggestion, the complete pass is retried at size 800. The learned geometry is used without crop dilation.

detector.onnx and reader.onnx are the unmodified source ONNX artifacts. PyTorch checkpoints, conversion tools, training code, datasets, user images, caches, and serving infrastructure are intentionally excluded.

Setup

Python >=3.12 is supported. From a fresh repository checkout:

Access is gated. Request access on Hugging Face, accept the license, and authenticate before downloading:

hf auth login
hf download Flippd/pinball-score-ocr --local-dir ./pinball-score-ocr
cd pinball-score-ocr

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

For CUDA, replace onnxruntime with onnxruntime-gpu; do not install both in one environment. Use --device cuda or --device cuda:N. CPU is the portable default.

Python usage

CLI

python inference.py ./photo.jpg --device cpu

The command writes indented JSON. --confidence overrides the configured 0.9 suggestion threshold, and --model-dir selects a directory containing both ONNX files and config.json.

API

from inference import PinballScoreExtractor

extractor = PinballScoreExtractor(device="cpu")
result = extractor.predict("./photo.jpg")
print(result["suggestions"])

PinballScoreExtractor resolves packaged artifacts relative to inference.py, so it does not depend on the process working directory. ScoreSuggester is also exported from pinball_score_ocr; its default artifact directory is the repository root. SCORE_OCR_MODELS_DIR can override that default. CPU tuning variables are SCORE_OCR_ORT_THREADS and SCORE_OCR_READER_WORKERS, both positive integers.

Inputs and preprocessing

Input is one Pillow-readable image path. The runtime decodes the image, converts it to RGB, and applies EXIF orientation. Very small detected crops (under 16 × 10 pixels) are discarded.

The detector receives contiguous CHW float32 RGB in [0,1] after aspect-preserving letterbox padding with RGB 114. Detector boxes are returned as normalized image coordinates. Reader crops become contiguous [B,3,48,320] float32 RGB in [0,1]; preserved-aspect content is placed at the left of an RGB-127 canvas.

Images remain local when this repository is run as documented. Codec support depends on the Pillow installation.

Outputs

predict returns:

{
  "suggestions": [{"score": "22919490", "confidence": 0.9999}],
  "detections": [
    {
      "bounding_box": {"x1": 0.1, "y1": 0.2, "x2": 0.8, "y2": 0.4},
      "score": "22919490",
      "confidence": 0.9999
    }
  ],
  "timing_ms": {
    "detection": 0.0,
    "preprocessing": 0.0,
    "reader": 0.0,
    "decoding": 0.0
  }
}

The example illustrates the schema; values depend on the image and hardware. Scores contain 1–12 digits, with leading zeros normalized. Suggestions require the configured confidence threshold, are deduplicated by normalized score, and are sorted by confidence. Empty suggestions and detections are valid when no acceptable score is found. Confidence is a model ranking signal, not a correctness guarantee.

Evaluation metadata

config.json records source-observed evaluation results and their populations. Under the packaged 384→800 fallback strategy, a 10,000-sample grouped-v3 test split reported 77.97% strict top-1, 87.23% in-list, and 94.59% shown, with fallback used for 8.64% of samples. These results do not guarantee performance on other image distributions.

Limitations and usage constraints

Results may be wrong or empty for glare, blur, oblique views, occlusion, low resolution, unusual display technology, non-score digits, partial scores, animations, multiple displays, or out-of-distribution images. The detector may find unrelated numeric regions, and the confidence threshold may reject a correct read or retain an incorrect one. Applications should show alternatives and confidence and require human review when an error matters.

The model reads visible digits; it does not establish player identity, ownership, location, authenticity, or game state. Do not use it for unlawful activity, biometric identification, surveillance, extracting unnecessary personal information, attempts to recover private training data, or as a substitute for meaningful human review in consequential decisions.

License, support, and attribution

The model materials use the Flippd Community Model License 1.0, which is not an open-source license. Personal, educational, research, and genuinely non-commercial community use is permitted under its terms. Commercial use requires a separate written license; contact admin@flippd.gg. See the license for the community-support threshold, redistribution requirements, restrictions, and complete terms.

Public projects must display:

Powered by Flippd Pinball Vision.

An About, Credits, Acknowledgments, documentation, or README location must also state:

This project uses Flippd Score Extraction, developed by the Pindigo/Flippd team under the Flippd Community Model License 1.0.

Privacy

Running downloaded weights locally does not, by itself, send images, predictions, or other model inputs to Flippd. For a gated repository, Hugging Face provides Flippd with the username, email address, access-form answers, and related access information described in PRIVACY.md. Flippd does not use gate-request information for unrelated marketing or sell it. Flippd's general privacy policy is at https://flippd.gg/privacy-policy. Privacy requests may be sent to admin@flippd.gg; do not send passwords or access tokens.

Citation

@misc{flippd_score_extraction_2026,
  author       = {Flippd, LLC},
  title        = {Flippd Pinball Vision — Score Extraction},
  year         = {2026},
  version      = {1.0.0},
  howpublished = {Hugging Face model repository},
  url          = {https://huggingface.co/Flippd/pinball-score-ocr}
}

Contact

• Model and access questions: admin@flippd.gg
• Commercial licensing: admin@flippd.gg
• Privacy requests: admin@flippd.gg

Copyright © 2026 Flippd, LLC.