Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file. The format

## [Unreleased]

### Added
- Add a "Coordinates" section to README.md, explaining the relationship between the `y0`/`y1` and `top`/`bottom`/`doctop` coordinate systems, why bounding boxes are expressed as `(x0, top, x1, bottom)`, and which objects carry which properties (h/t @soodoku). ([#389](https://github.com/jsvine/pdfplumber/issues/389))

### Fixed
- Initialize PDFium's form environment in `get_page_image` so that filled AcroForm field content is included when rendering pages via `Page.to_image()`. ([#1367](https://github.com/jsvine/pdfplumber/issues/1367))

Expand Down
28 changes: 28 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,33 @@ Each instance of `pdfplumber.PDF` and `pdfplumber.Page` provides access to sever

Each object is represented as a simple Python `dict`, with the following properties:

#### Coordinates

Horizontal coordinates are unambiguous: `x0` and `x1` are both measured from the left edge of the page. Vertical coordinates come in two varieties, and mixing them is a common source of confusion:

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I might reframe this slightly. It's less that the coordinates "come in two varieties", but rather that pdfplumber uses top/bottom but retains reference to the original y0/y1 coords.


| Property | Measured from | Direction |
|----------|---------------|-----------|
|`y0`, `y1`| Bottom of the page | Upward |
|`top`, `bottom`| Top of the page | Downward |
|`doctop`| Top of the *document* | Downward |

The `y0`/`y1` pair follows the PDF specification's own coordinate system, and is retained for compatibility with `pdfminer.six`. Everything else in `pdfplumber` places the origin in the __top-left__ corner. In particular, bounding boxes are expressed as `(x0, top, x1, bottom)` — *not* `(x0, y0, x1, y1)` — which is what `.crop(...)`, `.within_bbox(...)`, and the visual-debugging methods expect.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd cut the , and is retained for ... part of the first sentence. I'd also cut the part inside the em-dashes.


The top-left origin was chosen because ([#198](https://github.com/jsvine/pdfplumber/issues/198)) people generally read PDFs from the top-left toward the bottom-right; because measuring from the top is what makes `doctop` — the distance from the top of the *whole document* — able to distinguish objects at similar heights on different pages; and because most adjacent layout systems (SVG, Canvas, PIL/Pillow, which `pdfplumber` itself uses for visual debugging) also put the origin in the top-left.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The doctop part of the explanation, although true, feels like a bit of a distraction, and slightly difficult to follow. Maybe just keep this paragraph to the first and third parts?


For a page whose `MediaBox` begins at the origin — the typical case — the two systems convert simply:

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the y-flavored variables are the "original" ones, and top/bottom the conversions, I might suggest framing the code block below in those terms, instead of vice versa.


```python
y1 == page.height - top
y0 == page.height - bottom
```

If the `MediaBox` does not begin at `(0, 0)`, both conversions are shifted by its vertical offset, `page.mediabox[1]`.

Not every object carries both varieties. Objects parsed directly from the PDF — `char`, `line`, `rect`, `curve`, `image`, `annot`, and `hyperlink` — have all of the properties above. Objects that `pdfplumber` computes for you use only the top-down properties: the dicts returned by `.extract_words(...)` provide `top`, `bottom`, and `doctop` but no `y0`/`y1`, and those returned by `.search(...)` provide `top` and `bottom`. Relatedly, a `line`'s or `curve`'s `pts` are `(x, top)` tuples.

Because object bounding boxes are normalized, `top` is never greater than `bottom`, and `height` (equal to `bottom - top`) is never negative.

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we can probably cut this line. Or does it clarify something that is a common source of confusion? (Perhaps I'm just overlooking that.)


#### `char` properties

| Property | Description |
Expand Down Expand Up @@ -576,6 +603,7 @@ Many thanks to the following users who've contributed ideas, features, and fixes
- [Anton Ilin](https://github.com/bronislav)
- [Sebastian Cao](https://github.com/cycsmail)
- [Kaspar Naraghi](https://github.com/kaninaba94)
- [Gaurav Sood](https://github.com/soodoku)

## Contributing

Expand Down
Loading