Layout Prediction Data Structures#

Overview#

Docling's layout analysis pipeline converts page images into structured Cluster objects, which are the primary unit passed between layout detection, postprocessing, and document assembly stages. All data structures are defined in docling/datamodel/base_models.py and consumed by LayoutModel and the downstream assembler.

Core Data Structures#

Cluster#

Cluster is the central output of layout prediction. Fields:

LayoutPrediction#

LayoutPrediction is a thin container holding a list of Cluster objects for a single page. It is stored in page.predictions.layout after the layout stage completes.

Page#

Page carries all per-page state through the pipeline:

page.cells is a property that returns parsed_page.textline_cells 1.

PagePredictions#

PagePredictions holds all model outputs for a page:

• layout: LayoutPrediction | None
• tablestructure: TableStructurePrediction | None
• figures_classification: FigureClassificationPrediction | None
• equations_prediction: EquationPrediction | None
• vlm_response: VlmPrediction | None

Page Element Types#

After assembly, clusters are converted into typed BasePageElement subclasses 2:

The union type PageElement = Union[TextElement, Table, FigureElement, ContainerElement] is used throughout the assembler 3.

Raw Predictor Output → Cluster Conversion#

LayoutPredictor.predict_batch() (from docling-ibm-models) returns plain dicts with keys label, confidence, l, t, r, b (pixel coordinates, top-left origin) 4.

LayoutModel.predict_layout() converts each dict into a Cluster 5:

1. Label normalization: The label string is lower-cased and spaces/hyphens replaced with underscores to match DocItemLabel enum values (e.g., "Section-header" → "section_header").
2. BoundingBox construction: BoundingBox.model_validate(pred_item) reads the l/t/r/b pixel fields directly.
3. Cluster instantiation: id = sequential index within the page, cells = [] (filled later by postprocessor).

After raw cluster construction, LayoutPostprocessor(page, clusters, self.options).postprocess() is called immediately, returning (processed_clusters, processed_cells) 6.

Label Sets Defined on LayoutModel#

LayoutModel defines label-group constants used downstream by PageAssembleModel 7:

Postprocessing Pipeline (Summary)#

See the Layout Postprocessor article for full details. Key transformations applied to raw clusters before they become LayoutPrediction.clusters:

1. Confidence thresholding — per-label gates (0.45–0.5) filter low-confidence detections 8.
2. Label remapping — TITLE → SECTION_HEADER (so DocItemLabel.TITLE never surfaces in the document) 8.
3. Cell assignment — text cells from page.cells are spatially matched to clusters via R-tree/interval-tree indexes; unmatched cells become new TEXT clusters if create_orphan_clusters=True 9.
4. Overlap resolution — Union-Find groups overlapping clusters; one winner is selected per group using area/confidence thresholds, with separate parameters for regular, picture, and wrapper types 8.
5. Wrapper containment — clusters ≥80% inside a WRAPPER_TYPE bbox become its Cluster.children and are removed from the top-level list 8.

Key Source Files#