G-G-Games/diecamera-models

dieCamera dice readers

Four ONNX models that read physical polyhedral dice from a webcam frame: which dice are on the table, and what each one landed on. They run offline on CPU or any DX12 GPU (DirectML) in ~50–100 ms a frame, and are the local reader inside dieCamera.

Trained on G-G-Games/diecamera-dice.

file	job	size
dice-shape.onnx	YOLOv8 detector — finds each die, classifies its type	43MB
dice-value-glyph.onnx	YOLOv8 detector — finds the up-face numeral on each die	43MB
dice-value.onnx	ConvNeXt classifier — reads that numeral, 21-way "0".."20"	106MB
dice-value-cls.onnx	YOLOv8-cls — reads a whole-die crop directly, 60-way	20MB

Each ships with a .classes.json giving its output order. The class list is not optional — the indices mean nothing without it.

Two ways to read a face

dice-shape finds and types the dice in both pipelines. What differs is how the numeral is read:

Three-pass (dice-shape → dice-value-glyph → dice-value) localises the numeral on the full frame and classifies a tight crop of it. Argmax is gated to the die type's legal range, so a "15" can never come back for a d8, and the returned confidence is a softmax over the in-range classes only.

Two-pass (dice-shape → dice-value-cls) skips localisation and classifies the die crop whole, as one of 60 (type, face) classes. A fifth the size and one less model call.

Both are shipped. Which is better is genuinely unsettled — see below.

Accuracy, honestly

Reported by their authors, on their own held-out splits:

• dice-shape — mAP50 0.886 on a shared three-domain validation set (v2). Its predecessor scored 0.995 on a single-domain split and 0.752 here; the higher number was an easier test set, not a better model.
• dice-value (three-pass) — cross-validated per type: d8 0.88 · d10 0.72 · d12 0.75 · d20 0.55.
• dice-value-cls (two-pass) — face top-1 0.411 on held-out crops. Most of that came from training at 224px instead of downscaling crops to 128, which was worth +0.12 by itself.

Measured head-to-head on identical frames from the training corpus:

frames	three-pass	two-pass
whole corpus (563 dice)	0.490	0.480
30 newest, sharp 5MP (113 dice)	0.575	0.699

Do not read that table as a verdict. Both models were trained on this corpus with splits that were not recorded, and the two-pass model was retrained after most of those newest frames existed — so its 0.699 is partly recall. Only five frames in the corpus postdate its training. There is no clean shared holdout yet, and the per-author numbers above are better evidence than anything measured after the fact.

Die-type detection is identical either way (0.961 on the same frames) because both start from dice-shape.

What they are not

These are rig specialists, not a general dice reader. They were trained on a handful of webcams over a small tray, and accuracy falls off sharply on unfamiliar lighting, backgrounds, or dice sets. The best single predictor of whether they will work for you is how many pixels land on a die face: the reference rig reads well at ~270px across a die and poorly at ~140px.

The known failure is 6 vs 9 on a d10, which is ambiguous on plenty of real dice sets and is not fully solvable from pixels alone.

Consuming application note: dieCamera never posts a face without showing it to a human first. A fast, correctable guess is more useful there than a slow accurate one — these models are tuned for that trade, not for autonomous use.

Usage

import json, onnxruntime as ort
sess = ort.InferenceSession("dice-shape.onnx")
classes = json.load(open("dice-shape.classes.json"))["classes"]
# 640x640 letterboxed RGB, NCHW, 0-1 -> standard YOLOv8 output; NMS, then classes[class_id]

The full pipeline — letterboxing, NMS, glyph-to-die matching, the range gate, and the ImageNet normalisation the classifier expects — is implemented in TypeScript in src/readers/local/. The crop recipe must match training exactly (detector box + 0.1 margin, stretch-resized to 224×224, ImageNet-normalised); drifting from it reintroduced a domain-shift bug that once took a value model from 97% on web images to 17.5% on the real rig.

Credits

• dice-value.onnx and dice-value-glyph.onnx — the three-pass value reader, and its runtime, by Triveni Gandhi (@trivenigandhi), contributed in dieCamera PR #6. She also contributed capture frames to the dataset.
• dice-shape.onnx and dice-value-cls.onnx — @eschatus.

License

AGPL-3.0. Use, modify, or redistribute these weights — including as part of a hosted or network-accessible service — under AGPL-3.0, which requires releasing corresponding source for your derivative under the same terms. A separate commercial license, without the AGPL's copyleft/source-disclosure obligations, is available from G-G-Games for closed commercial use; contact us for terms. The dieCamera application itself is licensed separately (see its own repo). The training data is CC BY-SA 4.0 and published separately.

(Provisional — this replaces an earlier MIT license on this card. Not yet cleared by counsel; do not rely on the enforceability of the commercial-license carve-out until a lawyer has reviewed it.)