docling-project / docling-project/docling
Add OCR option to skip pages with a usable text layer
- Dominant language
- Python
- Stars
- 66.4k
- Forks
- 4.8k
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 84
Description
### Requested feature
Some PDFs contain both image resources and a usable native text layer.
Today, with `do_ocr=True`, OCR region selection is driven by bitmap coverage. That is useful for scanned PDFs, but it can do unnecessary OCR on born-digital PDFs where the text layer is already sufficient. It can also introduce noisier OCR text when the native text should be preferred.
I would like an opt-in OCR option that skips OCR for pages where Docling has already parsed a usable text layer, while preserving OCR for scanned or sparse-text pages.
Proposed API:
```python
OcrOptions(skip_text_layer_pages=True)
```
Expected behavior:
- default behavior remains unchanged
- `force_full_page_ocr=True` still takes precedence
- pages with enough native text cells return no OCR rectangles
- sparse text, such as a footer/header on a scanned page, does not suppress OCR
- existing bitmap coverage behavior remains unchanged for pages without a usable text layer
This should live in Docling's OCR rectangle selection path so it works for all OCR engines and all callers.
Related context: #2029 and #2036.
### Alternatives
A caller can preflight PDFs outside Docling and set `do_ocr=False` for the whole document. That works for some applications, but it is coarse: one mixed PDF can contain both born-digital pages and scanned pages.
Another option is `do_ocr="auto"`, but that changes the type and meaning of an existing boolean field and overlaps with `ocr_preset="auto"`, which already refers to OCR engine selection.
Contributor guide
Assessment
This issue has not been assessed yet.