Coordinate Space Conversions

By specification, PDF documents have their own coordinate space, which is different from the coordinate space used by Android’s views. While Android views 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.

PDF page coordinates

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

Copy
1
2
3
4
// Get the PDF coordinates of the annotation.
val annotationRect = someAnnotation.boundingBox
// Convert the annotation's PDF coordinates to view coordinates (pixels).
fragment.convertPdfRectToViewRect(annotationRect, someAnnotation.pageIndex)
Copy
1
2
3
4
// Get the PDF coordinates of the annotation.
final RectF annotationRect = someAnnotation.getBoundingBox();
// Convert the annotation's PDF coordinates to view coordinates (pixels).
fragment.convertPdfRectToViewRect(annotationRect, someAnnotation.getPageIndex());

ℹ️Note: Since every page of a PDF document has its own coordinate space, the conversion method also takes a page argument.

Conversion Methods

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

  • convertPdfPointToViewPoint() and convertViewPointToPdfPoint() convert a single point (stored within a PointF instance) from page coordinates to view coordinates and vice versa, respectively.

  • convertPdfRectToViewRect() and convertViewRectToPdfRect() convert a rectangle (stored within a RectF instance) from page coordinates to view coordinates and vice versa, respectively.

Conversion Matrix

If you need more control over the coordinate conversion, you can also retrieve a Matrix object using getPageToViewTransformation, which holds the page-to-view transformation. The matrix is invertible, allowing you to create a view-to-page transformation matrix, like so:

Copy
1
2
3
4
5
6
7
// Get the current page to view transformation. The second parameter can take either a
// matrix object you would like to reuse, or null if you would like to create a new object.
val pageToView : Matrix = fragment.getPageToViewTransformation(currentPage, null)

// Create a new matrix object and set it to the page-to-view transformation.
val viewToPage = Matrix()
pageToView.invert(viewToPage)
Copy
1
2
3
4
5
6
7
// Get the current page to view transformation. The second parameter can take either a
// matrix object you would like to reuse, or null if you would like to create a new object.
Matrix pageToView = fragment.getPageToViewTransformation(currentPage, null);

// Create a new matrix object and set it to the page-to-view transformation.
Matrix viewToPage = new Matrix();
pageToView.invert(viewToPage);

Have a look at the API reference of PdfFragment 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, e.g. 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 taking into account 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 in page 79 of the PDF 1.7 Specification for more information.