PDF Rendering and OCR Pipeline#

The PDF rendering and OCR pipeline covers two sequential stages within Docling's StandardPdfPipeline:

1. Preprocess — PagePreprocessingModel rasterizes each page to PIL images via a PDFium backend, extracts PDF text cells, and computes a text-quality score.
2. OCR — A pluggable OCR engine (Tesseract, EasyOCR, RapidOCR, etc.) receives cropped region images and produces TextCell objects that are merged with the existing PDF-extracted cells.

These are the first two of five concurrent threaded stages 1. OCR runs after Preprocess because it depends on both the page image and the layout-cluster predictions generated there.

Key source files:

Page Rendering (Preprocess Stage)#

PagePreprocessingModel.__call__() runs two sub-steps for each valid page: image population then cell extraction.

Image population — _populate_page_images() always renders the page at scale=1.0 to warm the image cache, then renders again at options.images_scale if set, storing that as page._default_image_scale. Rendering delegates to page._backend.get_page_image(scale, cropbox).

Inside PyPdfiumPageBackend.get_page_image() 2: the page is rendered by pypdfium2 at scale × 1.5 — a supersampling factor applied to sharpen sub-pixel edges in vector content — and the resulting bitmap is then PIL-resized down to (round(width × scale), round(height × scale)). The native bitmap is closed immediately after .to_pil().copy() to release the underlying C memory before the lock is released 3.

Cell extraction — _parse_page_cells() calls page._backend.get_segmented_page() to extract PDF text/bitmap cells. It also aggregates text-quality scores across cells and stores the 10th-percentile score as conv_res.confidence.pages[page_no].parse_score — a signal that downstream logic can use to detect pages with corrupt or missing text layers 4.

The images_scale value is threaded from PdfPipelineOptions.images_scale (default 1.0; the CLI tool defaults to 2.0) 5. Values above 2.0 are known to cause bugs 6.

Supersampling and Raster-Only Detection#

The 1.5× supersample → resize strategy sharpens vector PDFs but is lossy for scanned (raster-only) pages: the scan's pixels are already rasterized, so the round-trip can silently drop borderline OCR text. PR #3803 documents an isolated case where an entire sentence was lost (page CER 0.184 vs ~0.05 for direct rendering).

The fix (PR #3803 — OPEN) introduces _is_raster_only() in a new shared base ManagedPdfiumPageBackend. The method walks page.get_objects() up to a depth of 16 (traversing form XObjects, since scans are frequently form-wrapped), and classifies a page as raster-only when it contains exclusively image objects with no text, vector, or annotation content. For raster-only pages, get_page_image() renders directly at the requested scale — skipping the supersample entirely — and crops any pixel excess from PDFium's ceil() rounding rather than resampling 7.

Tuning the supersample factor: A new PdfBackendOptions.supersample_factor field (default 1.5) lets callers override or disable supersampling. Setting it to 1.0 produces direct rendering on all pages regardless of content type 7.

The shared rendering logic is also hoisted into the base class so the fix applies consistently to both DoclingParseDocumentBackend and PyPdfiumDocumentBackend 7.

OCR Region Detection#

Before invoking any OCR engine, BaseOcrModel.get_ocr_rects() computes which page regions should be OCR'd. The strategy is controlled by OcrOptions.mode 8:

PDF-aware detection (_find_pdf_aware_layout_ocr_rects()) builds two rtree spatial indexes — one for PDF text cells, one for bitmap rects — then iterates over layout clusters and retains any cluster that (a) intersects a bitmap rect or (b) has no intersection with any text cell. This is the mechanism that avoids redundant OCR on pages with a reliable programmatic text layer.

Surviving rects pass through _deduplicate_rects(): they are rasterized into a binary image, dilated by a 20×20 kernel to merge nearby boxes into connected components, and the bounding boxes of those components are returned as the final OCR input rects. The method also returns an area_frac coverage ratio that callers can inspect.

force_full_page_ocr=True (deprecated) is a backward-compatibility shim that sets mode = OcrMode.FULL_PAGE 9. Prefer setting mode directly.

Tesseract CLI: Per-Region Rendering and Invocation#

TesseractOcrCliModel 10 is the reference implementation of the OCR stage. Its __call__() loop:

1. Calls get_ocr_rects(page) to get the target regions.
2. For each non-zero-area rect, renders a high-resolution crop: page._backend.get_page_image(scale=self.scale, cropbox=ocr_rect) — where self.scale = 3 (hard-coded), yielding 216 DPI from a 72 DPI base 11.
3. Writes the crop to a temp PNG, then runs OSD (tesseract --psm 0 -l osd) to detect page orientation. If orientation ≠ 0°, the image is rotated before OCR 12.
4. Runs tesseract <file> stdout tsv and parses the TSV result into TextCell objects, remapping Tesseract pixel coordinates back to PDF page space via tesseract_box_to_bounding_rectangle() 13.
5. Calls post_process_cells() to merge OCR cells with the existing PDF text cells, using PDF_FIRST priority in PDF_AWARE_LAYOUT_REGIONS mode (PDF cells win at overlapping positions) and OCR_FIRST in LAYOUT_REGIONS mode.

Security: Language identifiers, tessdata paths, and file names are sanitized against injection at construction time via static methods 14.

Debug visualization: Set settings.debug.visualize_ocr = True to write annotated images (yellow OCR rects, magenta OCR cells, gray PDF cells) to settings.debug.debug_output_path 15 16.

Configuration Reference#

All rendering and OCR options are set on PdfPipelineOptions 17 and OcrOptions subclasses 18:

OcrMode.DEFAULT is wired to PDF_AWARE_LAYOUT_REGIONS — the most selective mode, which skips OCR on pages that already have a good text layer 19.

For fully scanned PDFs, use OcrMode.FULL_PAGE. In that mode post_process_cells() discards all non-OCR word/char cells so stale programmatic cells don't corrupt downstream table structure extraction 20. If the layout model classified the scan as a PictureItem, export with traverse_pictures=True to surface the OCR text 6.