Module ocr_need 

Scan detection: how much OCR a page needs, before any recognizer runs. Scan detection: how much OCR a page needs, before any recognizer runs.

page_needs_ocr surveys one page through the interpreter and reports its shape as an OcrNeed: born-digital text (OcrNeed::None), an image of a page with no usable text layer (OcrNeed::Full), or text around image regions that carry no text of their own (OcrNeed::Partial).

The survey counts what the page draws rather than what its resources name: a /XObject entry nothing ever draws is not a scan of anything. Glyphs are split three ways – readable, invisible (render mode 3) and garbage (no usable Unicode mapping) – and only the readable ones count as a text layer. Image coverage is the union of the drawn image rectangles over the page rectangle, so overlapping images are not counted twice.

This is page SHAPE, not policy. Whether a OcrNeed::Full page is OCR’d is decided by the caller’s mode (off / auto / force); in particular an already searchable scan – image plus a full invisible text layer – still reports OcrNeed::Full, because an invisible layer is not trusted to be the page’s text. Skipping pages whose invisible layer already explains them is a policy refinement for the OCR wiring, not a detection verdict.

Thresholds

Constant	Value	Meaning
MIN_READABLE_GLYPHS	40	readable visible glyphs that make a text layer
FULL_PAGE_IMAGE_COVERAGE	0.50	image share of the page that makes a scan Full
PARTIAL_MIN_IMAGE_FRACTION	0.15	image share of the page that makes one region large
PARTIAL_MAX_TEXT_OVERLAP	0.05	text share of an image below which it is uncovered

Each constant carries its own rationale below. The 40-glyph floor is shared with the vision routing’s character floor: a scan regularly carries a stamped page number or a scanner header in real text while the body is pixels, and forty is above that and far below what any page of prose draws.

Enums

OcrNeed

How much OCR a page needs.

Functions

page_needs_ocr

How much OCR page page (0-based) of doc needs.