Coordinate Systems
- 4 minutes to read
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.
- World Coordinate System
- User Coordinate system
- Page Coordinate System
- Convert Between Coordinate Systems
- Convert World Coordinates to Page Coordinates
- DPI in Coordinate Systems
#World Coordinate System
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.
#Usage
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.
#User Coordinate system
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:
#Usage
The user coordinate system is an internal PDF coordinate system. The following members use this coordinate system:
- The document processor’s low-level document model API (the PdfDocument class). Use the PdfDocumentProcessor.Document property to obtain the document model.
- PdfAnnotation.Rect
- PdfPageTreeObject.CropBox. Please note that the size of the unit is a point (1/72 of an inch).
The high-level API refers to the page coordinate system.
#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.
#Usage
This coordinate system is used when you obtain existing page content (text, images, annotations, facades, and more).
| Product | API |
|---|---|
| PDF Document API | Pdf |
| Win |
Pdf |
| WPF PDF Viewer | Pdf |
#Convert Between Coordinate Systems
Depending on the PDF file operation, you may need to convert from one coordinate system to another coordinate system.
#Convert World Coordinates To Page Coordinates
If you use the following method, world coordinates are converted to page coordinates automatically:
- overloaded PdfDocumentProcessor.CreateDestination methods;
- overloaded PdfDocumentProcessor.RenderNewPage methods (see PDF Graphics API);
- overloaded PdfGraphics.AddToPageBackground methods (see PDF Graphics API);
- overloaded PdfGraphics.AddToPageForeground methods (see PDF Graphics API).
#Use a Conversion Formula
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.
#Convert Page/User Coordinates to World Coordinates
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 |
#DPI in Coordinate Systems
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.