officefileapi-120032-pdf-document-api-coordinate-systems.md
The coordinate systems define the position, orientation, and size of text, graphics, and images that appear on a page. The coordinate systems are determined with respect to the current page.
This document describes the three coordinate systems used in the PDF Document API and how to convert from one coordinate system to another.
The world coordinate system models a specific graphics world.
Origin (0,0): At the top-left corner of the page.
Axis Directions : A positive X increases towards the right; a positive Y increases towards the bottom.
The PdfGraphics class uses the world coordinate system to perform all its operations including manipulations of content, text, images, and other elements.
Refer to the following section for more information: PDF Graphics.
Origin (0,0): Can be placed anywhere on or even outside the page.
Axis Directions : A positive x increases towards the right; a positive y increases upward.
This coordinate system is used to define the crop box - the visible page area that is displayed or printed.
The image below illustrates the user and page coordinate systems, along with their relationship:
The user coordinate system is an internal PDF coordinate system. The following members use this coordinate system:
The high-level API refers to the page coordinate system.
Origin (0, 0): At the bottom-left corner of the crop box. Relative to the user coordinate system, the origin of the page coordinate system is offset by crop box left along the X axis and crop box bottom along the Y axis.
Axis Directions : A positive x increases towards the right; a positive y increases upward.
This coordinate system is used when you obtain existing page content (text, images, annotations, facades, and more).
| Product | API |
|---|---|
| PDF Document API | PdfDocumentProcessor.FindText |
| PdfDocumentProcessor.GetDXImages | |
| PdfDocumentProcessor.GetText | |
| PdfWord class. | |
| WinForms PDF Viewer | PdfViewer.FindText |
| WPF PDF Viewer | PdfViewerControl.FindText |
| PdfViewerControl.GetText | |
| PdfViewerControl.ScrollIntoView |
Depending on the PDF file operation, you may need to convert from one coordinate system to another coordinate system.
If you use the following method, world coordinates are converted to page coordinates automatically:
The world coordinates (units) are converted to page coordinates (points) using the following formula:
x = (unitX / dpiX) * 72;
y = cropBox.Height - (unitY / dpiY) * 72.
Use the PdfPageTreeObject.CropBox property to get the page crop box height.
You must convert the user coordinates to world coordinates, for example, when you need to substitute a text form field with an image.
The following table lists example topics that describe conversion between the given coordinate systems:
| Coordinate Systems | Topic |
|---|---|
| Page to World | How to: Highlight Search Results in a Document |
| User to World | How to: Replace a Form Field with an Image |
When you manipulate PDF file content, you operate with points. 1 point is a 1/DPI of an inch. The DPI value in this formula depends on the coordinate system you use.
The following table lists default DPI values depending on the coordinate system:
| Coordinate System | Default DPI |
|---|---|
| World | 96 |
| User/ Page | 72 |
The DPI of a coordinate system means that if you set DPI to 96 and a graphic element’s size in the World coordinate system equals 96 x 96 pixels, this element will be rendered in as a PDF document with the size of 1 x 1 inch.