Pokémon Card Recognition System

Comprehensive AI-powered system for identifying, analyzing, and grading Pokémon trading cards using image embeddings and machine learning.

Features

• Card Recognition: Identify Pokémon cards using image similarity matching
• Damage Detection: Automatically detect scratches, edge wear, bending, and surface damage
• Quality Analysis: Evaluate print quality, sharpness, and color accuracy
• Card Centering: Analyze card centering and alignment
• Grading System: Assign grades 1-10 based on physical condition
• Scalable Architecture: Built for production use with FastAPI
• AWS S3 Integration: Store and process large datasets
• FAISS Indexing: Fast similarity search across thousands of cards

System Architecture

Components

1. Backend API (FastAPI)

   • RESTful endpoints for card analysis
   • Image upload and processing
   • Similarity search queries

2. Embedding Service (PyTorch/ResNet50)

   • Pre-trained deep learning model
   • Image feature extraction
   • Vector normalization

3. FAISS Index (Facebook AI Similarity Search)

   • Fast similarity search
   • Metadata management
   • Batch indexing

4. AWS S3 Integration

   • Dataset storage
   • Image retrieval
   • Scalable cloud infrastructure

5. Card Grading Engine

   • Damage analysis
   • Quality metrics
   • Grade calculation

Project Structure

pokemon-card-system/
├── app/
│   ├── api/
│   │   ├── card_routes.py       # Card analysis endpoints
│   │   └── admin_routes.py      # Admin/management endpoints
│   ├── models/
│   │   └── schemas.py           # Pydantic request/response models
│   ├── services/
│   │   ├── embedding_service.py # Image embedding generation
│   │   ├── s3_service.py        # AWS S3 operations
│   │   ├── faiss_service.py     # FAISS index management
│   │   └── card_grading_service.py # Card grading logic
│   ├── utils/
│   │   ├── logger.py            # Logging setup
│   │   └── image_processing.py  # Image analysis utilities
│   ├── main.py                  # FastAPI application factory
│   └── __init__.py
├── config/
│   ├── settings.py              # Configuration management
│   └── __init__.py
├── scripts/
│   ├── build_index.py           # Build FAISS index from S3
│   └── test_api.py              # API testing script
├── data/                        # FAISS indexes and metadata
├── requirements.txt             # Python dependencies
├── run.py                       # Application entry point
├── Dockerfile                   # Docker container definition
├── docker-compose.yml           # Docker Compose configuration
├── .env.example                 # Environment variables template
└── README.md                    # This file

Installation

Prerequisites

• Python 3.11+
• Docker & Docker Compose (optional)
• AWS credentials (if using S3)
• CUDA-capable GPU (optional, for faster processing)

Local Setup

1. Clone repository

cd pokemon-card-system

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

cp .env.example .env
# Edit .env with your AWS credentials and settings

5. Build FAISS index from S3

python scripts/build_index.py

6. Run application

python run.py

API will be available at http://localhost:8000

Docker Setup

1. Build and run with Docker Compose

docker-compose up --build

2. Access API

http://localhost:8000

Configuration

All settings are defined in config/settings.py and can be overridden via environment variables in .env:

AWS Configuration

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
S3_BUCKET_NAME=pokemon-cards-dataset
S3_DATASET_PREFIX=pokemon_cards_dataset/

Model Configuration

EMBEDDING_MODEL=resnet50  # Options: resnet50, resnet152, efficientnet_b0
DEVICE=cpu                # Options: cpu, cuda

Grading System

# Grades 1-10 mapping
10 = Gem Mint
9 = Mint
8 = Near Mint
7 = Excellent
6 or lower = Poor condition

API Endpoints

Card Analysis

POST /api/v1/card/analyze

• Upload and analyze a Pokémon card image
• Returns: Grade, condition, detected issues, and matched similar card

Request:

curl -X POST "http://localhost:8000/api/v1/card/analyze" \
  -F "file=@card.jpg" \
  -F "card_name=Pikachu" \
  -F "return_detailed=true"

Response:

{
  "card_name": "Pikachu",
  "grade": 8,
  "condition": "Near Mint",
  "detected_issues": ["minor edge wear"],
  "confidence": 0.94,
  "matched_card": {
    "card_name": "Pikachu Holo",
    "similarity_score": 0.92,
    "s3_key": "pokemon_cards_dataset/pikachu_001.jpg"
  },
  "damage_ratio": 0.05,
  "centering_score": 0.85,
  "print_quality": 0.9
}

Card Comparison

POST /api/v1/card/compare

• Compare two card images for similarity

Request:

curl -X POST "http://localhost:8000/api/v1/card/compare" \
  -F "file1=@card1.jpg" \
  -F "file2=@card2.jpg"

Response:

{
  "similarity": 0.87,
  "card1": {
    "grade": 8,
    "condition": "Near Mint",
    "damage_ratio": 0.05
  },
  "card2": {
    "grade": 7,
    "condition": "Excellent",
    "damage_ratio": 0.12
  }
}

Index Status

GET /api/v1/card/index-status

• Get FAISS index statistics

Response:

{
  "total_embeddings": 5000,
  "embedding_dimension": 2048,
  "index_type": "IndexFlatL2",
  "metadata_count": 5000
}

Admin Endpoints

GET /api/v1/admin/s3/list-images

• List all images in S3 bucket

GET /api/v1/admin/s3/image-count

• Get total image count

GET /api/v1/admin/s3/image-metadata/{key}

• Get metadata for specific image

Workflow Examples

Build Dataset Index

1. Upload all Pokémon card images to S3:

aws s3 sync ./pokemon_cards ./s3://pokemon-cards-dataset/pokemon_cards_dataset/

2. Build FAISS index:

python scripts/build_index.py

Analyze a Card

1. Upload card image:

import requests

with open('my_card.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/api/v1/card/analyze',
        files={'file': f},
        params={'card_name': 'Charizard', 'return_detailed': True}
    )

print(response.json())

2. Get grading result with detected issues

Compare Cards

with open('card1.jpg', 'rb') as f1, open('card2.jpg', 'rb') as f2:
    response = requests.post(
        'http://localhost:8000/api/v1/card/compare',
        files={'file1': f1, 'file2': f2}
    )

print(f"Similarity: {response.json()['similarity']}")

Performance Optimization

For Production

1. Use GPU

DEVICE=cuda  # Enable CUDA for faster processing

2. Optimize FAISS Index

• Use IndexIVFFlat for large datasets (>1M embeddings)
• Implement GPU-accelerated FAISS

3. Caching

• Cache frequent similarity searches
• Use Redis for embedding cache

4. Scaling

• Use multiple API workers
• Load balance with Nginx/HAProxy
• Distribute FAISS indexes across shards

Model Selection

• ResNet50: Balanced speed/accuracy (default)
• ResNet152: Slower but more accurate
• EfficientNet-B0: Faster inference

Damage Detection Algorithm

The system detects card damage using:

1. Edge Detection (Sobel filters)
2. Damage Clustering (Connected component analysis)
3. Damage Ratio (Pixel-level analysis)
4. Damage Types:
   • Scratches
   • Edge wear
   • Bending
   • Surface wear
   • Centering issues
   • Print quality issues

Grading Criteria

Grade	Condition	Description
10	Gem Mint	Perfect condition, no visible wear
9	Mint	Excellent condition, minimal wear
8	Near Mint	Very good, light wear visible
7	Excellent	Good condition, moderate wear
6	Good	Fair condition, visible wear
≤5	Poor	Significant damage or wear

Troubleshooting

Index not building

• Check AWS credentials
• Verify S3 bucket exists and contains images
• Check available disk space

API returns low confidence

• Dataset may not contain similar cards
• Image quality too poor
• Card not in training dataset

Slow inference

• Use GPU (DEVICE=cuda)
• Reduce image size before upload
• Use simpler model (EfficientNet-B0)

Dependencies

Key Python packages:

• fastapi - Web framework
• torch + torchvision - Deep learning
• faiss-cpu - Similarity search
• boto3 - AWS S3
• pillow - Image processing
• scikit-image - Image analysis
• pydantic - Data validation

License

[Add your license here]

Contributing

[Add contribution guidelines]

Support

For issues or questions:

1. Check existing GitHub issues
2. Review API documentation at /docs
3. Check logs in ./logs/ directory

Deployment

AWS Deployment (ECS)

1. Build Docker image
2. Push to ECR
3. Create ECS task definition
4. Deploy to ECS cluster

Local Production

1. Use production ASGI server: gunicorn
2. Set DEVICE=cuda if GPU available
3. Configure environment variables
4. Run behind Nginx reverse proxy

Example Gunicorn command:

gunicorn \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  app.main:app