docling-pp-doc-layout 0.1.0__py3-none-any.whl

docling_pp_doc_layout/__init__.py

@@ -0,0 +1,3 @@
+"""A Docling plugin for PaddlePaddle PP-DocLayout-V3 model document layout detection."""
+
+__version__ = "0.1.0"

docling_pp_doc_layout/label_mapping.py

@@ -0,0 +1,34 @@
+"""Mapping from PP-DocLayout-V3 label names to docling DocItemLabel values.
+
+Every label produced here must exist in
+``docling.utils.layout_postprocessor.LayoutPostprocessor.CONFIDENCE_THRESHOLDS``
+so that the postprocessor can apply confidence filtering without a ``KeyError``.
+"""
+
+from __future__ import annotations
+
+from docling_core.types.doc import DocItemLabel
+
+LABEL_MAP: dict[str, DocItemLabel] = {
+    "abstract": DocItemLabel.TEXT,
+    "algorithm": DocItemLabel.CODE,
+    "aside_text": DocItemLabel.TEXT,
+    "chart": DocItemLabel.PICTURE,
+    "content": DocItemLabel.TEXT,
+    "doc_title": DocItemLabel.TITLE,
+    "figure_title": DocItemLabel.CAPTION,
+    "footer": DocItemLabel.PAGE_FOOTER,
+    "footnote": DocItemLabel.FOOTNOTE,
+    "formula": DocItemLabel.FORMULA,
+    "formula_number": DocItemLabel.TEXT,
+    "header": DocItemLabel.PAGE_HEADER,
+    "image": DocItemLabel.PICTURE,
+    "number": DocItemLabel.TEXT,
+    "paragraph_title": DocItemLabel.SECTION_HEADER,
+    "reference": DocItemLabel.TEXT,
+    "reference_content": DocItemLabel.TEXT,
+    "seal": DocItemLabel.PICTURE,
+    "table": DocItemLabel.TABLE,
+    "text": DocItemLabel.TEXT,
+    "vision_footnote": DocItemLabel.FOOTNOTE,
+}

docling_pp_doc_layout/model.py

@@ -0,0 +1,225 @@
+"""PP-DocLayout-V3 layout model for the docling standard pipeline.
+
+Runs PaddlePaddle PP-DocLayout-V3 locally via HuggingFace ``transformers``
+to detect document layout elements and returns ``LayoutPrediction`` objects
+that docling merges with its standard-pipeline output.
+"""
+
+from __future__ import annotations
+
+import logging
+import warnings
+from typing import TYPE_CHECKING
+
+import numpy as np
+import torch
+from docling.datamodel.base_models import BoundingBox, Cluster, LayoutPrediction, Page
+from docling.models.base_layout_model import BaseLayoutModel
+from docling.utils.accelerator_utils import decide_device
+from docling.utils.layout_postprocessor import LayoutPostprocessor
+from docling.utils.profiling import TimeRecorder
+from docling_core.types.doc import DocItemLabel
+from transformers import AutoImageProcessor, AutoModelForObjectDetection
+
+from docling_pp_doc_layout.label_mapping import LABEL_MAP
+from docling_pp_doc_layout.options import PPDocLayoutV3Options
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from docling.datamodel.accelerator_options import AcceleratorOptions
+    from docling.datamodel.document import ConversionResult
+    from docling.datamodel.pipeline_options import BaseLayoutOptions
+    from PIL import Image
+
+logger = logging.getLogger(__name__)
+
+
+class PPDocLayoutV3Model(BaseLayoutModel):
+    """Layout engine using PP-DocLayout-V3 via HuggingFace transformers."""
+
+    def __init__(
+        self,
+        artifacts_path: Path | None,
+        accelerator_options: AcceleratorOptions,
+        options: PPDocLayoutV3Options,
+        *,
+        enable_remote_services: bool = False,  # noqa: ARG002
+    ) -> None:
+        self.options = options
+        self.artifacts_path = artifacts_path
+        self.accelerator_options = accelerator_options
+
+        self._device = decide_device(accelerator_options.device)
+        logger.info(
+            "Loading PP-DocLayout-V3 model %s on device=%s",
+            options.model_name,
+            self._device,
+        )
+
+        self._image_processor = AutoImageProcessor.from_pretrained(
+            options.model_name,
+        )
+        self._model = AutoModelForObjectDetection.from_pretrained(
+            options.model_name,
+        ).to(self._device)
+        self._model.eval()
+
+        self._id2label: dict[int, str] = self._model.config.id2label
+        logger.info("PP-DocLayout-V3 model loaded successfully")
+
+    @classmethod
+    def get_options_type(cls) -> type[BaseLayoutOptions]:
+        """Return the options class for this layout model."""
+        return PPDocLayoutV3Options
+
+    def _run_inference(
+        self,
+        images: list[Image.Image],
+    ) -> list[list[dict]]:
+        """Run PP-DocLayout-V3 on a batch of PIL images.
+
+        Returns a list (per image) of lists of detection dicts with keys
+        ``label``, ``confidence``, ``l``, ``t``, ``r``, ``b``.
+        """
+        inputs = self._image_processor(images=images, return_tensors="pt")
+        inputs = {k: v.to(self._device) for k, v in inputs.items()}
+
+        with torch.no_grad():
+            outputs = self._model(**inputs)
+
+        target_sizes = [img.size[::-1] for img in images]  # (height, width)
+        results = self._image_processor.post_process_object_detection(
+            outputs,
+            target_sizes=target_sizes,
+            threshold=self.options.confidence_threshold,
+        )
+
+        batch_detections: list[list[dict]] = []
+        for result in results:
+            detections: list[dict] = []
+
+            polys = result.get("polygons") or result.get("polygon_points")
+            if polys is None:
+                polys = [None] * len(result["scores"])
+
+            for score, label_id, box, poly in zip(
+                result["scores"],
+                result["labels"],
+                result["boxes"],
+                polys,
+                strict=True,
+            ):
+                raw_label = self._id2label.get(label_id.item(), "text")
+                doc_label = LABEL_MAP.get(raw_label, DocItemLabel.TEXT)
+
+                if poly is not None and len(poly) > 0:
+                    # Flatten or handle nested points to extract min/max
+                    if isinstance(poly[0], int | float):
+                        xs = poly[0::2]
+                        ys = poly[1::2]
+                    else:
+                        xs = [pt[0] for pt in poly]
+                        ys = [pt[1] for pt in poly]
+                    x_min, x_max = min(xs), max(xs)
+                    y_min, y_max = min(ys), max(ys)
+                else:
+                    x_min, y_min, x_max, y_max = box.tolist()
+
+                detections.append({
+                    "label": doc_label,
+                    "confidence": score.item(),
+                    "l": x_min,
+                    "t": y_min,
+                    "r": x_max,
+                    "b": y_max,
+                })
+            batch_detections.append(detections)
+
+        return batch_detections
+
+    def predict_layout(
+        self,
+        conv_res: ConversionResult,
+        pages: Sequence[Page],
+    ) -> Sequence[LayoutPrediction]:
+        """Detect layout regions for a batch of document pages."""
+        pages = list(pages)
+
+        valid_pages: list[Page] = []
+        valid_images: list[Image.Image] = []
+        is_page_valid: list[bool] = []
+
+        for page in pages:
+            if page._backend is None or not page._backend.is_valid():  # noqa: SLF001
+                is_page_valid.append(False)
+                continue
+            if page.size is None:
+                is_page_valid.append(False)
+                continue
+            page_image = page.get_image(scale=1.0)
+            if page_image is None:
+                is_page_valid.append(False)
+                continue
+
+            valid_pages.append(page)
+            valid_images.append(page_image)
+            is_page_valid.append(True)
+
+        batch_detections: list[list[dict]] = []
+        if valid_images:
+            with TimeRecorder(conv_res, "layout"):
+                bs = self.options.batch_size
+                for i in range(0, len(valid_images), bs):
+                    batch = valid_images[i : i + bs]
+                    batch_detections.extend(self._run_inference(batch))
+
+        layout_predictions: list[LayoutPrediction] = []
+        valid_idx = 0
+
+        for idx, page in enumerate(pages):
+            if not is_page_valid[idx]:
+                existing = page.predictions.layout or LayoutPrediction()
+                layout_predictions.append(existing)
+                continue
+
+            detections = batch_detections[valid_idx]
+            valid_idx += 1
+
+            clusters: list[Cluster] = []
+            for ix, det in enumerate(detections):
+                cluster = Cluster(
+                    id=ix,
+                    label=det["label"],
+                    confidence=det["confidence"],
+                    bbox=BoundingBox(
+                        l=det["l"],
+                        t=det["t"],
+                        r=det["r"],
+                        b=det["b"],
+                    ),
+                    cells=[],
+                )
+                clusters.append(cluster)
+
+            processed_clusters, processed_cells = LayoutPostprocessor(page, clusters, self.options).postprocess()
+
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore",
+                    "Mean of empty slice|invalid value encountered in scalar divide",
+                    RuntimeWarning,
+                    "numpy",
+                )
+                conv_res.confidence.pages[page.page_no].layout_score = float(
+                    np.mean([c.confidence for c in processed_clusters])
+                )
+                conv_res.confidence.pages[page.page_no].ocr_score = float(
+                    np.mean([c.confidence for c in processed_cells if c.from_ocr])
+                )
+
+            prediction = LayoutPrediction(clusters=processed_clusters)
+            layout_predictions.append(prediction)
+
+        return layout_predictions

docling_pp_doc_layout/options.py

@@ -0,0 +1,46 @@
+"""Configuration model for the PP-DocLayout-V3 layout engine."""
+
+from __future__ import annotations
+
+from typing import Annotated, ClassVar, Literal
+
+from docling.datamodel.pipeline_options import LayoutOptions
+from pydantic import ConfigDict, Field
+
+
+class PPDocLayoutV3Options(LayoutOptions):
+    """Options for the PP-DocLayout-V3 layout detection engine.
+
+    Uses a HuggingFace-hosted PP-DocLayout-V3 model to detect document
+    layout elements (text, tables, figures, headers, etc.) in page images.
+
+    Attributes:
+        model_name: HuggingFace model repository ID.
+        confidence_threshold: Minimum confidence score for detections.
+    """
+
+    kind: ClassVar[Literal["ppdoclayout-v3"]] = "ppdoclayout-v3"
+
+    model_name: Annotated[
+        str,
+        Field(description="HuggingFace model repository ID for PP-DocLayout-V3."),
+    ] = "PaddlePaddle/PP-DocLayoutV3_safetensors"
+
+    confidence_threshold: Annotated[
+        float,
+        Field(
+            ge=0.0,
+            le=1.0,
+            description="Minimum confidence score to keep a detection.",
+        ),
+    ] = 0.5
+
+    batch_size: Annotated[
+        int,
+        Field(
+            gt=0,
+            description="Batch size for layout inference.",
+        ),
+    ] = 8
+
+    model_config = ConfigDict(extra="forbid")

docling_pp_doc_layout/plugin.py

@@ -0,0 +1,12 @@
+"""Docling plugin entry point registering the PP-DocLayout-V3 layout engine."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from docling_pp_doc_layout.model import PPDocLayoutV3Model
+
+
+def layout_engines() -> dict[str, Any]:
+    """Return layout engine classes provided by this plugin."""
+    return {"layout_engines": [PPDocLayoutV3Model]}

docling_pp_doc_layout-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: docling-pp-doc-layout
+Version: 0.1.0
+Summary: A Docling plugin for PaddlePaddle PP-DocLayout-V3 model document layout detection.
+Project-URL: Homepage, https://github.com/DCC-BS/docling-pp-doc-layout
+Project-URL: Repository, https://github.com/DCC-BS/docling-pp-doc-layout
+Project-URL: Issues, https://github.com/DCC-BS/docling-pp-doc-layout/issues
+Project-URL: Changelog, https://github.com/DCC-BS/docling-pp-doc-layout/releases
+Author-email: Yanick Schraner <yanick.schraner@bs.ch>, Tobias Bollinger <tobias.bollinger@bs.ch>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: docling>=2.73
+Requires-Dist: torch
+Requires-Dist: transformers>=5.1.0
+Description-Content-Type: text/markdown
+
+# docling-pp-doc-layout
+
+A [Docling](https://github.com/docling-project/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](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3), enabling high-accuracy, instance segmentation-based layout analysis with polygon bounding box support, properly processed in optimized batches for enterprise scalability.
+
+---
+
+<p align="center">
+  <a href="https://github.com/DCC-BS/docling-pp-doc-layout">GitHub</a>
+  &nbsp;|&nbsp;
+  <a href="https://pypi.org/project/docling-pp-doc-layout/">PyPI</a>
+</p>
+
+---
+
+[![PyPI version](https://img.shields.io/pypi/v/docling-pp-doc-layout.svg)](https://pypi.org/project/docling-pp-doc-layout/)
+[![Python versions](https://img.shields.io/pypi/pyversions/docling-pp-doc-layout.svg)](https://pypi.org/project/docling-pp-doc-layout/)
+[![License](https://img.shields.io/github/license/DCC-BS/docling-pp-doc-layout)](https://github.com/DCC-BS/docling-pp-doc-layout/blob/main/LICENSE)
+[![CI](https://github.com/DCC-BS/docling-pp-doc-layout/actions/workflows/main.yml/badge.svg)](https://github.com/DCC-BS/docling-pp-doc-layout/actions/workflows/main.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Coverage](https://codecov.io/gh/DCC-BS/docling-pp-doc-layout/graph/badge.svg)](https://codecov.io/gh/DCC-BS/docling-pp-doc-layout)
+
+
+## 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.
+
+```mermaid
+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
+
+```bash
+# 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.
+
+```python
+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
+
+The `PPDocLayoutV3Options` dataclass gives you full control over the engine:
+
+| Parameter               | Type    | Default | Description |
+|-------------------------|---------|---------|-------------|
+| `batch_size`            | `int`   | 8       | How many pages to process per single step. Decrease to lower memory usage; Increase to speed up processing of large documents. |
+| `confidence_threshold`  | `float` | 0.5     | The minimum confidence score (0.0 - 1.0) required to keep a layout detection cluster. |
+| `model_name`            | `str`   | `"PaddlePaddle/PP-DocLayoutV3_safetensors"` | HuggingFace repository ID. Allows overriding if you host your local copy or a fine-tuned version. |
+
+
+## Development
+
+If you wish to contribute or modify the plugin locally:
+
+```bash
+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](LICENSE) © DCC Data Competence Center

docling_pp_doc_layout-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+docling_pp_doc_layout/__init__.py,sha256=5oubMsuaB2fR-gWT6HCmKZN6GGntqFHq4CpbODzCJws,112
+docling_pp_doc_layout/label_mapping.py,sha256=jXBBwfYIWLOtQW5qdtm1HYdV0Is7THFQLu450Xg-vZA,1207
+docling_pp_doc_layout/model.py,sha256=FSvZg5aNpNI5eQn59h2grtlOcDjZIjBAOYlkX20dGHY,8110
+docling_pp_doc_layout/options.py,sha256=oN6xtSP6fZaWRhtSqXWB28HfpOuBgAC7Gf8H4ExebXs,1302
+docling_pp_doc_layout/plugin.py,sha256=ByMR-eUTYtZ0bjc0DPa1I_VlSb8PLmElDgTvBPYTztk,358
+docling_pp_doc_layout/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+docling_pp_doc_layout-0.1.0.dist-info/METADATA,sha256=vT7CeQv9gO48AWEjV1xN5zZiP-duWXsEydpAShUTJdM,6203
+docling_pp_doc_layout-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+docling_pp_doc_layout-0.1.0.dist-info/entry_points.txt,sha256=GWD1I-zcU5f4ZRLrUVBSb0VpeUcB5o5Q6_xJv78vnzQ,77
+docling_pp_doc_layout-0.1.0.dist-info/licenses/LICENSE,sha256=APpdFXym3_5C78pFAfnlLvmP7umPBWYpQ2MKidnoRuw,1091
+docling_pp_doc_layout-0.1.0.dist-info/RECORD,,

docling_pp_doc_layout-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

docling_pp_doc_layout-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[docling.plugins]
+layout_model = docling_pp_doc_layout.plugin:layout_engines

docling_pp_doc_layout-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Data Competence Center Basel-Stadt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.