README.md

---
license: other
license_name: flippd-community-model-license-1.0
license_link: "https://huggingface.co/Flippd/pinball-classifier/blob/main/LICENSE.md"
gated: true
pipeline_tag: image-classification
library_name: onnxruntime
model_name: "Flippd Pinball Vision — Machine Classifier"
tags:
  - pinball
  - computer-vision
  - image-classification
  - 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 — Machine Classifier

Flippd Pinball Vision identifies the pinball machine shown in an image. Release `1.0.0` was published on 2026-07-31. The private training corpus is not distributed.

The repository contains two supported ONNX artifacts. The root FP32 graph is the Python/server/CPU model. The browser FP16 graph is the browser/mobile model; it is not a CPU/server replacement, because source ONNX Runtime CPU measurements used materially more memory.

## Artifacts

| Path | Target | Precision | Input | Bytes | SHA-256 | Metadata format | Model version |
|---|---|---|---|---:|---|---:|---|
| `model.fp32.onnx` | Python, server, CPU (CUDA optional) | FP32 | float32 `[B, 3, 256, 256]`, dynamic batch | 92,330,323 | `dca2a822bd2318a8cceeeed069944f0403d3a933ccee8046eab37ffbf7c6d061` | 2 | `dino3s-hierarchical-mlp-bakeoff-v1-labels-v2` |
| `browser/model.fp16.onnx` | Browser and mobile | mixed FP16/FP32 | float32 `[1, 3, 256, 256]`, fixed batch 1 | 47,200,821 | `8ddbe216c1cd0416a1f6528fc07169a989e5f8f39569ceab1afbc6d9b2e8e839` | 3 | `dino3s-hierarchical-mlp-browser-fp16-v1` |

Both graphs use the `dinov3-vits16` encoder, ONNX opset 18, label schema 2, and the same ordered vocabularies. Both passed the full ONNX checker. The browser graph uses FP16 weights and general compute while retaining exactly 24 attention-score MatMul/Softmax nodes in FP32 to prevent observed FP16 overflow; its inputs and outputs are FP32. It prefers WebGPU and requires a WASM fallback.

## Download and installation

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

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

Python `>=3.12` is supported. Install the standalone FP32 example dependencies:

```bash
python -m pip install -r requirements.txt
```

For CUDA, replace `onnxruntime` with `onnxruntime-gpu`; do not install both in the same environment.

## FP32 Python usage

### CLI

```bash
python inference.py ./photo.jpg --top-k 5 --device cpu
```

Optional controls include `--threads N` and `--device cuda` or `--device cuda:N`. The command prints indented JSON and exits nonzero on image decoding, checksum, provider, validation, or inference failure.

### API

```python
from inference import PinballClassifier

classifier = PinballClassifier(device="cpu", threads=4)
result = classifier.predict("./photo.jpg", top_count=5)

print(result["group"])
print(result["machine"])
print(result["exact"])
```

`PinballClassifier` defaults to the model and metadata beside `inference.py`. It verifies the metadata contract and model SHA-256 before creating an ONNX Runtime session.

## Browser usage

The browser example must be served over static HTTP; opening `index.html` as a local file is not supported. From the downloaded repository root:

```bash
python -m http.server 8000
```

Then open http://127.0.0.1:8000/browser/ and choose a local image. The page attempts WebGPU first and creates a fresh WASM session if WebGPU session creation fails. The selected provider is displayed. To exercise this fallback deliberately, open http://127.0.0.1:8000/browser/?forceWebgpuFailure=1.

The page fetches the model and metadata only from the downloaded repository on the same origin. No Hugging Face token enters browser code, and the page makes no Hub API or remote model request. Network access is required only to load the pinned ONNX Runtime Web 1.22.0 JavaScript/WASM runtime assets from jsDelivr; model access and inference remain local.

## Inputs and preprocessing

The Python path decodes with Pillow and converts to RGB. It resizes the short edge to 256 while preserving aspect ratio, using integer-truncated dimensions and bicubic interpolation, then center-crops 256 × 256 with offsets `round((dimension - 256) / 2.0)`. It converts HWC to contiguous CHW float32, divides by 255, and normalizes channels with:

- mean: `[0.485, 0.456, 0.406]`
- standard deviation: `[0.229, 0.224, 0.225]`

The browser follows the same resize, crop, RGB, layout, scaling, and normalization contract using a canvas with high-quality smoothing. Browser canvas resampling is not byte-identical to Pillow, so preprocessing parity is not claimed. Neither implementation applies EXIF orientation normalization. Pillow-supported image codecs vary by installation.

## Outputs and labels

Each inference returns three independent ranked heads in this order:

1. `group_logits`: 1,225 group classes (`G<group>`)
2. `machine_logits`: 1,544 machine classes (`G<group>-M<machine>`)
3. `exact_logits`: 1,499 exact classes (`G<group>-M<machine>[-A<alias>]` or `__unknown__`)

The identifiers are canonical [Open Pinball Database (OPDB)](https://opdb.org) identifiers. Group, machine, and alias components retain OPDB's `G`, `M`, and `A` prefixes and are combined cumulatively as shown above; `__unknown__` is the sole non-OPDB sentinel.

The ordered vocabularies in each artifact's `onnx-metadata.json` are the authoritative class maps. Their canonical vocabulary SHA-256 is `7f0de4a0cc94845d5e6f429ca9c6eac81dbef4e7cdfe5f008267ce19d78c1cc1`. Logits are already temperature-scaled; clients do not apply the metadata temperatures again. The examples compute a stable softmax independently for each head, sort descending, and return one to twenty `{ "id", "confidence" }` candidates with confidence rounded to six decimals. `__unknown__` is an ordinary exact class, not a general detector for inappropriate or out-of-distribution images.

The heads are independent rankings and provide no acceptance decision. Applications should expose confidence and use appropriate human review rather than silently treating a candidate as certain.

## Evaluation

These are source-observed export results, not measurements made with browser canvas preprocessing:

| Evaluation | Result |
|---|---:|
| Sealed 63,038-image exact top-1, FP32 | 91.0038% |
| Sealed 63,038-image exact top-1, FP16 | 90.9927% |
| Exact top-5 after FP16 conversion | Unchanged |
| Top-1 parity across group, machine, and exact heads on 200 deterministic held-out images | 100% |

Top-1 parity does not imply equal logits or confidence values.

## Limitations

Predictions may be wrong for visually ambiguous, cropped, low-quality, multiple-machine, unusual-viewpoint, remake, alternate-art, or out-of-distribution images. Detail images, occlusion, and poor lighting may remove the evidence needed for identification. `__unknown__` does not reliably identify all unsuitable inputs. Callers should show confidence, preserve alternatives where useful, and require human review when an error matters.

The model identifies visual evidence associated with a machine. It does not establish ownership, location, authenticity, edition provenance, market value, or whether every visible component belongs to the predicted title. Do not use it for unlawful activity, biometric identification, surveillance, 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—including paid products, business operations, advertising, sponsorships, consulting, and other commercial benefit—requires a separate written license; contact **admin@flippd.gg**.

A free community project may receive optional tips or Patreon-style support without becoming commercial only while every license condition remains satisfied, including materially equal service for contributors and non-contributors, no purchased benefits, no advertising/sponsorship/affiliate or required-payment revenue, and no more than **US $5,000 gross qualifying support in any rolling twelve-month period**. See `LICENSE.md` for the 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 the Flippd Machine Classifier, 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. 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_machine_classifier_2026,
  author       = {Flippd, LLC},
  title        = {Flippd Pinball Vision — Machine Classifier},
  year         = {2026},
  version      = {1.0.0},
  howpublished = {Hugging Face model repository},
  url          = {https://huggingface.co/Flippd/pinball-classifier}
}
```

## Contact

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

Copyright © 2026 Flippd, LLC.