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 positions from a board, screenshot, or book page
chessvision board chessboard.png

# Predict directly from clipboard (screenshot or copied image)
chessvision board

# Predict chess positions from a PDF document
chessvision pdf document.pdf

# Predict a single square image
chessvision square square.png

Python API

from chessvision import (
    BoardDetector,
    BoardPredictor,
    Orientation,
    PDFPredictor,
    PieceClassifier,
    Turn,
)

# 1. Full Board Recognition
predictor = BoardPredictor()
prediction = predictor.predict(
    "chessboard.png", orientation=Orientation.AUTO, turn=Turn.AUTO, castling="auto"
)

print(prediction.ascii_board)
print(f"FEN: {prediction.fen}")
print(f"Confidence: {prediction.confidence:.2%}")
print(f"Valid: {prediction.is_valid}")
if not prediction.is_valid:
    print(f"Errors: {prediction.validation_errors}")
print(f"Lichess URL: {prediction.lichess_url}")
print(f"Chess.com URL: {prediction.chesscom_url}")

# Access the chess.Board object directly
board = prediction.board

# 2. Multi-Board Detection
detector = BoardDetector()
boards = detector.detect("page.png")  # Returns list of DetectedBoard objects

for board in boards:
    prediction = predictor.predict(board)
    print(f"Box: {board.box}, FEN: {prediction.fen}")

# 3. Multi-Page PDF Prediction
pdf_predictor = PDFPredictor()
for result in pdf_predictor.predict("document.pdf"):
    print(f"{result.label}: {result.prediction.fen}")

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

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

CLI Subcommands

chessvision board

Castling Options

# Predict from clipboard (screenshot or copied image)
chessvision board

# Specify board perspective explicitly
chessvision board chessboard.png --orientation black
chessvision board chessboard.png -o white

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

# Specify side to move explicitly
chessvision board chessboard.png --turn black
chessvision board chessboard.png -t white

# Specify analysis platform explicitly
chessvision board chessboard.png --open --site chess.com
chessvision board chessboard.png --open -s lichess

chessvision pdf

# Predict chess positions from a PDF document
chessvision pdf document.pdf

# Export detected positions to a PGN file
chessvision pdf document.pdf --output positions.pgn
chessvision pdf document.pdf -o positions.pgn

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.