RustODotnet 0.2.5

RustODotnet

RustODotnet exposes canonical RustO OCR API for .NET. Initialize model session once, run many request-local detections, then dispose engine.

dotnet add package RustODotnet
# Add matching language-model package when needed:
# dotnet add package RustODotnet.Models.PPOCRv6.Tiny

Complete example

using System;
using System.IO;
using RustODotnet;

var config = InitializeConfig.Ppv6();
using var ocr = RustO.Initialize(config);

var result = ocr.DetectText(
    new UriImageSource("invoice.jpg"),
    new OcrRunOptions
    {
        Output = OutputGranularity.Words,
        TextScore = 0.55f,
        MaxSideLen = 1600f,
        Detection = new DetectionRunOptions
        {
            LimitSideLen = 960,
            LimitType = "max",
        },
        Postprocess = new PostprocessRunOptions
        {
            UseDilation = true,
        },
    });

switch (result)
{
    case StructuredDetectTextResult structured:
        foreach (var item in structured.Items)
            Console.WriteLine($"{item.Text} ({item.Score:F2}) at {item.Frame.Left}, {item.Frame.Top}");
        break;
    case SpatialDetectTextResult spatial:
        Console.WriteLine(spatial.Text);
        break;
}

Example structured output:

Total (0.98) at 40, 120
$12.50 (0.96) at 140, 120

Public API

Initialization config

Initialization selects model preset/resources. It does not control per-image preprocessing.

using var ocr = RustO.Initialize(InitializeConfig.Ppv6(
    detection: new DetectionConfig { ModelPath = "models/det.mnn" },
    recognition: new RecognitionConfig
    {
        ModelPath = "models/rec.mnn",
        DictPath = "models/dict.txt",
    }));

Model resolution checks model-package content and common application/model paths. For custom resources, pass explicit paths. Core and model NuGet package versions must match.

Request-local options

OcrRunOptions applies only to one DetectText call. Unset properties merge with initialized defaults and do not mutate next call.

var options = new OcrRunOptions
{
    Output = OutputGranularity.Words,
    LineYThreshold = 0.5f,
    WordXThreshold = 0.4f,
    TextScore = 0.55f,
    MaxSideLen = 1600f,
    Detection = new DetectionRunOptions
    {
        LimitSideLen = 960,
        LimitType = "max",
        Mean = new[] { 0.485f, 0.456f, 0.406f },
        Std = new[] { 0.229f, 0.224f, 0.225f },
    },
    Postprocess = new PostprocessRunOptions
    {
        Threshold = 0.3f,
        BoxThreshold = 0.6f,
        MaxCandidates = 1000,
        UnclipRatio = 2.0f,
        UseDilation = true,
    },
};

Detection and Postprocess are root-level OcrRunOptions properties. No nested Preprocessing API exists.

Sources and output

var fromPath = ocr.DetectText(new UriImageSource("/tmp/receipt.png"));
var fromBytes = ocr.DetectText(new BytesImageSource(File.ReadAllBytes("receipt.png")));

var spatial = ocr.DetectText(
    new UriImageSource("table.png"),
    new OcrRunOptions { Output = OutputGranularity.Spatial });

if (spatial is SpatialDetectTextResult layout)
    Console.WriteLine(layout.Text);
// Item                 Amount
// Coffee                $3.50
// Total                $12.50

TextResult has Text, Score, BoxPoints, and Frame. BoxPoints contains top-left, top-right, bottom-right, bottom-left image-pixel coordinates. Frame is axis-aligned with Left, Top, Width, Height.

Errors and lifecycle

• RustOException indicates native initialization, model, image decode, option, or OCR failure.
• Constructors reject null source payloads. Validate input file/resource availability before detection.
• Always dispose RustO; using var handles success and failure paths.
• Invalid request options do not require reinitialization. Correct options and call DetectText again.