Generate

Main class used to generate a GIF. See readme for usage.

class gifpgn.CreateGifFromPGN(game: Game)

Bases: object

Parameters:

game (chess.pgn.Game) – An instance of chess.pgn.Game from the python-chess library.

add_analysis_bar(width: int = 30) → None

Adds an analysis bar to the right side of the chess board.

Note

Requires that a PGN has been loaded with [%eval ...] annotations for each half move.

Alternatively the PGN can be decorated using the gifpgn.utils.PGN class.

Parameters:

width (int) – Width of the analysis bar in pixels, defaults to 30

Raises:

MissingAnalysisError – At least one ply in the PGN has a missing [%eval ...] annotation

add_analysis_graph(height: int = 81, line_width: int = 1) → None

Adds an analysis graph to the bottom of the chess board.

Note

Requires that a PGN has been loaded with [%eval ...] annotations for each half move.

Alternatively the PGN can be decorated using the gifpgn.utils.PGN class.

Parameters:

• height (int) – Height of the analysis graph in pixels, defaults to 81

• line_width (int) – Width of graph line (and x axis line) in pixels, defaults to 1

Raises:

MissingAnalysisError – At least one ply in the PGN has a missing [%eval ...] annotation

add_headers(height: int = 20) → None

Adds headers with player names, captured pieces, and clock (if PGN contains [%clk ...] annotations) to the top and bottom of the chess board.

Parameters:

height (int) – Height of headers in pixels, defaults to 20

property board_size: int

int: Size of the board in pixels, defaults to 480

Note

Size will be rounded down to the nearest multiple of 8

enable_arrows()

Enables move and check arrows

enable_nags()

Enable numerical annoation glyphs

Note

Requires that a PGN has been loaded with [%eval ...] annotations for each half move.

Alternatively the PGN can be decorated using the gifpgn.utils.PGN class.

Raises:

MissingAnalysisError – At least one ply in the PGN has a missing [%eval ...] annotation

property frame_duration: float

float: Duration of each frame in seconds, defaults to 0.5

generate(output_file: str | None = None) → BytesIO | None

Generate the GIF and either save it to the specified file path or return the raw bytes if no file path is specified.

game = chess.pgn.read_game(io.StringIO(pgn_string))
gif = CreateGifFromPGN(game)
gif.generate("/path/to/output.gif")

Parameters:

output_file (Optional[str]) – Filepath to save to, defaults to None

Return Optional[BytesIO]:

Raw bytes of the generated GIF if output_file parameter is set, else returns None

property max_eval: int

int: Maximum evaluation displayed on analysis graph or bar in centipawns, defaults to 1000

property piece_theme: PieceTheme

PieceTheme: Instance of gifpgn.PieceTheme

reverse_board()

Reverses the board so that black is at the bottom

property square_colors: BoardTheme

BoardTheme: An instance of gifpgn.BoardTheme

class gifpgn.PieceTheme(value)

Enum with valid piece themes

game = chess.pgn.read_game(io.StringIO(pgn_string))
gif = CreateGifFromPGN(game)
gif.piece_theme = PieceTheme.CASES

Alpha Blue
Cases Green
Maya Brown
Regular Purple

ALPHA = 'alpha'

Alpha theme by Eric Bentzen, free for personal use.

CASES = 'cases'

Cases theme by Matthieu Leschemelle, freeware.

MAYA = 'maya'

Maya theme by Armando Hernandez Marroquin, freeware.

REGULAR = 'regular'

Regular theme by Alastair Scott, freeware.

class gifpgn.BoardThemes(value)

Class to select one of the built-in board themes

game = chess.pgn.read_game(io.StringIO(pgn_string))
gif = CreateGifFromPGN(game)
gif.square_colors = BoardThemes.BLUE

BLUE = ('#eae9d2', '#4b7399')

BROWN = ('#f0d9b5', '#b58863')

GREEN = ('#ebecd0', '#739552')

LIGHT_BLUE = ('#f0f1f0', '#c4d8e4')

PURPLE = ('#f0f1f0', '#8476ba')

RED = ('#f5dbc3', '#bb5746')

class gifpgn.BoardTheme(white: str = '#f0d9b5', black: str = '#b58863')

Class for creating your own board theme containing colors for the white and black squares

game = chess.pgn.read_game(io.StringIO(pgn_string))
gif = CreateGifFromPGN(game)
gif.square_colors = BoardTheme(white="#ffffff", black="#000000")

black: str = '#b58863'

square_color(color: bool)

white: str = '#f0d9b5'