README.md

---
license: other
license_name: flippd-community-model-license-1.0
license_link: LICENSE.md
gated: true
pipeline_tag: image-to-text
library_name: onnxruntime
model_name: "Flippd Pinball Vision — Score Extraction"
tags:
  - pinball
  - computer-vision
  - optical-character-recognition
  - onnx
  - noncommercial
  - community-license
extra_gated_heading: "Access Flippd Pinball Vision"
extra_gated_description: >-
  Free for non-commercial and qualifying community use. Commercial use
  requires a separate license.
extra_gated_button_content: "Agree and request access"
extra_gated_prompt: >-
  By requesting access, you agree to the Flippd Community Model License 1.0.
extra_gated_fields:
  "Intended use":
    type: select
    options:
      - "Personal or hobby"
      - "Education or research"
      - "Free community project"
      - "Commercial evaluation"
      - "Commercial use"
      - "Other"
  "Brief description": text
  "I agree to the Flippd Community Model License": checkbox
---

# 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.

| Path | Purpose | Bytes | SHA-256 |
|---|---|---:|---|
| `detector.onnx` | Dynamic-shape FP32 score-region detector | 37,745,852 | `f45144d7e131a2dcc537d718972e77405c0718c1cbc6099b9b60fd9b533dbd0d` |
| `reader.onnx` | FP32 CTC reader, `[B,3,48,320]` to `[B,80,11]` | 32,033,410 | `703e2b546995d2676484d7715fdca87691f5ecaa10df19e8c535708c3b47a262` |
| `config.json` | Runtime thresholds and source evaluation metadata | 2,080 | `12d244829610e9e6ccc8297777eedad5da7ea46d19d41ec9c4628022cfb38e1b` |

`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:

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

```bash
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

```bash
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

```python
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:

```json
{
  "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](LICENSE.md), 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`](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

```bibtex
@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.