bytedance / bytedance/pdf-parser
fix: preserve table position in page reading order
- Dominant language
- Python
- Stars
- 14
- Forks
- 9
- Avg merge
- 43m
- Merged PRs (30d)
- 1
Description
## Problem
When table extraction is enabled, `_extract_page_blocks()` appends every table block to `page_blocks` before it walks the page's text and image blocks. As a result, tables are emitted before all surrounding content regardless of their vertical position on the page.
This affects current `main` at `c6478aae9ab50a13fc54c0599a0a459396c15b99` and release `0.0.5`.
## Source evidence
In `hi_pdf_parser/parser.py`:
1. `_extract_table_blocks()` is called and its results are immediately added with `page_blocks.extend(table_blocks)`.
2. Only afterward does the function iterate over `page.get_text("dict")["blocks"]` and append text/image results.
3. `_post_process_blocks()` merges adjacent content but does not sort the combined page blocks by their coordinates.
A page laid out as `introductory paragraph -> table -> concluding paragraph` therefore produces `table -> introductory paragraph -> concluding paragraph`.
## Expected behavior
Extracted blocks should preserve the page's reading order, including the relative position of tables, text, and images.
## Impact
Generated Markdown and API responses can materially change document meaning, especially when prose introduces or explains a table.
## Why there is no PR in this report
A safe fix needs a maintainer-approved ordering policy for multi-column pages, overlapping blocks, figures, and tables, plus representative regression PDFs. The current fixtures do not contain enough table-heavy layouts to validate an ordering algorithm without risking new extraction regressions.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start in hi_pdf_parser/parser.py by reading _extract_page_blocks(), _extract_table_blocks(), and _post_process_blocks(), then inspect the current table-related fixtures and representative PDFs. First clarify the ordering policy for multi-column pages, overlapping blocks, figures, and tables with a maintainer. Done means text, image, and table blocks preserve reading order without introducing extraction regressions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100