PDF Page Coordinates
The starting point for positioning form fields and annotations using JavaScript
PDF page coordinates are measured in points. Since there are 72 points per inch, a regular 8.5" x 11" page is 612 points wide and 792 points high. To create a blank one-page PDF with JavaScript, use the app.newDoc method, which takes two optional input parameters:
nWidth, the page width in points.
nHeight, the page height in points.
If the parameters are omitted, the default values are 612 for nWidth and 792 for nHeight. Therefore, if you run the following script in the JavaScript console of Acrobat Pro it will produce a one-page 8.5" x 11" PDF:
app.newDoc();The following script (with input parameters) will produce the same result:
app.newDoc(612, 792);The following script (with named input parameters) will also produce the same result:
app.newDoc({nWidth: 612, nHeight: 792});So there are three ways to write the script that produce the same result. The first is the easiest.
You can also use math equations in your script to calculate the points like this:
app.newDoc(8.5*72, 11*72);Obviously you wouldn’t need to do calculations for creating this standard one-page PDF, but if you’re creating odd size pages you can save yourself the step of using a calculator to determine the coordinates by adding the calculations into your script and letting the JavaScript engine do them for you. This tip is helpful for positioning form fields and annotation markups that will be outlined in future posts.
Note that the file produced will have a random name and a .tmp (temporary) file extension until it is saved.
Take the Acrobat Pro JavaScript eLearning Course and Get One Year of Access to Several Acrobat Automation Tools
Obtaining Page Coordinates
PDF pages have different boundary boxes. To obtain the coordinates of a PDF page, use the doc.getPageBox method (doc is a variable representing the document object "this"). This method takes two optional input parameters:
cBox, the type of box. Options are: Art, Bleed, BBox, Crop (the default), and Trim.
nPage, the page number (page numbers are 0-based so 0 is page 1, 1 is page 2, etc.)
Full disclosure: For most PDF pages, all cBox types have the same coordinates, except BBox, which is mystery to me. I only ever use Crop and I don’t know much about the others, except for the fact they are used in graphic design and professional printing processes. If somebody wants to set me straight in the comment section, I welcome your insight.
If you created a one-page PDF with a script as described previously, and you run one of the following scripts in the console, it will return 0, 792, 612, 0 which is an array of crop box coordinates for page one:
this.getPageBox(); //OR
this.getPageBox("Crop",0);//OR
this.getPageBox({cBox:"Crop",nPage:0});Since the cBox default is Crop and the nPage default is 0, and they are both optional input parameters, if they are omitted they are assumed to be Crop and 0, the first page of the document. If you replace "Crop" with "Art", "Media", or "Bleed" in either of the scripts above and run the script it will also return 0, 792, 612, 0.
What Does This Array of Coordinates Represent?
The array represents a rectangle in rotated user space. A page can have a rotation (in degrees) of 0, 90, 180, or 270. 0 degrees is not rotated. Clockwise rotation by 90 degrees, in order, creates page rotations of 90, 180, and 270.
The first and last array elements will always be zero for the crop box, with the 2nd being the height, and the 3rd being the width. Starting with the left side of the box, or edge of the page and working clockwise, the array elements are left, top, right, bottom. Technically, the rectangle has two points: The top left, where the first and second array elements intersect (0 and 792 in our example), and bottom right, where the third and fourth array elements intersect (612 and 0 in our example). I find it easier to look at the array as left, top, right, bottom.
If the page has a rotation other than zero, it’s not the way the page views on the screen that represents the positions. For example, if the page has a rotation of 90 degrees, then it has been rotated 90 degrees clockwise. The left side of the page is now at the top and the top of the page is on the right. The right side of the page is at the bottom and the bottom is on the left. The first array element is still the left side of the page, but it’s showing at the top of the screen.
Some standard size PDF pages that are landscape view have crop box sizes of [0, 612, 792, 0] where the height is 8.5" and the width is 11.5", and the page has rotation of zero. Others have crop box sizes of [0, 792, 612, 0] where the height is 11" and the width is 8.5", but the page rotation is 90 degrees, as pictured above. This can get very confusing when attempting to place form fields and annotations on the page using JavaScript since the two pages with exact same content will look identical on the screen. The first zero-rotation example is the easiest to work with because you don’t have to adjust your script for page rotations.
More Confusion
Just to throw confusion fuel on the fire, when you convert a file from another program like Microsoft Word, Excel, Publisher, etc. you can end up with either result, depending the method used for the conversion. When using the document feeder with adjustable guides on a scanner to produce a PDF, you can end up with either result determined by whether you fed the pages vertically of horizontally. Both results will look identical on your screen but one will have zero page rotation and the other will have 90 or 270 degrees rotation.
Obtaining The Page Rotation
Run this simple line of code in the JavaScript Console, which takes one optional input parameter, the 0-based page number for which you want to obtain the rotation:
this.getPageRotation(1);The script above will return the rotation of page 2. If the nPage parameter is omitted it will return the rotation of the first page in the document (the default):
this.getPageRotation();If you need to check the pages of a multiple-page PDF for rotations other than zero you can run the following script in the console:
for(var i=0; i<this.numPages; i++)
{
console.println("Page "+ Number(i+1) + ":" + this.getPageRotation(i));
}In my next post I’ll discuss how to crop and reverse-crop using JavaScript. Thank you for reading.