docling-pp-doc-layout

A Docling plugin that provides document layout detection using the PaddlePaddle PP-DocLayout-V3 model.

This plugin seamlessly integrates with Docling's standard pipeline to replace the default layout models with PP-DocLayout-V3, enabling high-accuracy, instance segmentation-based layout analysis with polygon bounding box support, properly processed in optimized batches for enterprise scalability.

GitHub  |  PyPI

Overview

docling-pp-doc-layout provides the PPDocLayoutV3Model layout engine for Docling. It automatically registers itself into Docling's plugin system upon installation. When configured in a Docling DocumentConverter, it intercepts page images, batches them, and infers document structural elements (text, tables, figures, headers, etc.) using HuggingFace's transformers library.

Key Features:

• High Accuracy Layout Parsing: Uses the RT-DETR instance segmentation framework.
• Polygon Conversion: Gracefully flattens complex polygon masks to Docling-compatible bounding boxes.
• Enterprise Scalability: Configurable batch sizing avoids out-of-memory (OOM) errors on large documents.

Architecture & Integration

When you install this package, Docling discovers it automatically through standard Python package entry points.

flowchart TD
    A[Docling DocumentConverter] --> B[PdfPipeline]

    subgraph Plugin System
    C[Docling PluginManager] -.->|Discovers via entry-points| D[docling-pp-doc-layout]
    D -.->|Registers| E[PPDocLayoutV3Model]
    end

    B -->|Initialization| C
    B -->|Predict Layout Pages| E
    E -->|Batched Tensors| F[HuggingFace AutoModel]
    F -->|Raw Polygons / Boxes| E
    E -->|Post-processed Clusters & BoundingBoxes| B

Requirements

• Python 3.13+
• docling>=2.73
• transformers>=5.1.0
• torch

Installation

# with uv (recommended)
uv add docling-pp-doc-layout

# with pip
pip install docling-pp-doc-layout

Usage

Using docling-pp-doc-layout is exactly like configuring standard Docling options.

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling_pp_doc_layout.options import PPDocLayoutV3Options

# 1. Define Pipeline Options
pipeline_options = PdfPipelineOptions()

# 2. Configure our custom PPDocLayoutV3Options
pipeline_options.layout_options = PPDocLayoutV3Options(
    batch_size=8,  # Tweak for GPU VRAM usage
    confidence_threshold=0.3,  # Filter low-confidence detections
    model_name="PaddlePaddle/PP-DocLayoutV3_safetensors",  # Target HuggingFace model repo
)

# 3. Create the converter
converter = DocumentConverter(format_options={"pdf": PdfFormatOption(pipeline_options=pipeline_options)})

# 4. Convert Document
result = converter.convert("path/to/your/document.pdf")
print("Converted elements:", len(result.document.elements))

Configuration Options

All options can be set via environment variables (useful for Docker / Compose deployments) or programmatically via PPDocLayoutV3Options. Explicit constructor arguments always take precedence over environment variables.

Environment variables

Boolean variables accept true, 1, yes (case-insensitive) as truthy values; any other value is treated as false.

PPDocLayoutV3Options

The PPDocLayoutV3Options class gives you full control over the engine:

create_orphan_clusters, keep_empty_clusters and skip_cell_assignment configure docling's layout post-processing. With docling 2.116 or newer, docling runs that step itself after OCR (OCR only runs inside layout regions), so the plugin returns the raw detections. With older docling the plugin post-processes its detections itself.

Labels and lists

PP-DocLayout-V3 has 25 classes. Its HuggingFace config.json merges five of them (header_image and footer_image into "header"/"footer", display_formula and inline_formula into "formula", vertical_text into "text"), so the plugin maps the model's own class list by class id. Inline formulas stay part of their text line, logos in page headers and footers are page furniture, and bibliography entries (reference_content) become list items; the block around them is dropped so docling keeps the entries.

The model has no list-item class. Without help, docling builds no lists from its layout: bullet points come out as separate paragraphs starting with "·". list_detection restores them:

• rules (default): after OCR, when the text of every region is known, text regions whose lines start with a list marker become list items, and a region holding several items is split. Markers are bullet glyphs (including Symbol/Wingdings bullets from Word documents), enumerators that form a sequence (1./2., a)/b), (i)/(ii); a lone 12. März stays text) and small isolated marks left of a line where OCR read nothing (bullets that OCR drops on scans or that the PDF draws as shapes). A one-column table whose lines all start with a bullet becomes a list. Table-of-contents lines, paragraph numbers such as (1) and EU amendment markers such as ►M3 are not list markers. No extra model; the time cost is negligible.
• heron: additionally runs docling's own layout model (Heron) next to PP-DocLayout-V3 and adopts its list-item boxes inside PP text regions; list items whose enumerator has no neighbour are turned back into text. Better on scans where OCR garbles the markers, about 5-30 % slower (a second layout model).
• off: no list detection (bibliography entries still become list items; that is the label mapping).

On a benchmark with exact ground truth (list pages born-digital and scanned, traps such as numbered headings, dates and amounts) and 14 real documents:

List detection runs after OCR, where docling has no plugin interface: the plugin wraps LayoutPostprocessor.postprocess for the pages it laid out (docling >= 2.116). The wrapper never breaks a conversion; if docling's internals change or detection fails, it logs a warning and keeps docling's regions (lists then stay plain text).

Development

If you wish to contribute or modify the plugin locally:

git clone https://github.com/DCC-BS/docling-pp-doc-layout.git
cd docling-pp-doc-layout

# Install dependencies and pre-commit hooks
make install

# Run checks (ruff, ty) and tests (pytest)
make check
make test

License

MIT © DCC Data Competence Center