ChessMoveHeatmap

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.

An Introduction by Phillyclause89 (Not ChatGPT or GitHub Copilot)

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...

Features

✅ 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.

Installation

Prerequisites

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.

Steps to Set Up the Project

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]
```

Run the Application

python main.py

This will open the Chess Heatmap UI, allowing you to load a PGN file for analysis.

Optional: Compile with Cython for Performance

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.

Usage

Loading a PGN File

Click File > Open PGN and select a .pgn chess game file.
The heatmap will compute in the background and display when ready.

Move Navigation

Press the Right Arrow (→) to advance to the next move.
Press the Left Arrow (←) to go back to the previous move.

Customization Options

Change Default Board Colors: Options > Change Board Colors
Change Default Font: Options > Font
Change Depth: Options > Change Depth

Standalone Color Legend

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

Project Structure

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)

Documentation

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.

Performance Considerations

Recursive Depth & Complexity: Heatmap calculations have an estimated O(35^d) complexity (where d is the recursion depth). Higher depth values may lead to performance degradation.
Parallel Processing: The app utilizes parallel processing for efficiency, but large depth values can still be computationally intensive.

Future Plans

🎨 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