A visual heatmap generator for chess PGN games, built with Python, tkinter
, numpy
, and python-chess
. This application analyzes possible move activity throughout a chess game and generates a dynamic heatmap visualization.
The idea for this project got into my head over 2 years ago. And I even got as far as a version that ran ok upto depth 1. But sadly, I never put that project on GitHub and only have that video to remember it by. Anyway, someone on r/learnpython made a post asking for project ideas and I mentioned this one as a fun one that I remember doing once upon a time. I felt bad that I had lost the code to show for it though, thus I have decided to restart the project from scratch. Though I admit to using chatgpt for doc generation and rubberduck debugging this go around as there is no way I'm typing the rest of this ReadMe out on my own...
- ✅ PGN File Support – Load chess games from PGN files for analysis.
- ✅ Move-by-Move Navigation – Step through the game and observe heatmap changes dynamically.
- ✅ Parallelized Heatmap Calculation – Uses
ProcessPoolExecutor
for efficient computation. - ✅ Customizable Board Colors & Fonts – Adjust square colors and piece fonts directly in the UI.
- ✅ Real-time Heatmap Updates – Background processing ensures smooth rendering.
- ✅ Real-time Heatmap Updates – Background processing ensures smooth rendering.
Ensure you have Python 3.7 - 3.10 installed. Python 3.11+ is not supported at this stage and will require significant refactoring to imports for compatibility. See issue #16 for details.
PhillyNote: There are no distribution plans for this project beyond what is accommodated here on GitHub.
-
Clone the Repository:
git clone https://github.com/Phillyclause89/ChessMoveHeatmap.git cd ChessMoveHeatmap
-
Set Up a Virtual Environment:
python -m venv .venv source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
-
Install Dependencies:
-
Preferred Method (Using
requirements.txt
):pip install -r requirements.txt
-
Alternative (Untested) Method (Using
.toml
): Use this method if you prefer.toml
files. However, note that this approach is not officially supported and may not work as expected:pip install .[all]
-
python main.py
This will open the Chess Heatmap UI, allowing you to load a PGN file for analysis.
For optimal performance, it is recommended to compile the project and the python-chess
library with Cython. This can be done using the following no-argument command:
python setup.py
This will compile all relevant components automatically, improving the speed of recursive calculations and other performance-critical operations.
Note: For details on partial compile options or reproducing specific benchmarking tests, see the Cython Benchmarking Results README.
- Click File > Open PGN and select a
.pgn
chess game file. - The heatmap will compute in the background and display when ready.
- Press the Right Arrow (
→
) to advance to the next move. - Press the Left Arrow (
←
) to go back to the previous move.
- Change Default Board Colors:
Options > Change Board Colors
- Change Default Font:
Options > Font
- Change Depth:
Options > Change Depth
The standalone standalone_color_legend.py
script can be used to understand what the heatmap colors represent. Integration of a color legend into the main application is planned for a future release. See issue #17 for details.
python standalone_color_legend.py
ChessMoveHeatmap/
├── main.py # Main GUI Application
├── standalone_color_legend.py # Standalone app to visualize heatmap colors (legend)
├── setup.py # Optional setup script for compiling with Cython (recommended for performance)
├── chmengine/ # Chess Engine Module
├── chmutils/ # Heatmap Calculation Utilities
├── heatmaps/ # Core Heatmap objects, foundational to the entire project
├── tooltips/ # GUI sub-package for tooltip popups on board hover
├── docs/ # Documentation and Images
├── tests/ # Unit Tests and Benchmarking Results (incl. Cython benchmarks)
│ └── CythonBenchmarkingResults/ # Benchmarking results of using Cython for performance
├── pgns/ # Example PGN Files and game outputs
│ └── trainings/ # Output directory for engine training games
├── SQLite3Caches/ # Cached Heatmaps and Q-Tables (Auto-Generated)
│ ├── Better/ # Cached Heatmaps with the updated algorithm (created during main app usage)
│ ├── QTables/ # Q-Tables generated by the engine during console interactions
│ └── Faster/ # Cached Heatmaps with the deprecated, faster discounting algorithm (rarely used)
Explore the full API documentation for ChessMoveHeatmap, including usage guides, advanced topics, and troubleshooting tips, on the GitHub Pages site:
👉 ChessMoveHeatmap API Documentation
This site includes links to additional resources, such as benchmarking results and tutorials, to help you make the most of the project.
- Recursive Depth & Complexity: Heatmap calculations have an estimated O(35^d) complexity (where
d
is the recursion depth). Higherdepth
values may lead to performance degradation. - Parallel Processing: The app utilizes parallel processing for efficiency, but large depth values can still be computationally intensive.
- 🎨 Integrate Color Legend – Adapt
standalone_color_legend.py
into the main UI. See issue #17. - 🚀 Optimize Performance – Explore better recursion and caching strategies. See issue #4, issue #8 and issue #16
- 📈 Enhanced Visualizations – Provide more customization for scaling heatmap intensities. See issue #6, issue #7, issue #10 and issue #11
- 👾 AI Improvements – Refine logic for
CMHMEngine2
based on game outcomes. See issue #13
The chmengine
module is an experimental chess engine component that leverages heatmaps to inform move decisions. While still in development and not yet integrated into the main application, it provides features such as:
- Playing games against the engine.
- Training the engine using reinforcement learning.
For detailed usage examples and instructions, see the chmengine README.
This project is licensed under the MIT License. See the LICENSE file for details.
- Phillyclause89 – Project Creator & Lead Developer
- ChatGPT (OpenAI) – Development Assistance, Documentation, Debugging, and README Updates
- GitHub Copilot (OpenAI) – Code Suggestions, Inline Completions, and Documentation Drafting
This project is my own personal learning exercise, and I am not inclined to accept any contributions at this time. I have no interest in setting up the necessary project frameworks required for successful collaborative development. See issue #15 for more details.