A4 QR Code Sheet Generator

A containerized tool for generating A4 printable sheets containing a grid of 4x5 cm (width x height) rectangles with cutting lines, featuring 3x3 cm QR codes and labels in the Roboto Mono font. The text labels are sized to match the 3 cm width of the QR code when the text contains exactly 10 characters.

---

💡 Why is this useful?

QR codes are highly machine-readable and easily recognized in photographs, even at various angles, lighting conditions, or distances. This tool is perfect for creating labels to tag physical assets, locations, or items.

Real-world Use Case Example: Imagine you need to track gas meters across multiple properties:

1. Generate a QR code with the value cow13gas (standing for "Cowbridge Rd 13, gas meter").
2. Print and place this QR code next to the physical gas meter.
3. When technicians take photos of the gas meter and upload them, you can programmatically or visually filter the photo gallery to quickly select all photographs of that specific gas meter simply by detecting the QR code.

---

🛠️ Data Persistence Design

To keep the environment clean and light, this project strictly defines what data persists:

Data Type	Location	Persistence	Description
Input Values	values.txt	Persistent (Host)	File where you enter your alphanumeric values to be encoded.
Generated PDF	output/qrcodes.pdf	Persistent (Host)	The resulting A4 PDF containing the printable grid.
QR Code Images	output/qrcodes/*.png	Persistent (Host)	High-resolution PNG files for individual QR codes.
TeX Template	Inside Container	Ephemeral	The Jinja2 LaTeX template used for layout.
TeX Auxiliary Files	/tmp/qr_build (Container)	Ephemeral	Intermediate files (.aux, .log, .tex) are discarded after compilation.

---

🚀 Getting Started

1. Build and Start the Container

Start the generator container in the background:

docker compose up -d

2. Enter Your Values

The generator reads values from values.txt. If the file doesn't exist, it will be automatically created on the first execution with a helper description and a ruler to help you measure the 10-character limit.

You can also create it manually:

# Enter alphanumeric values not exceeding 10 characters, one per line.
# Blank lines and lines starting with '#' are ignored.
#
# Use this 10-character ruler as a reference:
# ----------
cow13gas
A1B2C3D4E5

3. Generate QR Codes and A4 Sheet

Run the generator script inside the running container:

docker compose exec generator generate

Once execution completes, you will find:

• output/qrcodes.pdf: The ready-to-print A4 sheet with cutting lines.
• output/qrcodes/: A folder containing the individual high-resolution QR code images.

---

⚠️ Validation & Error Handling

• 10-Character Limit: Any value exceeding 10 characters, or containing non-alphanumeric characters, will print an error message at the end of execution. The script will still generate QR codes and the A4 PDF for all other valid values, but it will exit with a non-zero error code (1) to notify you.
• QR Code Versioning: The generator uses a Version 1 (21x21 modules) QR code with Level H (highest) error correction by default. Lowercase values (e.g. cow13gas) require Binary/Byte mode instead of Alphanumeric mode. If a value does not fit into Version 1, the generator automatically upgrades it to Version 2 or 3 and prints a warning to inform you.

---

⚙️ Regenerating Examples

If you modify examples/example-values.txt and want to update the example PDF and PNG files, a Makefile is provided in the root directory to automate this process:

# Regenerate example-qrcodes.pdf and example-qrcodes.png
make

# Clean generated example files
make clean

Note

The Makefile rule runs a fail-safe script that safely backups your current values.txt input, copy-swaps the example inputs, runs the container generation task, and automatically restores your original values.txt upon completion or script failure.

---

💻 Tech Stack

This tool relies on a lightweight, containerized stack designed for reliability and reproducible builds:

• Base OS: debian:trixie-slim
• Programming Language: Python 3
• Core Python Libraries:
  • qrcode & Pillow for generating high-resolution QR codes (with customizable parameters).
  • jinja2 for formatting variables into LaTeX source templates.
• PDF Compiler: XeLaTeX (provided by TeX Live) for robust path-based loading of TrueType fonts and precise page geometry.
• Typography: Roboto Mono (TrueType monospace font)

---

📷 Example Output

Here is the A4 sheet generated from the inputs in examples/example-values.txt:

Disclaimer

This project was entirely vibe-coded with Gemini 3.5 Flash (high thinking effort setting). See prompt.txt.