Coordinate Space Conversions

By specification, PDF documents have their own coordinate space, which is different from the coordinate space used by many image formats and graphical interfaces. While other formats have their origin in the top-left corner, with y coordinates increasing in a downward direction, the y coordinates in PDF documents increase upward, starting in the bottom-left corner.

Additionally, the PDF coordinate space can be offset from the visible bottom-left corner of a page due to a crop box, and it can also be rotated due to the page being rotated. This is efficient because it means cropping or rotating a page is just setting a value: You don’t need to change the content stream or any of the annotations on the page. However, this can also be confusing to work with. Therefore, PSPDFKit exposes a normalized page coordinate space, which always puts the origin in the bottom-left corner of the visible area of the page.

PSPDFKit provides an easy-to-use API for transforming between the PDF coordinate space and other coordinate spaces. For example, the following code uses the PSPDFKit conversion API to retrieve the non-normalized, top-left origin coordinate space representation of a page size:

PdfDocument document = ...
int pageIndex = 0;
Rect boundingBox = document.getPage(0).getPageInfo().getBoundingBox();

// Bounding box without crop box or rotation considered. The origin is set at the top-left corner of the box.
Rect rawBoundingBox = document.getProjection().toRawRect(boundingBox, pageIndex);

See the PdfProjection API for more information.

How to Convert between Raster Image Pixels and Points

The concept of resolution does not apply to PDF documents unless they have been converted into raster images, i.e. images whose dimensions are expressed in pixels. The default unit PSPDFKit returns for page sizes is the point, which is easily converted into inches by considering the fact that 1 inch is equal to 72 points. Inch separation results from dividing the size in points of a particular page by 72. Resolution, expressed in DPI (dots per inch), is thus the result of dividing the page size in points by the inch separation. To summarize, these are the relations you have to consider when you need to convert between points/inches and pixels in PDF:

1 inch = 72 points
Inch separation = points / 72
DPI (resolution) = pixels / inch separation

Note that, since PDF 1.6, the relationship between inches and points may be specified as greater than 1⁄72 by means of the UserUnit entry of the page dictionary. See table 30 on page 79 of the PDF 1.7 specification for more information.