How to Work with Generation in Python

Aspose.OMR FOSS for Python builds an OMR form from a tree of element configs rooted at TemplateConfig, then renders it to a page image and .omr descriptor with OmrEngine.Generate(). This guide walks through building a simple answer-sheet template and generating it.

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
from omr.generation.config import TemplateConfig
from omr.generation.config.elements.parents import PageConfig
from omr.generation.config.elements import AnswerSheetConfig

Step 3: Build the Template Tree

Create a TemplateConfig root, a PageConfig for the single page, and an AnswerSheetConfig for a 20-question numbered answer matrix (4 option bubbles per question).

tpl = TemplateConfig()
tpl.Name = "quiz"
page = PageConfig()
sheet = AnswerSheetConfig()
sheet.Name = "answers"
sheet.AnswersCount = 4    # bubbles per question (e.g. A-D)
sheet.ElementsCount = 20  # number of questions
page.Children = [sheet]
tpl.Children = [page]

Step 4: Generate and Save

engine = OmrEngine()
gen = engine.Generate(tpl)
gen.Save("out", "quiz")   # -> out/quiz.png + out/quiz.omr

Common Issues and Fixes

My generated page looks empty. Check that every element is actually added to a parent’s Children list — an element constructed but never appended to a page’s (or container’s) Children is never rendered.

I need a PDF instead of a PNG. Not available in this release — GenerationResult.SaveAsPdf() raises NotImplementedError. Use the PNG output from Save() and convert externally if a PDF is required.

I set Overflow and nothing changed. This release’s render engine does not yet honor Overflow/LongWordHandling — the enums parse and validate correctly, but overflow behavior is not yet configurable. This is tracked on the upstream roadmap.

Frequently Asked Questions

Can I build the same template without Python objects?

Yes — the markup DSL builds the same element tree from plain text, passed directly to OmrEngine.Generate().

How do I generate a multi-page template?

Add more than one PageConfig to TemplateConfig.Children; GenerationResult.MultipageTemplateImages returns one image per page.

Does the engine keep state between `Generate()` calls?

No — OmrEngine is stateless; each call is independent.