QRStamp

Batch PDF generator with embedded QR codes from SVG templates. Perfect for creating tickets, labels, certificates, or any document that needs unique QR codes.

QRStamp stamps QR codes onto your designs efficiently and beautifully.

Features

• Batch processing - Generate hundreds of PDFs with unique QR codes in seconds
• PDF/A conversion - Automatic conversion to PDF/A-1b format with linearization for archival and fast web viewing
• SVG templates - Use your existing designs from Illustrator, Figma, or any vector tool
• Precise positioning - Control exact QR code placement and size
• Flexible scaling - Output PDFs at any size (A4, letter, custom dimensions)
• Vector quality - All QR codes remain crisp and scalable
• Simple CLI - Easy to use command-line interface with sensible defaults

Requirements

• Python 3.7 or higher
• Cairo library (system dependency)
• Ghostscript (for PDF/A conversion)

Installation

Step 1: Install System Dependencies

macOS:

brew install cairo ghostscript

Ubuntu/Debian:

sudo apt-get install libcairo2-dev ghostscript

Windows:

• Cairo: Download GTK+ runtime from https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
• Ghostscript: Download from https://www.ghostscript.com/download/gsdnld.html

Step 2: Create a Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

Step 3: Install Python Dependencies

pip install -r requirements.txt

Or install dependencies directly:

pip install qrcode[pil] cairosvg

Usage

Quick Start (Recommended)

Use the provided run script that handles environment setup automatically:

./run.sh --list list.txt --x 100 --y 200 --size 200

Manual Usage

If you prefer to run the script directly:

On macOS:

source venv/bin/activate
export DYLD_LIBRARY_PATH="/opt/homebrew/opt/cairo/lib:$DYLD_LIBRARY_PATH"
python pdf-qrcode.py --list list.txt --x 100 --y 200 --size 200

On Linux:

source venv/bin/activate
python pdf-qrcode.py --list list.txt --x 100 --y 200 --size 200

On Windows:

venv\Scripts\activate
python pdf-qrcode.py --list list.txt --x 100 --y 200 --size 200

Command Line Options

Option	Default	Description
--list	list.txt	Path to text file containing URLs/codes
--template	template.svg	Path to SVG template file
--x	100	X position for QR code
--y	200	Y position for QR code
--size	200	Size of QR code in pixels
--color	#000000	QR code color in hex format (e.g., #FF0000 for red)
--width	(auto)	Target PDF width in mm (height calculated proportionally)
--height	(auto)	Target PDF height in mm (width calculated proportionally)
--output	output	Output directory for generated PDFs
--prefix	qr_	Prefix for output filenames
--keep-svg	false	Keep intermediate SVG files
--no-pdfa	false	Skip automatic PDF/A conversion

Examples

Basic generation with default settings:

./run.sh
# Uses list.txt and template.svg with default position/size

Custom position and size:

./run.sh --x 50 --y 150 --size 180

Custom PDF dimensions (A4 size - 210mm x 297mm):

./run.sh --width 210 --height 297

Scale PDF to specific height (width calculated proportionally):

./run.sh --height 150

Custom template and output directory:

./run.sh --list codes.txt --template custom.svg --output pdfs/

Keep SVG files and use custom prefix:

./run.sh --keep-svg --prefix ticket_

Colored QR codes (use quotes to escape #):

./run.sh --color "#FF0000"  # Red QR code
./run.sh --color "#0066CC"  # Blue QR code
./run.sh --color "2ECC40"   # Green (# is optional)

Skip PDF/A conversion:

./run.sh --no-pdfa  # Only generate regular PDFs

List File Format

The list file supports two formats:

Format 1: Numbered URLs (with arrow separator)

1→https://example.com/page1
2→https://example.com/page2
3→https://example.com/page3

Format 2: Plain URLs (one per line)

https://example.com/page1
https://example.com/page2
https://example.com/page3

Template File

Your SVG template should be a valid SVG file. The script will:

1. Load the template
2. Generate a QR code for each URL
3. Embed the QR code at the specified position
4. Convert the result to PDF

Example template structure:

<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 500 400">
  <!-- Your design here -->
  <rect fill="#fff" width="500" height="400"/>
  <text x="250" y="50" text-anchor="middle">My Certificate</text>
  <!-- QR code will be inserted at specified x,y position -->
</svg>

Output

The script generates:

• Regular PDFs in the output directory (e.g., output/qr_001.pdf, output/qr_002.pdf)
• PDF/A files in the pdfa subdirectory (e.g., output/pdfa/qr_001.pdf) - automatically created unless --no-pdfa is used
• Optional SVG files if --keep-svg is used
• Progress information during generation

PDF/A Format

PDF/A-1b is an ISO-standardized version of PDF specialized for digital archiving. The generated PDF/A files include:

• Archival compliance - Long-term document preservation
• Linearization - Fast web viewing ("fast web view")
• Embedded fonts - Guaranteed rendering consistency
• Color management - Consistent color reproduction

Use PDF/A files when you need:

• Long-term document storage
• Regulatory compliance
• Fast loading for web distribution
• Maximum compatibility across systems

Finding the Right Position

To find the best position for your QR code:

1. Open your template SVG in a vector editor (Inkscape, Illustrator, etc.)
2. Note the coordinate system (viewBox dimensions)
3. Position a test rectangle where you want the QR code
4. Use those coordinates for --x and --y parameters
5. Adjust --size to fit your design

Alternatively, run the script with --keep-svg and check the generated SVG files to fine-tune the position.

Advanced Usage

Convert Existing PDFs to PDF/A

If you already have PDFs and want to convert them to PDF/A:

python convert-to-pdfa.py --input output

Options for convert-to-pdfa.py:

• --input - Input directory with PDF files (default: output)
• --output - Output directory for PDF/A files (default: input/pdfa)
• --pattern - File pattern to match (default: *.pdf)
• --no-linearize - Disable PDF linearization

Troubleshooting

"no library called cairo was found"

• Cairo system library is not installed. Follow Step 1 in the Installation section
• On macOS: brew install cairo
• On Ubuntu/Debian: sudo apt-get install libcairo2-dev
• After installing Cairo, reinstall the Python dependencies: pip install --force-reinstall cairocffi cairosvg

"Ghostscript not found" or PDF/A conversion fails

• Ghostscript is not installed
• On macOS: brew install ghostscript
• On Ubuntu/Debian: sudo apt-get install ghostscript
• Alternatively, use --no-pdfa to skip PDF/A conversion

"Template file not found"

• Ensure template.svg exists in the current directory, or specify the correct path with --template

"No URLs found in list file"

• Check your list file format
• Ensure URLs are not empty or commented out

"Error converting to PDF"

• Ensure cairosvg is installed correctly
• Check that your SVG template is valid
• Try generating with --keep-svg to inspect the intermediate SVG

QR code not visible in output

• Adjust --x and --y to position within your template's viewBox
• Increase --size if the QR code is too small
• Check that the QR code isn't behind other elements (z-order)

License

MIT