flexible_printer

Flexible printer prep for oversized images and PDFs.

This repository contains a small Codex skill plus a Python utility for preparing print-safe PDFs. It can:

• scale oversized PDF pages onto Letter or A4 without printer-driver clipping;
• tile very wide, tall, or high-resolution images across multiple paper sheets;
• generate a combined preview PNG that shows the sheet layout and paper gaps before printing;
• keep the source artwork centered when the image and sheet grid do not match exactly, leaving outer white margins instead of cropping.

The current default paper target is US Letter. A4 is also supported.

Examples

Wide Panorama, 2 x 1 Letter Landscape

Original:

Cut preview:

Generated PDF:

examples/outputs/wide-panorama-letter-2x1.pdf

Command:

python3 scripts/scale_pdf_to_paper.py \
  examples/originals/wide-panorama.png \
  examples/outputs/wide-panorama-letter-2x1.pdf \
  --paper letter \
  --orientation landscape \
  --margin-in 0 \
  --tile-grid 2x1 \
  --preview-png examples/previews/wide-panorama-letter-2x1-preview.png

8K Square Map, 3 x 3 Letter Landscape

Original:

Cut preview:

Generated PDF:

examples/outputs/world-map-letter-3x3.pdf

Command:

python3 scripts/scale_pdf_to_paper.py \
  examples/originals/world-map-8k.png \
  examples/outputs/world-map-letter-3x3.pdf \
  --paper letter \
  --orientation landscape \
  --margin-in 0 \
  --tile-grid 3x3 \
  --preview-png examples/previews/world-map-letter-3x3-preview.png

For a map with readable place labels, 3x3 is usually better than 2x2; it uses more paper but preserves detail. 2x3 can be a useful compromise for square images on landscape Letter sheets.

Install

Use Python 3.10 or newer. The script depends on PyMuPDF and Pillow.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Image Tiling

Use fixed grids when you know the desired layout:

python3 scripts/scale_pdf_to_paper.py input.png output.pdf \
  --paper letter \
  --orientation landscape \
  --margin-in 0 \
  --tile-grid 2x1 \
  --preview-png preview.png

Use --tile-grid auto to let the script choose a small grid that materially improves the print scale over one sheet:

python3 scripts/scale_pdf_to_paper.py input.png output.pdf \
  --paper letter \
  --orientation landscape \
  --margin-in 0.25 \
  --tile-grid auto \
  --max-tile-pages 9 \
  --preview-png preview.png

Notes:

• --paper letter uses 8.5 x 11 in.
• --orientation landscape makes each output page 11 x 8.5 in.
• --margin-in 0 creates PDF pages with artwork reaching the sheet edge in the file.
• Many home printers still have an unprintable physical margin. If you need a seamless join, print with --margin-in 0 and trim the inner paper edges after printing.

PDF Scaling

For an oversized PDF page, omit --tile-grid. Each source page is proportionally scaled and centered on one target paper sheet.

python3 scripts/scale_pdf_to_paper.py input.pdf output-letter.pdf \
  --paper letter \
  --orientation auto \
  --margin-in 0.25 \
  --preview-png output-letter-preview.png

This avoids relying on printer-driver "fit to page" behavior, which can clip oversized PDFs on some AirPrint/CUPS paths.

Connecting And Printing

This repository does not assume a specific printer. On macOS or Linux with CUPS:

1. Add the printer through the system print settings or CUPS.
2. Find the queue name:

lpstat -p -d
lpstat -v

3. Check current jobs:

lpstat -W not-completed -o

4. Print a prepared PDF without driver scaling:

lp -d YOUR_QUEUE_NAME \
  -o media=Letter \
  -o print-scaling=none \
  -o sides=one-sided \
  output.pdf

For A4, use --paper a4 when generating the PDF and pass the matching CUPS media option for your printer.

Before printing expensive or multi-page color jobs, inspect the preview PNG and PDF page count.

Codex Skill

The reusable skill lives in skill/SKILL.md. Install it into your Codex skills directory or copy the relevant workflow into an existing printer skill.

The public skill intentionally avoids local queue names, device UUIDs, IP addresses, and user-specific paths.

License

MIT. Example images are included only as demonstration assets; replace them with your own artwork when licensing matters.