🧠 Chessboard Recognizer (Convert your chess images to FEN positions with one click!)

This project uses a deep learning model implemented in PyTorch to recognize the positions of chess pieces on a chessboard image and convert it into FEN notation. This library introduces an easy and fast function to simply predict a fen from an image, it vastly increases prediction accuracy, encompassing a wide variety of chess image formats from different sources. For more advanced usage it also provides reusable components for training, inference, and data preparation.

Full credits to linrock/chessboard-recognizer for chess image data, preprocessing and basis for the training algorithm, originally a simple CNN architecture built on a no longer supported version of TensorFlow 2. This version transitions to PyTorch and vastly improves prediction accuracy on a wide variety of chess image formats.

🧪 Usage Example

Check the demo usage notebook for more advanced usages (training/inference) 📓 examples/demo_usage.ipynb

Predict from an image

from chessimg2pos import predict_fen
fen = predict_fen("../images/chess_image.png")
print(fen)

Output:

11111111/11111111/11111111/1111p1K1/11k1P111/11111111/11111111/11111111

🖼️ Sample Results

📷 Input:

🎯 Predicted FEN:

11111111/11111111/11111111/1111p1K1/11k1P111/11111111/11111111/11111111

🚀 Getting Started

Requirements

• Python 3.10–3.14
• PyTorch
• Other dependencies in requirements.txt

pip install chessimg2pos

or

git clone https://github.com/mdicio/chessimg2pos
pip install -r requirements.txt

🙏 Acknowledgements

This project is a continuation and modernization of:

• linrock/chessboard-recognizer — the original TensorFlow implementation
• tensorflow_chessbot by Elucidation

Major thanks to these creators — this project wouldn’t exist without their work.

🧠 Core Classes

This project is centered around two powerful classes that handle training and prediction with a modern PyTorch-based architecture.

🔧 ChessRecognitionTrainer

Handles training and evaluation of the CNN-based chess piece classifier.

Example:

from chessimg2pos import ChessRecognitionTrainer

trainer = ChessRecognitionTrainer(
    images_dir="../../training_images/chessboards", # replace with your path
    model_path="../../models/test_model.pt",# replace with path where you want models tgo be saved
    generate_tiles=False,  # Set to True if tiles need to be generated from boards
    epochs = 5,
    overwrite = False
)
model, device, accuracy = trainer.train(classifier="enhanced")

🔍 ChessPositionPredictor

Loads a trained model and predicts a FEN string from a chessboard image.

Example:

from chessimg2pos import ChessPositionPredictor

predictor = ChessPositionPredictor("../../models/test_model.pt")
result = predictor.predict_chessboard("../images/ccom_1.png", return_tiles=True)

print("Predicted FEN:", result["fen"])
print("Confidence:", result["confidence"])
predictor.visualize_prediction(result)