The Core API

The Core API

omr.api is the small surface most code interacts with: OmrEngine, TemplateProcessor, ImageCollection, and the FormValidationLogic enum.

OmrEngine

OmrEngine is a stateless factory. Generate(source, settings) accepts a markup-DSL source or a TemplateConfig tree and returns a GenerationResult. GetTemplateProcessor(templateSource, validationLogic) loads a previously saved .omr file path and returns a bound TemplateProcessor; a stream source instead takes a text-encoding argument before the validation logic.

from omr.api import OmrEngine, FormValidationLogic

engine = OmrEngine()
gen = engine.Generate("final-exam.txt")
gen.Save("out", "final-exam")
processor = engine.GetTemplateProcessor("out/final-exam.omr", FormValidationLogic.Ignore)

FormValidationLogic

Controls engine behavior when a template validation rule — such as a multi-select constraint — is broken during recognition: Ignore (default) silently accepts the violation, Exception raises, and undefined is the enum’s zero value. The check only applies to questions whose Multiselect is disabled; GlobalPageSettings.Multiselect defaults to enabled.

TemplateProcessor

Recognize(source, recognitionThreshold) recognizes one scanned image. RecognizeFolder(folderPath, recognitionThreshold) recognizes every image in a folder in one call. Recalculate(result, recognitionThreshold) re-scores an already-recognized result with a different threshold, without re-reading the source image.

ImageCollection

An append-only, case-sensitive map from a name to raw image bytes. Add(name, image) registers an image, Contains(name) checks whether a name is already registered, Count reports how many are registered, and as_dict() returns the backing map. Markup can reference a registered image by name (?image=<name>) instead of a filesystem path.

from omr.api import ImageCollection

images = ImageCollection()
with open("logo.png", "rb") as f:
    images.Add("logo.png", f.read())

Tips and Best Practices

• Pass FormValidationLogic.Exception during development to surface multi-select violations immediately instead of silently ignoring them (only fires for questions with Multiselect disabled).
• Recalculate() is cheaper than re-scanning — use it when only the recognition threshold needs to change.
• ImageCollection names are case-sensitive; registering the same name twice raises rather than overwriting silently.
• Generate() reports most failures through GenerationResult.ErrorCode/ErrorMessage rather than raising — check ErrorCode before trusting a generated result.

Common Issues

FAQ

Is OmrEngine safe to reuse across multiple templates?

Yes — it is stateless; each Generate()/GetTemplateProcessor() call is independent.

How do I recognize a whole folder of scans at once?

Call TemplateProcessor.RecognizeFolder(folderPath, recognitionThreshold) instead of looping Recognize() yourself.

API Reference Summary

See Also

• Aspose.OMR — Enterprise Documentation