chess-fen-detector 0.2.0

Convert chess board images to FEN notation using deep learning

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

# Clone or download this package
cd chess-fen-detector

# Install in development mode
pip install -e .

# Or install normally
pip install .

Install dependencies only

pip install -r requirements.txt

Usage

Python API

Basic usage

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

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

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

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:

# 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

pip install -e ".[dev]"
pytest tests/

Code formatting

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:

# Check if model exists
ls chess_fen_detector/models/

TensorFlow installation issues

For GPU support:

pip install tensorflow[and-cuda]

For CPU-only (smaller installation):

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.