Python API

Python API

Import the user-facing API from occular:

from occular import (
    ocr, ocr_detailed, OCRPipeline, Settings,
    LayoutDetector, LayoutRegion, LayoutResult, LAYOUT_LABELS,
    TableRecognizer, model_info, WEIGHTS_DIR,
    download_layout, layout_ready,
    download_reading_order, reading_order_ready,
    get_optimal_workers, Registry,
)

Choose an entry point

Call	Image result	PDF result
ocr(path, **options)	str	list[str], one string per page
ocr_detailed(path, **options)	List of line dictionaries; .tables when tables are enabled	List of page dictionaries
pipeline.process_image(path)	List of line dictionaries; .tables when enabled	Not a PDF entry point
pipeline.process_pdf(path, dpi=300, force_ocr=False, workers=None)	Not an image entry point	List of page dictionaries
pipeline.get_text(path, **kwargs)	str	list[str]; PDF processing options go through kwargs

ocr() and ocr_detailed() accept these keyword-only options: deskew, lm, num_threads, gpu, languages, orientation, recognizer, tables, reading_order.

They do not accept dpi, workers, force_ocr or unwarp. Use OCRPipeline for these controls. A Settings object is accepted by OCRPipeline, not by ocr().

Reuse a configured pipeline

from occular import OCRPipeline, Settings

settings = Settings(
    num_threads=4,
    gpu=False,
    languages=None,
    deskew=True,
    orientation=False,
    unwarp=False,
    lm=True,
    reading_order=True,
    tables=False,
    detector=None,
    recognizer=None,
)
pipeline = OCRPipeline(settings)
lines = pipeline.process_image("document.png")

An explicitly supplied Settings object controls the configuration; constructor keyword options are used to construct settings only when no settings object is provided. Treat settings as construction-time configuration. To change model options, create a new pipeline rather than mutating pipeline.settings and expecting existing model sessions to rebuild.

Settings reference

Setting	Default	Accepted user-facing values
num_threads	None	Positive integer; automatic effective default is up to 8 available logical CPUs
gpu	False	True requests CUDA; CPU fallback is possible
languages	None	Language-code list, a single code string, or "auto"; None selects ru/en
deskew	True	Small page skew correction and per-line orientation handling
orientation	False	Image-path page orientation correction
unwarp	False	True, "always", or a model ID/local model path; see Preprocessing
lm	True	Beam + language model; False selects greedy decoding
reading_order	True	Layout-based OCR reading order
tables	False	Detect tables and assign recognized lines to cells
detector	None	Default registered detector (dbnet-onnx), or a registered custom name
recognizer	None	Default svtr_lcnet; "svtr_t" selects the larger architecture

print(Settings()) prints a human-readable summary. settings.resolved_threads() returns the resolved thread setting; it is not a worker-count estimator. The pipeline may further divide threads between process workers.

Line and page records

A line contains:

{
  "quad": [[20, 40], [220, 40], [220, 70], [20, 70]],
  "text": "Example text",
  "confidence": 0.95
}

This is an illustrative record, not a promised recognition result. Optional keys include orientation_deg and layout from per-line orientation handling, layout_region and layout_label from reading order, and table, cell and split from table processing. Use .get() for optional keys. In particular, layout and layout_label describe different things.

A PDF page contains page (one-based), method ("text" or "ocr"), results (lines), and optionally tables. Geometry units depend on method; see PDFs and coordinates.

Models, regions and extension utilities

API	Purpose
LayoutDetector(...).detect(image)	Return a LayoutResult containing page size and LayoutRegion objects
LayoutRegion.to_dict(), LayoutResult.to_dict()	Convert layout results to JSON-compatible dictionaries
LAYOUT_LABELS	Numeric class-ID to label mapping
TableRecognizer(...)(bgr_image)	Detect table geometry and structure without reading cell text
TableRecognizer.detect(bgr_image)	Return detected table boxes with confidence
TableRecognizer.structure(bgr_crop)	Return rows, columns and merged cells for a table crop
model_info()	Print available model files and local/cache status; does not download them
WEIGHTS_DIR	Package-local weight directory checked before the Hub cache
download_layout()	Ensure both layout and block-order weights exist; return the layout-model path
download_reading_order()	Alias for the same download operation
layout_ready(), reading_order_ready()	Check whether both layout and block-order files can be located
get_optimal_workers(max_workers=4)	Simple CPU-count helper; not the memory-aware automatic PDF worker policy
Registry	Advanced registration of detector/recognizer implementations

Custom registry implementations must meet the pipeline interfaces and may affect process-worker support. For ordinary documents, use the standard models and the options documented above.

Implementation references

Published 0.5.1 source: occular/init.py, occular/settings.py.