[yashikam19]

Summary

Since #3710 (2.116.0), bitmap_area_threshold raises a ValidationError, also with do_ocr=False. No OcrMode can replace it: FULL_PAGE OCRs every page, and DEFAULT OCRs every cluster that touches a bitmap, so pages with only logos or photos still get OCR.

This PR adds OcrOptions.page_bitmap_area_threshold (off by default). A page is OCRed only when bitmaps cover at least that fraction of it. Other pages skip OCR and keep their native text, whatever the mode.

TesseractCliOcrOptions(mode=OcrMode.FULL_PAGE, page_bitmap_area_threshold=0.97)

docling mixed.pdf --ocr-mode full_page --ocr-option page_bitmap_area_threshold=0.97

The change:

• pipeline_options.py: the new field (float | None, 0.0-1.0). The old bitmap_area_threshold works again, in the constructor and on assignment, with a DeprecationWarning, as force_full_page_ocr does.
• base_ocr_model.py: get_ocr_rects() returns no rects for a page below the threshold, so every engine supports it. In FULL_PAGE mode, a skipped page keeps its PDF line, word and char cells.
• page_preprocessing_model.py: in FULL_PAGE mode, native text is still extracted when the threshold is set.
• auto_ocr_model.py: OcrAutoModel passes the field to the engine it selects.
• Docs: a new section in docs/concepts/OCR.md and an example in the usage skill.

Issue resolved by this Pull Request:
Resolves #4834

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

Review evidence:

• Before and after, on a 3-page PDF made from test files, with Tesseract:

  page	bitmaps	main, FULL_PAGE	main, DEFAULT	this branch, FULL_PAGE + 0.97
  2206.01062.pdf p1, programmatic	1%	full-page OCR	OCR of 16% of the page	no OCR, native text
  picture_classification.pdf p1, pictures	15%	full-page OCR	OCR of 17% of the page	no OCR, native text
  ocr_test.pdf p1, scan	100%	full-page OCR	OCR of 8% of the page	full-page OCR

  The old bitmap_area_threshold=0.97 gives the last column, with the warning.

• Reference data: no change. The option is off by default.

• Tests: tests/test_ocr_page_bitmap_area_threshold.py (13 tests, real PDFs, default backend) covers the deprecated field (constructor, assignment, warning shown at the caller's line), pages above and below the threshold, and native lines, words and chars kept in FULL_PAGE mode.

• Commands: uv run pytest on the new tests and the OCR option, rect and cell tests: 207 passed. make validate: passed.

• Scope:

  • The old field sets only the threshold, not the mode. To OCR scans in full, as before OcrMode, also set mode=OcrMode.FULL_PAGE.
  • Saved configs from before 2.116.0 contain bitmap_area_threshold: 0.05. They now skip OCR on pages with less than 5% bitmaps, as they did then.
  • No test covers the OcrAutoModel change, because it would load a real OCR engine.

[github-actions]

✅ DCO Check Passed

Thanks @yashikam19, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit dc3c8309c6. The analysis read the diff only. It did not run code from this pull request.

This pull request adds page_bitmap_area_threshold to OcrOptions. Pages with bitmap coverage below this threshold skip OCR and keep their native text.

CI safety: no concern found. A maintainer must still approve CI.

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4654	open	changes the same code	related: PR #4654 touches OCR options and models to replace broken text layers with OCR, but it does not add page bitmap area filtering.
#3710	merged	referenced as #3710	related: PR #3710 introduced OCR modes and removed the previous bitmap_area_threshold, which this pull request restores as page_bitmap_area_threshold.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): blocker found

This review covers the full diff at cb2853c283. It read the code and did not run it.

The PR adds page_bitmap_area_threshold to skip OCR on pages with low bitmap coverage. When mode=OcrMode.FULL_PAGE is used, post_process_cells deletes native word_cells and char_cells on pages that skip OCR.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the changes since cb2853c283 at 07260b0df9. It read the code and did not run it.

I found no blocking defect in the update. The earlier blocker is fixed: post_process_cells now filters word and char cells only when OCR ran on the page. I could not check the real-PDF coverage values that the tests rely on (full coverage for ocr_test.pdf, about 15% for picture_classification.pdf).

Earlier findings

• fixed (blocker): FULL_PAGE mode clears native word and character cells on skipped pages

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

❌ Patch coverage is 94.87179% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/datamodel/pipeline_options.py	89.47%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!