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.5,  # 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.

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