# PP-DocLayoutV3
PP-DocLayoutV3 is PaddleOCR's document layout detector. It finds the regions of a page (text, titles, tables, figures, formulas, headers, footers, seals and more) and ranks them in reading order. LibreYOLO ports it as a detect family that needs no transformers or PaddlePaddle runtime.
Tasks: Detection. Install: pip install libreyolo.
Verified against LibreYOLO v1.8.0.

## Install

PP-DocLayoutV3 needs no optional extra. It is pure PyTorch and everything it
imports is in the base install.

```bash
pip install libreyolo
```

## Predict

Weights download from `LibreYOLO/LibrePPDocLayoutV3l` on first use.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibrePPDocLayoutV3l.pt")
result = model("page.png", conf=0.5)    # the upstream pipeline's threshold

for order, box, cls, score in zip(
    result.reading_order, result.boxes.xyxy, result.boxes.cls, result.boxes.conf
):
    print(int(order), result.names[int(cls)], round(float(score), 3), box.tolist())
```

**CLI**

```bash
libreyolo predict model=LibrePPDocLayoutV3l.pt source=page.png conf=0.5 save=True
```

**Official weights**

```python
from libreyolo import LibreYOLO

# Upstream's model.safetensors loads too: it is converted once and a
# LibreYOLO checkpoint is written beside it.
model = LibreYOLO("model.safetensors")
```

`Results.boxes` holds xyxy boxes on the original page, confidences and class
ids over 25 layout classes. Rows are sorted in reading order, and
`Results.reading_order` is a one-based int64 vector aligned with the boxes. It
slices with `results[i]` like `track_id` and appears as `reading_order` in
`Results.summary()` rows. Ranks are computed among the regions kept at `conf`;
a `classes=` filter or a `max_det` cut keeps the surviving ranks, so the values
can have gaps.

The upstream pipeline uses `conf=0.5`; LibreYOLO's default `conf=0.25` keeps
more low-confidence regions. As upstream, scores are per-class sigmoids and the
top 300 (query, class) pairs are kept, so one region can be reported with two
labels. No NMS is applied.

Classes: `abstract`, `algorithm`, `aside_text`, `chart`, `content`,
`display_formula`, `doc_title`, `figure_title`, `footer`, `footer_image`,
`footnote`, `formula_number`, `header`, `header_image`, `image`,
`inline_formula`, `number`, `paragraph_title`, `reference`,
`reference_content`, `seal`, `table`, `text`, `vertical_text`,
`vision_footnote`.

The same port runs the layout stage of [Falcon OCR](/docs/models/falcon-ocr)
with `layout=True`.

## Variants

One size, `l`: an RT-DETR-style set-prediction detector with an HGNetV2-L
backbone, mask-enhanced query initialisation and a global-pointer head that
scores every pair of regions. Input is a fixed 800x800 canvas (stretch resize,
RGB in `[0, 1]`, no normalization). It runs on CPU, CUDA and MPS; on MPS the
positional encoding is computed in float32, so results can differ in the last
bits.

Against the Apache-2.0 PyTorch reference in transformers, on CUDA in fp32 with
the same input tensor, logits, boxes, reading-order logits and masks match
exactly on three real pages and a random tensor. Training is not offered: it
needs reading-order and per-region mask supervision that LibreYOLO's detect
datasets do not carry. The per-region polygons upstream derives from the mask
branch are not exposed.

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | Axelera | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Detection | yes | yes | yes | yes | yes |  |  |  |  |  |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

ONNX (opset 17) and TorchScript, fixed 800x800, FP32. The graph outputs
`pred_logits`, `pred_boxes` and `order_votes`; exported backends return the
same `Results`, including `reading_order`.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibrePPDocLayoutV3l.pt")
model.export(format="onnx")             # fixed 800x800, FP32
model.export(format="torchscript")
```

**CLI**

```bash
libreyolo export model=LibrePPDocLayoutV3l.pt format=onnx
```

**Use the exported file**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibrePPDocLayoutV3l.onnx")
result = model("page.png", conf=0.5)
print(result.reading_order)
```

## Checkpoints

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibrePPDocLayoutV3l.pt` | 800 | Detection | apache-2.0 |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: PP-DocLayoutV3, PaddlePaddle Authors
- Upstream license: Apache-2.0
- Upstream source: https://github.com/PaddlePaddle/PaddleOCR
- LibreYOLO code: Apache-2.0
- Weights: Apache-2.0, republished at https://huggingface.co/LibreYOLO
- Interpretation: Apache-2.0 is a permissive license, so the PP-DocLayoutV3 weights and LibreYOLO's port can be used in commercial and closed-source products. Redistributing them means keeping the license text and attribution notices, and the license grants a patent license. LibreYOLO's network is an inference-only PyTorch port of the Apache-2.0 reference in Hugging Face Transformers (v5.22.1, commit 446a570e62b04a89ea001604ada7366baac2ea67, Copyright The PaddlePaddle Team and The HuggingFace Inc. team) and needs no transformers runtime (libreyolo/models/ppdoclayoutv3/NOTICE). The checkpoint is converted from PaddlePaddle/PP-DocLayoutV3_safetensors at revision e4f489dc536556fc1be02b973ba06756e0d4a2ac, declared Apache-2.0 by its model card; that repository ships no LICENSE file, so the mirror at LibreYOLO/LibrePPDocLayoutV3l carries the Apache-2.0 text of the PaddleOCR project. Conversion only strips a key prefix and adds metadata; learned parameters are unchanged, and the mirror is not gated.

PP-DocLayoutV3 is Apache-2.0, code and weights, by the
[PaddlePaddle Authors](https://github.com/PaddlePaddle/PaddleOCR). Commercial
use is allowed. The checkpoint is converted from
`PaddlePaddle/PP-DocLayoutV3_safetensors` by stripping a key prefix and adding
metadata; learned parameters are unchanged and the mirror is not gated.

## Citation

```bibtex
@misc{cui2026rtdoclayoutrealtimeendtoenddocument,
      title={RT-DocLayout: Real-Time End-to-End Document Layout Analysis with Reading Order in the Wild}, 
      author={Cheng Cui and Tingquan Gao and Xueqing Wang and Changda Zhou and Hongen Liu and Ting Sun and Yubo Zhang and Zelun Zhang and Jiaxuan Liu and Manhui Lin and Yue Zhang and Suyin Liang and Yiqing Xiang and Yi Liu},
      year={2026},
      eprint={2606.23344},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2606.23344}, 
}
```

Copied from https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors#citation
