cardcorpus

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.

Terminal
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.

Terminal
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 japanese

Or 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.

Terminal
cardcorpus-scan serve
# then open http://127.0.0.1:8000

From 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.

scan.py
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.

lookup.js
// 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:

  1. 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.
  2. 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.
  3. Read the number. A small reader reads the collector number off the bottom of the card.
  4. 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.
  5. 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:

PhotosCardsRight
Binder pages of vintage cards, at the camera's full resolution641620 (96.7%)
The same photos shrunk to 3000 px641618 (96.4%)
Cards photographed one at a time with a phone139125 (89.9%)
Varied real-world photos, many small, blurred or at an angle672585 (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.