Getting Started

Installation

Basic installation (inference only)

pip install "manuscript-ocr[cpu]"

The base package (pip install manuscript-ocr) installs shared components without an inference runtime. Choose [cpu], [gpu] or [web]; TrOCR additionally requires [trocr], for example [cpu,trocr].

GPU acceleration (NVIDIA CUDA)

When switching from CPU, first remove onnxruntime. Then install the GPU extra:

pip uninstall onnxruntime
pip install "manuscript-ocr[gpu]"

If CUDA/cuDNN libraries are not installed, also run:

pip install "onnxruntime-gpu[cuda,cudnn]"

In notebooks, restart the kernel after installation.

For device-resident TrOCR decoding, install manuscript-ocr[gpu,trocr-cuda] and a CUDA-enabled PyTorch build. ONNX Runtime must support DLPack export; this capability is not present in every CPU or GPU wheel. See TrOCR CUDA decoding for requirements and fallback behavior.

Browser inference uses runtime="web" and a host-provided ONNX Runtime Web bridge; installing [web] alone does not configure that bridge. See the repository’s docs/WEB_RUNTIME.md and scripts/browser_probe/README.md for setup and the browser demonstration.

You can switch models and pipeline components explicitly with the device parameter, for example device="cuda" for NVIDIA GPU or device="cpu" for CPU:

from manuscript.detectors import EAST
from manuscript.recognizers import TRBA
from manuscript.correctors import CharLM

detector = EAST(device="cuda")
recognizer = TRBA(device="cuda")
corrector = CharLM(device="cuda")

Quick Start

Basic usage example:

from manuscript import Pipeline

# Create pipeline
pipeline = Pipeline()

# Process image
result = pipeline.predict("document.jpg")

# Get recognized text
text = pipeline.get_text(result["page"])
print(text)

For stage configuration, custom processors, ensembles and result handling, see Pipeline Usage Guide.

Example Notebooks

Notebooks for version 0.1.13:

• Training the EAST detector.

• Training the TRBA recognizer.

• Integrating a custom detector into the pipeline.

• Integrating a custom recognizer into the pipeline.

• Integrating a custom corrector into the pipeline.

• Combining models and building ensembles.

• Exporting and using yolov8m-historical-line-segmenter.

• Exporting and using cyrillic PP-OCRv5 mobile recognition.

Additional installation options

Apple Silicon acceleration (CoreML)

pip install "manuscript-ocr[cpu]"

Official macOS onnxruntime wheels include the CoreML execution provider; a separate onnxruntime-silicon package is not needed. Use device="coreml" for the relevant models or pipeline components. See the ONNX Runtime CoreML documentation.

Installation with training support

pip install "manuscript-ocr[cpu,dev]"

This installs additional dependencies for model training:

• PyTorch and TorchVision

• ONNX export tools

• Training utilities (albumentations, tensorboard, etc.)

• Development tools (pytest, black, flake8, etc.)

Minimum System Requirements

• Python 3.9.2 or newer

• Linux (Ubuntu 20.04+), Windows 10+, or macOS 11+

• at least 2 CPU cores

• at least 8 GB RAM

• 16 GB RAM or more is recommended for model training

• NVIDIA GPU with CUDA support is recommended for acceleration

• at least 4 GB VRAM is recommended for GPU execution

CPU-only execution is supported, but performance may be significantly lower than on GPU. Model training currently targets CUDA-capable NVIDIA GPUs and falls back to CPU when CUDA is unavailable.