---
language:
  - en
  - multilingual

license: mit

tags:
  - CNN
  - ONNX
  - onnxruntime
  - Balatro

datasets:
  - proj-airi/games-balatro-2024-entities-detection
---

# Balatro (2024, game) card-corner classifier

This model classifies cropped Balatro card corners into rank and suit labels.
It is a small shared-backbone CNN, not an Ultralytics YOLO classifier.

## ONNX Interface

The exported ONNX model is available at:

```text
onnx/model.onnx
```

Input:

```text
images: float32[batch, 3, 64, 64]
```

Outputs:

```text
rank_logits: float32[batch, 13]
suit_logits: float32[batch, 4]
```

Rank label order:

```text
A, 2, 3, 4, 5, 6, 7, 8, 9, 10, J, Q, K
```

Suit label order:

```text
spades, hearts, clubs, diamonds
```

## Training Run

The recovered local training run is stored at:

```text
runs/classify/card-corner-cnn/mps-aug-weighted-seed2-latest
```

The run includes `args.json`, `metrics.json`, PyTorch checkpoints, and a copy
of the exported ONNX model under `onnx/model.onnx`.

Best validation metrics from the recovered run:

```text
rank_accuracy: 0.8387096774193549
suit_accuracy: 1.0
exact_accuracy: 0.8387096774193549
```

## Export

Use the export utility to regenerate the ONNX artifact from a checkpoint:

```bash
pixi run python cli/export-card-corner-classifier-onnx.py \
  --checkpoint runs/classify/card-corner-cnn/mps-aug-weighted-seed2-latest/card-corner-classifier-best.pt \
  --output models/games-balatro-2024-card-corner-classifier/onnx/model.onnx
```

## Publish

After authenticating with Hugging Face, upload this model directory as the model
repository root:

```bash
pixi run python - <<'PY'
from huggingface_hub import HfApi

repo_id = 'proj-airi/games-balatro-2024-card-corner-classifier'
folder = 'models/games-balatro-2024-card-corner-classifier'

api = HfApi()
api.create_repo(repo_id=repo_id, repo_type='model', exist_ok=True)
api.upload_folder(
    repo_id=repo_id,
    repo_type='model',
    folder_path=folder,
    commit_message='Add Balatro card-corner CNN ONNX model',
)
PY
```