| ---
|
| license: mit
|
| library_name: pytorch
|
| pipeline_tag: image-classification
|
| tags:
|
| - computer-vision
|
| - image-classification
|
| - mobilenet-v2
|
| - cards
|
| - solitaire
|
| - computer-use
|
| datasets:
|
| - solitaire-cards-dataset
|
| metrics:
|
| - accuracy
|
| ---
|
|
|
| # Solitaire Card Recognizer
|
|
|
| A 52-class playing-card classifier fine-tuned from **MobileNet v2** (ImageNet
|
| weights from `torchvision`). It was trained for an autonomous computer-use agent
|
| that plays Microsoft Solitaire Collection through the real screen and mouse:
|
| the agent sees only pixels, so this model is its "eyes".
|
|
|
| * **Accuracy:** 99.91 % (3251/3254) on the full dataset, **100 %** (650/650) on
|
| the held-out split
|
| * **Size:** 2,290,484 parameters (9.4 MB, `model.pth`)
|
| * **Latency:** 6.7 ms pure inference, 8.1 ms including crop and preprocessing
|
| (single crop, RTX 2060S); tens of milliseconds on CPU
|
| * **Input:** a full, fully visible card image (the training crops are 131×176 px;
|
| the model resizes to 224×224 and applies ImageNet normalization)
|
| * **Output:** one of 52 classes in the order of `classes.json`
|
| (`10_clubs … Q_spades`, matching `torchvision.datasets.ImageFolder` ordering)
|
|
|
| ## Usage
|
|
|
| ```python
|
| import json
|
| from huggingface_hub import hf_hub_download
|
| import torch, torchvision
|
| from PIL import Image
|
| from torchvision import transforms
|
|
|
| repo = "YanChi-pixel/solitaire-card-recognizer" # ← your namespace after upload
|
| weights = hf_hub_download(repo, "model.pth")
|
| classes = json.load(open(hf_hub_download(repo, "classes.json"), encoding="utf-8"))["classes"]
|
|
|
| model = torchvision.models.mobilenet_v2(weights=None)
|
| model.classifier[1] = torch.nn.Linear(model.classifier[1].in_features, len(classes))
|
| model.load_state_dict(torch.load(weights, map_location="cpu", weights_only=True))
|
| model.eval()
|
|
|
| tf = transforms.Compose([
|
| transforms.Resize((224, 224)),
|
| transforms.ToTensor(),
|
| transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
|
| ])
|
|
|
| img = Image.open("card.png").convert("RGB")
|
| with torch.no_grad():
|
| probs = torch.softmax(model(tf(img).unsqueeze(0)), dim=1)[0]
|
| rank_suit, idx = classes[int(probs.argmax())], int(probs.argmax())
|
| print(rank_suit, f"{float(probs[idx]):.3f}")
|
| ```
|
|
|
| ## Training data
|
|
|
| Collected and auto-labelled from live play: **3254 full cards (131×176 px)** in 52
|
| balanced classes, plus 3967 earlier corner crops (42×54 px) from the abandoned
|
| first pipeline. Published as
|
| [`solitaire-cards-dataset`](https://huggingface.co/datasets/solitaire-cards-dataset).
|
| Labels were produced semi-automatically (a local vision-language model plus manual
|
| sorting), so expect a small amount of label noise — the reported accuracy is
|
| measured against those labels, not against a human-audited test set.
|
|
|
| ## Limitations
|
|
|
| * It expects a **whole card**, not a tiny corner crop. The older 42×54 corner
|
| dataset (also published, folder `corners`) is out of distribution: a corner
|
| crop fed to this model returns a wrong class with moderate confidence — the
|
| corner pipeline was abandoned for exactly that reason.
|
| * Trained on the **Microsoft Solitaire Collection** card art at 1920×1040. Other
|
| card designs, fonts or resolutions are out of distribution.
|
| * It expects a **fully visible card**. A partially overlapped card inside a fan
|
| (only its top strip visible) is read unreliably — that is a data limitation, not
|
| a code bug, and it is documented in the agent's engineering notes.
|
| * It classifies a single card crop; it does not detect cards on a full screenshot
|
| (that geometry lives in the agent's `vision/` layer).
|
|
|
| ## Links
|
|
|
| * Code, tests and the full agent: [solitaire-computer-agent](https://github.com/YanChi-pixel/solitaire-computer-agent)
|
| * Interactive demo: [Space](https://huggingface.co/spaces/WildFuria/solitaire-card-recognizer-demo)
|
| * Case study: [ai-wiki.tech](https://ai-wiki.tech/en/cases/autonomous-computer-agent/)
|
|
|
| ## License
|
|
|
| MIT. MobileNet v2 architecture comes from `torchvision` (BSD-3-Clause).
|
|
|
