---
title: "Set OCR image and page limits in C#"
url: https://recursiveai.org/oneocr/cookbook/bound-untrusted-ocr-input-size/
description: "Limit pixels per frame and pages per call before OCR image decoding in C#. Handle size refusals, unreadable files, and cancellation separately."
version: "1.0.0"
---

# 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.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneOcr) · [GitHub](https://github.com/recursive-ai-oss/oneocr-csharp) · [Docs](https://recursiveai.org/oneocr/docs/) · [Download example (.zip)](https://recursiveai.org/oneocr/cookbook/bound-untrusted-ocr-input-size/bound-untrusted-ocr-input-size.zip)

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

```shell
dotnet add package RecursiveAI.OneOcr
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
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](https://recursiveai.org/oneocr/cookbook/bound-untrusted-ocr-input-size/bound-untrusted-ocr-input-size.zip), 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.

```csharp
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:

```csharp
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.

## Related recipes

- [Cancel an OCR operation](https://recursiveai.org/oneocr/cookbook/cancel-ocr-operation/)
- [Read a multi-page TIFF](https://recursiveai.org/oneocr/cookbook/ocr-multipage-tiff/)

## 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](https://github.com/recursive-ai-oss/oneocr-csharp/blob/8db430fb77c4d86d51686f15dfd9b5ccc20c99a7/src/OneOcr/OcrLimits.cs#L60-L64) 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](https://github.com/recursive-ai-oss/oneocr-csharp/blob/8db430fb77c4d86d51686f15dfd9b5ccc20c99a7/src/OneOcr/ImageGuard.cs#L27-L51) 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.
