Aspose.OMR FOSS
Python
How to Work with the API in Python

How to Work with the API in Python

Aspose.OMR FOSS for Python’s public API (omr.api) is intentionally small: OmrEngine, TemplateProcessor, ImageCollection, and FormValidationLogic. This guide shows how they fit together across a generate-and-recognize workflow.

Step-by-Step Guide

Step 1: Install the Package 

git clone https://github.com/aspose-omr-foss/Aspose.OMR-FOSS-for-Python.git
cd Aspose.OMR-FOSS-for-Python
pip install -e .
python -c "import omr; print('Aspose.OMR FOSS for Python is ready.')"

Step 2: Import Required Classes 

from omr.api import OmrEngine, FormValidationLogic

Step 3: Generate and Save a Template 

engine = OmrEngine()
gen = engine.Generate("final-exam.txt")
gen.Save("out", "final-exam")

Step 4: Load the Template for Recognition

Pass FormValidationLogic.Exception instead of the default Ignore if you want a violation to raise for questions that have multi-select disabled, instead of being silently accepted.

processor = engine.GetTemplateProcessor("out/final-exam.omr", FormValidationLogic.Exception)

Step 5: Recognize and Export 

result = processor.Recognize("scan.png")
print(result.GetCsv())

Common Issues and Fixes

FormValidationLogic.Exception never raises, even on a multi-marked question. The check only fires for a question with Multiselect disabled; GlobalPageSettings.Multiselect defaults to enabled, so confirm it is explicitly turned off for the question you expect to be single-select.

I need to recognize many scans at once. Use TemplateProcessor.RecognizeFolder(folderPath, recognitionThreshold) instead of calling Recognize() in a loop.

I registered an image under a name that was already used. ImageCollection.Add does not overwrite — check Contains(name) first, or use a unique name per image.

Frequently Asked Questions

Is OmrEngine safe to reuse across multiple templates?

Yes — it is stateless.

How do I re-score a result with a different threshold without re-scanning?

Call TemplateProcessor.Recalculate(result, recognitionThreshold).

How do I embed an in-memory image into markup instead of reading from disk?

Register it with ImageCollection.Add(name, image_bytes), then reference it in markup as ?image=<name>.

See Also