Features Overview

Features Overview

Aspose.OMR FOSS for Python covers three layers: designing a template, generating a page image and descriptor from it, and recognizing marks from a scanned copy.

Template Design

A template is a tree of element configs rooted at TemplateConfig. Question elements include ChoiceBoxConfig (fixed option bubbles), CheckBoxConfig (any-mark checkboxes), GridConfig and CompositeGridConfig (digit/symbol matrices merged into one value), and AnswerSheetConfig (numbered answer-bubble matrices). Layout containers (BlockConfig, ContainerConfig, PositionedBlockConfig) control borders, columns, and absolute positioning. The same tree can be built from a compact text-markup DSL instead of Python objects.

Generation

OmrEngine.Generate() renders a template into a GenerationResult — a page image plus a .omr descriptor JSON. MemoryGenerationResult exposes the same output as in-memory streams via GetImages()/GetOmr() for callers that do not want to touch the filesystem.

Recognition

TemplateProcessor.Recognize() reads one scanned image against the template it was created from. RecognizeFolder() batches that over every image in a folder. Recalculate() re-scores an already-recognized result with a different threshold without re-reading the source image. De-skew correction uses corner reference marks (ReferencePointsSettings).

Result Export

RecognitionResult exports to CSV, JSON, or XML, each with a matching in-memory stream variant (GetCsvAsStream, GetJsonAsStream, GetXmlAsStream).

Writing-System and Overflow Enums

Arabic, Hebrew, Persian, Urdu, and Bengali writing systems (alongside Western), and the LongWordHandling/OverflowAction enums, are present and parse correctly for API fidelity with the Aspose.OMR surface. Neither is yet honored by this release’s render engine — rendering is LTR/Western-only, and overflow behavior is not yet configurable. Both are tracked on the upstream roadmap.

Tips and Best Practices

• Use the markup DSL for simple forms; switch to the code-first TemplateConfig tree when you need programmatic control over element placement.
• FormValidationLogic.Exception surfaces multi-select violations immediately instead of silently ignoring them, for questions with multi-select disabled.
• Prefer RecognizeFolder() over looping Recognize() calls yourself when processing a batch of scans.
• Call Recalculate() instead of re-scanning when you only need to try a different recognition threshold.

Common Issues

FAQ

Does the library require any GUI or external OMR hardware?

No. It works entirely from image files (scans or photos) using numpy, opencv-python, and Pillow.

Can I generate a PDF of the template?

Not in this release — GenerationResult.SaveAsPdf() and MemoryGenerationResult.GetPDF() both raise NotImplementedError. Use the PNG output from Save()/GetImages() instead.

How do I process many scanned forms at once?

Use TemplateProcessor.RecognizeFolder(folderPath, recognitionThreshold) to recognize every image in a folder in one call.

API Reference Summary

See Also

• Aspose.OMR — Enterprise Documentation