Chess Scanner

Chess Scanner is a highly accurate machine learning model for detecting chessboard positions from cropped screenshots of chessboards. The model has been trained on various piece and board sets from popular chess websites (Lichess and others). The model works best with digital screenshots, although scanned images may work too (with varying results). Board annotations (arrows, circles, etc.) may cause misdetections, but generally, the model is robust to them.

The model achieves a very high accuracy with Lichess and Chess.com boards. A test set of 1000 positions was generated using python-chess. The model detected 1000/1000 positions correctly.

Demo video

demo.mp4

Installation

The model can be run from the command line, or deployed as an API using Docker.

Prerequisites

1. Clone this repository.
2. Download the latest chess_model.h5 from the Releases page.
3. Place the model file in the chess-scanner directory.

Command Line

1. Install the required Python packages:

   $ pip install -r requirements.txt

2. Run the model:

   $ python chess_eye.py <path to image> <white|black>

   The white or black argument marks the perspective of the screenshot, i.e. if ranks are numbered from 1 to 8 (white) or 8 to 1 (black).

3. After the detection is done, the model will output the detected chessboard position in Forsyth-Edwards Notation (FEN).

   rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR

API

1. Make sure you have Docker installed.

2. Build the Docker image:

   $ docker build -t chess-scanner .

3. Run the Docker container:

   $ docker run -p 8080:8080 chess-scanner

4. The API should now be running on http://localhost:8080. The API has a single endpoint: /api/predict/<white|black>. The white or black argument marks the perspective of the screenshot, i.e. if ranks are numbered from 1 to 8 (white) or 8 to 1 (black).

5. You can test it with cURL as follows:

   $ curl -X POST http://localhost:8080/api/detect/white --form 'file=@"circles.png"'                        

   As a response, you should receive a JSON with the FEN string:

   {"fen":"rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR"}

Shortcut

You can create a macOS Shortcut (used in the demo video) that you can invoke with a keyboard shortcut for quick access. Below is an example.