Skip to main content

🧾 ocralign

ocralign extracts layout-preserving text from PDFs and images plus a word-level coordinate mapping, so any character span in the extracted text (e.g. an NER entity) can be resolved back to bounding boxes on the original page — for drawing highlight overlays in a PDF viewer, PIL/cv2, or anything else.

The core is engine-agnostic: backends emit one canonical schema, and all locate/overlay logic runs on that schema. Two backends are built in:

backend="vanilla" (default) backend="docling"
Engine Tesseract (scans) / PyMuPDF text layer (digital) Docling layout models + Tesseract or RapidOCR
Output text Visually formatted monospace grid (mirrors the page) Structural markdown (headings, pipe tables, reading-order paragraphs)
Multi-column pages Interleaves columns Correct reading order
Tables Flattened by (x,y) proximity Recognized structure, rendered as pipe tables
Cost (CPU) ~1–2 s/page ~25–35 s/page (2-core CPU; GPU supported via device="cuda")
Install Base package pip install "ocralign[docling]" (~1 GB+ with models)

Both emit identical Word/Page/Document data, so locate() and overlays work the same regardless of backend. Use vanilla for simple single-column documents; switch to docling when a document has tables or multi-column layout and the text feeds an LLM/NER.


🔧 System Requirements

sudo apt update
sudo apt install -y tesseract-ocr

Installation

pip install ocralign             # vanilla backend only
pip install "ocralign[docling]"  # + docling backend (layout/table models, rapidocr)

Usage

from ocralign import process_pdf, process_image, locate, locate_substring, to_pixels

# Vanilla backend (default): visually formatted text
doc = process_pdf(
    "./scan.pdf",
    type="image",        # "image" for scanned PDFs (OCR), "digital" for PDFs with a text layer
    layout="normalized", # "normalized" (readable), "absolute" (proportional vertical gaps), "none" (plain)
    dpi=300,
)

page = doc.pages[0]
print(page.text)                 # layout-aligned text, same formatting as before
print(page.words[0])             # Word(text='Sample', bbox=(0.014, 0.02, ...), confidence=96.1,
                                 #      line_no=0, char_start=18, char_end=24)

# OCR a single image -> Page
page = process_image("./sample.png")

# Docling backend: structural markdown for complex layouts.
# Detects born-digital vs scanned automatically (no `type` parameter).
doc = process_pdf(
    "./two_column_with_tables.pdf",
    backend="docling",
    ocr_engine="rapidocr",   # or "tesseract" (rapidocr is the engine with a GPU path)
    device="cpu",            # "cuda" to run OCR + layout models on GPU
    workers=4,               # CPU page-parallelism: N processes, pages merged in order
    num_threads=4,           # per-process thread cap (torch + ONNX Runtime)
)
print(doc.pages[0].text)     # "## Heading\n\nParagraph...\n\n| cell | cell |..."

Scaling on CPU: workers=N converts pages in N processes (each loads its own model copies, ~1-1.5 GB RSS; defaults num_threads to cpu_count() // workers). Worth it for multi-page documents on multi-core machines; on GPU keep workers=1 and let the device do the batching.

⚠️ workers > 1 starts processes via spawn, which re-imports your script: the process_pdf call must live under if __name__ == "__main__": (or inside a function only called from there), or the pool crashes with BrokenProcessPool. Standard Python multiprocessing rule, but easy to trip on.

Docling + DPI note: Docling's OCR stage re-renders regions at 3× scale internally. Feed it ~100–150 DPI page images, not 300 DPI — higher input DPI roughly doubles OCR time for no accuracy gain.

Coordinate mapping & overlays

Bounding boxes are (x0, y0, x1, y1) as fractions of page width/height (0–1, origin top-left) — independent of OCR DPI and of whatever size the page is later rendered at.

# NER gives you a character span into page.text -> resolve to boxes.
# One box per visual line; spans that wrap lines return multiple boxes.
boxes = locate(page, char_start=120, char_end=134)

# Or search by substring (whitespace-flexible; layout spacing won't break matching)
occurrences = locate_substring(page, "Margaret Chen")

# Offsets into the full multi-page text (doc.text(add_marker=True))?
from ocralign import locate_in_document
page_boxes = locate_in_document(doc, start, end)   # -> [(page_number, bbox), ...]

# Convert to pixels for ANY render size (PIL, cv2, react-pdf, ...)
x0, y0, x1, y1 = to_pixels(boxes[0], rendered_width, rendered_height)

Frontend (e.g. react-pdf) needs no library at all — store the normalized boxes with your entities and draw an absolutely-positioned div at left = x0 * renderedPageWidth, etc.

Persistence

doc.save_json("doc.json")        # full schema: text + words + offsets, JSON round-trip
doc = Document.load_json("doc.json")
full_text = doc.text(add_marker=True)   # concatenated text with page markers

Adding a new OCR engine

Write one adapter that converts the engine's native output into List[Word] (normalized bboxes) — see ocralign/backends/vanilla/tesseract.py (~60 lines) or, for a full layout-aware pipeline, ocralign/backends/docling/. Layout rendering, offset mapping and locate() work unchanged on top of it. Commercial APIs (Textract, Document AI, Azure) already return word+bbox+confidence, so their adapters are thin translations.

Schema

{
  "schema_version": "1.0",
  "pages": [
    {
      "page_number": 1,
      "width_px": 2550, "height_px": 3300,
      "text": "formatted layout text ...",
      "words": [
        {"text": "Margaret", "bbox": [0.12, 0.08, 0.22, 0.10],
         "confidence": 96.4, "line_no": 3, "char_start": 118, "char_end": 126}
      ]
    }
  ]
}

Example input & overlay resolved via locate_substring:

Sample OCR Input

📎 See full extracted text here

Metadata

Release files for ocralign 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for ocralign 0.3.0
File Interpreter ABI Platform Actions
ocralign-0.3.0-py3-none-any.whl Python 3 none any Details for ocralign-0.3.0-py3-none-any.whl

Release files / ocralign-0.3.0-py3-none-any.whl

Download URL ocralign-0.3.0-py3-none-any.whl
Size 36.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9be0052509c3d4dae9191ef78fc54ab30fd1ba53fe227fc191f307d163c6ce5b
BLAKE2b-256 checksum
How to use checksums
7f53981fa69126f978754dc81ec0c43428d69cde2fb1c6c572b10ac7513abe29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.5

Security for ocralign 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page