pdftract/notes/pdftract-56txm.md

Verification Note: pdftract-56txm

Bead Description

Phase 4.5: Reading Order (coordinator)

Summary

This coordinator bead oversees the Phase 4.5 reading order determination subsystem. All 4 child beads are closed and verified. The implementation is fully functional with comprehensive test coverage.

Child Beads Status

Bead ID	Title	Status	Verification Note
pdftract-5tvv1	Tagged-PDF fast-path stub	CLOSED	notes/pdftract-5tvv1.md
pdftract-4md5z	XY-cut recursive widest-whitespace split	CLOSED	Implementation in reading_order.rs
pdftract-4bylb	Docstrum fallback (k=5 NN graph)	CLOSED	notes/pdftract-4bylb.md
pdftract-18cb4	Reading order rank assignment + algorithm tag	CLOSED	notes/pdftract-18cb4.md

Implementation Location

All Phase 4.5 reading order code resides in:

• crates/pdftract-core/src/layout/reading_order.rs (primary implementation)
• crates/pdftract-core/src/extract.rs (integration and tagged-PDF stub)

Acceptance Criteria Verification

✅ All 4 children closed

Status: PASS

Evidence:

• bf show confirms all 4 children have Status: closed
• Each child has verification note or code evidence

✅ Two-column academic paper: all left-col blocks before all right-col blocks

Status: PASS

Evidence:

• Test test_xy_cut_two_columns_left_then_right passes
• XY-cut correctly orders blocks by column (left before right, then top-to-bottom within columns)
• Test creates 2 columns with 3 blocks each; verifies order [0,1,2,3,4,5]

✅ Magazine with sidebar: main text separated from sidebar

Status: PASS

Evidence:

• Test test_docstrum_magazine_main_and_sidebar passes
• Docstrum correctly identifies 2 connected components (main + sidebar)
• Main column visited before sidebar (roots sorted by column ASC, y DESC)

✅ Single-column text: XY-cut produces single region

Status: PASS

Evidence:

• Test test_xy_cut_single_column_top_to_bottom passes
• XY-cut detects single column via overlapping x-ranges (is_single_column)
• Returns order sorted by y descending (top-to-bottom reading)

✅ Tagged PDF: TAGGED_PDF_STRUCT_TREE_DEFERRED emitted, falls through to XY-cut

Status: PASS

Evidence:

• Test test_tagged_pdf_emits_deferred_diagnostic passes (extract.rs)
• Diagnostic emitted once per document when catalog.mark_info.is_tagged
• Falls through to XY-cut with reading_order_algorithm = "xy_cut"

Test Results

Compilation: ✅ PASS

cargo check -p pdftract-core
Exit code: 0

Reading order tests: ✅ PASS (27/27)

running 27 tests
test layout::reading_order::tests::test_*
test result: ok. 27 passed; 0 failed; 0 ignored

Key tests:

• test_xy_cut_two_columns_left_then_right - Two-column ordering
• test_xy_cut_single_column_top_to_bottom - Single column detection
• test_docstrum_magazine_main_and_sidebar - Magazine layout
• test_assign_reading_order_docstrum_fallback - Docstrum trigger
• test_tagged_pdf_emits_deferred_diagnostic - Tagged PDF diagnostic

Algorithm Selection Logic

From assign_reading_order (reading_order.rs lines 745-778):

1. Run XY-cut to get initial order and region statistics
2. Calculate small_region_ratio = small_region_count / region_count
3. Trigger Docstrum if: small_region_count > 10 AND small_region_ratio > 0.5
4. Assign reading_order_rank = 0, 1, 2, ... to blocks in final order
5. Return algorithm string: "xy_cut" or "docstrum"

Constants:

• REGION_COUNT_THRESHOLD = 10
• MIN_BLOCKS_PER_REGION = 3
• SMALL_REGION_RATIO_THRESHOLD = 0.5

Integration

The reading order subsystem is integrated into the main extraction pipeline:

• Entry point: extract.rs calls assign_reading_order after block formation
• Algorithm tag: returned algorithm string set in PageResult.reading_order_algorithm
• Rank assignment: each block gets unique reading_order_rank in 0..block_count

Phase 4.5 Completeness

All acceptance criteria met. Reading order determination is fully functional with:

• XY-cut for rectilinear layouts (preferred path)
• Docstrum fallback for irregular layouts
• Tagged-PDF diagnostic and fall-through
• Proper rank assignment and algorithm tagging

References

• Plan section: Phase 4.5 Reading Order (lines 1734-1759)
• XY-cut: Nagy & Seth 1984
• Docstrum: O'Gorman 1993