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.
dotnet add package RecursiveAI.OneOcr dotnet add package RecursiveAI.OneOcr.Models
Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
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, 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:
recognition language document character information dictionary reading exampleThe 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”.
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:
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
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 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 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. 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.