Understanding coordinates

PDF documents have their own coordinate system, which differs from Android's coordinate system. When you ask for the position of an annotation in a PDF document using the PDFTron API, the position is given in PDF page coordinates instead of Android screen coordinates. To illustrate this, here is a screen capture of an annotation and a table of its coordinates as PDF page coordinates, screen coordinates, and scrolling coordinates:

Coordinatesx1y1x2y2
PDF page coordinates62.8165.3538.4415.5
Screen coordinates62.01368.61023.9862.5
Scrolling coordinates5063.01368.66024.9862.5

PDF page coordinates (page pt)

In a PDF document, the location (0, 0) is at the bottom left corner of the PDF page. The x axis extends horizontally to the right and y axis extends vertically upward. A Page pt represents a point in page coordinates.

A page may have a rotation or translation associated with it. In this case, the coordinate (0, 0) may no longer correspond to the bottom left corner of the page relative to the viewer.

For example, here is the same page as above, but rotated 90 degrees clockwise. Notice how the coordinates of the points in the rotated page have all stayed the same in relation to each other, but the coordinate (0, 0) is now at the top left corner of the viewport.

Screen coordinates (screen pt)

In Android views and in the PDFViewCtrl class, the locations of a view are measured in screen coordinates. Point (0, 0) is at the top left corner of the view. The x axis extends horizontally to the right and the y axis extends vertically downward. A Screen pt represents a point in screen coordinates.

Since screen coordinates measure Android views, if PDFViewCtrl zooms in, the annotation's screen coordinates may change.

For example, here are two screen captures of the same annotation before and after zooming in, and a table showing how its screen coordinates change:

left (x1)bottom (y1)right (x2)top (y2)
Before zoom in215.81148.8805.8734.6
After zoom in2.41130.0986.8638.8

Scrolling coordinates

In PDFViewCtrl, users can flip pages horizontally or vertically. In scrolling coordinates, the point (0, 0) is located at the top left corner of the view in page 1. The x axis extends horizontally to the right and the y axis extends vertically downward.

Converting between different coordinates

PDFViewCtrl allows you to convert from one coordinate system to another with ease:

MethodDescription
convPagePtToHorizontalScrollingPt(double, double, int)Converts a point from page space to scrolling space.
convPagePtToScreenPt(double, double, int)Converts a point from page space to screen space.
convScreenPtToPagePt(double, double, int)Converts a point from screen space to page space.