Page cropbox is not used for bbox if present

[stefanw]

Describe the bug

When a PDF page contains a cropbox that differs from the mediabox the positions of the extracted text will not be correct and drawing them via page.to_image().draw_rects(...) will not work as expected.

Code to reproduce the problem

import pdfplumber

pdf = pdfplumber.open("pdfplumber-cropbox.pdf", repair=True)
page = pdf.pages[0]
im = page.to_image()
im.draw_rects(page.extract_words())
im.save("pdfplumber-bad-cropbox.jpg")
im

PDF file

pdfplumber-cropbox.pdf

Expected behavior

I would expect pdfplumber to take the cropbox as the bbox.

Actual behavior

Even when the cropbox is present it is not taken as the page's bbox.

Screenshots

Environment

• pdfplumber version: 0.10.2
• Python version: 3.11
• OS: Mac

Additional context

The problem seems to be this line in the Page class:

self.mediabox = resolve_all(mediabox) or self.cropbox

The mediabox is a required page attribute, so self.cropbox will never be assigned as the mediabox.
The cropbox is optional, so my guess is that the code should be:

self.mediabox = self.cropbox or resolve_all(mediabox)

Indeed this change improves the positioning significantly, although it's still not perfectly aligned.

[jsvine]

Hi @stefanw, and thank you for flagging this! I've now spent a couple of hours looking into it and wanted to send you this update. Although I think .mediabox is correctly assigned as the main .bbox (since it's the mediabox which most closely corresponds to the possible user space), there definitely is a bug here, and I think it may have multiple nuanced sources — more to do with the PageImage conversion, but also some related calculations. In any case, will post again here when I'm closer to a solid fix. Thanks again.

[stefanw]

Hey @jsvine, thanks for looking into this. I think the cropbox is meant to represent the visible user space and is used in other implementations as the transformation base (e.g. pdfbox). The PDF standard says:

The crop box defines the region to which the contents of the page are to be
clipped (cropped) when displayed or printed. Unlike the other boxes, the crop
box has no defined meaning in terms of physical page geometry or intended
use; it merely imposes clipping on the page contents. However, in the absence
of additional information (such as imposition instructions specified in a JDF
or PJTF job ticket), the crop box will determine how the page’s contents are to
be positioned on the output medium. The default value is the page’s media
box.
(emphasis mine)

[jsvine]

Hi @stefanw, this should now be fixed via 07d9997 (now available on develop), which standardizes the handling of .cropbox and .mediabox, particularly with regards to PageImage.

As a demonstration of the fixes, now the character and line bounding boxes are rendered as expected:

Your interpretation of .cropbox is correct, but Page.bbox represents something slightly different in pdfplumber: The box in which the page's objects (visible or not) are expected to exist. This becomes relevant for Page.crop(...), which needs to track the area to which the user has filtered the page objects. For that, I believe we want to start with .bbox = .mediabox because users will (I believe) initially want programmatic access to all graphical objects regardless of whether they are placed within .cropbox.

Thanks again for opening this issue, which helped me to identify inconsistencies in how the various boxes were handled. Closing it for now, but feel free to continue the conversation, point out edge-cases I might have missed, et cetera.