BiernyVR/pokemon-classifier-mobilenetv3

⚡ Pokémon Classifier (1,025 Classes — Gen 1 to Gen 9)

An ultra-fast, lightweight MobileNetV3-Large vision model trained to identify all 1,025 Pokémon across Generations 1 through 9 (from Bulbasaur #0001 to Pecharunt #1025).

Designed for Edge AI and mobile deployment (sub-25ms on smartphone CPU, ~22 MB file size, 0ms latency offline). Originally developed as the core computer vision engine for a native Android talking Pokédex.

---

🌟 Model Highlights

• Complete Pokédex Coverage: All 1,025 official Pokémon species recognized across 9 generations.
• Edge-Ready & Lightweight: Only ~22.4 MB in ONNX format, ~4.2M parameters.
• Dual Formats Provided:
  • pokemon_classifier.onnx — Fully optimized for ONNX Runtime (Android, iOS, Raspberry Pi, Web, C++, Python).
  • pokemon_mobilenet_large_best.pth — PyTorch checkpoint with model weights.
  • pokemon_labels.json — 1,025 labeled entries mapping class index to National Pokédex ID and name.
• Mobile First: Built to power real-time camera scanning (CameraX + ONNX Runtime Android) of Pokémon trading cards, figurines, and books.

---

🚀 Quick Start (Inference)

Option 1: Using ONNX Runtime (Recommended, No PyTorch Needed)

pip install onnxruntime pillow numpy huggingface_hub

import json
import numpy as np
from PIL import Image
import onnxruntime as ort
from huggingface_hub import hf_hub_download

# 1. Download model and labels from Hugging Face Hub
model_path = hf_hub_download(repo_id="BiernyVR/pokemon-classifier-mobilenetv3", filename="pokemon_classifier.onnx")
labels_path = hf_hub_download(repo_id="BiernyVR/pokemon-classifier-mobilenetv3", filename="pokemon_labels.json")

with open(labels_path, "r", encoding="utf-8") as f:
    labels = json.load(f)

# 2. Preprocess input image (224x224 RGB, standard ImageNet normalisation)
img = Image.open("your_pokemon_image.jpg").convert("RGB").resize((224, 224), Image.Resampling.BILINEAR)
arr = (np.array(img, dtype=np.float32) / 255.0 - [0.485, 0.456, 0.406]) / [0.229, 0.224, 0.225]
tensor = np.expand_dims(np.transpose(arr, (2, 0, 1)), axis=0).astype(np.float32)

# 3. Run Inference
session = ort.InferenceSession(model_path, providers=["CPUExecutionProvider"])
logits = session.run(None, {"input": tensor})[0][0]

# 4. Compute probabilities & Top 5
probs = np.exp(logits - np.max(logits))
probs /= probs.sum()
top5 = np.argsort(probs)[::-1][:5]

for rank, idx in enumerate(top5, 1):
    poke = labels[idx]
    print(f"#{rank}: {poke['name'].title()} (ID: #{poke['id']}) - {probs[idx]*100:.1f}%")

Option 2: Standalone CLI

You can also use the included infer.py:

python infer.py --image sample_pikachu.png --topk 5

---

📊 Generations Coverage

Generation	Region	ID Range	Key Examples
Gen 1	Kanto	#0001 – #0151	Bulbasaur, Charizard, Pikachu, Mewtwo
Gen 2	Johto	#0152 – #0251	Chikorita, Lugia, Tyranitar
Gen 3	Hoenn	#0252 – #0386	Treecko, Rayquaza, Lucario
Gen 4	Sinnoh	#0387 – #0493	Turtwig, Dialga, Arceus
Gen 5	Unova	#0494 – #0649	Victini, Reshiram, Zekrom
Gen 6	Kalos	#0650 – #0721	Chespin, Greninja, Xerneas
Gen 7	Alola	#0722 – #0809	Rowlet, Mimikyu, Solgaleo
Gen 8	Galar / Hisui	#0810 – #0905	Grookey, Zacian, Hisuian Zorua
Gen 9	Paldea / Kitakami	#0906 – #1025	Sprigatito, Koraidon, Pecharunt

---

🛠️ Model Architecture & Training

• Base Architecture: torchvision.models.mobilenet_v3_large (pretrained on ImageNet-1K).
• Classifier Head: Linear projection 960 -> 1025 classes.
• Input Specification: [batch_size, 3, 224, 224], dynamic batching supported.
• Training Techniques:
  • Multi-source sprite & artwork dataset (official artwork, Home 3D renders, pixel sprites).
  • Heavy geometric & photometric augmentations (rotation, perspective jitter, affine transformation, blur, lighting variation) to simulate camera capture from physical trading cards.
  • Cosine annealing learning rate schedule with AdamW optimizer.

---

⚖️ Disclaimer & Attribution

• Pokémon and Pokémon character names are trademarks and copyright of Nintendo, Creatures Inc., and GAME FREAK Inc.
• This model is a fan-made, non-commercial educational project designed for on-device computer vision research and children's education.