Datagrunt 4.6.6: Correct PDF Coordinates on Cropped Pages

Datagrunt 4.6.6 fixes element positions from the default pdfium engine on cropped PDF pages.

What Was Wrong

A PDF page’s visible area is its CropBox intersected with its MediaBox, and either box may be inherited from the page tree. When that visible area does not start at the page origin — a cropped scan, a page whose MediaBox has a non-zero origin — PDFReader(..., engine="pdfium") reported every text and image position shifted by the crop origin, on every page rotation. In the regression fixtures the shift was about 50 points, so bounding boxes did not line up with the rendered page.

Pages whose visible area starts at the origin — most PDFs — were always correct, and their output does not change in 4.6.6.

What Changed

The pdfium engine now measures every text and image box from the top-left corner of the page’s visible area (pdfium’s page bounding box, which includes boxes inherited from the page tree), for all four page rotations. Page width and height were already reported for the visible area, so positions and page size now share one frame.

from datagrunt import PDFReader

page = PDFReader("cropped_report.pdf").to_dicts()["document"]["pages"][0]
print(page["width"], page["height"])

for element in page["elements"]:
    position = element["position"]
    print(element["type"], position["x"], position["y"], position["w"], position["h"])

At a 72 DPI render, one point is one pixel, so these boxes overlay the rendered page directly.

Known Limitations

• Tables on cropped pages. Table detection still reports table positions without the crop offset, so on cropped pages a table’s position is shifted and some table cell text can also appear as body text. Fixed in 4.6.7.
• engine="pymupdf" is unchanged by this release; on rotated pages it reports coordinates in the unrotated page frame.

Upgrading

uv pip install --upgrade datagrunt