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
