protograf

protograf is an application written in Python for creating simple, regular, graphical designs in PDF (or PNG/GIF/SVG) format via a script.

protograf has been primarily created to handle the prototyping of cards, counters, tiles, boards and boxes for board games, including hexagonal grids, but can also be used for creating any relatively simple design that has regular or repetitive elements; typically a mix of graphics and text.

You do not need to know the Python language to be able to use protograf but you do need Python installed on your machine!

:notebook: Documentation

The online documentation for protograf is available at Read the Docs; its highly recommended to read the sections in the order presented in the Guide.

If you're not familiar with any kind of programming or scripting, you should at least read some of the introductory sections, and especially the installation before proceeding...

:information_desk_person: Support

News and discussion happens at the BoardGameGeek Guild; the developer is active there and can also be contacted with a request to join the Discord server for support and chats.

:hammer_and_wrench: Requirements

protograf requires Python (version of 3.13 or higher) to be installed and running on your machine.

If this is not your current Python version, or Python is not installed on your machine, you may want to install uv which is a cross-platform tool able to install Python.

If using uv, it is recommended to also create and use a virtual environment.

:toolbox: Quick Start (for the impatient)

Assuming that Python 3.13 or higher is installed on your machine, you can then install protograf via:

pip install protograf

or, if using uv:

uv pip install protograf

To check that protograf is working, you can use one (or more) of the files from any of the various examples sub-directories.

As a quick test, make a copy of example1.py script from the examples/manual directory. To do so, open the example1.py link in your browser, click on the Raw button (near the top right), and then save the web page as a file into a local directory on your machine.

Open a command-line window (also known as a terminal or a console), change to the directory where you saved the above file and type:

python example1.py

and press the Enter key.

This script is very simple - it just contains these lines:

# `example1` script for protograf
# Written by: Derek Hohls
# Created on: 29 February 2026
from protograf import *
Create()
Save()

and is designed to produce a single, blank, A4-sized page in a PDF file.

It should create an output file called example1.pdf, which will appear in the same directory as the script. You should be able to open and view this file using any PDF-capable program or application. (If you run the script in a Python shell, the output file will be called test.pdf)

If this works, then download and try out other scripts from any of the examples sub-directories (note some examples may require additional files such as images, CSV files, or spreadsheets). You can download all the examples in a single ZIP file.

If it does not work, you may want to look at more detail provided in the installation guide.

:handshake: Contributions

Please see the list of contributors.

:flower_playing_cards: Recent Features

This section highlights a few of the more recent features added. The full feature list is available in the documentation.

• RaceTrack
• Image alteration operations
• New abstract board example: Mancala
• New shapes: Band (aka "Annular Sector")
• CardBox: create foldable boxes for decks of cards
• Common gaming objects: Cube, Domino, Die and Pentomino(es)
• HexHex boards
• Pathways: (arcs and lines) on a Hexagonal grid
• Stripes: interior "areas" for a Rectangle
• Cards:
  • extract cards as a TableTopSimulator image
  • support for card-back designs
  • grid marks for hexagonal cards/tiles
  • corner crosses as grid marks
  • card-specific bleed areas
• Color support for CYMK

:game_die: Potential Features

Features not yet checked off are not guaranteed to be implemented; they just represent current / potential areas of work or ideas.

• Common objects:
  • Meeple (Polyshape with curves)
• Cards:
  • icon alignment
• Others:
  • snail-drawn Greek Key

:jigsaw: Potential Examples

These are possible examples to show board creation based on existing games:

• Wargame board: show full --terrain features (vector and bitmap)
• WarpWar board: show a fully-styled example
• Traveller board: show a fully-styled Star System
• 18xx board: show a basic map with tracks, towns, cities and off-map areas

:mega: Acknowledgements

The world is full of power and energy and a person can go far by just skimming off a tiny bit of it. "Snow Crash", Neal Stephenson, 1992.

As usual, with Python, you are building "on the shoulders of giants". In this case, the pyMuPDF library provides all of the core infrastructure used to do the underlying graphics processing, PDF file creation and images exports; protograf is effectively a highly customised wrapper to simplify common uses around its existing and extensive capabilities. Internal terminology, such as shapes, was developed before the adoption of pyMuPDF and it is just coincidental that these are similar!

Earlier versions of protograf used the ReportLab PDF Toolkit, which is also a powerful and useful library for supporting this type of application.

Users on BoardGameGeek have provided invaluable feedback and suggestions!

:books: Additional Libraries

• cairoSVG https://pypi.org/project/cairosvg/ - support for drawing SVG images
• bgg-api https://pypi.org/project/bgg-api/ - support for access to the BoardGameGeek API
• xlrd https://pypi.org/project/xlrd/ - access to Excel .xls files
• openpyxl https://pypi.org/project/openpyxl/ - access to Excel .xlsx files
• imageio https://pypi.org/project/imageio/- support for compiling PNGs into a GIF
• jinja https://jinja.palletsprojects.com - template logic with variables
• pillow https://github.com/python-pillow/Pillow - support for image processing
• segno https://github.com/heuer/segno/ - support for QRCode creation

:scroll: License

protograf is licensed under the GNU General Public License.