Scanner
Give it a photo of one card, a table of cards or a binder page. It finds every card and says which print each one is, in English, Japanese or Simplified Chinese, from 1996 to this year's sets. It runs on your own machine.
Install
The scanner is a Python package (Python 3.10 or newer). Its code is on GitHub and its models and index are on Hugging Face; the first run downloads them and keeps them in the Hugging Face cache.
It picks the fastest hardware it finds by itself: an NVIDIA GPU, then Apple silicon's GPU, then the CPU. It says which when it starts (scanner ready in 4.2 s on mps). To choose one yourself, pass --device cpu, cuda or mps.
pip install \
"cardcorpus-scanner @ git+https://github.com/cardcorpus/pokemon-card-scanner"Scan a photo
cardcorpus-scan prints one line per card: its name, set and number, its address in the dataset, and how closely its picture matched.
--json writes everything: each card's four corners in the photo, its five best candidates in order and the evidence behind them.
cardcorpus-scan binder-page.jpg
# everything it found, as JSON
cardcorpus-scan binder-page.jpg --json out.json
# only Japanese cards
cardcorpus-scan binder-page.jpg --language japaneseOr use the web page
cardcorpus-scan serve opens a page where you can drop, paste or choose a photo, or take one with your webcam. First picks show as soon as the cards are matched, and each is replaced by the checked answer as it is ready.
The page and the scanner run on your computer and your photos stay there. Card details and pictures are read from cardcorpus.com.
cardcorpus-scan serve
# then open http://127.0.0.1:8000From Python
scanner.scan returns the cards it found, each with its quad (four corners), its candidates best first, and a quality: sure, printing_unclear (only other prints of the same card are close), unsure, likely_wrong or back.
Pass on_first or on_progress to get the first picks and then each card as it is double-checked, so a page can show results as they arrive. The repository's README lists every field.
from cardcorpus_scanner import Scanner
scanner = Scanner.load()
result = scanner.scan("binder-page.jpg") # a path or a PIL image
for card in result["cards"]:
best = card["candidates"][0]
print(best["name"], best["set_name"], best["number"])
print(best["print"], card["quality"])From a scan to the card's data
Each candidate's print is a card's address in this dataset: its set id, a slash, its card id. Where the photo shows one particular variant, the candidate also has its variant, an id in that card's variants.
So everything else about the card (rarity, illustrator, other languages, prices) is one request away.
// best["print"] is "<set id>/<card id>"
const print = "english/base-set/4";
const at = print.lastIndexOf("/");
const setId = print.slice(0, at), cardId = print.slice(at + 1);
const set = await fetch(`https://pokemon.cardcorpus.com/v1/sets/${setId}.json`)
.then((res) => res.json());
const card = set.cards.find((c) => c.id === cardId);How it works
Naming a card takes several steps, each with its own small model:
- Find the cards. A detector of 1.4 million parameters finds each card's four corners, so a tilted card on a crowded page is still cut out cleanly.
- Match the painting. Each card is straightened and fingerprinted by a fine-tuned DINOv3 ViT-S/16, and its fingerprint is compared with pictures of every card in the dataset.
- Read the number. A small reader reads the collector number off the bottom of the card.
- Tell the prints apart. Reprints share a painting. A print picker (a fine-tuned PE-Core S/16) looks at the whole card, and a checker lines the photo up with each print's own picture and compares the places they differ: the set symbol, the number, the copyright line.
- Check the variant. On older English cards it looks for the 1st Edition stamp, and on the e-Card sets at the e-Reader strips, which tell a reverse holo from a standard variant.
Accuracy and speed
On photos the models never saw in training, counting a card right when the first pick is the exact print:
| Photos | Cards | Right |
|---|---|---|
| Binder pages of vintage cards, at the camera's full resolution | 641 | 620 (96.7%) |
| The same photos shrunk to 3000 px | 641 | 618 (96.4%) |
| Cards photographed one at a time with a phone | 139 | 125 (89.9%) |
| Varied real-world photos, many small, blurred or at an angle | 672 | 585 (87.1%) |
It answers as it goes. The first answer for every card on a binder page arrives in under a second, about 60 ms a card on a Mac mini's GPU. Each card is then double-checked, and a 12-card page is finished in about 3 to 4 seconds.
The PennySleeve app runs the same steps in Swift on an iPhone, offline, with first answers in about a third of a second. This Python version agrees with the app on 99% of first picks. To try the scanner without installing anything, get PennySleeve on the App Store: it's free, and the Scan tab is this pipeline.
It knows the cards that were in the dataset when its index was built, so a card released since is named as the closest card it knows. It reads which print a card is, not its condition, and it wasn't tested on cards in graded slabs.
Licenses
- The code is Apache 2.0.
- The card matcher is a fine-tune of Meta's DINOv3 and is under the DINOv3 License. The other models are Apache 2.0.
- The index of fingerprints is CC BY 4.0.
Each repository lists which license covers which file. Built with DINOv3.