---
title: "OCR with beam search decoding in C#"
url: https://recursiveai.org/oneocr/cookbook/ocr-with-beam-search-decoding/
description: "Enable CTC beam search with a character language model in OneOcr for C#. Run greedy and beam decoding on the same image and compare the real text."
version: "1.0.0"
---

# OCR with beam search decoding 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/ocr-with-beam-search-decoding/ocr-with-beam-search-decoding.zip)

Greedy decoding, the default, picks the most likely character at each step. Beam search keeps alternative readings in CTC (connectionist temporal classification), the step that turns recognition scores into text. A character language model can help rank ambiguous words; it does not guarantee a correction. Page reading and word boxes remain greedy.

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

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

```csharp
using OneImage;
using OneOcr;
using OneOcr.Decoding;
using OneOcr.Models;

if (!BundledModels.TryReadLanguageModel(
        out byte[] data, out string? reason))
    throw new InvalidOperationException(reason);
File.WriteAllBytes("language.ocr-lm", data);
var engine = OcrEngine.LoadBundled();
var options = new DecodeOptions {
    Mode = CtcDecoding.Beam, BeamWidth = 8,
    LanguageModel = CharLanguageModel.Load(
        "language.ocr-lm")
};
Console.WriteLine(engine.ToText(
    Image.Load("words.png"), options));
```

Unzip [the example](https://recursiveai.org/oneocr/cookbook/ocr-with-beam-search-decoding/ocr-with-beam-search-decoding.zip), then `dotnet run`.

The snippet exports `language.ocr-lm` from the models package. Use `words.png` from the download: a synthetic line of tiny, blurred italic text. The snippet prints:

```text
recognition language document character information dictionary reading example
```

## The full program

Running `dotnet run` in the unzipped example runs this full greedy-versus-beam program. It exports the bundled character language model, loads it from a file, then prints both decoders’ text. Here beam decoding corrects the greedy readings “recagniton”, “informoton” and “esampãe” to “recognition”, “information” and “example”.

```csharp
using OneImage;
using OneOcr;
using OneOcr.Decoding;
using OneOcr.Models;

if (!BundledModels.TryReadLanguageModel(out byte[] data, out string? reason))
    throw new InvalidOperationException(reason);
File.WriteAllBytes("language.ocr-lm", data);
var greedy = OcrEngine.LoadBundled();
var beam = greedy.WithDecoding(new DecodeOptions
{
    Mode = CtcDecoding.Beam,
    BeamWidth = 8,
    LanguageModel = CharLanguageModel.Load("language.ocr-lm")
});
var image = Image.Load("words.png");
Console.WriteLine("Greedy:");
Console.WriteLine(greedy.ToText(image));
Console.WriteLine("Beam:");
Console.WriteLine(beam.ToText(image, beam.Decoding));
```

`dotnet run` prints:

```text
Greedy:
recagniton language document character informoton dictionary reading esampãe
Beam:
recognition language document character information dictionary reading example
```

An invalid decoding setting throws `ArgumentException`; a beam wider than the configured `OcrLimits.MaxBeamWidth` throws `OcrLimitException`.

## Related recipes

- [Extract text from an image](https://recursiveai.org/oneocr/cookbook/extract-text-from-image/)
- [Read OCR words and coordinates as JSON](https://recursiveai.org/oneocr/cookbook/page-json/)

## The short answer

Set `DecodeOptions.Mode` to `CtcDecoding.Beam`, supply a `CharLanguageModel`, and pass those options to `engine.ToText(image, options)`. Alternatively, create an engine with `WithDecoding(options)` and explicitly pass its `Decoding` to the plain-text call, as the full program does. Neither method turns page-model reading into beam decoding.

The model file is exported at runtime so it need not be copied into the download. You can replace it with a compatible character language model file of your own.

## What is the difference between greedy search and beam search?

Keep the recognizer and decoder roles separate. The recognizer produces class scores over time. CTC decoding turns them into text by handling repeated classes and blank steps. Greedy decoding chooses the winning class at each step, merges repeats and drops blanks. OneOcr’s prefix beam search instead retains alternative prefixes while scoring candidate readings. The [decoding specification](https://recursiveai.org/oneocr/docs/decoding/) defines its scoring and tie rules.

`WithDecoding` returns a new engine that shares the loaded recognizer; the original engine is unchanged. That lets the full program compare the same image and weights with two decoding choices.

### Is beam search better than greedy decoding for OCR?

It is not a guarantee of a better transcription. On the tiny, blurred italic text above, beam decoding corrects three misspelled words. On the labeled form tried while preparing this example, it instead added spurious short lines. A correction on this input does not establish better results on other images. Choose a decoder using the documents your application actually reads, and check the text against those documents rather than assuming that a wider beam fixes OCR errors.

The character model ranks words by their character sequences. It is not a sentence-level reasoning model: the [character model specification](https://recursiveai.org/oneocr/docs/char-lm/) says that it scores one word at a time, with no context across spaces. A model suitable for one collection of words may not be suitable for another.

Words containing digits or code symbols are read as greedy decoding reads them, according to the [decoding docs](https://recursiveai.org/oneocr/docs/decoding/). This protects identifiers from language-model correction. It does not mean that every digit in the image is correct; the recognizer can still misread the pixels.

### Can I use beam search and keep OCR word boxes?

`Ocr` and `ToMarkdown` always use greedy CTC because word boxes come from the greedy alignment. Configuring a beam engine does not change that page-reading contract. If you need coordinates, use the page model and inspect its words; if you need alternative plain text, use the explicit decoding overload shown here.

Do not attach beam-decoded strings to greedy word boxes by their position in a string. A changed reading can have a different length or spacing, so the text alone does not establish a new alignment. For an application that needs highlights, keep the page result as its coordinate-bearing source and the beam text as a separate reading.
