<div align="center">

# Chess CV

<p align="center">
  <a href="https://github.com/S1M0N38/chess-cv/releases">
    <img alt="GitHub release" src="https://img.shields.io/github/v/release/S1M0N38/chess-cv?include_prereleases&sort=semver&style=for-the-badge&logo=github"/>
  </a>
  <a href="https://www.python.org/downloads/">
    <img alt="Python 3.13+" src="https://img.shields.io/badge/python-3.13+-blue.svg?style=for-the-badge&logo=python&logoColor=white"/>
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge"/>
  </a>
</p>

<img src="docs/assets/model.svg" alt="Model Architecture" width="600">

*CNN-based chess piece classifier*

</div>

---

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 ~95-97% 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.

## ⚡️ Quick Start

```bash
pip install chess-cv
```

Then use pre-trained models:

```python
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](https://s1m0n38.github.io/chess-cv/) or explore:

- **[Setup Guide](https://s1m0n38.github.io/chess-cv/setup/)** – Installation and data preparation
- **[Usage Guide](https://s1m0n38.github.io/chess-cv/usage/)** – Training, evaluation, and deployment
- **[Model Usage](https://s1m0n38.github.io/chess-cv/inference/)** – Using pre-trained models and the library
- **[Architecture](https://s1m0n38.github.io/chess-cv/architecture/)** – Model design and performance characteristics
- **[Hugging Face Integration](https://s1m0n38.github.io/chess-cv/HUGGINGFACE_INTEGRATION/)** – Model deployment guide

## License

This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.

---

<div align="center">

[Get Started](#quick-start) • [Contribute](CONTRIBUTING.md) • [Report Issues](https://github.com/S1M0N38/chess-cv/issues)

</div>
