README.md

---
license: agpl-3.0
library_name: ultralytics
pipeline_tag: object-detection
base_model: Ultralytics/YOLO11
tags:
- object-detection
- ultralytics
- yolo11
- onnx
- onnxruntime
- playing-cards
- card-detection
- casino
- live-game-defender
model-index:
- name: lgd-cards-gen2
  results:
  - task:
      type: object-detection
    dataset:
      type: lgd-poc-video-holdout
      name: LGD frozen PoC table-video holdout (117 frames, private)
    metrics:
    - type: recall
      value: 0.68
      name: Pip recall @50 (code-aware)
    - type: precision
      value: 0.604
      name: Precision proxy
---

# LGD Cards — Gen 2 (day-1 video) · YOLO11s playing-card detector, 52 classes

The second generation of the **Live Game Defender (LGD)** playing-card detector: gen 1 fine-tuned on
the **first day of real casino-table video** from our proof-of-concept rig. This closed most of the
synthetic→real gap that held gen 1 back on real footage.

> **Superseded** by **[`lgd-cards-gen3`](https://huggingface.co/sroot/lgd-cards-gen3)** (day-2 video,
> holdout recall 0.85 — the current served model). Gen 2 is published for provenance/reproducibility.

## Generations

| Gen | Repo | Trained on | Frozen real-video holdout recall | Status |
|---|---|---|---|---|
| 1 | [lgd-cards-gen1](https://huggingface.co/sroot/lgd-cards-gen1) | Roboflow `ow27d` v4 dataset | — (dataset-val only) | superseded |
| 2 | **lgd-cards-gen2** (this) | + day-1 PoC table video | **0.68** | superseded |
| 3 | [lgd-cards-gen3](https://huggingface.co/sroot/lgd-cards-gen3) | + day-2 PoC table video | 0.85 | ✅ current |

Chip detectors: [lgd-chips-gen1](https://huggingface.co/sroot/lgd-chips-gen1) · [lgd-chips-gen2](https://huggingface.co/sroot/lgd-chips-gen2).

## Classes (52)

```
10C 10D 10H 10S 2C 2D 2H 2S 3C 3D 3H 3S 4C 4D 4H 4S 5C 5D 5H 5S
6C 6D 6H 6S 7C 7D 7H 7S 8C 8D 8H 8S 9C 9D 9H 9S
AC AD AH AS JC JD JH JS KC KD KH KS QC QD QH QS
```

`C`=Clubs, `D`=Diamonds, `H`=Hearts, `S`=Spades. Full order is in `model.classes.json`.

## Files

- `model.onnx` — ONNX export (run with `onnxruntime`).
- `model.classes.json` — ordered class-name sidecar (index → card code).
- `metrics.json` — training config + full per-label holdout evaluation.

## Training

- **Base:** Ultralytics `yolo11s.pt` (COCO-pretrained), 40 epochs (early-stop patience 15), `imgsz=640`.
- **Data:** Roboflow `ow27d` base set **+ day-1 PoC table recordings**, auto-labeled (pip boxes
  proposed by the gen-1/ow27d detector, verified/named by an LLM over a closed 52-code vocabulary),
  materialized as serve-matching 2×2 tiles (3,112 train / 445 val tiles). Labeling cost **$3.41**.
- **Hardware:** NVIDIA RTX 3060 (12 GB).

## Metrics — frozen real-video holdout

Scored on a **frozen 117-frame holdout** of our own PoC recordings (never trained on), serve-style
auto-grid tiling, threshold 50, code-aware:

| Recall | Precision proxy |
|---|---|
| 0.68 | 0.604 |

> ⚠️ **Not casino accuracy (rule of the project).** The holdout is our own proof-of-concept footage;
> ground-truth labels are LLM-verified, not fully human-verified. This demonstrates the detector
> *mechanism* and the generation-over-generation improvement, not a real-world full-deck accuracy
> claim. Dataset-internal `mAP@50` (0.81) is in `metrics.json` and is likewise not real-world.

## Usage

```python
import json, onnxruntime as ort
sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
names = json.load(open("model.classes.json"))   # index -> "AS", "10H", ...
# 640x640 letterboxed input; this model detects corner PIPS — cluster same-code pips into one card.
```

## License & provenance

**AGPL-3.0**, a fine-tune of **Ultralytics YOLO11** (`yolo11s.pt`, AGPL-3.0) — these weights inherit
AGPL-3.0 and **are not an original work of ours**. Networked deployment triggers AGPL §13 (offer the
Corresponding Source). `onnxruntime` (MIT) keeps the inference code AGPL-free; the weights stay AGPL.

Built for **Live Game Defender (LGD)** — an on-prem AI integrity monitor for live casino table
games. © 2026 TechTools s.r.o.