From debb577e8a5596f14ced06a1dbbc889d6db37e65 Mon Sep 17 00:00:00 2001 From: ***** <721466+soodoku@users.noreply.github.com> Date: Sun, 26 Jul 2026 20:40:12 -0700 Subject: [PATCH 1/3] Document the two vertical coordinate systems in README The README defines y0/y1/top/bottom/doctop once per object type, in five separate property tables, but never explains why there are two vertical coordinate systems, which one bounding boxes use, or how to convert between them. That gap has repeatedly been reported as a bug: #198, #845, #1332, and most recently #1369. Add a "Coordinates" section above the per-object tables covering which properties are measured from the page bottom versus the page and document top, that bounding boxes are (x0, top, x1, bottom), why the top-left origin was chosen, the conversion between the systems and its MediaBox caveat, and which objects carry which properties. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 3 +++ README.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c62972b4..2913b6fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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)) diff --git a/README.md b/README.md index 59668e7c..c83023eb 100644 --- a/README.md +++ b/README.md @@ -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. + +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. + +For a page whose `MediaBox` begins at the origin — the typical case — the two systems convert simply: + +```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. + #### `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 From 619c3c5e270b16b8a4aa5055fec622b5855eaa25 Mon Sep 17 00:00:00 2001 From: ***** <721466+soodoku@users.noreply.github.com> Date: Sun, 2 Aug 2026 20:07:13 -0700 Subject: [PATCH 2/3] Address coordinate documentation review --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c83023eb..f4e59f8c 100644 --- a/README.md +++ b/README.md @@ -156,21 +156,19 @@ Horizontal coordinates are unambiguous: `x0` and `x1` are both measured from the 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. -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. +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, 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. For a page whose `MediaBox` begins at the origin — the typical case — the two systems convert simply: ```python -y1 == page.height - top -y0 == page.height - bottom +top == page.height - y1 +bottom == page.height - y0 ``` 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. - #### `char` properties | Property | Description | From 66206153030e8915ecc7d8c850d915d322360a80 Mon Sep 17 00:00:00 2001 From: ***** <721466+soodoku@users.noreply.github.com> Date: Sun, 1 Nov 2026 21:01:41 -0800 Subject: [PATCH 3/3] Clarify cropped-page coordinates and address documentation feedback --- README.md | 50 +++++++++++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index f4e59f8c..68a032de 100644 --- a/README.md +++ b/README.md @@ -144,31 +144,6 @@ 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. - -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, 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. - -For a page whose `MediaBox` begins at the origin — the typical case — the two systems convert simply: - -```python -top == page.height - y1 -bottom == page.height - y0 -``` - -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. - #### `char` properties | Property | Description | @@ -309,6 +284,31 @@ Additionally, both `pdfplumber.PDF` and `pdfplumber.Page` provide access to seve If you pass the `pdfminer.six`-handling `laparams` parameter to `pdfplumber.open(...)`, then each page's `.objects` dictionary will also contain `pdfminer.six`'s higher-level layout objects, such as `"textboxhorizontal"`. +### Coordinates + +`pdfplumber` uses `top` and `bottom` for vertical coordinates, increasing downward from the top of the page. It also retains the original `y0` and `y1` properties, which increase upward from the bottom of the page. + +| Property | Measured from | Direction | +|----------|---------------|-----------| +|`y0`, `y1`| Bottom of the page | Upward | +|`top`, `bottom`| Top of the page | Downward | +|`doctop`| Top of the *document* | Downward | + +Bounding boxes use `(x0, top, x1, bottom)`, as expected by `.crop(...)`, `.within_bbox(...)`, and the visual-debugging methods. The top-left origin follows typical reading order and the convention used by SVG, Canvas, and PIL/Pillow ([#198](https://github.com/jsvine/pdfplumber/issues/198)). + +For objects on an original, **uncropped** page whose `MediaBox` begins at `(0, 0)`, the conversions are: + +```python +top = page.height - y1 +bottom = page.height - y0 +``` + +For an original page with a nonzero `MediaBox` origin, add `page.mediabox[1]` to both expressions. + +Cropping keeps the original page coordinate system; it does not move the origin to the crop's corner. A cropped page has a different `.height`, and objects intersecting its boundary can have clipped `top` and `bottom` values while retaining their original `y0` and `y1`. Use the cropped objects' `top` and `bottom` directly rather than applying the formulas above to the cropped page. + +Objects parsed from the PDF carry the coordinate properties listed in their tables above. The dictionaries returned by `.extract_words(...)` provide `top`, `bottom`, and `doctop` but no `y0`/`y1`; `.search(...)` results provide `top` and `bottom`. A line's or curve's `pts` are `(x, top)` tuples. + ## Visual debugging `pdfplumber`'s visual debugging tools can be helpful in understanding the structure of a PDF and the objects that have been extracted from it.