Selective OCR: spend vision only where evidence fails
pdf-inspector treats OCR as a controlled extension of native extraction, not as the first step for every PDF. This chapter follows the lifecycle that turns a page-quality signal into visual recovery: choose a routing policy, validate the exact page set, render only that set, resolve the runtime only when it is needed, and keep the page order and coordinate transform intact. The result is a way to plan OCR around evidence and operational boundaries rather than around a blanket “scan everything” rule.
Three modes are three policies
The optional vision layer exposes three modes with different meanings. Off never runs OCR and is the default. It preserves the native-only behavior even when the application was built with OCR capabilities. Auto runs OCR only on pages selected by pdf-inspector's existing detector and text-quality signals, optionally narrowed by a caller's page selection. Force OCRs every selected page, or every page in the document when no selection is supplied. The modes are policies about which evidence to trust and how much additional work to authorize; they are not merely low, medium, and high OCR settings.
The distinction is easiest to see in a mixed document. Suppose native extraction identifies pages 4 and 17 as scanned or unreliable while the rest of the report has usable text. Auto can route those pages and leave the others on the native path. If an operator is testing OCR against a known page range, Force can process the selected pages even when native text is clean. If the application only wants classification and native Markdown, Off keeps the vision layer out of the execution path.
Native extraction still runs first in the complete OCR pipeline. That ordering matters because the native result supplies both content and the recommendation list. The pipeline can discover that no page needs visual recovery and return without loading the renderer, opening the model cache, accessing the network, or initializing inference. It can also retain a clean native fragment on a page that is flagged for OCR, so a later fusion step has something to compare rather than assuming the OCR hypothesis must replace everything.
The route is therefore controlled by two inputs: what pdf-inspector observed and what the caller is willing to process. Auto is not a learned model that sees every visual defect. It follows the project's current recommendations, which can include image-only pages, vectorized text, suspicious encodings, or template-like backgrounds. Force is useful for explicit experiments or a deliberate policy, but it trades away the main cost advantage of selective routing.
The modes also change what kind of evidence the application is asking for. Off asks for the native answer and its quality metadata, so an unresolved page remains unresolved rather than being silently repaired. Auto asks for a conditional answer: use the native path wherever its signals are sufficient and add visual evidence only where the route says it is needed. Force asks a comparative question or enforces a policy that does not trust the native path even on clean pages. Choosing Force can be reasonable for an evaluation, a document class known to contain unreliable text layers, or a workflow that needs a uniform OCR-derived representation. It should be an explicit operational decision, because it increases work and may introduce recognition hypotheses where exact native text was available.
This makes the mode a boundary of authority. The router decides which pages may enter the visual path, but the caller still owns the consequence of publishing, comparing, or withholding the result. A mode does not turn a low-confidence page into a high-confidence page; it only determines which evidence-gathering transition is permitted.
Page identity and transforms are contracts
Once pages are selected, the route must preserve their identity.