rusto 0.3.2__tar.gz → 0.4.0__tar.gz

rusto-0.4.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: rusto
+Version: 0.4.0
+Summary: Pure Rust OCR library for Python based on RapidOCR, Indra OCR, and pure-Rust MNN (rusto-nn)
+Author-email: RustO Contributors <contact@rusto.dev>
+License-Expression: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+
+# rusto (Python SDK)
+
+Official Python bindings for **RustO!** — a high-performance, pure-Rust OCR engine powered by Indra OCR, PaddleOCR, and the pure-Rust MNN (`rusto-nn`) inference runtime via UniFFI.
+
+## Features
+
+- **Zero-Config Indra OCR**: `RustO.initialize()` automatically downloads and caches the default `indraocr` models on first run from Hugging Face Hub.
+- **Context Manager Support**: Deterministic native resource cleanup with `with RustO.initialize() as engine:` or `engine.close()`.
+- **Full Document Pipeline**: Neural document unwarping (`with_auto_unwarp()`), page orientation detection (`with_orientation_detection()`), semantic layout analysis, and reading-order recovery (`with_layout_reading()`).
+- **Fluent Builder API**: Chain `.as_lines()`, `.as_words()`, `.as_spatial()`, `.as_tsv()`, or `.with_output(...)` into a single `.run()` terminal method.
+- **Zero-Copy Raw RGB Support**: Feed NumPy / OpenCV / Pillow RGB8 buffers directly via `.rgb(pixels, width, height, stride)`.
+
+## Installation
+
+```bash
+pip install rusto
+```
+
+## Quick Start
+
+```python
+from rusto import RustO
+
+# Zero-config initialization (auto-downloads Indra OCR models from Hugging Face Hub if not cached)
+with RustO.initialize() as engine:
+    result = (
+        engine.detect_text("invoice.png")
+        .with_auto_unwarp()
+        .with_layout_reading()
+        .as_lines()
+        .run()
+    )
+
+    if result.is_STRUCTURED():
+        for item in result.results:
+            print(
+                f"[{item.score:.2f}] ({item.layout_type or 'line'} #{item.region_id}) {item.text}"
+            )
+
+    # Reconstructed 2D spatial text layout
+    spatial = engine.detect_text("invoice.png").as_spatial().run()
+    if spatial.is_SPATIAL():
+        print(spatial.text)
+```
+
+You can also manage the engine lifecycle explicitly without a `with` block:
+
+```python
+from rusto import InitializeConfig, RustO
+
+engine = RustO.initialize(InitializeConfig.indra())
+try:
+    result = engine.detect_text("invoice.png").as_words().run()
+    if result.is_STRUCTURED():
+        for word in result.results:
+            print(word.text, word.frame)
+finally:
+    engine.close()
+```
+
+## Custom Configuration & Offline Models (.mnn / .rten)
+
+Select canonical model tiers (`"indraocr"`, `"ppocrv6-tiny"`, `"ppocrv6-small"`, `"ppocrv5-mobile"`, `"ppocrv4-mobile"`), languages, or local model paths:
+
+```python
+from rusto import (
+    DetectionConfig,
+    InitializeConfig,
+    LayoutConfig,
+    RecognitionConfig,
+    RustO,
+    UnwarpConfig,
+)
+
+# Preset by canonical model + language (auto-downloaded to cache)
+cfg = InitializeConfig.for_model("ppocrv6-tiny", lang="latin")
+engine = RustO.initialize(cfg)
+engine.close()
+
+# Explicit local assets for offline environments
+offline_cfg = InitializeConfig(
+    template="indra",
+    enable_reading_order=True,
+    detection=DetectionConfig(enabled=True, model_path="./models/indra_det.mnn"),
+    recognition=RecognitionConfig(
+        enabled=True,
+        model_path="./models/indra_rec.mnn",
+        dict_path="./models/indra_meta.json",
+    ),
+    unwarp=UnwarpConfig(enabled=True, model_path="./models/uvdoc.mnn"),
+    layout=LayoutConfig(enabled=True, model_path="./models/layout_cdla.mnn"),
+)
+with RustO.initialize(offline_cfg) as offline_engine:
+    res = offline_engine.detect_text("scan.png").with_auto_unwarp().as_lines().run()
+```
+
+Pre-download models into a target cache directory ahead of time (e.g., during Docker image build):
+
+```python
+from rusto import download_model
+
+paths = download_model(model="indraocr", lang="latin", cache_dir="./models-cache")
+```
+
+## Input Sources & Raw RGB Buffers
+
+Pass a file path (`str` or `Path`), encoded image `bytes`, `ImageSource`, or raw interleaved 24-bit RGB pixels:
+
+```python
+from pathlib import Path
+import numpy as np
+from rusto import RustO
+
+with RustO.initialize() as engine:
+    # 1. Encoded PNG/JPEG bytes
+    png_bytes = Path("invoice.png").read_bytes()
+    res_bytes = engine.detect_text(png_bytes).as_lines().run()
+
+    # 2. Raw HxWx3 uint8 RGB array (e.g. from Pillow / imageio)
+    rgb_array = np.zeros((720, 1280, 3), dtype=np.uint8)
+    height, width, _ = rgb_array.shape
+    stride = width * 3
+
+    res_rgb = (
+        engine.detect_text()
+        .rgb(rgb_array.tobytes(), width, height, stride)
+        .as_lines()
+        .run()
+    )
+```
+
+## 6-Phase Pipeline Options
+
+Customize every phase of OCR execution per request:
+
+```python
+from rusto import (
+    DetectionRunOptions,
+    OutputGranularity,
+    PostDetectionOptions,
+    PostRecognitionOptions,
+    PreDetectionOptions,
+    PreRecognitionOptions,
+    RecognitionRunOptions,
+)
+
+result = (
+    engine.detect_text("document.jpg")
+    .with_orientation_detection()
+    .with_auto_unwarp()
+    .with_layout_reading()
+    .with_pre_detection(PreDetectionOptions(descreen_strength=0.3, target_max_side=1280))
+    .with_detection(DetectionRunOptions(limit_side_len=960, limit_type="max"))
+    .with_post_detection(PostDetectionOptions(threshold=0.3, box_threshold=0.6, unclip_ratio=1.6))
+    .with_pre_recognition(PreRecognitionOptions(line_y_threshold=0.5, word_x_threshold=0.4))
+    .with_recognition(RecognitionRunOptions(batch_size=8))
+    .with_post_recognition(PostRecognitionOptions(score_threshold=0.5))
+    .with_output(OutputGranularity.LINES)
+    .run()
+)
+```
+
+## Result Reference
+
+`DetectTextResult` is a tagged union returned by `.run()`:
+
+- `result.is_STRUCTURED()` -> `True` for `.as_lines()` and `.as_words()`. Access `result.results` (`list[TextResult]`):
+  - `item.text` (`str`): Recognized text string.
+  - `item.score` (`float`): Confidence score (`0.0` – `1.0`).
+  - `item.box_points` (`list[Point]`): 4 polygon vertices (`x`, `y`).
+  - `item.frame` (`Frame`): Axis-aligned bounding box (`width`, `height`, `top`, `left`).
+  - `item.region_id` (`int | None`): Layout region index when `with_layout_reading()` is active.
+  - `item.layout_type` (`LayoutType | None`): Semantic region category (`TEXT`, `TITLE`, `TABLE`, `HEADER`, `FOOTER`, `FIGURE`, etc.).
+- `result.is_SPATIAL()` -> `True` for `.as_spatial()`. Access `result.text` (`str`).
+
+## License
+
+Apache-2.0 OR MIT

rusto-0.4.0/README.md

@@ -0,0 +1,178 @@
+# rusto (Python SDK)
+
+Official Python bindings for **RustO!** — a high-performance, pure-Rust OCR engine powered by Indra OCR, PaddleOCR, and the pure-Rust MNN (`rusto-nn`) inference runtime via UniFFI.
+
+## Features
+
+- **Zero-Config Indra OCR**: `RustO.initialize()` automatically downloads and caches the default `indraocr` models on first run from Hugging Face Hub.
+- **Context Manager Support**: Deterministic native resource cleanup with `with RustO.initialize() as engine:` or `engine.close()`.
+- **Full Document Pipeline**: Neural document unwarping (`with_auto_unwarp()`), page orientation detection (`with_orientation_detection()`), semantic layout analysis, and reading-order recovery (`with_layout_reading()`).
+- **Fluent Builder API**: Chain `.as_lines()`, `.as_words()`, `.as_spatial()`, `.as_tsv()`, or `.with_output(...)` into a single `.run()` terminal method.
+- **Zero-Copy Raw RGB Support**: Feed NumPy / OpenCV / Pillow RGB8 buffers directly via `.rgb(pixels, width, height, stride)`.
+
+## Installation
+
+```bash
+pip install rusto
+```
+
+## Quick Start
+
+```python
+from rusto import RustO
+
+# Zero-config initialization (auto-downloads Indra OCR models from Hugging Face Hub if not cached)
+with RustO.initialize() as engine:
+    result = (
+        engine.detect_text("invoice.png")
+        .with_auto_unwarp()
+        .with_layout_reading()
+        .as_lines()
+        .run()
+    )
+
+    if result.is_STRUCTURED():
+        for item in result.results:
+            print(
+                f"[{item.score:.2f}] ({item.layout_type or 'line'} #{item.region_id}) {item.text}"
+            )
+
+    # Reconstructed 2D spatial text layout
+    spatial = engine.detect_text("invoice.png").as_spatial().run()
+    if spatial.is_SPATIAL():
+        print(spatial.text)
+```
+
+You can also manage the engine lifecycle explicitly without a `with` block:
+
+```python
+from rusto import InitializeConfig, RustO
+
+engine = RustO.initialize(InitializeConfig.indra())
+try:
+    result = engine.detect_text("invoice.png").as_words().run()
+    if result.is_STRUCTURED():
+        for word in result.results:
+            print(word.text, word.frame)
+finally:
+    engine.close()
+```
+
+## Custom Configuration & Offline Models (.mnn / .rten)
+
+Select canonical model tiers (`"indraocr"`, `"ppocrv6-tiny"`, `"ppocrv6-small"`, `"ppocrv5-mobile"`, `"ppocrv4-mobile"`), languages, or local model paths:
+
+```python
+from rusto import (
+    DetectionConfig,
+    InitializeConfig,
+    LayoutConfig,
+    RecognitionConfig,
+    RustO,
+    UnwarpConfig,
+)
+
+# Preset by canonical model + language (auto-downloaded to cache)
+cfg = InitializeConfig.for_model("ppocrv6-tiny", lang="latin")
+engine = RustO.initialize(cfg)
+engine.close()
+
+# Explicit local assets for offline environments
+offline_cfg = InitializeConfig(
+    template="indra",
+    enable_reading_order=True,
+    detection=DetectionConfig(enabled=True, model_path="./models/indra_det.mnn"),
+    recognition=RecognitionConfig(
+        enabled=True,
+        model_path="./models/indra_rec.mnn",
+        dict_path="./models/indra_meta.json",
+    ),
+    unwarp=UnwarpConfig(enabled=True, model_path="./models/uvdoc.mnn"),
+    layout=LayoutConfig(enabled=True, model_path="./models/layout_cdla.mnn"),
+)
+with RustO.initialize(offline_cfg) as offline_engine:
+    res = offline_engine.detect_text("scan.png").with_auto_unwarp().as_lines().run()
+```
+
+Pre-download models into a target cache directory ahead of time (e.g., during Docker image build):
+
+```python
+from rusto import download_model
+
+paths = download_model(model="indraocr", lang="latin", cache_dir="./models-cache")
+```
+
+## Input Sources & Raw RGB Buffers
+
+Pass a file path (`str` or `Path`), encoded image `bytes`, `ImageSource`, or raw interleaved 24-bit RGB pixels:
+
+```python
+from pathlib import Path
+import numpy as np
+from rusto import RustO
+
+with RustO.initialize() as engine:
+    # 1. Encoded PNG/JPEG bytes
+    png_bytes = Path("invoice.png").read_bytes()
+    res_bytes = engine.detect_text(png_bytes).as_lines().run()
+
+    # 2. Raw HxWx3 uint8 RGB array (e.g. from Pillow / imageio)
+    rgb_array = np.zeros((720, 1280, 3), dtype=np.uint8)
+    height, width, _ = rgb_array.shape
+    stride = width * 3
+
+    res_rgb = (
+        engine.detect_text()
+        .rgb(rgb_array.tobytes(), width, height, stride)
+        .as_lines()
+        .run()
+    )
+```
+
+## 6-Phase Pipeline Options
+
+Customize every phase of OCR execution per request:
+
+```python
+from rusto import (
+    DetectionRunOptions,
+    OutputGranularity,
+    PostDetectionOptions,
+    PostRecognitionOptions,
+    PreDetectionOptions,
+    PreRecognitionOptions,
+    RecognitionRunOptions,
+)
+
+result = (
+    engine.detect_text("document.jpg")
+    .with_orientation_detection()
+    .with_auto_unwarp()
+    .with_layout_reading()
+    .with_pre_detection(PreDetectionOptions(descreen_strength=0.3, target_max_side=1280))
+    .with_detection(DetectionRunOptions(limit_side_len=960, limit_type="max"))
+    .with_post_detection(PostDetectionOptions(threshold=0.3, box_threshold=0.6, unclip_ratio=1.6))
+    .with_pre_recognition(PreRecognitionOptions(line_y_threshold=0.5, word_x_threshold=0.4))
+    .with_recognition(RecognitionRunOptions(batch_size=8))
+    .with_post_recognition(PostRecognitionOptions(score_threshold=0.5))
+    .with_output(OutputGranularity.LINES)
+    .run()
+)
+```
+
+## Result Reference
+
+`DetectTextResult` is a tagged union returned by `.run()`:
+
+- `result.is_STRUCTURED()` -> `True` for `.as_lines()` and `.as_words()`. Access `result.results` (`list[TextResult]`):
+  - `item.text` (`str`): Recognized text string.
+  - `item.score` (`float`): Confidence score (`0.0` – `1.0`).
+  - `item.box_points` (`list[Point]`): 4 polygon vertices (`x`, `y`).
+  - `item.frame` (`Frame`): Axis-aligned bounding box (`width`, `height`, `top`, `left`).
+  - `item.region_id` (`int | None`): Layout region index when `with_layout_reading()` is active.
+  - `item.layout_type` (`LayoutType | None`): Semantic region category (`TEXT`, `TITLE`, `TABLE`, `HEADER`, `FOOTER`, `FIGURE`, etc.).
+- `result.is_SPATIAL()` -> `True` for `.as_spatial()`. Access `result.text` (`str`).
+
+## License
+
+Apache-2.0 OR MIT

{rusto-0.3.2 → rusto-0.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rusto"
-version = "0.3.2"
-description = "Pure Rust OCR library for Python based on RapidOCR and PaddleOCR"
+version = "0.4.0"
+description = "Pure Rust OCR library for Python based on RapidOCR, Indra OCR, and pure-Rust MNN (rusto-nn)"
 readme = "README.md"
 authors = [{ name = "RustO Contributors", email = "contact@rusto.dev" }]
 license = "MIT"