---
license: other
library_name: ultralytics
pipeline_tag: object-detection
tags:
  - trading-card-games
  - object-detection
  - yolo
  - onnx
  - riftbound
---

# TCGscanner Card Detector

This repository contains the current ONNX card-boundary detector used by the TCGscanner prototype.

The model is a single-class YOLO detector. Its task is to localize the physical trading card in a camera frame or photograph. Card identification is handled separately by SigLIP 2 visual embeddings and LanceDB vector search in the application repository.

## Files

- `riftbound_regions.onnx`: exported ONNX detector expected at `models/riftbound_regions.onnx` by the scanner.

## Current Artifact

- Size: `11.70 MB`
- SHA256: `8566d3c8556183c780eab0937f65d9862bdfc57697bfd3c33135218f28230f41`
- Class labels: `card`
- Default confidence threshold in the app: `0.35`

## Training Summary

The detector was trained on a universal TCG detection dataset that combines localized card examples from multiple trading card domains. The objective is to learn generic card geometry rather than the visual identity of a specific game.

The selected hybrid experiment used corners, polygons, and isolated full-card samples. The June 27, 2026 audit run reported:

| Experiment | Test precision | Test recall | Test mAP50 | Test mAP50-95 |
| --- | ---: | ---: | ---: | ---: |
| localization_only | 0.9957 | 1.0000 | 0.9950 | 0.9141 |
| hybrid | 0.9992 | 1.0000 | 0.9950 | 0.9635 |

The selected hybrid run was stopped manually during epoch 42 after the validation curve had stabilized for the scanner use case. Its best validation checkpoint was epoch 40 with `mAP50=0.9942` and `mAP50-95=0.9628`.

## Usage

```bash
uv run python scripts/download_detector.py
```

The scanner loads the downloaded model from:

```text
models/riftbound_regions.onnx
```

## Limitations

- This detector only localizes the card boundary.
- It does not identify the card.
- The current dataset still needs more real-world Riftbound photographs.
- Pricing and collection features are outside this model repository.