PyMuPDF coordinate system(s)

[millivolt9]

I'm looking to get a handle on the coordinate system(s) used in pymupdf.

I know that for any given page, the origin is supposed to be the "top left", and that positive x -> right and positive y -> down, and that this comes from mupdf. However, I'm not clear on anything more specific than that. Is the origin the top left corner of the page, the mediabox, the top left corner of the cropbox? Something else?

The documentation says: "The MediaBox is the only rectangle, for which there is no difference between MuPDF and PDF coordinate systems: Page.mediabox will always show the same coordinates as the /MediaBox key in a page’s object definition. For all other rectangles, MuPDF transforms coordinates such that the top-left corner is the point of reference."

This was helpful to me because I'm familiar with PDF coordinate systems, but it doesn't say how, for example, the coordinates returned by Page.get_text(“words”) are related to the coordinates returned by page.get_pixmap().irect.

My first thought, based on the documentation's example (just below the quote above) was that both of these, as well as all other rect-like coordinates, are indeed in the same coordinate system, and that this coordinate system is that which has an origin at the top-left of the mediabox, has positive x -> right and positive y -> down, and has scale that matches PDF's default user space coordinate system. Is this the case?

On a related note, what does page.get_pixmap() actually return a pixmap of? Is is the mediabox, cropbox, or something else?

Finally, I noticed the links in the pymupdf documentation for the Adobe PDF reference are broken... I found a document at https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf, but maybe this isn't the place to mention that.

[JorjMcKie]

... as well as all other rect-like coordinates, are indeed in the same coordinate system, and that this coordinate system is that which has an origin at the top-left of the mediabox, has positive x -> right and positive y -> down, and has scale that matches PDF's default user space coordinate system. Is this the case?

In (Py-) MuPDF, page.rect equals the CropBox in dimension but always has the top-left value (0,0). It also reflects page rotation, CropBox does not.

The coordinates of .get_text() and friends are relative to the top-left of the unrotated page.rect. Which implies that there may happen negative values if stuff exists above or to the left of that. Or may have larger x,y-values than page width or height.

If you can find the new location of that PDF reference, please submit a PR.

[millivolt9]

When you said CropBox, you meant PyMuPDF's Cropbox, and not PDF's /CropBox, correct?

So page.rect and PyMuPDF's CropBox (retrieved as page.cropbox) both represent some rectangle that has a given width and height, the only difference is that page.rect can change with rotation (per the PDF Page's /Rotate, which is equivalent to page.rotation) and the other can't.

So when you say

The coordinates of .get_text() and friends are relative to the top-left of the unrotated page.rect

that is equivalent to saying that the coordinates of page.get_text() are relative to the top-left of page.cropbox. Or am I missing something? Also, regarding "and friends", is there any info in the documentation about what does and doesn't follow this standard?

From experiments I've found that get_pixmap() returns a pixmap of cropbox, including any rotations. Does this sound right, or is there some other subtlety?

Thanks so much for your help.

[JorjMcKie]

When you said CropBox, you meant PyMuPDF's Cropbox, and not PDF's /CropBox, correct?

No, there only is /CropBox. It is accessible via page.cropbox as you write.

equivalent to saying that the coordinates of page.get_text() are relative to the top-left of page.cropbox.

No! At best you could say, they are relative to the cropbox if that would have (0,0) as top-left.

what does and doesn't follow this standard?

There is no exception. Pixmap is no exception either: it contains no coordinates. Like neither Page.rect itself is an exception - both respect page rotation.

Methods and attributes refer to the unrotated page - for input and output: if you insert something (text, drawings, images, annotations, ...) you must use unrotated coordinates.
Where needed (e.g. when interfacing with other packages), there are three Page matrices available to do the coordinate transformations:

1. transformation_matrix reflects what happened to the PDF coordinates when they where converted to MuPDF geometry,
2. rotation_matrix
3. derotation_matrix

The latter two are the inverse of each other and transform coordinates from/to the rotated page. They are the Identity matrix for unrotated pages and change when page rotation is changed:

In [1]: import fitz
In [2]: doc=fitz.open()
In [3]: page=doc.new_page()
In [4]: page.transformation_matrix
Out[4]: Matrix(1.0, 0.0, 0.0, -1.0, 0.0, 842.0)
In [5]: page.rotation_matrix
Out[5]: Matrix(1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
In [6]: page.derotation_matrix
Out[6]: Matrix(1.0, -0.0, -0.0, 1.0, 0.0, 0.0)
In [7]: page.set_rotation(90)
In [8]: page.rotation_matrix
Out[8]: Matrix(0.0, 1.0, -1.0, 0.0, 842.0, 0.0)
In [9]: page.derotation_matrix
Out[9]: Matrix(0.0, -1.0, 1.0, 0.0, -0.0, 842.0)

[millivolt9]

No, there only is /CropBox. It is accessible via page.cropbox as you write.

I'm sorry, but I'm very confused now. My interpretation is that the documentation explicitly says that PDF's /CropBox and page.cropbox can be different things on page 321:

The MediaBox is the only rectangle,
for which there is no difference between MuPDF and PDF coordinate systems: Page.mediabox will always
show the same coordinates as the /MediaBox key in a page’s object definition. For all other rectangles, MuPDF
transforms coordinates such that the top-left corner is the point of reference. This can sometimes be confusing
– you may for example encounter a situation like this one:
• The page definition contains the following identical values: /MediaBox [ 36 45 607.5 765 ], /
CropBox [ 36 45 607.5 765 ].
• PyMuPDF accordingly shows page.mediabox = Rect(36.0, 45.0, 607.5, 765.0).
• BUT: page.cropbox = Rect(36.0, 0.0, 607.5, 720.0), because the two y-coordinates have been
transformed (45 subtracted from both of them).

Am I misreading the documentation? Because to me, that says pretty explicitly that page.cropbox and /CropBox are different, because page.cropbox is defined relative to page.mediabox (which it says IS ABSOLUTELY EQUAL to /MediaBox). Of course I'd expect them to be equal in an absolute sense once their different coordinate systems are taken into account. The problem is, I know what /CropBox's coordinate system is, but page.cropbox's isn't explicitly defined from what I can tell.

There is no exception. Pixmap is no exception either: it contains no coordinates.

Doesn't the documentation on page 236 say Pixmap.x and Pixmap.y are coordinates of the top left corner? Do you mean that it's just a different coordinate system, or do you mean that those aren't true coordinates at all?

I understand the idea of Page.rotation_matrix and Page.derotation_matrix, but I think without some of these more basic points clarified, I can't really use them with confidence.

I feel like I'm missing something really basic here, but thanks for your help.

[JorjMcKie]

CropBox:
A different coordinate system does not mean page.cropbox is a different thing from /CropBox. Only its values may be different from those found under /CropBox - because of the MuPDF coordinate system. That's all.
So inside PyMuPDF, the /CropBox array is taken, then page.transformation_matrix is applied to its values to yield the property page.cropbox.
Now clear?

Pixmap.x and Pixmap.y are coordinates of the top left corner?

Yes, but the top-left corner of the pixmap, nothing else. The values have nothing to do with any document page. Nothing at all. If a pixmap is made from a document page with default parameters, its irect equals page.rect.irect. This is where their relationship ends. Else when using suitable matrix, dpi or clip parameters, there will not be any such relationship right from the start.
Pixmap coordinates address pixels with integer indices.
Page coordinates address points using float values.
This should underpin that pixmap coordinates are a different animal.

A pixmap even need not stem from a document page as far as that is concerned. Its x/y values can be used to position image content when copying beween pixmaps. You can also arbitrarily modify them - and you would in the mentioned case.

Even inside PDF, images are being addressed with top-left=(0,0).
Among the main motivators for MuPDF to use its own geometry is that it does not only support PDF, but a handful of other documents (XPS, EPUB, CBZ, FB2, etc.) ... all with the same API. Among those are all images which also can be opened as a Document (not only as a Pixmap) - even multi-page images like TIFF.

[millivolt9]

That's extremely helpful, thank you. One more question... when the documentation refers to "PDF space", "PDF coordinates", etc., is that referring to PDF's "default user space"?

[JorjMcKie]

is that referring to PDF's "default user space"?

Yes, that is correct.

[julian-smith-artifex-com]

Finally, I noticed the links in the pymupdf documentation for the Adobe PDF reference are broken... I found a document at https://opensource.adobe.com/dc-acrobat-sdk-docs/standards/pdfstandards/pdf/PDF32000_2008.pdf, but maybe this isn't the place to mention that.

Thanks for mentioning this bad link, your suggested URL looks good.

I've updated my tree so this fix will be in the next release.