chess-fen-detector 0.2.0
Convert chess board images to FEN notation using deep learning
License: MIT
Requires Python: >=3.7
Keywords: chess, fen, computer-vision, deep-learning, image-processing

# Chess FEN Detector

A Python package that uses deep learning to detect chess piece positions from images and convert them to FEN (Forsyth-Edwards Notation).

## Features

- 🎯 Accurate chess piece detection using CNN
- 🖼️ Support for various image formats (PNG, JPG, etc.)
- 📦 Easy-to-use Python API
- 💻 Command-line interface
- 🚀 Bundled pre-trained model included

## Installation

### From source

```bash
# Clone or download this package
cd chess-fen-detector

# Install in development mode
pip install -e .

# Or install normally
pip install .
```

### Install dependencies only

```bash
pip install -r requirements.txt
```

## Usage

### Python API

#### Basic usage

```python
from chess_fen_detector import ChessFENDetector

# Initialize the detector
detector = ChessFENDetector()

# Get FEN notation from an image
fen = detector.predict_fen('path/to/chessboard.png')
print(f"FEN: {fen}")
```

#### Display image with FEN

```python
from chess_fen_detector import ChessFENDetector

detector = ChessFENDetector()

# Display the image with predicted FEN as title
detector.display_with_fen('path/to/chessboard.png')
```

#### Using convenience functions

```python
from chess_fen_detector import get_fen, display_with_predicted_fen

# Quick FEN extraction
fen = get_fen('path/to/chessboard.png')

# Display with FEN
display_with_predicted_fen('path/to/chessboard.png')
```

#### Using a custom model

```python
from chess_fen_detector import ChessFENDetector

detector = ChessFENDetector(model_path='path/to/custom_model.keras')
fen = detector.predict_fen('chessboard.png')
```

### Command Line Interface

After installation, you can use the `chess-fen-detect` command:

```bash
# Basic usage
chess-fen-detect chessboard.png

# Display the image with predicted FEN
chess-fen-detect chessboard.png --display

# Use a custom model
chess-fen-detect chessboard.png --model custom_model.keras

# Enable verbose output
chess-fen-detect chessboard.png --verbose
```

## FEN Notation

FEN (Forsyth-Edwards Notation) is a standard notation for describing chess positions. The package outputs FEN strings that represent the piece positions on the board.

Example output: `rnbqkbnr-pppppppp-8-8-8-8-PPPPPPPP-RNBQKBNR`

Piece symbols:
- Lowercase: black pieces (p=pawn, r=rook, b=bishop, n=knight, q=queen, k=king)
- Uppercase: white pieces (P=pawn, R=rook, B=bishop, N=knight, Q=queen, K=king)
- Numbers: empty squares (1-8)
- Dashes (-): separate ranks (rows)

## Requirements

- Python >= 3.7
- TensorFlow >= 2.8.0
- scikit-image >= 0.19.0
- NumPy >= 1.21.0
- Matplotlib >= 3.3.0

## Model Information

The package includes a pre-trained CNN model (`chess_best_model_mini.keras`) that:
- Takes chess board images as input
- Resizes and processes them into 64 tiles (one per square)
- Predicts the piece on each square
- Outputs FEN notation

## Package Structure

```
chess-fen-detector/
├── chess_fen_detector/
│   ├── __init__.py          # Package initialization
│   ├── detector.py          # Main detector class
│   ├── cli.py              # Command-line interface
│   └── models/
│       └── chess_best_model_mini.keras  # Pre-trained model
├── examples/
│   └── example_usage.py    # Usage examples
├── tests/
│   └── test_detector.py    # Unit tests
├── setup.py                # Setup configuration
├── pyproject.toml          # Modern Python packaging config
├── requirements.txt        # Dependencies
├── MANIFEST.in            # Package data files
├── README.md              # This file
└── LICENSE                # License information
```

## Development

### Running tests

```bash
pip install -e ".[dev]"
pytest tests/
```

### Code formatting

```bash
black chess_fen_detector/
flake8 chess_fen_detector/
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- Uses TensorFlow/Keras for deep learning
- Built with scikit-image for image processing

## Troubleshooting

### Model not found error

Make sure the model file is included in the package:
```bash
# Check if model exists
ls chess_fen_detector/models/
```

### TensorFlow installation issues

For GPU support:
```bash
pip install tensorflow[and-cuda]
```

For CPU-only (smaller installation):
```bash
pip install tensorflow-cpu
```

## Future Improvements

- [ ] Support for different board orientations
- [ ] Confidence scores for predictions
- [ ] Batch processing of multiple images
- [ ] Web API interface
- [ ] Mobile-optimized model

## Contact

For questions or issues, please open an issue on the GitHub repository.