Visualizing Chess Engine Heuristics with Python and Manim

Chess animator

I have recently been developing a Python-based toolset designed to translate chess game data (PGN) into structured video via the Manim animation engine. The project, chess-animator, provides a programmatic framework for visualizing moves alongside underlying evaluation metrics produced by engine analysis.

The package integrates python-chess for logic and Stockfish for centipawn evaluation, generating a multi-panel animation that includes a real-time evaluation bar and comparative metrics for various positional factors.

The source code and documentation are available on GitHub: https://github.com/wdjoyner/chess-animator

---

Technical Note: Metric Definitions and Scaling

A primary objective of this visualization is to map engine heuristics to an intuitive geometric scale. The evaluation bar and the positional metrics strip follow these specific definitions:

• Evaluation Bar Scaling: The bar is normalized such that a 100-centipawn advantage (+1.0) corresponds to the height of exactly one square on the adjacent 8x8 chessboard. The visual range is clamped at ±5.0 to maintain resolution for positional play while clearly indicating decisive tactical advantages.
• Space: This metric quantifies territorial control by counting squares controlled by a side, with higher weights assigned to squares in the opponent's half of the board (ranks 5–8 for White, 1–4 for Black).
• Mobility: Calculated as the number of legal moves available to a side's pieces, weighted by piece type to reflect the relative importance of activity for different units.
• King Safety: A structural assessment based on the defensive integrity of the pawn shield and the proximity of friendly versus enemy pieces to the king's square.

By utilizing Manim’s ability to render mathematical objects, these metrics are updated move-by-move in synchronization with the piece animations. This provides a granular view of how the character of a position evolves through the interaction of these heuristics.

Here is an example of the game below

[Event "Candidates Tournament"]
[Site "Toronto CAN"]
[Date "2024.04.04"]
[Round "5"]
[White "Caruana, Fabiano"]
[Black "Nepomniachtchi, Ian"]
[Result "1-0"]
[WhiteElo "2803"]
[BlackElo "2758"]
[ECO "C54"]
[Opening "Italian Game"]

1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. c3 Nf6 5. d3 d6 
6. O-O O-O 7. Re1 a6 8. Bb3 Ba7 9. h3 Re8 10. Nbd2 Be6 
11. Bc2 d5 12. exd5 Bxd5 13. Nf1 h6 14. Ng3 Qd7 
15. Be3 Bxe3 16. Rxe3 Rad8 17. Qe2 Qc8 18. Rae1 b5 
19. Qd2 Ne7 20. d4 exd4 21. cxd4 Ng6 22. Bb3 Bxb3 
23. axb3 Rxe3 24. Rxe3 Nf4 25. Qc3 Rd5 26. Ne5 N6h5 
27. Nxh5 Nxh5 28. Re1 Nf6 29. Nc6 Qd7 30. Ne5 Qc8 
31. Nc6 Qd7 32. Ne5 1-0

Stockfish Analysis of Analysis: WCC 2018, Carlsen vs. Caruana Round 2

I wrote a package (with claude and gemini's help) that takes a pgn file of chess games, runs them all through stockfish for analysis, then creates a terse latex report (link below) for selected top games (such as the game discussed in this column). This "Chess Game Analysis" (CGA) was posted to my github repo. This latex report was run through Gemini and the post below was created.

Precision in London: Carlsen vs. Caruana, Round 2

Analysis generated by Stockfish 17.1 | Event Date: 2018.11.10

The second round of the 2018 World Chess Championship in London [cite: 17, 18] was a masterclass in technical accuracy. Playing White, Magnus Carlsen faced Fabiano Caruana in a game that engine analysis now classifies as "balanced and one-sided," with White maintaining a slight but consistent comfort level throughout.

Game Statistics

Metric	Magnus Carlsen (White)	Fabiano Caruana (Black)
Total Moves	49	48
Accuracy	97.7%	98.6%
Avg. Centipawn Loss	4.6	2.9
Blunders/Mistakes	0	0

Positional Breakdown

While the game ended in a draw, the underlying positional metrics show a fascinating tug-of-war between different strategic advantages:

• Space: Caruana (Black) held a consistent edge in territory, averaging a score of 0.36 compared to Carlsen's 0.29.
• Mobility: Carlsen countered Black's space by maintaining more active pieces, with an average mobility score of 1.62 vs. Caruana's 1.42.
• King Safety: White enjoyed significantly higher safety metrics (0.67 avg) compared to Black (-0.05 avg), particularly as the game progressed.
• Tactical Threats: Carlsen maintained a higher average threat level (4.78) than Caruana (3.51), keeping the pressure on the challenger.

Conclusion

With a total evaluation spread of only 0.63, this encounter is the definition of "Balanced" play. Neither side allowed a single inaccuracy or mistake, resulting in a technical 1/2-1/2 draw.

The latex report can be found here: Download Full PDF Report.