Translation(s): none

An exploration of how pdftopdf treats rotation of pages in a PDF file. The focus is on pdftopdf's autorotation feature.


The purpose of most of this account is to examine and explain the treatment of what are often called portrait and landscape pages in a PDF file when they are handled by the filtering subsystem on a Debian 8 (jessie) and later CUPS printing system. On Debian 7 (wheezy) the page management of rotation by pdftopdf is significantly different.

Portrait and landscape are not clearly defined technical terms. Generally speaking, they refer to the way a rectangular object is normally orientated. Very often the orientation takes place when sense needs to be easily made of what the object displays. For example, an A4 sheet of paper with text parallel to the short edge would be held in portrait mode, short edge horizontal. With text parallel to the long edge, a 90 or 270 degree rotation would take the sheet to landscape mode for ease of reading. In other words, in this case, the ease of viewing criterion determines whether a printed page is designated portrait or landscape.

Portrait and landscape are conventions to describe what we see displayed. Beware of using the phrase "landscape printing". This openSUSE page explains why.

A PDF contains information about the dimensions of a page and any page rotation. The criterion for designating a PDF page as portrait or landscape is whether its width dimension is greater or less than its height dimension after any rotation has been taken into account. Whether or not a printout on paper is conveniently viewable with or without rotating the sheet is irrelevant.

The Role of pdftopdf

Printers, even modern IPP printers, have limitations. Overall, they cannot directly scale the text in a PDF, directly do N-up printing, directly rotate a page or directly use a specific font when printing a text file. It is not that they could not be manufactured to do such things; they just don't (in general).

So we need a filter, pdftopdf, to apply such options to a PDF file it receives. pdftopdf is a page management filter that handles a wide range of options, including ones that are specific to CUPS and cups-filters and others that are better not left to being dealt with by an an IPP printer. We will look at how it manages rotation of pages in a PDF file.

Portrait and Landscape Pages in a PDF

A PDF file with mixed orientation pages would be useful to have. mixed.pdf can be downloaded for you to use.

The file has three document pages. Information on each page can be displayed with pdfinfo:

pdfinfo -f 1 -l 3 mixed.pdf

For the first page:

Page    1 size: 595 x 842 pts (A4)
Page    1 rot:  0

The page width is less than its height; it is a portrait designed page. rot: 0 tells a PDF interpreter, pdftopdf in this instance, not to rotate the page. This indicates it is interpreted as a PDF portrait page.

The second page has:

Page    2 size: 841.89 x 595.28 pts (A4)
Page    2 rot:  0

This is a landscape designed page because its width is greater than its height. There is no rotation done by a PDF interpreter. It would be designated a PDF landscape page.


Page    3 size: 595 x 842 pts (A4)
Page    3 rot:  90

This is a portrait designed page but a PDF interpreter rotates it 90 degrees clockwise, making it a PDF landscape page.

Printing Portrait and Landscape Pages

Many printers take paper and feed it through the printer short edge first so that text is printed parallel to this edge. For suitably sized paper, page 1 should produce a satisfactory printout. On the other hand, pages 2 and 3 will probably have some part of the right-hand portion of the image not printed if they are sent as-is to the printer.

There are three solutions the printing system could adopt to overcome this problem.

  1. Rotate document pages 2 and 3 relative to the printer page before printing them. This is the solution adopted in cups-filters 1.28.7 and earlier.

  2. Redesign landscape pages to be portrait with text parallel to the long edge and zero rotation. That is, rotate the page content to fit on a PDF portrait page. This appears to be the technique used in cups-filters 1.28.12 and later.
  3. Alter the images of document pages 2 and 3 to make them fit the width of the medium they are being printed on.

In these three cases all pages remain or become PDF portrait pages, which makes them suitable to be sent to a printer that takes paper short edge first

pdftopdf and Autorotation

A good way to appreciate what pdftopdf does to fit an image on a page of paper is to use cupsfilter. A PPD file, test.ppd, is available for this test and later ones; or you can provide your own. The command to use only the pdftopdf filter is

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf mixed.pdf > out.pdf

mixed.pdf can be compared with out.pdf using a PDF viewer and it can be seen that pages 2 and 3 have been autorotated to fit the images on paper which goes through a printer short edge first.

For cups-filters 1.28.7 and earlier, let's see what pdfinfo reports for out.pdf and compare it with what was given for mixed.pdf:

Page    1 size: 595 x 842 pts (A4)
Page    1 rot:  0
Page    2 size: 841.89 x 595.28 pts (A4)
Page    2 rot:  270
Page    3 size: 595 x 842 pts (A4)
Page    3 rot:  0

Effectively, all pages have become PDF portrait pages. This makes them suitable to be sent to a printer that takes paper short edge first

Now for cups-filters 1.28.12 and later:

Page    1 size: 595 x 842 pts (A4)
Page    1 rot:  0
Page    2 size: 595 x 842 pts (A4)
Page    2 rot:  0
Page    3 size: 595 x 842 pts (A4)
Page    3 rot:  0

Once again, all pages have been converted to PDF portrait pages.

  • All print jobs sent from an application or via lp/lpr will undergo selective treatment of landscape pages by pdftopdf.
  • The autorotate feature is the only way a PDF with mixed orientation pages will be printed correctly when sent to a printer with lp/lpr or from some applications.

Edit test.ppd and alter the line with *LandscapeOrientation to read

*LandscapeOrientation: Minus90

and repeat the previous cupsfilter command. You should observe that the autorotation is now 90 degrees clockwise. Deleting or commenting out the line gives the same result.

Autorotation can be dispensed with by using -o nopdfAutoRotate-default or -o pdfAutoRotate-default=off when setting up a print queue or, on a job-to-job basis with lp/lpr, by -o nopdfAutoRotate or -o pdfAutoRotate=off. There is no way to turn it off from an application. Test with

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf -o nopdfAutoRotate mixed.pdf  > out.pdf
pdfinfo -f 1 -l 3 out.pdf

The landscape and orientation-requested Options

CUPS has a help page on Command-Line Printing and Options. It says there that

The -o landscape option will rotate the page 90 degrees....

The direction of rotation is governed by *LandscapeOrientation in the PPD file. Minus90 rotates all pages in a PDF file 90 degrees clockwise; Plus90 rotates by the same amount but anticlockwise. *LandscapeOrientation is part of Adobe's PostScript Printer Description File Format Specification.

For driverless printing, the CUPS and cups-filters PPD generators do not put a *LandscapeOrientation line in a PPD file. Autorotation will produce a 90 degree clockwise rotation of a PDF page.

On the same page we see:

The -o orientation-requested=N option rotates the page depending on the value of N:
-o orientation-requested=4 - landscape orientation (90 degrees)

However, the orientation-requested=4 option always rotates every page in a file in an anticlockwise sense. *LandscapeOrientation is not consulted by it. orientation-requested=N is an IPP attribute specified in rfc8011.

pdftopdf acts on the landscape and orientation-requested=N options whether or not autorotation (which is applied after either of these two options) is operative. The following command with *LandscapeOrientation as Plus90 in test.ppd might prove instructive with cups-filters 1.28.7 and earlier.

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf -o orientation-requested=4 mixed.pdf > out.pdf

pdfinfo -f 1 -l 3 out.pdf shows:

Page    1 size: 595 x 842 pts (A4)
Page    1 rot:  180
Page    2 size: 841.89 x 595.28 pts (A4)
Page    2 rot:  270
Page    3 size: 595 x 842 pts (A4)
Page    3 rot:  0

The fit-to-page Option

Suppose you want pages 2 and 3 of mixed.pdf to be printed with the text parallel to the short edge of the paper and also for them to fit on the sheet. Autorotation will have to be off for that.

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf -o 'fit-to-page nopdfAutoRotate' mixed.pdf > out.pdf

For fitting all pages on the sheet of paper and having text parallel to its long edge:

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf -o 'fit-to-page nopdfAutoRotate landscape' mixed.pdf > out.pdf

The Landscape and Portrait Options in Applications

The printing dialog of a graphical application usually offers Landscape and Portrait options. The meaning attached to these two words when printing can differ from what CUPS means and also have different meanings for different applications. Not only that, but Portrait and Landscape may be instructions to be acted on by the application and not the printing system.

For example, Okular and Qpdfview rely on the printing system to process their Portrait and Landscape options.

On the other hand:

Autorotation with pdftopdf still functions as usual no matter how the applications themselves deal with their Portrait and Landscape options. This could be a major factor in the decrease in bug reports involving applications and page rotation.

A pdftopdf Bonus

Very simply - try this:

/usr/sbin/cupsfilter -p test.ppd -m application/vnd.cups-pdf -o 'fit-to-page booklet' mixed.pdf > out.pdf

Available only through the PDF workflow.


Tobias Hoffmann <smilingthax SPAMFREE AT googlemail DOT com>, Till Kamppeter <till.kamppeter SPAMFREE AT gmail DOT com> and many others for writing and improving the pdftopdf filter.

See Also