I just solved my own issue, while researching Apache PDFBox: https://stackoverflow.com/a/54045861.

I think you sort of alluded to it in other support tickets, but I had to convert from x,y in the bottom left hand corner of the document to x,y in the top left.

I'm going to leave it open only as I think the docs would benefit from a brief section explaining how to convert "PDF Canvas Units" to typical x/y coordinate space. Feel free to close if you disagree!

Thanks! Re-reading those comments it's clear in retrospect, I just didn't grasp it the first time.

I implemented it just using python and not considering rotation. For completeness, it seems like you are suggesting that this will work most of the time, but not all. Is rotation the only additional case to consider?

Or is the easiest solution just to use the raw APIs for each coordinate pair in the bounding box since it will handle it reliably?

I implemented it just using python and not considering rotation. For completeness, it seems like you are suggesting that this will work most of the time, but not all. Is rotation the only additional case to consider?

Yes, that's what I meant.
I think rotation is probably not the only additional case, though (there's the aforementioned "any opposite corners" problem, for one thing), and I'd indeed recommend to call these raw API functions since that's what seems safest/easiest.

Got it! I'm very unfamiliar with ctypes, but based on the method signature it seems to suggest that the method I would be using FPDF_PageToDevice returns values as integers instead of float/double which would be a problem since all of the values I'm working with have lots of decimal values.

FPDF_EXPORT FPDF_BOOL FPDF_CALLCONV FPDF_PageToDevice(FPDF_PAGE page,
--
  | int start_x,
  | int start_y,
  | int size_x,
  | int size_y,
  | int rotate,
  | double page_x,
  | double page_y,
  | int* device_x,
  | int* device_y);

Am I understanding this incorrectly?

If so, the logic for the method in FPDF_PageToDevice turns out to not actually be that complicated so if that method doesn't work I'll likely just come back to this later and re-implement it in python using the helper methods you made for PDFMatrix.

Is it possible currently to easily call the raw methods on a page object like CPDF_Page-> GetDisplayMatrix?

based on the method signature it seems to suggest that the method I would be using FPDF_PageToDevice returns values as integers instead of float/double which would be a problem since all of the values I'm working with have lots of decimal values.

Ooh, yes. If you're not actually targeting a bitmap to draw on, that sounds like a problem.
I guess you can use a large bitmap and then downscale so you don't run into real precision trouble, but yes, that's inelegant. Need to think about this...

Is it possible currently to easily call the raw methods on a page object like CPDF_Page-> GetDisplayMatrix?

Sadly the CPDF_* API layer is pdfium's private C++ backend which we can't access with ABI bindings / ctypes.
This is an unfortunate but known limitation of our (one could say, quick and dirty) bindings concept :(

OK thank you! This has been incredibly helpful -- really appreciate the pointers. Yes I think I'm doing something a bit different than others here (but it does work!)

GetDisplayMatrix is actually really simple as well so we've solved my issue for now -- https://pdfium.googlesource.com/pdfium.git/+/798e18f5e5cfb672c7f3186f6358b84c5ff7785b/core/fpdfapi/page/cpdf_page.cpp

That's good to hear, thanks!

However, I'm still left to think what I should do with pypdfium2 now.
And I'm sort of wondering why you want to change coordinate representation if you don't actually work with device pixels?

I am rendering a "highlight" layer in a web interface to highlight specific text in a displayed pdf. The rendering engine uses percentage values to determine where to place items so I need to use the right coordinate space.

I'm fairly new to all of this so honestly not sure if my suggestion is too narrow....but as far as what would be helpful to my use-case, if you had a python API implementation of FPDF_PageToDevice that maintained precision, I would 100% use that instead of what I'm likely to implement when I come back to this. But this also might be too narrow a use-case, so just a note somewhere in the docs that explains PDF coordinate space (and then a reference to it in the API docs for all of the methods that return coordinates) would have also been totally sufficient!

I see, thank you for elaborating.

Maybe, as an alternative to a python re-implementation, we could ask pdfium to add a float equivalent of FPDF_PageToDevice()? We don't need any bitmap parameters, just two functions for (almost-)lossless back and forth translation between normalized and native PDF coordinates.

That would work perfectly!

Commit a379ecc (in the devel branch) adds a helper around FPDF_PageToDevice() / FPDF_DeviceToPage(), but only to translate between a page and a corresponding bitmap rendering.

The quest for float coordinate normalization still stands.

Thanks for the update!

Our docs often mention coordinate order, such as left, bottom, right, top for rectangle return.
That feels problematic. At least we should add something like "relative to the PDF coordinate system".
Or maybe we should avoid these terms entirely and use unspecific variable names instead, e.g. x0, y0, x1, y1?

I think I'll convert this to a discussion, because I figured I don't like the idea of implementing coordinate conversion from scratch in pypdfium2 (nor would I have the time to do so). Especially given there is FPDF_PageToDevice() / FPDF_DeviceToPage() already, which covers the main use case.

However, to any users affected, feel free to file a feature request at pdfium for float coordinate normalization (or perhaps even contribute a patch yourself).