Chapter 3
Pages

cpdf -scale-page "<scale x> <scale y>" [-fast] in.pdf [<range>] -o out.pdf

cpdf -scale-to-fit "<x size> <y size>" [-fast]
     [-scale-to-fit-scale <scale>]
     in.pdf [<range>] -o out.pdf

cpdf -scale-contents [<scale>] [<position>] [-fast]
     in.pdf [<range>] -o out.pdf

cpdf -shift "<shift x> <shift y>" [-fast] in.pdf [<range>] -o out.pdf

cpdf -rotate <angle> in.pdf [<range>] -o out.pdf

cpdf -rotateby <angle> in.pdf [<range>] -o out.pdf

cpdf -upright [-fast] in.pdf [<range>] -o out.pdf

cpdf -rotate-contents <angle> [-fast] in.pdf [<range>] -o out.pdf

cpdf -hflip [-fast] in.pdf [<range>] -o out.pdf

cpdf -vflip [-fast] in.pdf [<range>] -o out.pdf

cpdf -mediabox "<x> <y> <w> <h>" in.pdf [<range>] -o out.pdf

cpdf -cropbox "<x> <y> <w> <h>" in.pdf [<range>] -o out.pdf

cpdf -remove-cropbox in.pdf [<range>] -o out.pdf

(Also bleed, art, and trim versions of these two commands, for example -artbox, -remove-trimbox)

cpdf -frombox <boxname> -tobox <boxname> [-mediabox-if-missing]
     in.pdf [<range>] -o out.pdf

cpdf -hard-box <boxname> [-fast] in.pdf [<range>]
     [-mediabox-if-missing] -o out.pdf

cpdf -show-boxes [-fast] in.pdf [<range>] -o out.pdf

cpdf -trim-marks [-fast] in.pdf [<range>] -o out.pdf

3.1 Page Sizes

Any time when a page size is required, instead of writing, for instance "210mm 197mm" one can instead write a4portrait. Here is a list of supported page sizes:

aa03ppoorrttrraaiitt        aa14ppoorrttrraaiitt          aa25ppoorrttrraaiitt
a6portrait        a7portrait          a8portrait
a9portrait        a10portrait

a0landscape       a1landscape         a2landscape
a3landscape       a4landscape         a5landscape
a6landscape       a7landscape         a8landscape
a9landscape       a10landscape

uusslleetgtaelrppoorrttrraaiitt  uusslleetgtaelrllaannddssccaappee

3.2 Scale Pages

The -scale-page operation scales each page in the range by the X and Y factors given. This scales both the page contents, and the page size itself. It also scales any Crop Box and other boxes (Art Box, Trim Box etc). As with several of these commands, remember to take into account any page rotation when considering what the X and Y axes relate to.

cpdf -scale-page "2 2" in.pdf -o out.pdf

Convert an A4 page to A2, for instance.

The -scale-to-fit operation scales each page in the range to fit a given page size, preserving aspect ratio and centering the result.

cpdf -scale-to-fit "297mm 210mm" in.pdf -o out.pdfcpdf -scale-to-fit a4portrait in.pdf -o out.pdf

Scale a file’s pages to fit A4 portrait.

The scale can optionally be set to a percentage of the available area, instead of filling it.

cpdf -scale-to-fit a4portrait -scale-to-fit-scale 0.9 in.pdf -o out.pdf

Scale a file’s pages to fit A4 portrait, scaling the page 90% of its possible size.

NB: -scale-to-fit operates with respect to the media box not the crop box. If necessary, set the media box to be equal to the crop box first. In addition, -scale-to-fit presently requires that the origin of the media box be (0, 0). This can be assured by preprocessing with -upright (described elsewhere in this chapter).

The -scale-contents operation scales the contents about the center of the crop box (or, if absent, the media box), leaving the page dimensions (boxes) unchanged.

cpdf -scale-contents 0.5 in.pdf -o out.pdf

Scale a file’s contents on all pages to 50% of its original dimensions.

To scale about a point other than the center, one can use the positioning commands described in Section 8.2.4. For example:

cpdf -scale-contents 0.5 -topright 20 in.pdf -o out.pdf

Scale a file’s contents on all pages to 50% of its original dimensions about a point 20pts from its top right corner.

3.3 Shift Page Contents

The -shift operation shifts the contents of each page in the range by X points horizontally and Y points vertically.

cpdf -shift "50 0" in.pdf even -o out.pdf

Shift pages to the right by 50 points (for instance, to increase the binding margin).

3.4 Rotating Pages

There are two ways of rotating pages: (1) setting a value in the PDF file which asks the viewer (e.g. Acrobat) to rotate the page on-the-fly when viewing it (use -rotate or -rotateby) and (2) actually rotating the page contents and/or the page dimensions (use -upright (described elsewhere in this chapter) afterwards or -rotate-contents to just rotate the page contents).

The possible values for -rotate and -rotate-by are 0, 90, 180 and 270, all interpreted as being clockwise. Any value may be used for -rotate-contents.

The -rotate operation sets the viewing rotation of the selected pages to the absolute value given.

cpdf -rotate 90 in.pdf -o out.pdf

Set the rotation of all the pages in the input file to ninety degrees clockwise.

The -rotateby operation changes the viewing rotation of all the given pages by the relative value given.

cpdf -rotateby 90 in.pdf -o out.pdf

Rotate all the pages in the input file by ninety degrees clockwise.

The -rotate-contents operation rotates the contents and dimensions of the page by the given relative value.

cpdf -rotate-contents 90 in.pdf -o out.pdf

Rotate all the page contents in the input file by ninety degrees clockwise. Does not change the page dimensions.

The -upright operation does whatever combination of -rotate and -rotate-contents is required to change the rotation of the document to zero without altering its appearance. In addition, it makes sure the media box has its origin at (0,0), changing other boxes to compensate. This is important because some operations in CPDF (such as scale-to-fit), and in other PDF-processing programs, work properly only when the origin is (0, 0).

cpdf -upright in.pdf -o out.pdf

Make pages upright.

3.5 Flipping Pages

The -hflip and -vflip operations flip the contents of the chosen pages horizontally or vertically. No account is taken of the current page rotation when considering what ”horizontally” and ”vertically” mean, so you may like to use -upright (see above) first.

cpdf -hflip in.pdf even -o out.pdf

Flip the even pages in in.pdf horizontally.

cpdf -vflip in.pdf -o out.pdf

Flip all the pages in in.pdf vertically.

3.6 Boxes and Cropping

All PDF files contain a media box for each page, giving the dimensions of the paper. To change these dimensions (without altering the page contents in any way), use the -mediabox operation.

cpdf -mediabox "0pt 0pt 500pt 500pt" in.pdf -o out.pdf

Set the media box to 500 points square.

The four numbers are minimum x, minimum y, width, height. x coordinates increase to the right, y coordinates increase upwards. PDF file can also optionally contain a crop box for each page, defining to what extent the page is cropped before being displayed or printed. A crop box can be set, changed and removed, without affecting the underlying media box. To set or change the crop box use -cropbox. To remove any existing crop box, use -remove-cropbox.

cpdf -cropbox "0pt 0pt 200mm 200mm" in.pdf -o out.pdf

Crop pages to the bottom left 200-millimeter square of the page.

cpdf -remove-cropbox in.pdf -o out.pdf

Remove cropping.

Note that the crop box is only obeyed in some viewers. Similar operations are available for the bleed, art, and trim boxes (-art, -remove-bleed etc.)

cpdf -frombox <boxname> -tobox <boxname> [-mediabox-if-missing]
     in.pdf [<range>] -o out.pdf

Copy the contents of one box to another.

This operation copies the contents of one box (Media box, Crop box, Trim box etc.) to another. If -mediabox-if-missing is added, the media box will be substituted when the ’from’ box is not set for a given page. For example

cpdf -frombox /TrimBox -tobox /CropBox in.pdf -o out.pdf

copies the Trim Box of each page to the Crop Box of each page. The possible boxes are /MediaBox, /CropBox, /BleedBox, /TrimBox, /ArtBox.

A hard box (one which clips its contents by inserting a clipping rectangle) may be created with the -hard-box operation:

cpdf -hard-box /TrimBox in.pdf -o out.pdf

This means the resultant file may be used as a stamp without contents outside the given box reappearing. The -mediabox-if-missing option may also be used here.

3.7 Showing Boxes and Printer’s Marks

The -show-boxes operation displays the boxes present on each page as method of debugging. Since boxes may be coincident, they are shown in differing colours and dash patterns so they may be identified even where they overlap. The colours are:

M ed ia box  Red
Cropb ox   Green
Artbox     Blue
Trim box    Orange
Bleed box   Pink

The -trim-marks operation adds trim marks to a PDF file. The trim box must be present.

JavaScript Interface

 
// CHAPTER 3. Pages 
 
/** Scales the page dimensions and content by the given scale, about (0, 0). 
Other boxes (crop etc. are altered as appropriate) 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} sx x scale 
@arg {number} sy y scale */ 
function scalePages(pdf, range, sx, sy) {} 
 
/** Scales the content to fit new page dimensions (width x height) multiplied 
by scale (typically 1.0). Other boxes (crop etc. are altered as appropriate). 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} sx x scale 
@arg {number} sy y scale 
@arg {number} scale scale */ 
function scaleToFit(pdf, range, sx, sy, scale) {} 
 
/** A0 Portrait paper */ 
var a0portrait = 0; 
 
/** A1 Portrait paper */ 
var a1portrait = 1; 
 
/** A2 Portrait paper */ 
var a2portrait = 2; 
 
/** A3 Portrait paper */ 
var a3portrait = 3; 
 
/** A4 Portrait paper */ 
var a4portrait = 4; 
 
/** A5 Portrait paper */ 
var a5portrait = 5; 
 
/** A0 Landscape paper */ 
var a0landscape = 6; 
 
/** A1 Landscape paper */ 
var a1landscape = 7; 
 
/** A2 Landscape paper */ 
var a2landscape = 8; 
 
/** A3 Landscape paper */ 
var a3landscape = 9; 
 
/** A4 Landscape paper */ 
var a4landscape = 10; 
 
/** A5 Landscape paper */ 
var a5landscape = 11; 
 
/** US Letter Portrait paper */ 
var usletterportrait = 12; 
 
/** US Letter Landscape paper */ 
var usletterlandscape = 13; 
 
/** US Legal Portrait paper */ 
var uslegalportrait = 14; 
 
/** US Legal Landscape paper */ 
var uslegallandscape = 15; 
 
/** Scales the page content to fit the given page size, possibly multiplied by 
scale (typically 1.0) 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {"paper size"} papersize paper size 
@arg {number} s scale */ 
function scaleToFitPaper(pdf, range, papersize, s) {} 
 
/** Positions on the page. Used for scaling about a point, and adding text. 
 
A position is an anchor and zero or one or two parameters. 
 
posCentre: Two parameters, x and y<br/> 
posLeft: Two parameters, x and y<br/> 
posRight: Two parameters, x and y<br/> 
top: One parameter - distance from top<br/> 
topLeft: One parameter - distance from top left<br/> 
topRight: One parameter - distance from top right<br/> 
left: One parameter - distance from left middle<br/> 
bottomLeft: One parameter - distance from bottom left<br/> 
bottom: One parameter - distance from bottom<br/> 
bottomRight: One parameter - distance from bottom right<br/> 
right: One parameter - distance from right<br/> 
diagonal: Zero parameters<br/> 
reverseDiagonal: Zero parameters */ 
 
/** Absolute centre */ 
var posCentre = 0; 
 
/** Absolute left */ 
var posLeft = 1; 
 
/** Absolute right */ 
var posRight = 2; 
 
/** The top centre of the page */ 
var top = 3; 
 
/** The top left of the page */ 
var topLeft = 4; 
 
/** The top right of the page */ 
var topRight = 5; 
 
/** The left hand side of the page, halfway down */ 
var left = 6; 
 
/** The bottom left of the page */ 
var bottomLeft = 7; 
 
/** The bottom middle of the page */ 
var bottom = 8; 
 
/** The bottom right of the page */ 
var bottomRight = 9; 
 
/** The right hand side of the page, halfway down */ 
var right = 10; 
 
/** Diagonal, bottom left to top right */ 
var diagonal = 11; 
 
/** Diagonal, top left to bottom right */ 
var reversediagonal = 12; 
 
/** Scales the contents of the pages in the range about the point given by 
the position, by the scale given. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {anchor} anchor anchor to scale contents about 
@arg {number} p1 position argument 1 
@arg {number} p2 position argument 2 
@arg {number} scale scale */ 
function scaleContents(pdf, range, anchor, p1, p2, scale) {} 
 
/** Shifts the content of the pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} dx x shift 
@arg {number} dy y shift */ 
function shiftContents(pdf, range, dx, dy) {} 
 
/** Changes the viewing rotation to an absolute value. Appropriate rotations 
are 0, 90, 180, 270. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} rotation rotation */ 
function rotate(pdf, range, rotation) {} 
 
/** Rotates the content about the centre of the page by the given number of 
degrees, in a clockwise direction. Appropriate rotations 
are 0, 90, 180, 270. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} rotation rotation */ 
function rotateBy(pdf, range, rotation) {} 
 
/** Rotates the content about the centre of the page by the given number of 
degrees, in a clockwise direction. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} angle angle */ 
function rotateContents(pdf, range, angle) {} 
 
/** Changes the viewing rotation of the pages in the range, counter-rotating 
the dimensions and content such that there is no visual change. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function upright(pdf, range) {} 
 
/** Flips horizontally the pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function hFlip(pdf, range) {} 
 
/** Flips vertically the pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function vFlip(pdf, range) {} 
 
/** Crops a page, replacing any existing crop box. The dimensions are in 
points. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {number} x x position 
@arg {number} y y position 
@arg {number} w width 
@arg {number} h height */ 
function crop(pdf, range, x, y, w, h) {} 
 
/** Removes any crop box from pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function removeCrop(pdf, range) {} 
 
/** Removes any trim box from pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function removeTrim(pdf, range) {} 
 
/** Removes any art box from pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function removeArt(pdf, range) {} 
 
/** Removes any bleed box from pages in the range. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function removeBleed(pdf, range) {} 
 
/** Adds trim marks to the given pages, if the trimbox exists. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function trimMarks(pdf, range) {} 
 
/** Shows the boxes on the given pages, for debug. 
@arg {pdf} pdf PDF document 
@arg {range} range page range */ 
function showBoxes(pdf, range) {} 
 
/** Makes a given box a hard box i.e clips it explicitly. 
@arg {pdf} pdf PDF document 
@arg {range} range page range 
@arg {string} boxname box name */ 
function hardBox(pdf, range, boxname) {}