Introduction
Aspose.OMR FOSS for Python is an open-source library for designing OMR (optical mark recognition) forms — multiple-choice answer sheets, checkbox forms, and surveys — and recognizing the marks a respondent fills in from a scanned or photographed image. It targets developers automating exam grading, survey tabulation, or form-based data collection in Python.
The library imports as import omr and has no dependency on any Aspose commercial package. It is MIT licensed and built on three dependencies: numpy, opencv-python, and Pillow. This is an early release (v0.1.0) covering the foundation, generation, and recognition layers of the full Aspose.OMR surface.
What’s Included
A Code-First Template Tree
A template is a tree of element configs rooted at TemplateConfig, with PageConfig for each physical page and element configs such as ChoiceBoxConfig, CheckBoxConfig, GridConfig, CompositeGridConfig, and AnswerSheetConfig for the questions themselves. BlockConfig and ContainerConfig provide bordered boxes and column layouts, and PositionedBlockConfig places children at absolute coordinates.
from omr.generation.config import TemplateConfig
from omr.generation.config.elements.parents import PageConfig, CheckBoxConfig
tpl = TemplateConfig()
tpl.Name = "survey"
page = PageConfig()
cb = CheckBoxConfig()
cb.Name = "Q1"
page.Children = [cb]
tpl.Children = [page]
A Text-Markup DSL
The same element tree can be built from a compact text format instead of Python objects — useful for hand-authoring a template quickly or generating one from a simpler data source.
from omr.api import OmrEngine
markup = [
"?choicebox=Rate it",
"(1) Poor (2) Fair (3) Good",
"&choicebox",
]
engine = OmrEngine()
result = engine.Generate(markup)
Recognition and Export
TemplateProcessor.Recognize() reads a scanned image against a previously generated template and returns a RecognitionResult. The result exports to CSV, JSON, or XML, each with a matching in-memory stream variant (GetCsvAsStream, GetJsonAsStream, GetXmlAsStream).
Writing-System and Overflow Enums
The template layer defines Arabic, Hebrew, Persian, Urdu, and Bengali writing systems (alongside the Western default), and LongWordHandling/OverflowAction subclasses (Clip, NoClip, Wrap) for text overflow. Both enum groups parse and validate correctly for API fidelity with the Aspose.OMR surface, but this release’s render engine is LTR/Western-only and does not yet honor overflow behavior — both are tracked on the upstream roadmap as not-yet-implemented.
De-Skew and Recalibration
Recognition corrects for scan skew using corner reference marks (ReferencePointsSettings). TemplateProcessor.Recalculate() re-applies a different recognition threshold to an existing result without re-scanning the image.
Quick Start
git clone https://github.com/aspose-omr-foss/Aspose.OMR-FOSS-for-Python.git
cd Aspose.OMR-FOSS-for-Python
pip install -e .from omr.api import OmrEngine, FormValidationLogic
engine = OmrEngine()
gen = engine.Generate("final-exam.txt") # or a code-first TemplateConfig
gen.Save("out", "final-exam") # -> out/final-exam.png + out/final-exam.omr
processor = engine.GetTemplateProcessor("out/final-exam.omr", FormValidationLogic.Ignore)
result = processor.Recognize("scan.png") # -100 = auto-calibrated threshold
print(result.GetCsv()) # also GetJson() / GetXml()
Open Source & Licensing
Aspose.OMR FOSS for Python is MIT licensed and hosted on GitHub. Commercial use is permitted under the same terms as any MIT-licensed project. For enterprise features and production support, see Aspose.OMR — Enterprise Product Family.