Document Block Processing Pipeline#

Overview#

The block processing pipeline converts raw layout model detections into structured, paragraph-level blocks stored in middle.json. It runs in two sequential stages per document:

1. Per-page: Raw layout detections → preproc_blocks (via MagicModel)
2. Document-level: preproc_blocks → para_blocks (via para_split + finalizers)

The handoff point is finalize_middle_json, which orchestrates the full document-level post-processing sequence after all pages have been processed.

Stage 1: Raw Block Construction (preproc_blocks)#

Entry point: page_model_info_to_page_info() constructs a MagicModel instance for each page.

MagicModel.__init__ runs four steps in sequence 1:

1. __fix_axis() — Rescales all bounding boxes from model coordinates back to PDF coordinates and drops degenerate boxes (width or height ≤ 2 pixels) 2.
2. __post_process() — Re-indexes layout detections and separates inline_formula and ocr_text entries into dedicated span lists 3.
3. __build_page_blocks() — Maps PP-DocLayoutV2 label strings to BlockType enums 4, attaches text/formula spans to text-type blocks via SpanBlockMatcher, and converts visual-type blocks (image, table, chart, interline equation) into single-span line structures 5.
4. __classify_visual_blocks() — Groups orphaned captions and footnotes with their nearest visual parent (image/table/chart/code), producing two-layer composite blocks. Captions/footnotes that can't be matched are re-typed as BlockType.TEXT 6.

__build_return_blocks() then splits page_blocks into two lists 7:

• preproc_blocks — all content blocks passed downstream
• discarded_blocks — headers, footers, page numbers, aside text, page footnotes

The caller retrieves these via magic_model.get_preproc_blocks() and magic_model.get_discarded_blocks() 8.

Stage 2: Paragraph Merging (para_blocks)#

Entry point: para_split(page_info_list) — called as part of finalize_middle_json_from_preproc().

para_split operates across all pages at once and writes results back into each page's para_blocks key 9.

Block Grouping#

__process_blocks() first partitions the flat block list into groups, breaking at any ABSTRACT, INTERLINE_EQUATION, DOC_TITLE, or PARAGRAPH_TITLE block — these act as natural paragraph boundaries that prevent merging across section titles.

List vs. Text Classification#

__is_list_or_index_block() re-classifies each TEXT block within a group as LIST, INDEX, or TEXT using geometric and textual heuristics 10:

• Index blocks: ≥80% of lines start or end with a digit 11
• Centered list blocks: most lines don't touch either edge and are centered 12
• List blocks: ≥2 lines flush left with ragged right edges, end-punctuation patterns, or numeric-start patterns 13
• Language is detected on the block text to adjust right-edge thresholds for CJK vs. Latin scripts

Merge Heuristics#

Within each group, blocks are iterated in reverse order and conditionally merged into the next block 16:

Cross-page merges are tagged with SplitFlag.CROSS_PAGE on affected spans 17.

Blocks whose lines were merged away have SplitFlag.LINES_DELETED = True set and are excluded from the final para_blocks output.

Post-para_split Finalizers#

finalize_middle_json_from_preproc() runs these steps in order 18:

1. optimize_formula_number_blocks() — resolves formula number placement
2. para_split() — the main paragraph merge step
3. cross_page_table_merge() — stitches tables split across pages
4. apply_title_leveling_to_pdf_info() — assigns heading hierarchy levels
5. _post_block_process() — renames DOC_TITLE → TITLE (level 1), PARAGRAPH_TITLE → TITLE (level 2), VERTICAL_TEXT → TEXT

Key Data Structures#

Key Source Files#