Zaya.OCR.Impl.OneOcr 2.0.0

Zaya.OCR

Pluggable OCR and text-layout abstractions for the Zaya ecosystem — engines expose metadata and SettingDescriptors, hosts pass settings into CreateSessionAsync.

Packages

Requires Zaya.Primitives 2.0.0. Impl packages depend on Zaya.Logging 1.0.0. Update channel for plugins: plugin-Zaya.OCR-v2.0-latest. See versioning and CHANGELOG.

Docs: API & articles

Features

• IOCRService — engine id, localized name/description, Settings, PreferredPixelFormat, CreateSessionAsync
• IOCRSession — RecognizeAsync(IRawImage) → IOCRResult (words + confidence) from Zaya.Primitives.OCR
• ITextLayoutService / ITextLayoutSession — structure OCR words into paragraphs/lines (ITextResult: Paragraphs + FullText)
• ITextLineExt / ITextParagraphExt — optional tracking/ghost metadata for debug overlay (as ITextLineExt / as ITextParagraphExt)
• SettingDescriptor — typed UI settings from Zaya.Primitives.Settings
• Failures surface as LocalizedException for host UI
• Impl constructors take ILoggingWrapper (parameterless uses EmptyLoggingWrapper) and wrap sessions / nested services for Trace/Debug logging
• Plugin zips include plugin.json with entryPoint (e.g. Zaya.OCR.Impl.OneOcr.OneOcrService)

There is no separate InitializeAsync / OcrEngineProvider: create a session with defaults or an explicit settings dictionary.

Installation

<PackageReference Include="Zaya.OCR" Version="2.0.0" />
<PackageReference Include="Zaya.OCR.Impl.OneOcr" Version="2.0.0.0" />

<PackageReference Include="Zaya.OCR.Impl.WindowsMediaOcr" Version="2.0.0.0" />
<PackageReference Include="Zaya.OCR.Impl.ProximityTextLayout" Version="2.0.0.0" />

Zaya.Logging is pulled transitively by the Impl packages.

Plugin zips for ScreenTranslator hosts (stable names) from GitHub Releases (plugin-Zaya.OCR-v2.0-latest):

• Zaya.OCR.Impl.OneOcr.zip
• Zaya.OCR.Impl.WindowsMediaOcr.zip
• Zaya.OCR.Impl.ProximityTextLayout.zip

Quick start (OneOCR)

using System.Drawing;
using Zaya.OCR.Impl.OneOcr;
using Zaya.OCR.Services;

using var ocr = new OneOcrService(); // or new OneOcrService(logging)

using var session = await ocr.CreateSessionAsync(new Dictionary<string, object>
{
    ["source"] = "auto",          // SnippingTool, then download URL fallback
    ["minConfidence"] = 40,       // 0–100
});

using var bitmap = new Bitmap(@"C:\screenshot.png");
var result = await session.RecognizeAsync(bitmap); // Bitmap extension in Impl.OneOcr

foreach (var word in result.Words)
    Console.WriteLine($"'{word.Text}' at {word.Bounds} ({word.Confidence:P0})");

Typed settings helper:

var config = new OneOcrConfig
{
    Source = OneOcrSource.Auto,
    MinConfidence = 40,
};
using var session = await ocr.CreateSessionAsync(
    config.ToDictionary()
        .Where(kv => kv.Value is not null)
        .ToDictionary(kv => kv.Key, kv => kv.Value!));

Or DI:

services.AddOneOcr();
// services.AddWindowsMediaOcr();
// services.AddProximityTextLayout();

Engine lifecycle

Resolve IOCRService (new / DI / plugin host)
  → Read DisplayName / Description / Settings (build UI)
  → CreateSessionAsync(settings)   // or CreateSessionAsync() for defaults
  → RecognizeAsync(IRawImage | Bitmap)
  → Dispose session / service

Session creation (download, missing DLL, etc.) throws LocalizedException subclasses such as OneOcrSnippingToolNotFoundException, OneOcrDllNotFoundException.

OneOCR settings (EngineId: oneocr)

source = auto: use complete cache if present; else try SnippingTool; if not found, download via downloadUrl.

Full details: docs/articles/oneocr-settings.md

Windows Media OCR settings (EngineId: windows-media-ocr)

Requires Windows 10+, OCR language packs, and typically MSIX package identity for desktop hosts. Details: docs/articles/windows-media-ocr-settings.md

Input formats

Proximity Text Layout settings (EngineId: proximity-text-layout)

Merges OCR words into lines/paragraphs by proximity heuristics. Optional filters (word / line / paragraph) run before layout finalization. Optional stabilization (enableStabilization) snaps line bounds to the previous frame, smooths text flicker, and keeps unmatched paragraphs as ghosts. Debug overlay can read match/ghost fields via ITextLineExt / ITextParagraphExt (e.g. IsGhost, PreviousFrameText).

using Zaya.OCR.Impl.ProximityTextLayout;

using var layout = new ProximityTextLayoutService();
using var layoutSession = await layout.CreateSessionAsync(new Dictionary<string, object>
{
    ["enableStabilization"] = true,
    ["centerThresholdXPercent"] = 300,
    ["centerThresholdYPercent"] = 75,
});
var structured = await layoutSession.ProcessAsync(ocrResult);

Layout heuristics

Integer thresholds are stored as ints and applied as /100 at runtime when they are percentages. Units are stated in each setting description.

Filters (tables)

Each of wordFilters, lineFilters, and paragraphFilters is a table of rules applied at that stage (words → lines → paragraphs → stabilization). Case is always ignored.

Stabilization (across frames)

holdNewBlocks, levenshteinThreshold, and ghostMaxFrames are visible in UI only when enableStabilization is true. Tracking settings (centerThreshold*, merge/word-gap hysteresis) stay visible because line/paragraph matching always runs.

Requirements

• Zaya.OCR — .NET 8+
• OneOCR — Windows 10 build ≥ 22000 (Windows 11), x64; native oneocr.dll + model from SnippingTool, local folder, or download URL
• Windows Media OCR — Windows 10+; WinRT Windows.Media.Ocr; OCR language packs; desktop apps usually need package identity (MSIX)

Ecosystem

• Zaya.Primitives — IRawImage, PixelFormat, LocalizedString, LocalizedException, BoundingBox, Zaya.Primitives.OCR.*, Zaya.Primitives.Settings.* (2.0.0)
• Zaya.Logging — ILoggingWrapper / EmptyLoggingWrapper for Impl constructors and session wrapping (1.0.0)
• Zaya.ScreenTranslator — host that loads OCR / layout plugins and binds settings in UI

License

MIT