churro_ocr.page_detection

Public page detection interfaces.

class churro_ocr.page_detection.PageCandidate

Bases: object

Intermediate page candidate returned by a page detector.

Parameters:

• bbox – Bounding box in source-image coordinates.

• image – Optional already-cropped page image. When provided, detection callers use this image directly instead of cropping from bbox or polygon.

• polygon – Optional polygon in source-image coordinates.

• metadata – Detector-side metadata attached to the candidate.

__init__(bbox=None, image=None, polygon=(), metadata=<factory>)

Parameters:

• bbox (tuple[float, float, float, float] | None)

• image (Image | None)

• polygon (tuple[tuple[float, float], ...])

• metadata (dict[str, Any])

Return type:

None

class churro_ocr.page_detection.DocumentPage

Bases: object

A document page image with optional OCR output attached.

Parameters:

• page_index – Page position in the current output sequence.

• image – Page image.

• source_index – Index of the original source item that produced the page.

• bbox – Bounding box in source-image coordinates when available.

• polygon – Polygon in source-image coordinates when available.

• metadata – Caller-side or detector-side metadata for the page.

• text – OCR text attached to the page when OCR has been run.

• provider_name – Provider identifier attached by OCR.

• model_name – Model name attached by OCR.

• ocr_metadata – Provider-returned OCR metadata for this page.

property width: int

Return the current page image width in pixels.

property height: int

Return the current page image height in pixels.

classmethod from_image(image, *, page_index=0, source_index=0, metadata=None)

Create a document page from an in-memory image.

Parameters:

• image (Image) – Source page image.

• page_index (int) – Page position to attach to the page.

• source_index (int) – Source index to attach to the page.

• metadata (dict[str, Any] | None) – Optional caller-side metadata for the page.

Returns:

New page object with a copied image.

Return type:

DocumentPage

classmethod from_image_path(path, *, page_index=0, source_index=0, metadata=None)

Create a document page from an image path.

Parameters:

• path (str | Path) – Path to the page image on disk.

• page_index (int) – Page position to attach to the page.

• source_index (int) – Source index to attach to the page.

• metadata (dict[str, Any] | None) – Optional caller-side metadata for the page.

Returns:

New page object loaded from path.

Return type:

DocumentPage

with_ocr(*, text, provider_name, model_name, ocr_metadata=None)

Return a copy of the page with OCR output attached.

Parameters:

• text (str) – OCR text for the page.

• provider_name (str) – Provider identifier to attach.

• model_name (str) – Model name to attach.

• ocr_metadata (dict[str, Any] | None) – Provider-returned OCR metadata.

Returns:

Copy of the current page with OCR fields filled in.

Return type:

DocumentPage

__init__(page_index, image, source_index, bbox=None, polygon=(), metadata=<factory>, text=None, provider_name=None, model_name=None, ocr_metadata=<factory>)

Parameters:

• page_index (int)

• image (Image)

• source_index (int)

• bbox (tuple[float, float, float, float] | None)

• polygon (tuple[tuple[float, float], ...])

• metadata (dict[str, Any])

• text (str | None)

• provider_name (str | None)

• model_name (str | None)

• ocr_metadata (dict[str, Any])

Return type:

None

class churro_ocr.page_detection.PageDetectionRequest

Bases: object

Request payload for image page detection.

Parameters:

• image – In-memory image to detect pages from. Mutually exclusive with image_path.

• image_path – Path to an image on disk. Mutually exclusive with image.

• trim_margin – Margin in pixels to add around detected crops.

require_image()

Return the input image, loading it from disk when needed.

Returns:

Copy of the requested image.

Raises:

ConfigurationError – If both or neither of image and image_path are provided.

Return type:

Image

__init__(image=None, image_path=None, trim_margin=30)

Parameters:

• image (Image | None)

• image_path (str | Path | None)

• trim_margin (int)

Return type:

None

class churro_ocr.page_detection.PageDetectionResult

Bases: object

Page detection output for an image or PDF.

Parameters:

• pages – Detected pages in output order.

• source_type – Input source type, typically "image" or "pdf".

• metadata – Detection-level metadata, such as PDF rasterization settings.

__init__(pages, source_type, metadata=<factory>)

Parameters:

• pages (list[DocumentPage])

• source_type (str)

• metadata (dict[str, Any])

Return type:

None

class churro_ocr.page_detection.PageDetectionBackend

Bases: Protocol

Async interface for page detection.

async detect(image)

Detect page candidates from one image.

Parameters:

image (Image) – Source image to analyze.

Returns:

Page candidates in reading order.

Return type:

list[PageCandidate]

__init__(*args, **kwargs)

class churro_ocr.page_detection.PageDetector

Bases: object

Detect one or more page crops from an input image.

Create a page detector.

Parameters:

backend – Optional low-level backend or async callable. When not provided, the full input image is treated as a single page.

__init__(backend=None)

Create a page detector.

Parameters:

backend (PageDetectionBackend | Callable[[Image], Awaitable[list[PageCandidate]]] | None) – Optional low-level backend or async callable. When not provided, the full input image is treated as a single page.

Return type:

None

async adetect(request)

Asynchronously detect pages for a single image.

Parameters:

request (PageDetectionRequest) – Detection request describing the source image.

Returns:

Detected page crops in reading order.

Return type:

list[DocumentPage]

detect(request)

Synchronously detect pages for a single image.

Parameters:

request (PageDetectionRequest) – Detection request describing the source image.

Returns:

Detected page crops in reading order.

Return type:

list[DocumentPage]

class churro_ocr.page_detection.DocumentPageDetector

Bases: object

Detect pages from raw images or PDFs.

Create a document page detector.

Parameters:

backend – Optional low-level detection backend or async callable.

__init__(*, backend=None)

Create a document page detector.

Parameters:

backend (PageDetectionBackend | Callable[[Image], Awaitable[list[PageCandidate]]] | None) – Optional low-level detection backend or async callable.

Return type:

None

async detect_image(request)

Detect pages in a single image.

Parameters:

request (PageDetectionRequest) – Detection request describing the source image.

Returns:

Detection result for one image input.

Return type:

PageDetectionResult

detect_image_sync(request)

Synchronously detect pages in a single image.

Parameters:

request (PageDetectionRequest) – Detection request describing the source image.

Returns:

Detection result for one image input.

Return type:

PageDetectionResult

async detect_pdf(path, *, dpi=300, trim_margin=30)

Rasterize a PDF and detect pages on each image.

Parameters:

• path (str | Path) – PDF path to rasterize.

• dpi (int) – Rasterization DPI used before detection.

• trim_margin (int) – Pixel margin added around detected crops.

Returns:

Detection result containing all detected pages from the PDF.

Return type:

PageDetectionResult

detect_pdf_sync(path, *, dpi=300, trim_margin=30)

Synchronously rasterize a PDF and detect pages on each image.

Parameters:

• path (str | Path) – PDF path to rasterize.

• dpi (int) – Rasterization DPI used before detection.

• trim_margin (int) – Pixel margin added around detected crops.

Returns:

Detection result containing all detected pages from the PDF.

Return type:

PageDetectionResult