pdftools.pdfposter¶

Scale and tile PDF images/pages to print on multiple pages.

pdfposter can be used to create a large poster by building it from multiple pages and/or printing it on large media. It expects as input a PDF file, normally printing on a single page. The output is again a PDF file, maybe containing multiple pages together building the poster. The input page will be scaled to obtain the desired size.

This is much like the well-known tool poster does for Postscript files, but working with PDF. Since sometimes poster does not like your files converted from PDF. :-) Indeed pdfposter was inspired by poster.

Download & Installation¶

Instructions for Windows Users¶

pdfposter requires Python. If you don’t have Python installed already, download and install Python 3.6 from https://python.org/download/3.6/

During installation, make sure to check “Include into PATH”.
If you already have Python installed, please check that your Python directory (normally C:\Python36 for python 3.6) and the Python Scripts directory (normally C:\Python36\Scripts) are in the system path. If not, just add them in My Computer ‣ Properties ‣ Advanced ‣ Environment Variables to the Path system variable.
Install pdfposter by running
```
pip install pdftools.pdfposter
```
Then run the console command pdfposter --help to get detailed help.

If the command pip is unknown to you system, please refer to the pip homepage for help.

Instructions for GNU/Linux and other Operating Systems¶

Most current GNU/Linux distributions provide packages for pdfposter. Simply search your distribution’s software catalog.

Also many vendors provide Python, and some even provide pdfposter. Please check your vendor’s software repository.

If your distribution or vendor does not provide a current version of pdfposter please read on.

If your vendor does not provide python please download Python 3.6 from https://www.python.org/download/ and follow the installation instructions there.

If you distribution or vendor missed providing pip, alongside python, please check your vendor’s or distribution’s software repository for a package called pip or python-pip. If this is not provided, please refer to the pip homepage for help.

Optionally you might want to install PyPDF2 - which is a requirement for pdfposter - provided by your distribution or vendor so at least this package will be maintained by your distribution. Check for a package named python-pypdf2 or that like.

Then continue with Installing pdfposter using pip below.

Installing pdfposter using pip¶

After installing Python (and optionally PyPDF2), just run:

sudo pip install pdftools.pdfposter

to install pdfposter for all users. For installing pdfposter for yourself only, run:

pip install --user pdftools.pdfposter

If your system does not have network access

download pdfposter from https://pypi.org/project/pdftools.pdfposter/,
downlaod PyPDF2 from https://pypi.org/project/PyPDF2/, and

run

sudo pip install pdftools.pdfposter-*.tar.gz PyPDF2-*.tar.gz

respective

pip install --user pdftools.pdfposter-*.tar.gz PyPDF2-*.tar.gz

Usage¶

pdfposter can be used to create a large poster by building it from multiple pages and/or printing it on large media. It expects as input a PDF file, normally printing on a single page. The output is again a PDF file, maybe containing multiple pages together building the poster. The input page will be scaled to obtain the desired size.

The program uses a simple but efficient method which is possible with PDF: All new pages share the same data stream of the scaled page. Thus resulting file grows moderately.

To control its operation, you need to specify either the size of the desired poster or a scale factor for the image:

Given the poster size, it calculates the required number of sheets to print on, and from that a scale factor to fill these sheets optimally with the input image.
Given a scale factor, it derives the required number of pages from the input image size, and positions the scaled image centered on this area.

Options¶

General Options¶

`-h, --help`	Show help message and exit
`--help-media-names`
	List available media and distance names and exit
`--help-box-definitions`
	Show help about specifying BOX for –media-size and –poster-size and exit
`--version`	Show program’s version number and exit
`-v, --verbose`	Be verbose. Tell about scaling, rotation and number of pages. Can be used more than once to increase the verbosity.
`-n, --dry-run`	Show what would have been done, but do not generate files.

Defining Input¶

`-f, --first`	First page to convert (default: first page).
`-l, --last`	Last page to convert (default: last page).
`-A, --art-box`	Use the content area defined by the ArtBox (default: use the area defined by the TrimBox)

Defining Output¶

`-m BOX, --media-size=BOX`
	Specify the desired media size to print on. See below for BOX. The default is A4 in the standard package.
`-p BOX, --poster-size=BOX`
	Specify the poster size. See below for BOX. pdfposter will autonomously choose scaling and rotation to best fit the input onto the poster (see EXAMPLES below). If you give neither the -s nor the -p option, the default poster size is identical to the media size.
`-s NUMBER`	Specify a linear scaling factor to produce the poster. Together with the input image size and optional margins, this induces an output poster size. So don’t specify both -s and -p. The scaling factor is applied to the width and height of the input image size. Thus, a scaling factor of 2 results in a poster 4 times the area compared to the original. Default is deriving the scale factor to fit a given poster size.

Box Definition¶

The BOX mentioned above is a specification of horizontal and vertical size. The syntax is as follows (with multiplier being specified optionally):

box = [ multiplier ] unit

multiplier = number “x” number

unit = medianame or distancename

Many international media names are recognised by the program, in upper and lower case, and can be shortened to their first few characters, as long as unique. For instance ‘A0’, ‘Let’. Distance names are like ‘cm’, ‘inch’, ‘ft’.

Medias are typically not quadratic but rectangular, which means width and height differ. Thus using media names is a bit tricky:

10x20cm:	obvious: 10 cm x 20 cm (portrait)
20x10cm:	same as 10x20cm, since all boxes are rotated to portrait format

Now when using media names it gets tricky:

1x1a4:

same as approx. 21x29cm (21 cm x 29 cm, portrait)

1x2a4:

same as approx. 21x58cm (21 cm x 58 cm, portrait)

This are two a4 pages put together at the small side: One portrait page wide and two portrait pages high.

2x1a4:

same as approx. 42x29cm, which is rotated to portrait and is (approx.) the same as 29x42cm (29 cm x 42 cm)

This are two a4 pages put together at the long side: Two portrait pages wide and one portrait page high.

Examples¶

These are some examples showing how to get a poster as you want.

pdfposter -mA3 -pA0 a4.pdf out.pdf:
	Prints an A4 input file on 8 A3 pages, forming an A0 poster.
pdfposter -p3x3Let a4.pdf out.pdf:
	Prints an inputfile on a poster of 3x3 Letter pages.

pdfposter -mA0 input.pdf out.pdf:
	Enlarges an inputfile to print on a large-media A0 capable device.
pdfposter -s4 input.pdf out.pdf:
	Enlarge an inputfile exactly 4 times, print on the default A4 media, and let `pdfposter` determine the number of pages required.

pdfposter -m10x10cm -pa0 a4.pdf out.pdf:
	Just to show how efficient `pdfposter` is: This will create a file containing 192 pages, but only 15 times as big as the single page. With a4.pdf being a quite empty page, this ratio should be even better for filled pages.

Examples for automatic scaling¶

For printing 2 portrait A4 pages high (approx. 58cm) and let pdfposter determine how many portrait pages wide, specify a large number of vertical pages. eg:

pdfposter -p999x2a4 testpage-wide.pdf out.pdf:
For printing 2 landscape A4 pages high (approx. 20cm) and let pdfposter determine how many landscape pages wide, specify a large number of horizontal pages. eg:

pdfposter -p2x999a4 testpage-wide.pdf out.pdf:

For these examples we use two input pages:

The tall example input page (5.0 cm x 27.9 cm)

The wide example input page (27.9 cm x 5.0 cm).

These are intentionally uncommon formats so the effects of running pdfposter will be more demonstrative.

Working With Portrait Images¶

Portrait images are higher than wide.

Tall test-page as poster: Two portrait pages wide and one portrait page high.

Example 1:

pdfposter -p 2x1a4 testpage-tall.pdf out.pdf

This are two a4 pages put together at the long side: Two portrait pages wide and one portrait page high.

Example 2:

pdfposter -p 1x2a4 testpage-tall.pdf out.pdf

This are two a4 pages put together at the small side: One portrait page wide and two portrait pages high.

Working With Landscape Images¶

Landscape images are wider than height.

Wide test-page as poster: Two portrait pages wide and one portrait page high.

Example 1:

pdfposter -p 2x1a4 testpage-wide.pdf out.pdf

This are two a4 pages put together at the long side: Two portrait pages wide and one portrait page high.

Example 2:

pdfposter -p 1x2a4 testpage-wide.pdf out.pdf

This are two a4 pages put together at the small side: One portrait page wide and two portrait pages high.

Donations¶

If you like pdfposter, please consider supporting me in some way.

Bank transfers

While PayPal donations are still very much appreciated PayPal takes a large cut and has rather questionable business practices.

If you have the ability to make SEPA bank transfers at a low cost (for example if you live within the EU) please contact Hartmut to ask for his bank details.

I trust in the power of free and open source software and thus made the entire source code publicly available for every one to use. However, it takes a lot of time to develop the software and manage the community. And I still need to make my living.

So, if you like the software, please consider donating, especially if your organization benefits from this project.

Thank you!

Bitcoin address

Bitcoin: 13qryeeJR5Hc7vR5AmQMWDuLzDEgSDNJi2
Bank-Transfer (prefered): If you have the ability to make SEPA bank transfers at a low cost please contact me and I’ll send you the account details. If you want a bill, please state so and also leave your name and address.
PayPal: Donate - if you want a bill, please state so and leave your name, address and email-address.
Please contact me to arrange some other kind of project grant, e.g. consulting or support.

Frequently Asked Questions¶

How can I suppress these superfluous empty pages?

Short Answer: Specify the desired output size using the same page-name as the medium-size:
```
pdfposter -mA5 -p2xA5 in.pdf out.pdf
```
Long Answer: If you are running:
```
pdfposter -mA5 -pA4 in.pdf out.pdf
```
you most probably expect the result to be 2 A5-pages large, but you will get three pages, where the third seams to be empty. (If you have a full-colored background, you will find a small line on the third page.)

And this is what went wrong:

In the command above, you say: “The output should be A4 sized”, while you mean: “The output should fit on two A5 pages”.

Basically you are right, if you say “hey, this ought to be the same!”. It is a scaling or rounding issue caused by ISO page sizes not scaling exactly (even as they should, see ISO 216). For example since A4 is 297 mm high, A5 should be 148.5 mm wide, but is only 148 mm wide.

So the solution is to specify on the command-line what you want: “should fit on two A5 pages”:
```
pdfposter -mA5 -p2xA5 in.pdf out.pdf
```
Are there other Python tools for manipulating PDF?

Yes, there are: * pdfnup * pdfsplit * pdfgrid

Changes¶

0.9 (unreleased)¶

Nothing changed yet.

0.8.1 (2022-11-04)¶

Fix box-scaling which was totally buggy in release 0.8 (and I wonder why nobody noticed).
Fix plural forms in info messages.

0.8 (2022-06-27)¶

Be less strict when reading PDF files.
Enhance some help messages.
Drop support for Python 2 and Python <= 3.5. Minimum supported versions are now 3.6 to 3.10.
Internal changes:
- Update required version of PyPDF to 2.1.1.
- Enhance code quality.

0.7 (2018-06-24)¶

Incompatible change: DIN lang and Envelope No. 10 are now defined as landscape formats.
New options -f/--first and -l/--last for specifying the first resp. last page to convert
Reduce the size of the output file a lot. Now the output file is nearly the same size as the input file. While this behaviour was intended from the beginning, it was not yet implemented for two reasons: The content was a) copied for each print-page and b) not compressed.
Make the content of each page appear only once in the output file. This vastly reduces the size of the output file.
Compress page content. Now the output file is nearly the same size as the input file in much more cases. I thought, the underlying library will do this automatically, but it does not.
Fix bug in PDF code used for clipping the page content. Many thanks to Johannes Brödel for reporting this bug.
Add support for Python 3.
Use PyPFDF2 instead of the unmaintained pyPDF.

0.6.0 (2013-05-21)¶

New option -A/--art-box to use the content area defined by the ArtBox instead of the TrimBox.
The page is now clipped to the TrimBox resp. ArtBox to ensure nothing outside of this box gets printed.
No longer set the CropBox, as this is interpreted quite differently by different renderers (even if the PDF 1.7 standard defines its behaviour).
Pages are now ordered top to bottom. This is a more natural for humans used to starting at the upper left. Thanks to Robert Schroll for the patch.
Smaller enhancements, e.g. more precise error massages, better error handling, etc.

0.5.0 (2009-04-20)¶

Fix source-distribution package: The Python source-files have been missing.

0.4.6 (2009-01-04)¶

Open PDF files in binary mode.
Fixes to the SConscript file.

…: Local Variables: mode: rst ispell-local-dictionary: “american” End:

Development¶

The source of pdfposter and its siblings is maintained at GitLab. Patches and pull-requests are hearty welcome.

Please submit bugs and enhancements to the Issue Tracker.
You may browse the code at the Repository Browser. Or you may check out the current version by running
```
git clone https://gitlab.com/pdftools/pdfposter.git
```

Historical Note: pdfposter was hosted at origo.ethz.ch, which closed in May 2012. Then pdfposter was hosted on gitorious.org, which was closed in May 2015 and merged into gitlab.