Layout Detection Configuration#

Docling's layout detection pipeline has two distinct configuration layers: inference-time parameters on LayoutPredictor (in docling-ibm-models) and postprocessing parameters on LayoutPostprocessor (in docling). Both are surfaced through PdfPipelineOptions.layout_options.

PdfPipelineOptions.layout_options#

The top-level entry point is PdfPipelineOptions.layout_options, which accepts a BaseLayoutOptions subclass. Two concrete types exist:

Both inherit from BaseLayoutOptions, which provides:

• keep_empty_clusters (default False) — retain clusters with no assigned text cells; useful for debugging empty figure regions 1
• skip_cell_assignment (default False) — bypass the spatial cell→cluster assignment pass entirely 2
• create_orphan_clusters (default True on LayoutOptions, False on LayoutObjectDetectionOptions) — unassigned text cells become new TEXT clusters 3

Inference-Time: LayoutPredictor parameters#

LayoutPredictor.__init__ in docling-ibm-models exposes the following parameters:

base_threshold is applied inside RTDetrImageProcessor.post_process_object_detection as an initial recall/precision knob 4. The LayoutModel currently constructs LayoutPredictor with only artifact_path, device, and num_threads — meaning base_threshold stays at its default 0.3 and blacklist_classes is empty unless the predictor is instantiated directly 5.

Postprocessing: LayoutPostprocessor constants#

After inference, LayoutPostprocessor applies per-label thresholding and overlap resolution using class-level constants — these are not runtime-configurable through PdfPipelineOptions and require source changes to adjust.

CONFIDENCE_THRESHOLDS#

Per-label confidence thresholds applied after the base_threshold gate 6:

Detections below these thresholds are filtered in _process_regular_clusters and _process_special_clusters 7 8.

LABEL_REMAPPING#

After thresholding, labels are remapped: TITLE → SECTION_HEADER 9. This is why DocItemLabel.TITLE predictions are never surfaced directly in the assembled document.

OVERLAP_PARAMS#

Three overlap-resolution parameter sets govern which cluster survives when two clusters overlap 10:

When two clusters overlap, the candidate is dropped if area_ratio ≤ area_threshold and conf_diff > conf_threshold. Picture and wrapper types require larger area differences and confidence gaps before a cluster is removed 11.

WRAPPER_TYPES and cross-type overlap#

TABLE, FORM, KEY_VALUE_REGION, and DOCUMENT_INDEX are treated as wrappers 12. Regular clusters ≥80% contained within a wrapper become its children. A KEY_VALUE_REGION overlapping a TABLE by >90% with a confidence advantage <0.1 is silently dropped in favor of the TABLE 13. Pictures with IoU >0.8 against a table are also removed 14.

Full-page pictures (bbox area > 90% of page area) are unconditionally filtered out 15.

Key Source Files#