Python API

Python: pick the result you need

Just text

from occular import ocr

text = ocr("scan.png")

An image returns one string. A PDF returns a list of strings, one per page.

Text with boxes and confidence

from occular import ocr_detailed

for line in ocr_detailed("scan.png"):
    print(line["text"])
    print(line["quad"])        # four corners of the text line
    print(line["confidence"])  # recognition score

quad is four [x, y] points. Image coordinates refer to the image after preprocessing. More about coordinates →

A reusable reader with settings

from occular import OCRPipeline, Settings

reader = OCRPipeline(Settings(tables=True))
lines = reader.process_image("invoice.png")

Create a pipeline once when processing many files. Use it for PDF controls too:

from occular import OCRPipeline

reader = OCRPipeline()
pages = reader.process_pdf("scan.pdf", dpi=300, force_ocr=True, workers=1)

Each page has page, method and results; with tables enabled it also has tables.

All settings and their defaults

Setting	Default	Explanation
deskew	True	Small-angle and line correction
orientation	False	Turn an image page upright
unwarp	False	Flatten a curved image page
reading_order	True	Arrange columns and blocks
tables	False	Recover table cells
languages	None	Default Russian/English or another language
lm	True	Use language context
gpu	False	Request CUDA
num_threads	None	Automatic, up to 8 available logical CPUs
recognizer	None	Default svtr_lcnet; alternative svtr_t
detector	None	Default registered detector

ocr() and ocr_detailed() accept the listed options except unwarp and detector. Use Settings with OCRPipeline for those.

dpi, force_ocr and workers belong to process_pdf(), not to Settings or ocr().

Helper APIs and optional result fields

Public helpers include LayoutDetector, LayoutRegion, LayoutResult, LAYOUT_LABELS, TableRecognizer, model_info, WEIGHTS_DIR, download_layout, layout_ready, download_reading_order, reading_order_ready, get_optimal_workers and Registry.

Optional line fields include orientation_deg, layout, layout_region, layout_label, table, cell and split. Use .get() when reading them: not every processing path adds every field.

reader.get_text(path) returns text using the configured pipeline. PDF options can be passed to it as keyword arguments.

Detailed behavior →