surya-tabular-ocr 0.1.0

English OCR, layout analysis, and table recognition from document images

Surya Tabular OCR

A trimmed fork of Surya focused on English-only OCR, layout analysis, and table recognition from document images. Programmatic use only — no CLI.

Installation

Requires Python 3.10+ and PyTorch. You may need to install the CPU version of torch first if you're not using a Mac or a GPU machine. See here for more details.

pip install surya-tabular-ocr
# or
uv add surya-tabular-ocr

Model weights download automatically on first use.

Usage

Table extraction pipeline (recommended)

Single-call interface that runs layout detection, table recognition, and OCR together:

from surya.pipeline import TableExtractionPipeline

pipeline = TableExtractionPipeline()  # loads all models once
result = pipeline.extract_tables(image, ocr=True)
# result is a plain dict: {"tables": [...], "image_size": [w, h]}

• Accepts PIL.Image or raw bytes
• ocr=True runs text recognition on each detected table
• skip_table_detection=True treats the whole image as one table

Individual predictors

OCR:

from PIL import Image
from surya.foundation import FoundationPredictor
from surya.recognition import RecognitionPredictor
from surya.detection import DetectionPredictor

image = Image.open("doc.png")
recognition = RecognitionPredictor(FoundationPredictor())
detection = DetectionPredictor()

predictions = recognition([image], det_predictor=detection)

Layout analysis:

from PIL import Image
from surya.foundation import FoundationPredictor
from surya.layout import LayoutPredictor

image = Image.open("doc.png")
layout = LayoutPredictor(FoundationPredictor())

predictions = layout([image])

Table recognition:

from PIL import Image
from surya.table_rec import TableRecPredictor

image = Image.open("table.png")
table_rec = TableRecPredictor()

predictions = table_rec([image])

Configuration

All settings are in surya/settings.py and overridable via environment variables:

• TORCH_DEVICE — override auto-detected device (e.g. cuda)
• RECOGNITION_BATCH_SIZE, DETECTOR_BATCH_SIZE, LAYOUT_BATCH_SIZE, TABLE_REC_BATCH_SIZE
• COMPILE_DETECTOR, COMPILE_LAYOUT, COMPILE_TABLE_REC, COMPILE_ALL — enable torch compilation

Development

git clone https://github.com/nexusaicodes/surya-tabular-ocr.git
cd surya-tabular-ocr
uv sync --group dev
pre-commit install          # enable ruff linting/formatting on commit
uv run pytest

License

Code is GPL-3.0-or-later (inherited from upstream). Model weights use a modified AI Pubs Open Rail-M license. See LICENSE and MODEL_LICENSE.

Acknowledgments

Trimmed fork of Surya by Vik Paruchuri and the Datalab team.