tokenpdf

TokenPDF: Generate printable PDFs for RPG tokens and map

TokenPDF is a lightweight Python library for creating printable PDF files containing RPG tokens and (possibly large) maps. It simplifies the process of generating monster-tokens, and fragmenting maps into printable pages, while minimizing the number of papers required. The library is fully configureable.

Changelog

See the Changelog for details on recent changes.

Getting Started

Installation

From PyPI

To install, use one of the following commands:

pip install tokenpdf
pip install tokenpdf[full]
pip install tokenpdf[full-gpu]

See below for more details on the installation options.

Core

Contains the core functionality of the library, including token generation and map fragmentation, and rendering to .svg files, and conversion to pdf using rsvg-convert executable.

pip install tokenpdf

PDF

For other PDF backends, add the pdf-rl, pdf-qt, and/or pdf-pr extras:

• pdf-rl: PDF output using reportlab (default)
  • pip install tokenpdf[pdf-rl]
• pdf-qt: PDF output using PySide6 (Qt)
  • pip install tokenpdf[pdf-qt]
• pdf-pr: PDF output using playwright
  • pip install tokenpdf[pdf-pr]
  • Note: playwright install is required to be run before using the playwright backend.

Image Filters

The rembg package is used for background removal. To install it, use either the cpu or gpu extras:

pip install tokenpdf[cpu]

The gpu extra will install onnxruntime-gpu. See that package for details about system requirements.

Full Installation

To install all extras, use either the full or the full-gpu extras:

pip install tokenpdf[full]

For CPU-based and GPU-based installations, respectively.

From source

git clone https://github.com/Dormat2/tokenpdf.git
cd tokenpdf
pip install -r requirements.txt

Command-Line Interface

The library provides both a command-line interface and a Python API. The CLI is the easiest way to get started.

python -m tokenpdf <config_files> [-o OUTPUT] [-v] [-s]

• config_files: One or more configuration files in TOML, JSON, YAML, or INI format. See examples below, or Configuration Reference for more details. Can only be omitted if -e flag is used.
• -e: Use the example configuration file (tokenpdf/data/example.toml).
• -o OUTPUT: The output PDF file (default: output.pdf). If ommited, the output name is derived from the first configuration file.
• -v: Enable verbose output.
• -s: Silence most output.

Example usage:

python -m tokenpdf example.toml -o my_tokens.pdf -v

Writing Configuration Files

Configurations define your monsters, their tokens, the maps, and the pdf layout and generation process.

Minimal Configuration: Single Token

TOML Example

output = "single_token.pdf"

[monsters.circle]
name = "Circle Token"
size = "Medium"
image_url = "https://picsum.photos/200"
tokens = [
    { type = "circle", size = "medium", count = 1 }
]

JSON Example

{
  "output": "single_token.pdf",
  "monsters": {
    "circle_token": {
      "name": "Circle Token",
      "size": "Medium",
      "image_url": "https://picsum.photos/200",
      "tokens": [
        { "type": "circle", "size": "medium", "count": 1 }
      ]
    }
  }
}

Adding Features Step-by-Step

1. Multiple Tokens for a single monster

Add multiple tokens for the same monster:

TOML Example

[monsters.circle_token]
name = "Circle Token"
size = "Medium"
image_url = "https://picsum.photos/200"
tokens = [
    { type = "circle", size = "medium", count = 5 }
]

JSON Example

{
  "monsters": {
    "circle_token": {
      "name": "Circle Token",
      "size": "Medium",
      "image_url": "https://picsum.photos/200",
      "tokens": [
        { "type": "circle", "size": "medium", "count": 5 }
      ]
    }
  }
}

Add a standing token for the same monster:

TOML Example

[monsters.circle_token]
name = "Circle Token"
size = "Medium"
image_url = "https://picsum.photos/200"
tokens = [
    { type = "circle", size = "small", count = 5 },
    { type = "standing", size = "medium", count = 5 }
]

Note: The size field is used to determine the token's dimensions in relation to the page size and the system (default: D&D5e) grid sizing (can be overriden). The size can be specified in the monster's configuration, and/or overriden in the token's configuration.

2. Customizing Token Appearance

Scaling:

TOML Example

[monsters.circle_token]
name = "Circle Token"
size = "Medium"
image_url = "https://picsum.photos/200"
tokens = [
    { type = "circle", size = "medium", count = 5, scale = 1.1, scale_rho = 0.1 }
]

JSON Example

{
  "monsters": {
    "circle_token": {
      "name": "Circle Token",
      "size": "Medium",
      "image_url": "https://picsum.photos/200",
      "tokens": [
        { "type": "circle", "size": "medium", "count": 5, "scale": 1.1, "scale_rho": 0.1 }
      ]
    }
  }
}

In this example, the scale field scales the token's size. The scale is determined by a log-normal distribution around 1.1, with a standard deviation of 0.1. This provides a more natural variation in token sizes. Omitting scale_rho will set the scale to a fixed value (1.1)

Global Settings

Customize the entire output, page, and layout behavior. Here’s how to configure some global settings.

1. Output File

Specify the name of the PDF file:

TOML

output = "my_custom_tokens.pdf"

JSON

{
  "output": "my_custom_tokens.pdf"
}

2. Page Settings

Define the paper size, orientation, and margins:

TOML

# General configuration
output = "wsc_{ps}.pdf"
verbose = true
system = "D&D 5e"
compress = true

# Paper settings
page_size = ["A2", "A3", "A4"]
orientation = "portrait"
margin = 0.05
optimize_images_for_dpi = 100
optimize_images_for_quality = 80

# Layout settings
rotation = true

JSON

{
  "output": "wsc_{ps}.pdf",
  "verbose": true,
  "system": "D&D 5e",
  "compress": true,
  "page_size": ["A2", "A3", "A4"],
  "orientation": "portrait",
  "margin": 0.05,
  "optimize_images_for_dpi": 100,
  "optimize_images_for_quality": 80,
  "rotation": true
}

3. Layout Options

Enable token rotation for better page utilization:

TOML

rotation = true

JSON

{
  "rotation": true
}

4. Reference

For a full reference of all available settings, see the Configuration Reference.

Screenshots

• Example configuration:
  

• Generated PDF:
  

Contributing

Contributions are welcome! Feel free to submit issues or pull requests via GitHub.