chessvision ♟️

A fast, lightweight chess board and piece recognition toolkit.

Install

# With uv (recommended)
uv tool install chessvision

# With pipx
pipx install chessvision

# As a library
uv add chessvision

# or
pip install chessvision

Usage

CLI

# Predict chess position on a full board image
chessvision board chessboard.png

# Predict a single square image
chessvision square square.png

Python API

from chessvision import BoardPredictor, Castling, Orientation, PieceClassifier

# 1. Full Board Recognition
predictor = BoardPredictor()
prediction = predictor.predict(
    "chessboard.png", orientation=Orientation.WHITE, castling=Castling.ALL
)

print(prediction.render_board)
print(f"FEN: {prediction.fen}")
print(f"Confidence: {prediction.confidence:.2%}")

# 2. Single Square Classification
classifier = PieceClassifier()
square_prediction = classifier.predict_square("square.png")
print(f"{square_prediction.label} [{square_prediction.confidence:.2%}]")

# 3. Batch Squares Classification
batch_predictions = classifier.predict_squares(["e4.png", "e5.png"])
for prediction in batch_predictions:
    print(f"{prediction.label} [{prediction.confidence:.2%}]")

CLI Subcommands

chessvision board

Castling Options

# Specify board perspective (white or black orientation)
chessvision board chessboard.png --orientation black
chessvision board chessboard.png -o black

# Specify castling availability
chessvision board chessboard.png --castling KQkq
chessvision board chessboard.png -c KQ

chessvision square

# Predict piece on a square image
chessvision square square.png

Model & Cache Management

chessvision automatically downloads the pre-trained ONNX piece classifier (chess_piece_classifier.onnx) from Hugging Face on its first run and caches it locally:

Default File Paths

Attributions

Training assets were extracted, and preprocessed from Lichess open-source piece sets and board themes (see their COPYING.md for individual asset licenses).

License

This project is licensed under the MIT License.