Coordinate Space Conversions

PDF documents have by specification their own coordinate space which is different from the coordinate space used by UIKit. While UIKit views have their origin in the top-left with y coordinates increasing downwards, the y coordinates in PDF documents increase upwards from the origin in the bottom-left.

PDF page coordinates

PSPDFKit provides a set of easy to use methods for transforming between PDF and view coordinate spaces. For example, following code uses the PSPDFKit conversion API to retrieve the on-screen coordinates of an annotation:

Copy
1
2
3
4
5
6
7
8
let pdfController: PSPDFViewController = ...
let annotation: PSPDFAnnotation = ...
if let pageView = pdfController.pageViewForPage(at: annotation.pageIndex) {
    // Get the PDF coordinates of the annotation.
    let annotationPDFRect = annotation.boundingBox
    // Convert the annotation’s PDF coordinates to view coordinates.
    let annotationViewRect = pageView.convertPDFRect(toViewRect: annotationPDFRect)
}
Copy
1
2
3
4
5
6
7
8
9
PSPDFViewController *pdfController = ...;
PSPDFAnnotation *annotation = ...;
PSPDFPageView *pageView = [pdfController pageViewForPage:annotation.pageIndex];
if (pageView) {
    // Get the PDF coordinates of the annotation.
    CGRect annotationPDFRect = annotation.boundingBox;
    // Convert the annotation’s PDF coordinates to view coordinates.
    CGRect annotationViewRect = [pageView convertPDFRectToViewRect:annotationPDFRect];
}

Conversion Methods

PSPDFPageView has a set of convenient methods for converting between PDF and view coordinates.

Copy
1
2
3
4
func convertPoint(toPDFPoint viewPoint: CGPoint) -> CGPoint
func convertPDFPoint(toViewPoint pdfPoint: CGPoint) -> CGPoint
func convertRect(toPDFRect viewRect: CGRect) -> CGRect
func convertPDFRect(toViewRect pdfRect: CGRect) -> CGRect
Copy
1
2
3
4
- (CGPoint)convertViewPointToPDFPoint:(CGPoint)viewPoint;
- (CGPoint)convertPDFPointToViewPoint:(CGPoint)pdfPoint;
- (CGRect)convertViewRectToPDFRect:(CGRect)viewRect;
- (CGRect)convertPDFRectToViewRect:(CGRect)pdfRect;

There are also conversion functions declared in PSPDFPageInfo. There is rarely a case where you need to use these functions, as the above methods on PSPDFPageView are better suited for most use cases. Use these functions only when you don't have any (page) views and still want to do PDF coordinate conversion.

Copy
1
2
3
4
func PSPDFConvertViewPointToPDFPoint(_ viewPoint: CGPoint, _ cropBox: CGRect, _ rotation: UInt, _ bounds: CGRect) -> CGPoint
func PSPDFConvertPDFPointToViewPoint(_ pdfPoint: CGPoint, _ cropBox: CGRect, _ rotation: UInt, _ bounds: CGRect) -> CGPoint
func PSPDFConvertPDFRectToViewRect(_ pdfRect: CGRect, _ cropBox: CGRect, _ rotation: UInt, _ bounds: CGRect) -> CGRect
func PSPDFConvertViewRectToPDFRect(_ viewRect: CGRect, _ cropBox: CGRect, _ rotation: UInt, _ bounds: CGRect) -> CGRect
Copy
1
2
3
4
CGPoint PSPDFConvertViewPointToPDFPoint(CGPoint viewPoint, CGRect cropBox, NSUInteger rotation, CGRect bounds);
CGPoint PSPDFConvertPDFPointToViewPoint(CGPoint pdfPoint, CGRect cropBox, NSUInteger rotation, CGRect bounds);
CGRect PSPDFConvertPDFRectToViewRect(CGRect pdfRect, CGRect cropBox, NSUInteger rotation, CGRect bounds);
CGRect PSPDFConvertViewRectToPDFRect(CGRect viewRect, CGRect cropBox, NSUInteger rotation, CGRect bounds);

Page Info

PSPDFPageInfo can be used to get information for a specific page in a document. You can get this object by retrieving the PSPDFPageInfo object for a specific page on a PSPDFDocument using pageInfoForPageAtIndex:.

PSPDFPageInfo includes information like the rect of a page, transforms and page rotation.

Note that some PDF files also can have rotation set on pages. You can get this value by checking the rotation property. This can be a value between 0 and 270 in 90 degree steps. The rotation also influences where e.g. programmatically added annotations are placed in a document, so make sure to use the convert methods from PSPDFPageView before setting an annotations boundingBox, as these methods are correctly handling pages with any rotation.

The rotatedRect property correctly calculates the page rect by incorporating the rotation.

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, e.g. images whose dimensions are expressed in pixels. The default unit that PSPDFKit returns for page sizes is the point, which is easily converted into inches by taking into account 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 in page 79 of the PDF 1.7 Specification for more information.