Recursive AI

Load a custom OCR recognition model in C#

OneOcr is a free, open-source OCR library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Load recognition weights from a file to use a fine-tuned OCR model. OneOcr accepts its crnn-v0 model container (OneOcr’s own model file format), not arbitrary neural-network files.

Terminal
dotnet add package RecursiveAI.OneOcr
dotnet add package RecursiveAI.OneOcr.Models

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneImage;
using OneOcr;
 
// recognizer.ocr: your fine-tuned model, or export the bundled
// starting weights with BundledModels.ReadRecognizer()
// (using OneOcr.Models;), as the full program does.
var engine = OcrEngine.Load(
    "recognizer.ocr",
    withBundledModels: false);
Console.WriteLine(engine.ToText(
    Image.Load("form.png")));

Unzip the example, then dotnet run.

Use your own recognizer.ocr; the full program exports the bundled starting recognizer if that file is absent. form.png is included. Prints:

Text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00

The full program

The download includes form.png, an original synthetic form containing the four lines printed above.

No trained custom weights are included. This example exercises the file-loading API with the published starting weights. Replace recognizer.ocr with your fine-tuned container before running to use that model instead.

C#
using OneImage;
using OneOcr;
using OneOcr.Models;
 
// The demo exports the starting recognizer; use your fine-tuned file instead.
if (!File.Exists("recognizer.ocr"))
    File.WriteAllBytes("recognizer.ocr", BundledModels.ReadRecognizer());
var engine = OcrEngine.Load("recognizer.ocr", withBundledModels: false);
Console.WriteLine(engine.ToText(Image.Load("form.png")));
 
if (!BundledModels.TryReadDetector(out byte[] data, out string? reason))
    throw new InvalidOperationException(reason);
File.WriteAllBytes("detector.ocr", data);
var detected = engine.WithDetector("detector.ocr");
Console.WriteLine("With detector:");
Console.WriteLine(detected.ToText(Image.Load("form.png")));
try
{
    using var invalid = new MemoryStream(new byte[16]);
    OcrEngine.Load(invalid, withBundledModels: false);
}
catch (OcrModelException error)
{
    Console.WriteLine($"Bad model: {error.Message}");
}
Text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
With detector:
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00
Bad model: Not a model container: the magic bytes are wrong.

Load throws OcrModelException for malformed containers or the wrong architecture, and OcrLimitException when a model exceeds the configured limits.

Variations

Load from a stream instead of a path. This replaces the first load and read in the program:

C#
using var model = File.OpenRead("recognizer.ocr");
var engine = OcrEngine.Load(model,
    withBundledModels: false);
Console.WriteLine(engine.ToText(
    Image.Load("form.png")));
Text
Invoice number: INV-1042
Date: 2026-11-16
Customer: Jane Smith
Total: 125.00

The short answer

Call OcrEngine.Load("recognizer.ocr", withBundledModels: false) to load a recognizer alone, then call engine.ToText(image). Add a detector with WithDetector("detector.ocr") when you want explicit page detection too. Neither operation requires setting OcrEngine.Default, so different callers can use different model instances.

On its first run it exports the package’s starting weights. When your own recognizer file is already present, the program leaves it in place and loads it.

How do I load a custom OCR model in C#?

Use a OneOcr model container with the recognition architecture crnn-v0. The Load API accepts either a file path or a stream positioned at the start of that container. Loading weights is separate from choosing the image: load the engine first, then read each image using that engine.

The format is not inferred from a filename extension. Renaming another kind of model to .ocr does not convert its architecture or tensor layout. For your own weights, use the training workflow and the model container specification rather than changing an unrelated file’s suffix.

Does a custom recognizer need a page detector?

Not necessarily. With withBundledModels: false, the engine reads with the built-in classical line finder and no word model. The full program first runs in that configuration. It then loads an explicit detector file with WithDetector and reads the same image again. Both runs produce the printed form text in this example.

By default, Load(path) attaches bundled page models when available. That includes the page detector, word model and word frequencies. Merely supplying a recognizer path does not disable those additions. Pass false when you need recognition-only loading, and attach any detector you choose explicitly.

Why does loading an OCR model fail?

A malformed container or a container describing another architecture raises OcrModelException. The program demonstrates the malformed case with a short stream of zero bytes; the exact message is shown above. A model beyond the configured resource bounds raises OcrLimitException instead. A missing path is a file-access problem, not evidence that the weights are compatible.

Keep recognition weights distinct from document extraction weights. Recognition reads letters from the image. A document extractor consumes recognized words and assigns fields or key/value relationships. An extraction model is therefore not an interchangeable input to OcrEngine.Load. Use the appropriate loader for each role rather than trying loaders until one accepts a file.

For an application with several models, retain explicit engine references and pass the intended one to each read. This avoids changing a process-wide default simply to handle one document with another recognizer.

All oneocr recipes