Recursive AI

Batch OCR images in order in C#

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

Give OneOcr a list of single-frame images to get one result per input, in the same order.

Terminal
dotnet add package RecursiveAI.OneOcr

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

C#
using OneImage;
using OneOcr;
var engine = OcrEngine.LoadBundled();
var a = Image.Load("c.png");
var b = Image.Load("a.png");
foreach (var p in engine.Ocr([a, b]))
    Console.WriteLine((p.Index, p.ToText()));

Unzip the example, then dotnet run.

The download’s c.png starts with “Coffee break” and a.png with “April departure.” The snippet prints each page index and its text:

Text
(0, Coffee break
Meet at the station
Return before sunset)
(1, April departure
Meet at the station
Return before sunset)

The OneOcr package brings in OneImage, which supplies Image.Load.

The full program

The program loads c.png (“Coffee break”), a.png (“April departure”), and b.png (“Bicycle rental”) into memory. All three notes also say “Meet at the station” and “Return before sunset.” It checks both the indices and the first recognized lines, so a reordering can’t pass just because the page numbers are consecutive.

C#
using OneImage;
using OneOcr;
 
var engine = OcrEngine.LoadBundled();
string[] files = ["c.png", "a.png", "b.png"];
List<Image> images = files.Select(path => Image.Load(path)).ToList();
var pages = engine.Ocr(images);
string[] expected = ["Coffee break", "April departure", "Bicycle rental"];
if (pages.Count != files.Length)
    throw new InvalidOperationException("Expected one page per input.");
 
for (int i = 0; i < pages.Count; i++)
{
    var page = pages[i];
    var text = page.ToText().Split('\n')[0].Trim();
    if (page.Index != i || text != expected[i])
        throw new InvalidOperationException($"Unexpected result for {files[i]}.");
    Console.WriteLine($"{page.Index} {files[i]}: {text}");
}

dotnet run prints:

Text
0 c.png: Coffee break
1 a.png: April departure
2 b.png: Bicycle rental

If one of the images has multiple frames, the batch call throws ArgumentException; use OcrPages to read the frames of a single TIFF.

Variations

Continue numbering from an earlier batch. Replace the foreach in the first snippet with this asynchronous call and start the first result at 20:

C#
var options = new OcrOptions { PageIndex = 20 };
var pages = await engine.OcrAsync([a, b], options);
foreach (var page in pages)
    Console.WriteLine($"{page.Index}: {page.Words[0].Text}");
Text
20: Coffee
21: April

The short answer

Load the files into a list of Image objects in the order you want, then pass the list to engine.Ocr(images). Result pages[i] corresponds to images[i]. Its Index starts at 0 unless you set OcrOptions.PageIndex. The downloadable example uses an order other than alphabetical so you can see that the batch follows the input list, not the filenames.

How do I batch OCR multiple images in a specific order?

Decide the sequence before loading the images. For a set of photos that make up one scanned document, use the order stored with the document, not the order that files happen to appear in a directory listing. If your app needs to associate the recognized text with a file or an upload ID, keep that list next to the list of images. Match each result by its position in the returned list, even if the Index starts above zero.

The same ordering applies to OcrAsync. According to the OneOcr API docs at v1.0.0, the async call runs the same batch on a thread-pool thread. Keep the images alive until it completes. The list API returns no pages for an empty list. If the call throws, there’s no returned list of partial results to match with your inputs.

Should I batch OCR a multi-page file or read its pages directly?

Batch OCR takes separate images and expects each to have exactly one frame. OcrPages reads all frames of one file, such as a multi-page TIFF, in frame order. Don’t use the batch method with a multi-frame Image just because its pages belong in the same document. For a PDF, the PDF bridge handles page reading instead.

MaxPagesPerCall counts the images in the list for batch OCR and counts frames when reading a multi-frame image. If you choose to split a large list into smaller calls, set PageIndex to the number of pages already processed to preserve numbering across the calls. That changes the indices, not the order of each batch.

All oneocr recipes