Skip to content

0.5.0 — Tables in the pipeline, layout regions, multi-core PDF

Choose a tag to compare

@Bodhi42 Bodhi42 released this 27 Oct 08:38
· 6 commits to main since this release

0.5.0 — Tables in the pipeline, layout regions, and multi-core PDF processing

This release adds table output to the regular OCR pipeline, introduces optional layout analysis, and makes multi-page documents scale across CPU cores.

  • Tables in the OCR pipeline. Use Settings(tables=True), ocr(..., tables=True) or the CLI flag --tables. Recognized lines are placed into table cells (table, cell with row/column and spans), PDF pages gain a tables key, and plain-text output prints tables as Markdown in place. Lines that run across a cell border are split at a space, never inside a word. Off by default.

  • New table models in TableRecognizer. Trained on our own annotated corpus of real documents (forms, statements, invoices, books, scans). On its held-out part:

    • detection F1 0.82 (was 0.43), neighbouring tables no longer merge;
    • row/column grid F1 0.92 (was 0.80), merged cells F1 0.83 (was 0.58);
    • tall tables are no longer squashed; on tables with more than 50 rows, row F1 is 0.89 (was close to 0);
    • empty or missing rows and columns are fixed.

    Single-row and single-column tables no longer crash on GPU.

  • Layout regions (new, optional): LayoutDetector. Returns page regions with boxes, scores and one of 18 labels. It runs on CPU in about 0.3 s per page, and its weights (~42 MB) are downloaded on first use. The labels are informational only: nothing is removed or skipped because of them.

  • Experimental reading order from layout (off by default). OCRPipeline(experimental_layout_order=True) reorders lines by layout regions, using either a small trained block-order model (~5 ms per page) or XY-cut. The text itself is unchanged; each line gains layout_region and layout_label.

  • Multi-page work scales across cores. process_pdf(workers=N), ocr() on PDFs and the CLI --workers option (now also for folders) process pages in separate worker processes instead of threads. Throughput rose from 0.66 to 1.57 pages/s at 8 workers, and to about 3 pages/s on large PDFs. Cores are split by physical cores on Linux and macOS. A single page is also faster: 2.35 → 1.64 s.

    Processes require an if __name__ == "__main__": guard in your script. Without it, Occular falls back to threads and shows a one-time warning.

  • Faster native decoder. occular-decode 0.2.0 (optional, in native/wheels/) now scales under concurrent load: 13k → 49k lines/s at 16 parallel requests, with byte-identical text. A macOS arm64 wheel is now available.

  • Installation and platform fixes:

    • No source builds on supported platforms (#4). macOS gets OpenCV wheels that match its version, and Linux aarch64 uses plain onnxruntime. PyMuPDF is capped below 2.0.
    • On Windows, a separate wheel ships the Microsoft C++ runtime DLLs. Clean installs without the Visual C++ Redistributable now work.
    • On Windows, CLI output redirected to a file or pipe no longer fails with UnicodeEncodeError.
    • All console output is in English (#5).
    • The PyMuPDF fitz deprecation warning no longer appears.
  • Removed the ocr_skel alias, deprecated since 0.3.0. Use import occular and python -m occular.

Without the new options, the output is byte-identical to 0.4.6.

Full details are in CHANGELOG.md.

Upgrade:

pip install -U occular-ocr==0.5.0

With GPU dependencies:

pip install -U "occular-ocr[gpu]==0.5.0"