DOCSEARCHbyAlgolia
Submit Docs

ocrs

repository·main·Indexed 23 days ago

https://github.com/robertknight/ocrs

A modern OCR (Optical Character Recognition) engine written in Rust that uses machine learning models (PyTorch exported to ONNX) executed via the RTen engine to extract text from images. It provides a Rust crate, a C ABI via the ocrs-capi package, a command-line interface (ocrs-cli), and a WebAssembly version compatible with Node.js and web browsers. The library supports raw 8-bit pixels in row-major, channels-last (HWC) order for grey, RGB, and RGBA images.

Tokens
9.1K
Snippets
19
Records
70
Agent score
84%

What's inside ocrs

  2. Use Ocrs for text extraction in WebAssembly runtimes

    main
    Ocrs is a library designed for extracting text from images. This specific build is an alpha WebAssembly (Wasm) version, making it compatible with Node.js, web browsers, and other WebAssembly-supported runtimes.

  3. Follow ocrs-capi C ABI conventions

    main

    When integrating ocrs-capi into your application, adhere to these safety and concurrency rules:

    • Error Handling: Fallible functions return a pointer that is NULL on failure. Use ocrs_last_error() immediately after a failure to retrieve a human-readable error message. This error is thread-local and valid until the next fallible call on that thread.
    • Memory Management: Every pointer returned by the API must be released exactly once using its matching *_free function. Passing NULL to a *_free function is safe.
    • Concurrency: An engine instance can be used concurrently from multiple threads via a shared const OcrsEngine *. The engine parallelizes OCR calls internally. However, do not call ocrs_engine_free while any thread is still using the engine.
    • Panic Safety: Panics occurring within the Rust engine are caught at the FFI boundary and converted into a NULL return and an error message. If the library is built with panic = "abort", a panic will terminate the entire process.

  4. Install and run the ocrs example

    main

    To run a minimal OCR example, you must first download the required models in .rten format using the provided script, then run the example using cargo run.

    Important Performance Note: Always use the --release flag when running or building ocrs and its rten* dependencies. Debug builds are extremely slow and will result in significantly degraded performance.

    cd examples/

# Download models in .rten format.
./download-models.sh

# Run OCR on an image and print the extracted text.
cargo run --release --example hello_ocr rust-book.jpg

  5. Build the Ocrs browser extension

    main

    To build the extension from source, you must first build the WebAssembly OCR library and download the required pre-trained models before compiling the extension itself.

    Prerequisites:

    • A working make environment.
    • The ocrs-cli tool available via cargo.
    • Node.js and npm installed.

    Steps:

    1. Build WASM: Run make wasm in the repository root.
    2. Download Models: Use the ocrs-cli to download models to the cache, then move them to the local models/ocr directory:
      cargo run -r -p ocrs-cli test-image.jpeg
mkdir -p models/ocr
cp ~/.cache/ocrs/text-detection.rten ~/.cache/ocrs/text-recognition.rten models/ocr
      (Note: Replace test-image.jpeg with any valid image file.)
    3. Build Extension: Navigate to the extension directory, install dependencies, and build:
      cd ocrs-extension
npm install
make build
    4. Install in Chrome: Go to chrome://extensions, select "Load unpacked extension", and choose the ocrs-extension directory.
    # Build WASM library
make wasm

# Download and move models
cargo run -r -p ocrs-cli test-image.jpeg
mkdir -p models/ocr
cp ~/.cache/ocrs/text-detection.rten ~/.cache/ocrs/text-recognition.rten models/ocr

# Build the extension
cd ocrs-extension
npm install
make build

  6. Use the ocrs CLI to extract text

    main

    The ocrs CLI tool extracts text from images. On its first run, it automatically downloads required models to ~/.cache/ocrs.

    Basic usage:

    ocrs image.png

    If installed with the clipboard feature, you can extract text from the current system clipboard image using:

    ocrs --clipboard
# or
ocrs -c

  7. Install the ocrs CLI

    main

    To install the ocrs-cli tool, you must have Rust and Cargo installed on your system.

    Standard installation:

    cargo install ocrs-cli --locked

    To enable support for reading images directly from the system clipboard, install with the clipboard feature:

    cargo install ocrs-cli --locked --features clipboard

  8. Build and run ocrs locally

    main

    To build and run the library and CLI tool from the source code, ensure you have a recent stable Rust version installed.

    git clone https://github.com/robertknight/ocrs.git
cd ocrs
cargo run -p ocrs-cli -r -- image.png

  9. Use the Ocrs browser extension

    main

    The Ocrs browser extension enables text copying from images, videos, PDFs, or any other content within a Chrome tab.

    Workflow:

    1. Pin the extension: Click the puzzle piece icon in the Chrome toolbar and click the pin icon next to Ocrs.
    2. Capture text: Click the Ocrs logo in the toolbar. This takes a screenshot of the current tab and highlights selectable text regions.
    3. Exit: Click anywhere outside a text region or press Escape to close the OCR overlay.

  11. Build the ocrs-capi shared or static library

    main

    To use the C ABI for the ocrs engine, build the ocrs-capi package using Cargo. The resulting library is named ocrs_capi (to avoid conflict with the ocrs crate).

    • Shared library: Found at target/release/libocrs_capi.{so,dylib} or ocrs_capi.dll.
    • Static library: Found at target/release/libocrs_capi.a.

    To support custom models in ONNX format, enable the onnx feature during the build.

  12. Understand the TextItem trait and hierarchy

    main

    The TextItem trait defines a common interface for logical units of recognized text, such as words or lines. Any type implementing TextItem provides access to its constituent characters and its spatial extent.

    Key capabilities of a TextItem:

    • chars(): Returns a slice of TextChar objects.
    • bounding_rect(): Returns the axis-aligned bounding rectangle (Rect) encompassing all characters in the item.
    • rotated_rect(): Returns an oriented bounding rectangle (RotatedRect) that fits the characters, assuming horizontal/upright text orientation.

    The hierarchy follows a composition pattern: a TextLine contains multiple TextChars, and a TextLine can be subdivided into TextWords.