Module layout 

Reading-order layout pass for Tagged PDFs (round 29).

Plain raster (content-stream) order does not give logical reading order for multi-column / multi-block layouts: the painter would lay column 1’s first row, column 2’s first row, then column 1’s second row, etc., as it raster-scanned the page from top to bottom. Tagged PDF (ISO 32000-1 §14.8) factors logical structure out of visual layout: the catalog’s /StructTreeRoot carries a tree of /StructElems (sections, paragraphs, list items, table rows…) whose leaves are MarkedContentReferences (MCIDs) — integers that cross-reference the page’s /Span <</MCID n>> BDC … EMC-bracketed content-stream slices. Walking the tree in document order and resolving each MCID to its painted text run gives us the author-intended reading order, regardless of where the runs actually appear on paper.

This module’s read_in_logical_order performs that walk:

1. Open the catalog → find /StructTreeRoot (if absent, return a Raster-tagged result that delegates to crate::reader::extract_text).
2. Walk every page in document order, run the round-22 text walker with MCID tracking enabled (round-29 addition), and bucket each crate::reader::text::MarkedTextRun by (page_obj_num, mcid).
3. Recurse the StructTreeRoot’s /K tree. For every leaf that’s either a bare integer (MCID into the parent’s /Pg page) or a <</Type /MCR /Pg n /MCID m>> dict (MCID into the named page), look up the corresponding bucket and emit its runs in accumulation order. For every kid that’s a <</Type /StructElem …>> (or an indirect ref to one), recurse into its /K.

The walker is permissive — unknown /S (structure-type) names are recursed into anyway (they’re decorative — the spec encourages user-defined types — and any text under them still belongs in logical order). /OBJR (object reference) leaves are skipped: they reference annotations, not content, so they carry no text.

Provenance

ISO 32000-1:2008 §14.6 (Marked Content), §14.7 (Logical Structure), §14.8 (Tagged PDF). No third-party PDF library was consulted.

Structs

ReadingOrderText

Output of read_in_logical_order: the run sequence plus the flag that tells the caller which path produced them.

Enums

LayoutMode

Which path produced the ReadingOrderText runs.

Functions

read_in_logical_order

Walk the document’s logical structure tree and emit text runs in reading order. Falls back to raster order when no /StructTreeRoot is present.