Metadata-Version: 2.4
Name: chess-cv
Version: 0.2.0
Summary: CNN-based chess piece classifier
Project-URL: Homepage, https://github.com/S1M0N38/chess-cv
Project-URL: Issues, https://github.com/S1M0N38/chess-cv/issues
Project-URL: Repository, https://github.com/S1M0N38/chess-cv
Project-URL: Changelog, https://github.com/S1M0N38/chess-cv/blob/main/CHANGELOG.md
Author-email: S1M0N38 <bertolottosimone@gmail.com>
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: mlx>=0.24.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: pillow>=11.3.0
Description-Content-Type: text/markdown

<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://pypi.org/project/chess-cv/">
    <img alt="PyPI" src="https://img.shields.io/pypi/v/chess-cv?style=for-the-badge&logo=pypi&logoColor=white"/>
  </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 ~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](https://huggingface.co/datasets/S1M0N38/chess-cv-openboard) | -[^1]    | 95.78%           |

## ⚡️ 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>

[^1]: OpenBoard has an unbalanced class distribution (many more samples for empty square class), so accuracy is not representative.
