About

fentoboardimage takes a Fen string representing a Chess position, and renders a PIL image of the resulting position.

Examples

Examples can be found under the examples folder in this repository.

You can customize:

• the size and color of the board
• piece sprites
• black or white perspective
• Board highlighting for last move
• Arrows

Installation

Install the package using pip

$ pip install fentoboardimage

Then import the functions and use them as follows:

from fentoboardimage import fen_to_image, load_pieces_folder

board = fen_to_image(
    fen="rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    square_length=100,
    piece_set=load_pieces_folder("./pieces"),
    dark_color="#D18B47",
    light_color="#FFCE9E"
)
board.save("board.png")

Asset Setup

All asset paths are relative to your current working directory (where you run your script).

Piece Set Structure

your_project/
├── main.py
└── pieces/           # Path: "pieces" or "./pieces"
    ├── white/
    │   ├── King.png
    │   ├── Queen.png
    │   ├── Rook.png
    │   ├── Bishop.png
    │   ├── Knight.png
    │   └── Pawn.png
    └── black/
        ├── King.png
        ├── Queen.png
        ├── Rook.png
        ├── Bishop.png
        ├── Knight.png
        └── Pawn.png

Arrow Set Structure (Optional)

arrows/
├── Knight.png    # L-shaped arrow (3:2 ratio, points bottom-right → top-left)
└── Up.png        # Straight arrow (1:3 ratio, points upward, 3 sections: head/body/tail)

See the documentation for detailed arrow sprite specifications.

Making Paths Portable

For scripts that may run from different directories, use __file__ to resolve paths relative to your script:

import os

script_dir = os.path.dirname(os.path.abspath(__file__))
pieces_path = os.path.join(script_dir, "pieces")

piece_set = load_pieces_folder(pieces_path)

Usage

fen_to_image Parameters

Loading Functions

load_pieces_folder(path, cache=True)

Loads piece images from a folder. Returns a callable for use with piece_set.

load_arrows_folder(path, cache=True)

Loads arrow sprites from a folder. Returns a callable for use with arrow_set.

load_font_file(path)

Loads a TrueType font for coordinates. Returns a callable that accepts font size.

Development

This project uses UV for dependency management.

Setup

Install UV (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone the repository and install dependencies:

git clone https://github.com/reedkrawiec/fenToBoardImage.git
cd fenToBoardImage
uv sync

Running Tests

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest test/test_unit.py

# Run specific test class
uv run pytest test/test_unit.py::TestFenParser

Code Formatting

This project uses Black for code formatting:

# Format all Python files
uv run black .

# Check formatting without making changes
uv run black --check .

Documentation

Build the documentation locally:

# Build static site
uv run mkdocs build

# Serve locally with live reload
uv run mkdocs serve

The documentation will be available at http://127.0.0.1:8000/.

Dependencies

• Pillow