Skip to content

feat(ocr): improve Tesseract OCR reliability - #4942

Open
BBC-Esq wants to merge 1 commit into
docling-project:mainfrom
BBC-Esq:feat/ocr-tesseract-reliability
Open

feat(ocr): improve Tesseract OCR reliability#4942
BBC-Esq wants to merge 1 commit into
docling-project:mainfrom
BBC-Esq:feat/ocr-tesseract-reliability

Conversation

@BBC-Esq

@BBC-Esq BBC-Esq commented Oct 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

This PR makes both Tesseract engines (tesseract and tesserocr) more reliable on colour pages and on rotated text, and it makes the tesseract engine report its failures. It has four changes. I measured each one against main on public PDFs and on Docling's own test PDFs, on Windows 10 with Python 3.12, the Tesseract 5.5.0 CLI and tesserocr 2.10.0 (Tesseract 5.5.2).

Before and after. With forced (full-page) OCR, on a page with yellow highlighting, Tesseract found only 45% of the words (33% of the highlighted ones) in the colour image, against 97% (99% of the highlighted ones) in a grayscale copy. The table shows the share of the ground-truth words that appear in Docling's Markdown export, for all words / for the words under a highlighter mark:

Sample OCR mode main This PR
Newtown draft charter, page 23 as a scanned image full page 45.4% / 33.0% 97.4% / 99.3%
Newtown draft charter, all 47 pages full page 83.7% / 93.8% 96.8% / 99.5%
Newtown colour-code legend full page 97.3% / 0% 100% / 100%
Homer council slide, text on coloured boxes full page 94.1% 95.3%
Scanned court exhibit, page 3 full page 96.2% / 100% 96.2% / 100%
Newtown draft charter, page 23 as a scanned image default 98.4% / 99.6% 99.2% / 100%
Scanned court exhibit, page 3 default 96.2% / 100% 96.2% / 100%

No sample got worse. Forced OCR (OcrMode.FULL_PAGE, --force-ocr) gains the most. The default mode reads smaller layout regions, and there the colour effect was small in these tests.

1. Grayscale input. Tesseract thresholds a colour image channel by channel. A yellow highlighter mark is dark in the blue channel, so it can turn into a black block that hides its text. Both engines now convert each OCR region to grayscale before orientation detection and OCR. Direct Tesseract runs on Docling's 216-DPI renders, with the OCR command that the tesseract engine runs on main (all words / highlighted words):

Sample Colour Grayscale
Newtown draft charter, 36 highlighted pages (20,314 words, 5,109 highlighted) 82.6% / 71.1% 97.6% / 99.5%
Same document, page 23 46.2% / 33.0% 99.8% / 100%
Newtown colour-code legend 97.3% / 0% 100% / 100%
Scanned court exhibit, page 3 (19 highlighted words) 89.9% / 57.9% 95.9% / 100%
Homer council slide 100% 100%

Grayscale was better on 33 of the 36 charter pages, equal on 2, and worse on 1 (page 46: 95.6% → 95.0%). On a synthetic page with three highlighted lines, the colour image gave 21% of the highlighted words and the grayscale image 100%, with each of five highlighter colours (three yellows, green and pink). With six highlighted lines it was 12% against 100%. A single highlighted line was read in full either way. On 75 ordinary pages from Docling's test PDFs (40,358 words, both arms with the DPI from change 2), grayscale still gained: 91.14% → 91.77%, with 17 pages better and 8 worse.

Grayscale has a cost. In colour mode, Tesseract treats a pixel as text when any one channel is dark, so it reads light text on a strongly coloured box and light, saturated text on white; grayscale lowers the contrast of both. On a synthetic page with black body text, lines in orange, yellow, pink or light blue were read in full in colour but only 12–17% in grayscale, while red, blue, green, cyan and grey lines were read in full either way. On the real pages, the largest loss was the white labels on coloured boxes in Figure 4 of arXiv 2203.01017 (page 5): 31 words in direct Tesseract output. Those labels are inside a picture, so they do not reach the Markdown export on main or on this branch.

I also tried Tesseract's Sauvola thresholding (-c thresholding_method=2) instead of plain grayscale, both with the DPI. It reads the orange, pink and light-blue lines (not the yellow ones), and it matched grayscale on the real pages: 97.6% on the highlighted charter pages, 91.7% against 91.8% on the 75 ordinary pages, and 99.1% against 97.7% on the slide, exhibit and legend. But it made more of the ordinary pages worse than main (16 against 8), so this PR keeps plain grayscale.

2. Resolution. Docling renders OCR regions at 72 DPI × scale (216 DPI by default) but did not tell Tesseract, so Tesseract estimated the resolution from the text size; on 216-DPI renders it estimated, for example, 229 and 272 DPI. Both engines now pass the real value: --dpi for the CLI and SetSourceResolution for tesserocr. The effect is a small net gain, and it is mixed page by page (both arms with grayscale input):

Test set Without the DPI With the DPI Better / worse
202 layout regions from 16 documents, 41,590 words 90.95% 91.61% 17 / 10
75 full pages from 14 documents, 40,358 words 91.62% 91.77% 10 / 8

The largest gain was a table region, from 62.5% to 92.1% of its 331 words. The largest losses were 14 words in one region and 9 words on one page. On the Homer slide above, the DPI cost 4 words in Docling (97.6% with grayscale alone, 95.3% with both). I recommend it all the same: the net effect is positive in both sets, the largest single effect is a gain, and Tesseract no longer has to guess a resolution that Docling knows.

3. Orientation confidence. Docling runs Tesseract's orientation and script detection (OSD) on every OCR region, and it rotated the region on any detection. OSD reports its orientation confidence as the margin between its best and second-best orientation, so a value near 0 is a close call. The new option orientation_confidence_threshold (default 1.0) on TesseractCliOcrOptions and TesseractOcrOptions ignores detections below it; 0 restores the old behaviour. I ran OSD on 277 layout regions from 16 documents and on 90 full pages from 17 documents, as rendered (all upright) and rotated by 90°, 180° and 270°:

Layout regions Full pages
Upright text turned the wrong way, main 2 of 214 (confidence 0.06 and 1.17) not measured
Upright text turned the wrong way, this PR 1 of 213 (confidence 0.0, now ignored) 0 of 90
Rotated copies corrected, threshold 0 (old behaviour) 632 of 639 268 of 270
Rotated copies corrected, threshold 1.0 (new default) 619 of 639 265 of 270
Rotated copies corrected, threshold 14 (OCRmyPDF's page default) 392 of 639 220 of 270

The counts cover the regions and copies on which OSD returned a result. A threshold of 14 would drop 38% of the correct region rotations and 18% of the correct page rotations. With 1.0, the rotated copies that are no longer corrected hold 84 of the 114,209 words that Tesseract reads in all correctly rotated copies (0.07%), while the region that OSD turned the wrong way would have lost all 11 of its words. A region that is really sideways, the arXiv identifier in the margin of a paper (confidence 2.97), is still rotated and read in full.

4. Failures are reported. When Tesseract failed on a region in the tesseract engine, Docling only logged an error, and the document still ended as SUCCESS without that text. Now the engine also adds an ErrorItem for the page (DoclingComponentType.MODEL, FailureCategory.INFERENCE_FAILURE), the same way the KServe OCR engine reports a failed region, so the document ends as PARTIAL_SUCCESS. The engine now keeps Tesseract's stderr, so the error carries Tesseract's own message. Tesseract exits with 0 on blank, tiny and all-black regions, so the error marks real failures only. In the tesserocr engine, a failure raises an exception, which the pipeline already records for the page. None of the reference conversions reported an error.

An empty lang list still skips, without an error, a region whose script OSD cannot detect. OSD gives up on regions with too few characters, mostly pictures, and reporting those skips would turn 3 of 5 ordinary test documents (converted with lang=[]) into PARTIAL_SUCCESS. So this PR leaves that case unchanged.

Related pull requests:

Review evidence:

  • Reference data: unchanged. tests/test_e2e_ocr_conversion.py passes against the existing ground truth for every Tesseract configuration of both engines (default, layout-regions and full-page modes, and full-page mode with lang=[]), and for EasyOCR and RapidOCR.
  • New tests: 6 unit tests in tests/test_tesseract_ocr_cli_model.py and tests/test_tesseract_ocr_model.py (grayscale input, the DPI, the threshold and the error record) fail on main and pass here. tests/test_e2e_tesseract_highlighted_text.py OCRs a synthetic page with three highlighted lines (tests/data/ocr/sources/highlighted_text.png, 63 KB, regenerated by running the test module); on main, both engines miss 26 of its 42 highlighted words.
  • tests/test_e2e_rotated_ocr.py: same result as main (90° and 270° pass; 180° is still the expected failure of OCR-recognized text is dropped from output for 180°-rotated images, even with force_full_page_ocr #3839).
  • One run of the tests above plus test_tesseract_ocr_cli_lang, test_options, test_service_datamodels, test_ocr_options_force_full_page, test_ocr_engine_language_mapping, test_ocr_language and test_backend_webp: 306 passed, 6 skipped, 2 xfailed (the 180° cases).
  • Checks: the prek hooks (ruff, ruff format, ty, tach), tach module coverage and max-lines pass.
  • Not run: the full test suite, Linux, macOS and Tesseract 4.

Samples. The ground truth is the PDF text layer, or a manual transcription for image-only pages. The highlighted words are the words under a yellow highlighter mark. The public sources:

Checklist:

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

@BBC-Esq
feat(ocr): improve Tesseract OCR reliability
afacb27 
This PR makes both Tesseract engines (`tesseract` and `tesserocr`) more reliable on colour pages and on rotated text, and it makes the `tesseract` engine report its failures. It has four changes. I measured each one against `main` on public PDFs and on Docling's own test PDFs, on Windows 10 with Python 3.12, the Tesseract 5.5.0 CLI and tesserocr 2.10.0 (Tesseract 5.5.2).

**Before and after.** With forced (full-page) OCR, on a page with yellow highlighting, Tesseract found only 45% of the words (33% of the highlighted ones) in the colour image, against 97% (99% of the highlighted ones) in a grayscale copy. The table shows the share of the ground-truth words that appear in Docling's Markdown export, for all words / for the words under a highlighter mark:

| Sample | OCR mode | `main` | This PR |
|---|---|---|---|
| Newtown draft charter, page 23 as a scanned image | full page | 45.4% / 33.0% | 97.4% / 99.3% |
| Newtown draft charter, all 47 pages | full page | 83.7% / 93.8% | 96.8% / 99.5% |
| Newtown colour-code legend | full page | 97.3% / 0% | 100% / 100% |
| Homer council slide, text on coloured boxes | full page | 94.1% | 95.3% |
| Scanned court exhibit, page 3 | full page | 96.2% / 100% | 96.2% / 100% |
| Newtown draft charter, page 23 as a scanned image | default | 98.4% / 99.6% | 99.2% / 100% |
| Scanned court exhibit, page 3 | default | 96.2% / 100% | 96.2% / 100% |

No sample got worse. Forced OCR (`OcrMode.FULL_PAGE`, `--force-ocr`) gains the most. The default mode reads smaller layout regions, and there the colour effect was small in these tests.

**1. Grayscale input.** Tesseract thresholds a colour image channel by channel. A yellow highlighter mark is dark in the blue channel, so it can turn into a black block that hides its text. Both engines now convert each OCR region to grayscale before orientation detection and OCR. Direct Tesseract runs on Docling's 216-DPI renders, with the OCR command that the `tesseract` engine runs on `main` (all words / highlighted words):

| Sample | Colour | Grayscale |
|---|---|---|
| Newtown draft charter, 36 highlighted pages (20,314 words, 5,109 highlighted) | 82.6% / 71.1% | 97.6% / 99.5% |
| Same document, page 23 | 46.2% / 33.0% | 99.8% / 100% |
| Newtown colour-code legend | 97.3% / 0% | 100% / 100% |
| Scanned court exhibit, page 3 (19 highlighted words) | 89.9% / 57.9% | 95.9% / 100% |
| Homer council slide | 100% | 100% |

Grayscale was better on 33 of the 36 charter pages, equal on 2, and worse on 1 (page 46: 95.6% → 95.0%). On a synthetic page with three highlighted lines, the colour image gave 21% of the highlighted words and the grayscale image 100%, with each of five highlighter colours (three yellows, green and pink). With six highlighted lines it was 12% against 100%. A single highlighted line was read in full either way. On 75 ordinary pages from Docling's test PDFs (40,358 words, both arms with the DPI from change 2), grayscale still gained: 91.14% → 91.77%, with 17 pages better and 8 worse.

Grayscale has a cost. In colour mode, Tesseract treats a pixel as text when any one channel is dark, so it reads light text on a strongly coloured box and light, saturated text on white; grayscale lowers the contrast of both. On a synthetic page with black body text, lines in orange, yellow, pink or light blue were read in full in colour but only 12–17% in grayscale, while red, blue, green, cyan and grey lines were read in full either way. On the real pages, the largest loss was the white labels on coloured boxes in Figure 4 of arXiv 2203.01017 (page 5): 31 words in direct Tesseract output. Those labels are inside a picture, so they do not reach the Markdown export on `main` or on this branch.

I also tried Tesseract's Sauvola thresholding (`-c thresholding_method=2`) instead of plain grayscale, both with the DPI. It reads the orange, pink and light-blue lines (not the yellow ones), and it matched grayscale on the real pages: 97.6% on the highlighted charter pages, 91.7% against 91.8% on the 75 ordinary pages, and 99.1% against 97.7% on the slide, exhibit and legend. But it made more of the ordinary pages worse than `main` (16 against 8), so this PR keeps plain grayscale.

**2. Resolution.** Docling renders OCR regions at 72 DPI × `scale` (216 DPI by default) but did not tell Tesseract, so Tesseract estimated the resolution from the text size; on 216-DPI renders it estimated, for example, 229 and 272 DPI. Both engines now pass the real value: `--dpi` for the CLI and `SetSourceResolution` for tesserocr. The effect is a small net gain, and it is mixed page by page (both arms with grayscale input):

| Test set | Without the DPI | With the DPI | Better / worse |
|---|---|---|---|
| 202 layout regions from 16 documents, 41,590 words | 90.95% | 91.61% | 17 / 10 |
| 75 full pages from 14 documents, 40,358 words | 91.62% | 91.77% | 10 / 8 |

The largest gain was a table region, from 62.5% to 92.1% of its 331 words. The largest losses were 14 words in one region and 9 words on one page. On the Homer slide above, the DPI cost 4 words in Docling (97.6% with grayscale alone, 95.3% with both). I recommend it all the same: the net effect is positive in both sets, the largest single effect is a gain, and Tesseract no longer has to guess a resolution that Docling knows.

**3. Orientation confidence.** Docling runs Tesseract's orientation and script detection (OSD) on every OCR region, and it rotated the region on any detection. OSD reports its orientation confidence as the margin between its best and second-best orientation, so a value near 0 is a close call. The new option `orientation_confidence_threshold` (default 1.0) on `TesseractCliOcrOptions` and `TesseractOcrOptions` ignores detections below it; `0` restores the old behaviour. I ran OSD on 277 layout regions from 16 documents and on 90 full pages from 17 documents, as rendered (all upright) and rotated by 90°, 180° and 270°:

| | Layout regions | Full pages |
|---|---|---|
| Upright text turned the wrong way, `main` | 2 of 214 (confidence 0.06 and 1.17) | not measured |
| Upright text turned the wrong way, this PR | 1 of 213 (confidence 0.0, now ignored) | 0 of 90 |
| Rotated copies corrected, threshold 0 (old behaviour) | 632 of 639 | 268 of 270 |
| Rotated copies corrected, threshold 1.0 (new default) | 619 of 639 | 265 of 270 |
| Rotated copies corrected, threshold 14 (OCRmyPDF's page default) | 392 of 639 | 220 of 270 |

The counts cover the regions and copies on which OSD returned a result. A threshold of 14 would drop 38% of the correct region rotations and 18% of the correct page rotations. With 1.0, the rotated copies that are no longer corrected hold 84 of the 114,209 words that Tesseract reads in all correctly rotated copies (0.07%), while the region that OSD turned the wrong way would have lost all 11 of its words. A region that is really sideways, the arXiv identifier in the margin of a paper (confidence 2.97), is still rotated and read in full.

**4. Failures are reported.** When Tesseract failed on a region in the `tesseract` engine, Docling only logged an error, and the document still ended as `SUCCESS` without that text. Now the engine also adds an `ErrorItem` for the page (`DoclingComponentType.MODEL`, `FailureCategory.INFERENCE_FAILURE`), the same way the KServe OCR engine reports a failed region, so the document ends as `PARTIAL_SUCCESS`. The engine now keeps Tesseract's stderr, so the error carries Tesseract's own message. Tesseract exits with 0 on blank, tiny and all-black regions, so the error marks real failures only. In the `tesserocr` engine, a failure raises an exception, which the pipeline already records for the page. None of the reference conversions reported an error.

An empty `lang` list still skips, without an error, a region whose script OSD cannot detect. OSD gives up on regions with too few characters, mostly pictures, and reporting those skips would turn 3 of 5 ordinary test documents (converted with `lang=[]`) into `PARTIAL_SUCCESS`. So this PR leaves that case unchanged.

**Related pull requests:**

- docling-project#4709 adds orientation detection for RapidOCR (`detect_orientation`, off by default). It addresses the same rotated-text problem for another engine and shares no code with this PR. Both PRs change `pipeline_options.py` and `docs/concepts/OCR.md`, but in different sections, and they merge cleanly.
- docling-project#4654 and docling-project#4643 detect a broken PDF text layer and send it to OCR, docling-project#4654 per page and docling-project#4643 per region. This PR does not do that; the PRs complement each other. With a Tesseract engine, the pages and regions that they send to OCR get the changes in this PR. A page that docling-project#4654 replaces is OCR'd in full, which is where the grayscale input gains the most.

**Review evidence:**

- Reference data: unchanged. `tests/test_e2e_ocr_conversion.py` passes against the existing ground truth for every Tesseract configuration of both engines (default, layout-regions and full-page modes, and full-page mode with `lang=[]`), and for EasyOCR and RapidOCR.
- New tests: 6 unit tests in `tests/test_tesseract_ocr_cli_model.py` and `tests/test_tesseract_ocr_model.py` (grayscale input, the DPI, the threshold and the error record) fail on `main` and pass here. `tests/test_e2e_tesseract_highlighted_text.py` OCRs a synthetic page with three highlighted lines (`tests/data/ocr/sources/highlighted_text.png`, 63 KB, regenerated by running the test module); on `main`, both engines miss 26 of its 42 highlighted words.
- `tests/test_e2e_rotated_ocr.py`: same result as `main` (90° and 270° pass; 180° is still the expected failure of docling-project#3839).
- One run of the tests above plus `test_tesseract_ocr_cli_lang`, `test_options`, `test_service_datamodels`, `test_ocr_options_force_full_page`, `test_ocr_engine_language_mapping`, `test_ocr_language` and `test_backend_webp`: 306 passed, 6 skipped, 2 xfailed (the 180° cases).
- Checks: the prek hooks (ruff, ruff format, ty, tach), tach module coverage and max-lines pass.
- Not run: the full test suite, Linux, macOS and Tesseract 4.

**Samples.** The ground truth is the PDF text layer, or a manual transcription for image-only pages. The highlighted words are the words under a yellow highlighter mark. The public sources:

- Newtown, CT, 2015 draft charter (47 pages): https://cmsarchive.civicplus.com/Newtown%20CT/NewtownCT_BBoard/News%20Archive/S052C770B.2/NEWTOWN%20CHARTER%20Revision%20Commission%202015%20Draft%20%20Charter%203.pdf
- Newtown, CT, colour-code legend: https://cmsarchive.civicplus.com/Newtown%20CT/NewtownCT_BBoard/News%20Archive/S052C770B.4/Color%20Codes%207-10-15%205.pdf
- City of Homer, AK, council supplemental packet (the slide is page 5): https://www.cityofhomer-ak.gov/sites/default/files/fileattachments/city_council/meeting/75366/supplemental_packet.pdf
- "Page 23 as a scanned image" is page 23 of the draft charter, rasterized at 300 DPI into an image-only PDF.
- Scanned court exhibit, U.S. District Court for the Northern District of California, No. 4:24-cv-04722, ECF No. 379-75 (the highlighted line is on page 3): https://storage.courtlistener.com/recap/gov.uscourts.cand.433688/gov.uscourts.cand.433688.379.75.pdf

**Checklist:**

- [x] Documentation has been updated, if necessary.
- [x] Examples have been added, if necessary.
- [x] Tests have been added, if necessary.

Signed-off-by: BBC, Esquire <bbc@chintellalaw.com>
@github-actions github-actions Bot added enhancement New feature or request ocr labels Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

AI triage (advisory)

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

Warning

The AI analysis did not finish. Only the deterministic checks are shown.

Topic labels added: enhancement, ocr.

CI safety: not assessed.

Possibly related pull requests

PR State Signal Assessment
#4709 open referenced as #4709; also references issue #3839 not assessed
#4941 open changes the same code not assessed
#4654 open referenced as #4654 not assessed
#4643 open referenced as #4643 not assessed
#3999 merged also references issue #3839 not assessed

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

@BBC-Esq

BBC-Esq commented Oct 21, 2026

Copy link
Copy Markdown
Contributor Author

A quick followup message...I wanted to give a quick shout-out to the https://github.com/ocrmypdf/OCRmyPDF repository...it kicked off my study of the pdf format, how ridiculously complex and annoying it is, but useful...some of that repo's strategies were incorporated herein but I like to think that I added some of my own as well through many and many hours of struggling with .pdf files...

@mergify

mergify Bot commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🔴 1 of 2 protections blocking · waiting on 👀 reviews

Protection Waiting on
🔴 Require two reviewer for test updates 👀 reviews
🟢 Enforce conventional commit —

🔴 Require two reviewer for test updates

Waiting for

  • #approved-reviews-by >= 2
This rule is failing.

When test data is updated, we require two reviewers

  • #approved-reviews-by >= 2
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)(?:\(.+\))?(!)?:

@codecov

codecov Bot commented Oct 22, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

This was referenced Oct 25, 2026
Open
Merged

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

enhancement New feature or request ocr

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@BBC-Esq