[BUG] Coordinate key mismatch in `pymupdf.table.chars_in_rect()` drops table candidates and rows

[Hao-ActuaViz]

Description of the bug

In pymupdf/table.py, the internal helper function chars_in_rect(CHARS, rect) compares a top-down bounding box rect against character coordinates in CHARS.

However, while rect uses top-down Y coordinates (rect[1] is top, rect[3] is bottom) and the horizontal check uses top-down x0/x1, the vertical check in chars_in_rect compares rect[1] and rect[3] against c["y0"] and c["y1"] instead of c["top"] and c["bottom"].

def chars_in_rect(CHARS, rect):
    return any(
        1
        and rect[0] <= c["x0"]
        and c["x1"] <= rect[2]
        and rect[1] <= c["y0"]    # ❌ rect[1] is top-down Y, but c["y0"] is CTM / bottom-up
        and rect[3] >= c["y1"]    # ❌ rect[3] is top-down Y, but c["y1"] is CTM / bottom-up
        for c in CHARS
    )

Impact on Table Detection (find_tables()):
In table.py::clean_graphics(), candidate table boundary rectangles (prect0) are filtered using chars_in_rect(CHARS, prect0) to determine if a candidate box contains text.

• On standard full-page tables, c["y0"] and c["top"] happen to numerically overlap by coincidence, masking the issue.
• On short tables near the bottom of a page, continuation tables across page breaks, or pages with non-identity CTMs, c["y0"]/c["y1"] do not overlap with top-down rect[1]/rect[3].
• As a result, chars_in_rect returns False, clean_graphics() discards the candidate boundary box, line synthesis fails, and entire table rows (or short tables) disappear from find_tables().

Note that elsewhere in table.py (e.g. in has_text() around line 1554), top-down coordinates are correctly paired with c["top"] and c["bottom"]:

text_bboxes = [
    (c["x0"], c["top"], c["x1"], c["bottom"]) # ✅ Correct top-down pair used in has_text()
    for c in CHARS
    if c["text"] not in white_spaces
]

How to reproduce the bug

Minimal Code Example 1 (Direct Unit Test):

import pymupdf.table

# A character positioned at top=100.0, bottom=110.0 on an 800px page.
# Top-down coordinates: top=100, bottom=110
# CTM / bottom-up coordinates: y0=690, y1=700
char = {
    "x0": 10.0, "x1": 20.0,
    "top": 100.0, "bottom": 110.0,
    "y0": 690.0, "y1": 700.0
}

# Top-down bounding box clearly surrounding the character (top=90, bottom=120)
rect = (0.0, 90.0, 30.0, 120.0)

# Expected: True (character is inside the top-down bounding box)
# Actual: False (because chars_in_rect compares top-down rect bounds with y0/y1)
result = pymupdf.table.chars_in_rect([char], rect)
print("chars_in_rect result:", result)  # Outputs: False

Proposed Fix:

In src/table.py, update chars_in_rect to use c["top"] and c["bottom"]:

def chars_in_rect(CHARS, rect):
    """Check whether any of the chars in CHAR are inside rectangle 'rect'."""
    return any(
        1
        and rect[0] <= c["x0"]
        and c["x1"] <= rect[2]
-       and rect[1] <= c["y0"]
-       and rect[3] >= c["y1"]
+       and rect[1] <= c["top"]
+       and rect[3] >= c["bottom"]
        for c in CHARS
    )

PyMuPDF version

1.27.2.3

Operating system

MacOS

Python version

3.12

[Hao-ActuaViz]

Version 1.28.2 has the identical code at table.py:197

[JorjMcKie]

Thanks for spotting this!
Could you please let us have an example page showing the issue? Would help us creating a test script.
Thanks!

[Hao-ActuaViz]

Thanks for spotting this! Could you please let us have an example page showing the issue? Would help us creating a test script. Thanks!

We can use the script to generate an example file

import pymupdf

PAGE_W, PAGE_H = 595, 842          # A4
LEFT, RIGHT = 50, 500
ROWS = 5                            # 5 rows, 2 cols
ROW_H = 40
TOP = 60                            # short table, wholly above the centerline (421)
COL_X = [LEFT, 300, RIGHT]


def build(path):
    doc = pymupdf.open()
    page = doc.new_page(width=PAGE_W, height=PAGE_H)

    row_ys = [TOP + ROW_H * i for i in range(1, ROWS + 1)]
    bottom = row_ys[-1]

    # Horizontal rules: NOTE no rule at y=TOP -> row 1 has no top border.
    for y in row_ys:
        page.draw_rect(pymupdf.Rect(LEFT, y, RIGHT, y + 1), color=None, fill=(0, 0, 0))
    # Vertical rules span the full table height, including row 1.
    for x in COL_X:
        page.draw_rect(pymupdf.Rect(x, TOP, x + 1, bottom), color=None, fill=(0, 0, 0))

    for i in range(ROWS):
        y_text = TOP + i * ROW_H + ROW_H - 12
        page.insert_text((LEFT + 8, y_text), f"example cell text {2 * i + 1}", fontsize=11)
        page.insert_text((306, y_text), f"example cell text {2 * i + 2}", fontsize=11)

    doc.save(path)
    doc.close()


if __name__ == "__main__":
    build("find_tables_bug.pdf")

Then use the following script to test out the results

import pymupdf

PDF_PATH = "find_tables_bug.pdf"


def main():
    with pymupdf.open(PDF_PATH) as doc:
        page = doc[0]
        tables = list(page.find_tables(strategy="lines_strict"))
        rows = tables[0].extract() if tables else []

    print(f"pymupdf {pymupdf.__version__}")
    print(f"expected 5 rows, got {len(rows)}")
    for r in rows:
        print("   ", r)
    print()
    print("row 1 present:", any(c == "example cell text 1" for r in rows for c in r))


if __name__ == "__main__":
    main()

Execution:

(base) hao@Chun-Haos-MacBook-Air % .venv/bin/python hao_test/267_miss_parse_entry/generate_find_tables_bug_pdf.py 
(base) hao@Chun-Haos-MacBook-Air % .venv/bin/python hao_test/267_miss_parse_entry/reproduce_find_tables_bug.py 
Consider using the pymupdf_layout package for a greatly improved page layout analysis.
pymupdf 1.27.2.3
expected 5 rows, got 4
    ['example cell text 3', 'example cell text 4']
    ['example cell text 5', 'example cell text 6']
    ['example cell text 7', 'example cell text 8']
    ['example cell text 9', 'example cell text 10']

row 1 present: False