Recursive AI

Set OCR image and page limits in C#

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

Limit pixels (width × height, per frame) and pages before decoding uploads.

Terminal
dotnet add package RecursiveAI.OneOcr

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

C#
using OneOcr;
var limits = new OcrLimits {
    MaxImagePixels = 150_000,
    MaxPagesPerCall = 1
};
var engine = OcrEngine.LoadBundled(limits);
var pages = engine.OcrPages("map.png");
Console.WriteLine(pages.Count);

Unzip the example, then dotnet run.

The download’s map.png is a 560 × 245 train note beginning “Map for the morning train.” The snippet prints 1: one page fits the limits.

The full program

The example reads the train note and refuses wide.png, a 1,000 × 245 image that says “Wide.” It also opens two.tiff (two 220 × 110 frames, labeled “First” and “Second”) and not-an-image.txt (the line not an image). Finally it tries the train note again with an already-cancelled token.

C#
using OneOcr;
 
var engine = OcrEngine.LoadBundled(new OcrLimits
{
    MaxImagePixels = 150_000,
    MaxPagesPerCall = 1
});
 
TryRead("map.png", () => engine.OcrPages("map.png"));
TryRead("wide.png", () => engine.OcrPages("wide.png"));
using var frames = File.OpenRead("two.tiff");
TryRead("two.tiff", () => engine.OcrPages(frames));
using var invalid = File.OpenRead("not-an-image.txt");
TryRead("not-an-image.txt", () => engine.OcrPages(invalid));
 
using var stop = new CancellationTokenSource();
stop.Cancel();
TryRead("map.png", () => engine.OcrPages("map.png", cancellationToken: stop.Token));
 
static void TryRead(string name, Func<IReadOnlyList<OcrPage>> read)
{
    try
    {
        Console.WriteLine($"{name}: {read().Single().ToText().Split('\n')[0].Trim()}");
    }
    catch (OcrLimitException)
    {
        Console.WriteLine($"{name}: over the OCR limit");
    }
    catch (OcrFormatException)
    {
        Console.WriteLine($"{name}: unreadable image");
    }
    catch (OperationCanceledException)
    {
        Console.WriteLine($"{name}: cancelled");
    }
}

dotnet run prints:

Text
map.png: Map for the morning train
wide.png: over the OCR limit
two.tiff: over the OCR limit
not-an-image.txt: unreadable image
map.png: cancelled

The path, stream, and byte[] overloads of OcrPages apply the pixel and frame limits before decoding pixels; those limits don’t cap the encoded upload’s byte length.

Variations

Read buffered bytes instead of a path. Replace the last two lines of the snippet at the top if your application already has the encoded image in memory:

C#
byte[] bytes = File.ReadAllBytes("map.png");
var pages = engine.OcrPages(bytes);
Console.WriteLine(pages.Count);

It prints 1. For an upload, cap the encoded byte count before buffering it.

The short answer

Set MaxImagePixels and MaxPagesPerCall in OcrLimits when loading the engine. Give OcrPages the encoded input as a path, stream, or bytes. This passes the limits to the decoder before it decodes the pixels. If you load an Image first and then pass it to OCR, the engine can’t apply its limits to your earlier image load.

What is the maximum pixel size for an OCR image?

This setting is a count of pixels per frame, not a maximum width, height, or size on disk. Multiply width by height: the 560 × 245 PNG has 137,200 pixels and fits the example’s 150,000-pixel limit. The 1,000 × 245 PNG has 245,000 pixels and doesn’t fit. Pick a cap based on the image dimensions your feature needs; the recipe’s cap is for its small samples, not a recommendation for full-page scans. With no custom limits, the v1.0.0 settings allow 134,217,728 pixels (2^27) per frame.

How many pages can I read from a multi-page image?

Each decoded frame produces an OCR page. MaxPagesPerCall limits how many frames the decoder accepts. In the example, each frame in the TIFF is only 24,200 pixels, but the file still fails because two frames exceed the page cap of one. Both checks matter: limiting the pages alone still allows one very large frame, and limiting each frame alone doesn’t stop a file containing many small ones. These are image limits, not an upload-size limit or a total memory cap for the process.

How do I tell an oversized image from an unreadable one?

Handle OcrLimitException when the input exceeds a configured limit and OcrFormatException when the decoder can’t read the bytes. The image guard at v1.0.0 preserves the underlying image exception as the inner exception. Cancellation is a separate OperationCanceledException. Use it to stop the request rather than telling the user that their file is too big or damaged. A missing file or failed stream read is a separate I/O problem.

All oneocr recipes