{"id":37622902,"url":"https://github.com/georg-wolflein/chesscog","last_synced_at":"2026-01-16T10:42:44.962Z","repository":{"id":51078094,"uuid":"301457037","full_name":"georg-wolflein/chesscog","owner":"georg-wolflein","description":"Determining chess game state from an image.","archived":false,"fork":false,"pushed_at":"2025-01-11T15:54:38.000Z","size":35588,"stargazers_count":103,"open_issues_count":2,"forks_count":25,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-11T16:37:55.947Z","etag":null,"topics":["chess","chess-recognition","computer-vision","deep-learning","pytorch"],"latest_commit_sha":null,"homepage":"https://www.chesscog.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/georg-wolflein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-05T15:35:47.000Z","updated_at":"2025-01-10T10:23:42.000Z","dependencies_parsed_at":"2024-04-30T16:32:34.644Z","dependency_job_id":"7c42dd4d-f8c6-4f6e-ad92-d34906646990","html_url":"https://github.com/georg-wolflein/chesscog","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/georg-wolflein/chesscog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georg-wolflein%2Fchesscog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georg-wolflein%2Fchesscog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georg-wolflein%2Fchesscog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georg-wolflein%2Fchesscog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/georg-wolflein","download_url":"https://codeload.github.com/georg-wolflein/chesscog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/georg-wolflein%2Fchesscog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478050,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","chess-recognition","computer-vision","deep-learning","pytorch"],"created_at":"2026-01-16T10:42:44.181Z","updated_at":"2026-01-16T10:42:44.953Z","avatar_url":"https://github.com/georg-wolflein.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# chesscog\n\n![build](https://github.com/georg-wolflein/chesscog/workflows/build/badge.svg)\n\n_chesscog_ combines traditional computer vision techniques with deep learning to recognise chess positions from photos.\n\nThis repository contains the official code for the paper:\n\n\u003e [**Determining Chess Game State From an Image**](https://doi.org/10.3390/jimaging7060094)  \n\u003e Georg Wölflein and Ognjen Arandjelović  \n\u003e _Journal of Imaging_, vol. 7, no. 6, p. 94, June 2021.\n\nI originally developed this project as part of my [master thesis](https://github.com/georg-wolflein/chesscog-report/raw/master/report.pdf) at the University of St Andrews. Documentation is available [here](https://georg-wolflein.github.io/chesscog).\n\n## Related repositories\n\n- [chesscog-report](https://github.com/georg-wolflein/chesscog-report): the master thesis\n- [chesscog-app](https://github.com/georg-wolflein/chesscog-app): the proof-of-concept web app\n- [recap](https://github.com/georg-wolflein/recap): configuration management system developed as part of this project\n\n## Demo\n\nSee it in action at [chesscog.com](https://www.chesscog.com)!\n![Screenshot](https://github.com/georg-wolflein/chesscog/raw/master/docs/demo_screenshot.png)\n\n## Background\n\nA casual over-the-board game between two friends will often reach an interesting position. After the game, the players will want to analyse that position on a computer, so they take a photo of the position. On the computer, they need to drag and drop pieces onto a virtual chessboard until the position matches the one they had on the photograph, and then they must double-check that they did not miss any pieces.\n\nThe goal of this project is to develop a system that is able to map a photo of a chess position to a structured format that can be understood by chess engines, such as the widely-used Forsyth–Edwards Notation (FEN).\n\n## Overview\n\nThe chess recognition system is trained using a dataset of ~5,000 synthetically generated images of chess positions (3D renderings of different chess positions at various camera angles and lighting conditions).\nThe dataset is available [here](https://doi.org/10.17605/OSF.IO/XF3KA).\nAt a high level, the recognition system itself consists of the following pipeline:\n\n1. board localisation (square and corner detection)\n2. occupancy classification\n3. piece classification\n4. post-processing to generate the FEN string\n\n## Installing\n\nPlease consult Appendix C of my [master thesis](https://github.com/georg-wolflein/chesscog-report/raw/master/report.pdf) for a detailed set of instructions pertaining to the installation and usage of _chesscog_.\n\nThere are three methods of installing and running chesscog.\n\n1. **Using poetry (recommended).**\n   Ensure you have [poetry](https://python-poetry.org) installed, then clone this repository, and install the _chesscog_:\n   ```bash\n   git clone https://github.com/georg-wolflein/chesscog.git\n   cd chesscog\n   poetry install\n   ```\n   Note that you need to run `poetry shell` to activate the virtual environment in your shell before running any of the commands later in this README.\n2. **Using pip.**\n   This option will install _chesscog_ locally on your machine using pip (without a virtual environment).\n   ```bash\n   git clone https://github.com/georg-wolflein/chesscog.git\n   cd chesscog\n   pip install .\n   ```\n3. **Using Docker.**\n   Two Dockerfiles are provided: one for CPU (_cpu.Dockerfile_) and another with enabled GPU-acceleration (_Dockerfile_). Simply subsitute the name in the following command.\n   First, build the image:\n\n   ```bash\n   docker build -t chesscog -f cpu.Dockerfile .\n   ```\n\n   Then, run the image using:\n\n   ```bash\n   PWD=$(pwd); docker run -it -p 8888:8888 -p 9999:9999 -v $PWD/config:/config -v $PWD/runs:/chess/runs -v $PWD/results:/chess/results -v $PWD/models:/chess/models chesscog\n   ```\n\n   Open a browser to [http://localhost:8888](http://localhost:8888) which will display Jupyter lab running in the Docker container (the password is `chesscog`). Simply open a terminal in Jupyter lab and run the remaining instructions in this README.\n\n### Downloading the dataset and models\n\nTo download and split the dataset, run:\n\n```bash\npython -m chesscog.data_synthesis.download_dataset\npython -m chesscog.data_synthesis.split_dataset\n```\n\nFinally, ensure that you download the trained models:\n\n```bash\npython -m chesscog.occupancy_classifier.download_model\npython -m chesscog.piece_classifier.download_model\n```\n\n## Command line usage\n\nAs detailed in Appendix C.2 of my [master thesis](https://github.com/georg-wolflein/chesscog-report/raw/master/report.pdf), _chesscog_ provides various scripts that can be executed from the command line.\n\nOne particularly useful one is to perform an inference (see Appendix C.2.4) which can be carried out using:\n\n```bash\npython -m chesscog.recognition.recognition path_to_image.png --white\n```\n\nThe output will look as follows:\n\n```\n$ python -m chesscog.recognition.recognition data://render/train/3828.png --white\n. K R . . R . .\nP . P P Q . . P\n. P B B . . . .\n. . . . . P . .\n. . b . . p . q\n. p . . . . . .\np b p p . . . p\n. k r . . . r .\n\nYou can view this position at https://lichess.org/editor/1KR2R2/P1PPQ2P/1PBB4/5P2/2b2p1q/1p6/pbpp3p/1kr3r1\n```\n\nOther scripts are available for tasks such as:\n\n- training the models\n- fine-tuning on custom datasets\n- performing inference on fine-tuned models\n- locating the corner points\n- performing automated tests\n\nRelevant documentation is available in Appendix C.2 of my [master thesis](https://github.com/georg-wolflein/chesscog-report/raw/master/report.pdf).\nIn particular, Appendix C.2.6 contains instructions for fine-tuning the model to your own chess set, using only two input images. \nBe sure to run `python -m chesscog.transfer_learning.create_dataset` before training (a step I forgot to mention in those instructions, see [this issue](https://github.com/georg-wolflein/chesscog/issues/15).\n\nTo see an example of how the Python API is used in practice, check out the REST API developed for the _chesscog-app_ [here](https://github.com/georg-wolflein/chesscog-app/tree/master/api).\n\n## Citation\n\nIf you find this work helpful, please consider citing:\n\n```\n@article{wolflein2021jimaging,\n  author         = {W\\\"{o}lflein, Georg and Arandjelovi\\'{c}, Ognjen},\n  title          = {Determining Chess Game State from an Image},\n  journal        = {Journal of Imaging},\n  volume         = {7},\n  year           = {2021},\n  number         = {6},\n  article-number = {94}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorg-wolflein%2Fchesscog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeorg-wolflein%2Fchesscog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeorg-wolflein%2Fchesscog/lists"}