Repository navigation
Document the y0/y1 vs top/bottom/doctop coordinate systems in README
#1387
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: develop
Are you sure you want to change the base?
Changes from 1 commit
debb577
619c3c5
6620615
69571ba
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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: | ||
|
|
||
| | 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. | ||
|
Owner
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'd cut the |
||
|
|
||
| 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. | ||
|
Owner
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The |
||
|
|
||
| For a page whose `MediaBox` begins at the origin — the typical case — the two systems convert simply: | ||
|
Owner
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since the |
||
|
|
||
| ```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. | ||
|
Owner
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | | ||
|
|
@@ -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 | ||
|
|
||
|
|
||
There was a problem hiding this comment.
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
pdfplumberusestop/bottombut retains reference to the originaly0/y1coords.