CardPrintLayouter

A tool for creating print-ready PDFs from card images, optimized for printing custom card games, board games, and other card-based projects.

Features

• Arrange cards in a grid layout optimized for the specified page size
• Support for double-sided cards
• Multiple bleed handling options (add, remove, preserve)
• Automatic calculation of rows and columns based on card dimensions
• Support for reading cards from directories or zip files
• Hierarchical configuration through config files
• Guide lines for easy cutting

Installation

Package Manager Console

Install-Package Nezbo.CardPrintLayouter

.NET CLI

dotnet add package Nezbo.CardPrintLayouter

Usage

Basic Usage

using Nezbo.CardPrintLayouter; using var generator = new CardPdfGenerator(o => { o.SourcePath = @"path\to\your\card\images"; o.SeparationStrategy = SeparationStrategy.SeparateFiles; o.BackFileKey = "back"; o.IncludeBacks = true; }); generator.Generate();

Configuration Options

CardPrintLayouter uses a configuration system with hierarchical inheritance. You can place a cards.config file in any directory containing card images, and settings will be inherited from parent directories.

Available Options

Option	Description	Default Value
Source Files
SourcePath	Directory or zip file containing card images	Current directory
DefaultBack	Base filename for card backs	"back"
BackPatterns	Regular expressions to match front cards with specific backs	""
DoubleSidedIdentical	Whether the cards should have the same front and back	false
DoubleSidedSequential	Whether the cards should be printed as alternating between being a front and a back	false
Card Dimensions
CardWidthMM	Width of each card in millimeters	63
CardHeightMM	Height of each card in millimeters	88
CardReplication	Number of times each card is replicated	1
IncludeBacks	Whether to include card backs in the output	true
Bleed Settings
BleedStyle	Style of bleed (Border or Reversed)	Reversed
BleedStrategy	Strategy for handling bleed (None, Remove, Preserve, Add)	None
InputBleedXMM	Horizontal bleed in input images (mm)	0
InputBleedYMM	Vertical bleed in input images (mm)	0
OutputBleedXMM	Horizontal bleed in output PDF (mm)	0
OutputBleedYMM	Vertical bleed in output PDF (mm)	0
BleedXMM	Sets both InputBleedXMM and OutputBleedXMM	-
BleedYMM	Sets both InputBleedYMM and OutputBleedYMM	-
Page Settings
PageSize	Size of the output pages (Letter, A4, etc.)	Letter
PageMarginXMM	Horizontal margin on the page (mm)	10
PageMarginYMM	Vertical margin on the page (mm)	5
SpacingMM	Spacing between cards (mm)	5
AddGuidelines	Whether to add cutting guidelines	true
PageText	Text to display at the top or bottom of each page. Supports dynamic placeholders (see below)	""
PageTextLocation	Location of the page text. One of: TopLeft, TopCenter, TopRight, BottomLeft, BottomCenter, BottomRight	TopLeft
Output Settings
OutputFilename	Name of the output PDF or PNG file. If the extension is .png, generates images (one per page) with the format {Filename}{pageNo}.png	"cards.pdf"
OverrideOutputFile	Overwrite existing output file instead of auto-incrementing name	false
SeparationStrategy	How to separate cards (Continuous, SeparatePages, SeparateFiles)	Continuous

Configuration File Format

The cards.config file uses a simple key-value format:

CardWidthMM=63 CardHeightMM=88 BleedStrategy=Add BleedXMM=3 BleedYMM=3 PageSize=A4

Configuration Inheritance

Configuration settings are inherited in the following order (later ones override earlier ones):

1. Default values (built into the application)
2. Parent directory cards.config files
3. Current directory cards.config file
4. Command-line or programmatic options

This allows you to set common settings (like paper size) in a root directory, and override specific settings (like bleed options) in subdirectories.

Page Text and Dynamic Placeholders

You can add custom text to each page using the PageText option. This text can include dynamic placeholders that will be replaced with values for each page:

Placeholder	Description
{Page}	The current page number
{Pages}	The total number of pages
{Sheet}	The current sheet number (for double-sided printing)
{Sheets}	The total number of sheets (for double-sided printing)
{Side}	"Front" or "Back" depending on the page
{File}	The file name of the first card on the page
{FilePath}	The full file path of the first card on the page
{Folder}	The folder name containing the first card on the page
{FolderPath}	The full folder path containing the first card on the page

The position of this text is controlled by the PageTextLocation option, which can be set to any of:

• TopLeft
• TopCenter
• TopRight
• BottomLeft
• BottomCenter
• BottomRight

Example usage:

o.PageText = "{Page} / {Pages} - {Side} - {File}"; o.PageTextLocation = PageTextLocation.BottomRight;

---

Bleed Handling

CardPrintLayouter offers several strategies for handling card bleeds:

• None: No bleed processing is performed.
• Remove: Removes existing bleed from input images.
• Preserve: Keeps existing bleed as-is.
• Add: Adds new bleed to images that don't have it.

The bleed style can be set to:

• Border: Extends the card edge colors outward.
• Reversed: Creates a mirrored effect at the edges.

Card Backs

By default, the program looks for files named back.png, back.jpg, etc. for card backs. You can customize this with:

1. The BackFileKey option to specify a different base name
2. The BackPatterns option to match specific fronts with specific backs

Back Patterns

The BackPatterns option allows you to define regular expression patterns to match front card filenames with specific back filenames:

BackPatterns=[(.*creature.*);"creature_back",(.*spell.*);"spell_back"]

This example would match any filename containing "creature" with "creature_back" and any filename containing "spell" with "spell_back".

Front/Back Card Pairing

The program automatically tries to match images whose names only differ by ending in "front" and "back". This is useful for card games where each card has unique front and back artwork, stored as separate image files.

Example:

• With files "spell-front.png" and "spell-back.png"
• The program will create one card with "spell-front.png" as the front and "spell-back.png" as the back

Advanced Usage

Reading from ZIP Files

You can directly process cards from a ZIP file:

o.SourcePath = @"path\to\your\cards.zip";

Separation Strategies

You can control how cards are organized in the output:

• Continuous: All cards in a single continuous PDF
• SeparatePages: Each directory of cards starts on a new page
• SeparateFiles: Each directory of cards goes to a separate PDF file

PNG Output

CardPrintLayouter supports generating PNG images instead of PDFs. Simply set the OutputFilename to have a .png extension. When PNG format is used:

• Each page is generated as a separate PNG file
• Files are named with the format {Filename}{pageNo}.png (e.g., cards1.png, cards2.png, etc.)
• Images are generated at 300 DPI for high-quality output
• This is useful for web display, digital prototyping, or when you need individual page images

Example:

using var generator = new CardPdfGenerator(o => { o.SourcePath = @"C:\Cards"; o.OutputFilename = "cards.png"; // Will generate cards1.png, cards2.png, etc. }); generator.Generate();

Examples

Basic Configuration

using var generator = new CardPdfGenerator(o => { o.SourcePath = @"C:\Cards"; o.CardWidthMM = 63; o.CardHeightMM = 88; o.PageSize = PageSizes.A4; }); generator.Generate();

Adding Bleed to Cards

using var generator = new CardPdfGenerator(o => { o.SourcePath = @"C:\Cards"; o.BleedStrategy = BleedStrategy.Add; o.BleedXMM = 3; o.BleedYMM = 3; }); generator.Generate();

Generating Separate Files

using var generator = new CardPdfGenerator(o => { o.SourcePath = @"C:\Cards"; o.SeparationStrategy = SeparationStrategy.SeparateFiles; }); generator.Generate();

Requirements

• .NET 6.0 or higher

License

This project uses QuestPDF with the Community License.