Getting Started =============== Installation ------------ Basic installation (inference only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash 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: .. code-block:: bash pip uninstall onnxruntime pip install "manuscript-ocr[gpu]" If CUDA/cuDNN libraries are not installed, also run: .. code-block:: bash 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 :ref:`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: .. code-block:: python 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: .. code-block:: python 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 :doc:`pipeline_usage`. .. _example-notebooks: 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) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash 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.