chess-cv 0.2.1

CNN-based chess piece classifier

Chess CV

CNN-based chess piece classifier

---

A machine learning project that trains a lightweight CNN (156k parameters) from scratch to classify chess pieces from 32×32 pixel square images. The model achieves ~99.85% accuracy on synthetic training data generated by combining 55 board styles (256×256px) with 64 piece sets (32×32px) from chess.com and lichess.

By rendering pieces onto different board backgrounds and extracting individual squares, the model learns robust piece recognition across various visual styles.

Dataset	Accuracy	F1-Score (Macro)
Test Data	99.85%	99.89%
S1M0N38/chess-cv-openboard *	-	95.78%

* Dataset with unbalanced class distribution (e.g. many more samples for empty square class), so accuracy is not representative.

⚡️ Quick Start

pip install chess-cv

Then use pre-trained models:

from chess_cv.model import SimpleCNN
from huggingface_hub import hf_hub_download

# Load pre-trained model
model_path = hf_hub_download(repo_id="S1M0N38/chess-cv", filename="best_model.safetensors")
model = SimpleCNN(num_classes=13)
model.load_weights(model_path)

# Make predictions
predictions = model(image_tensor)

✨ Features

🪶 Lightweight Architecture

• 156k parameter CNN optimized for 32×32px images
• 13-class classification (6 white pieces, 6 black pieces, 1 empty)
• MLX framework for efficient training
• Aggressive data augmentation for robust generalization

🏗️ Complete Pipeline

• Synthetic data generation from board/piece combinations
• Training with early stopping and checkpointing
• Comprehensive evaluation with confusion matrices
• Optional Weights & Biases integration for experiment tracking
• Hugging Face Hub deployment for model sharing

📚 Documentation

For detailed documentation, visit s1m0n38.github.io/chess-cv or explore:

• Setup Guide – Installation and data preparation
• Train and Evaluate – Training, evaluation, and deployment
• Inference – Using pre-trained models and the library
• Architecture – Model design and performance characteristics

License

This project is licensed under the MIT License – see the LICENSE file for details.

---

Get Started • Contribute • Report Issues