pdf-reframe

pdf-reframe changes PDF page dimensions without scaling page content.

Padding is safe by default. If the requested target would crop any edge, the command stops unless --allow-crop is supplied explicitly. Every content transformation uses a scale matrix of exactly 1 x 1.

Installation

From a checkout:

python3 -m pip install .

For development:

python3 -m pip install -e .

Examples

Center pages that fit within US Letter:

pdf-reframe input.pdf output.pdf --target letter

Use the source MediaBox rather than the default CropBox:

pdf-reframe input.pdf output.pdf \
  --target letter \
  --source-box media

Inspect a true A4-to-Letter conversion. This pads horizontally and crops vertically:

pdf-reframe a4.pdf letter.pdf \
  --target letter \
  --dry-run \
  --verbose

Authorize that crop:

pdf-reframe a4.pdf letter.pdf \
  --target letter \
  --allow-crop

Custom target sizes accept points, inches, millimetres, or centimetres:

pdf-reframe input.pdf output.pdf --target 8.5inx11in
pdf-reframe input.pdf output.pdf --target 210mmx297mm

Other useful options:

--align center|north|south|east|west|nw|ne|sw|se
--landscape
--pages 2,5-7
--overwrite
--verbose

Named target sizes currently include Letter, Legal, Tabloid, Ledger, Executive, and A0 through A6.

Safety behavior

• Scaling is never performed.
• Cropping requires --allow-crop.
• Existing output files require --overwrite.
• A dry run never writes an output.
• Pages containing annotations are refused because translating page content would leave annotation coordinates misaligned. They may be discarded explicitly with --drop-annotations.
• Rotated source pages are currently refused.

The selected source box is translated into a target page whose MediaBox, CropBox, TrimBox, BleedBox, and ArtBox all match the requested size.

Development

Run the standard-library test suite:

python3 -m unittest discover -s tests -v

The package uses a conventional src/ layout and exposes both:

pdf-reframe --help
python3 -m pdf_reframe --help

License

MIT