API Reference

Pawn sizes

class rpgpawns.PawnSize(*values)

Pawn size presets.

Each size defines the maximum width and single-image height for the pawn. See PAWN_SPECS for the exact dimensions.

HUGE = 'huge'

LARGE = 'large'

MEDIUM = 'medium'

SMALL = 'small'

rpgpawns.pawn.PAWN_SPECS: dict[PawnSize, tuple[float, float]] = {PawnSize.HUGE: (75.0, 99.0), PawnSize.LARGE: (48.0, 63.0), PawnSize.MEDIUM: (28.0, 48.0), PawnSize.SMALL: (20.0, 28.0)}: Maximum width and single-image height (mm) for each PawnSize.

Pawn creation

rpgpawns.make_pawn(input_image: Image, size: PawnSize = PawnSize.MEDIUM) → Image

Convert an image to a paper-cut pawn image.

The output image has the following properties:

300 DPI
The original image is scaled to fit within the dimensions specified by size (see PAWN_SPECS), preserving aspect ratio
The image is duplicated along its top edge, mirrored vertically
White padding (at least MIN_PADDING_MM) is added at the top and bottom so that all pawns of the same size have identical total height
A thin faint grey border is drawn around the entire image

Parameters

input_image:: Input PIL Image in any mode and resolution.
size:: Pawn size preset. Defaults to PawnSize.MEDIUM.

Returns

PIL Image in RGB mode at 300 DPI.

Collage

rpgpawns.make_collage(pawns: Sequence[Image], margin_mm: float = 5.0) → list[Image]

Arrange pawn images on A4 pages.

Pawns are packed into rows from top to bottom. Tallest pawns are placed first; when the next pawn has a different height a new row is started. Within a row, pawns are placed left to right with COLLAGE_SPACING_MM between them. Pawns already include built-in top/bottom padding, so no extra vertical gap is added between rows.

When a new row would exceed the available page height, a new vertical band is started to the right of the widest row placed so far.

If the pawns do not fit on a single page, additional pages are created automatically.

Parameters

pawns:: Pawn images as returned by make_pawn(). Must not be empty.
margin_mm:: Page margin in millimeters. Defaults to COLLAGE_MARGIN_MM.

Returns

List of PIL Images in RGB mode at 300 DPI, each sized to A4 (210 mm x 297 mm).

Raises

ValueError: If pawns is empty.

Utility

rpgpawns.pawn.mm_to_px(mm: float, dpi: int = 300) → int: Convert millimeters to pixels at the given DPI.

Constants

rpgpawns.pawn.DPI

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

Output resolution in dots per inch (300).

rpgpawns.pawn.MIN_PADDING_MM

Convert a string or number to a floating-point number, if possible.

Minimum white padding added at the top and bottom of each pawn in millimetres.

rpgpawns.pawn.COLLAGE_SPACING_MM

Convert a string or number to a floating-point number, if possible.

Horizontal spacing between pawns in the collage in millimetres.