Generation

Generation

The generation layer (omr.generation) builds a template — a tree of element configs — and renders it into a page image plus a .omr descriptor via OmrEngine.Generate().

The Template Tree

TemplateConfig is the document root, containing one or more PageConfig objects. Every element below a page is a subclass of BaseConfig, carrying a Name and a Type discriminator (ConfigType).

from omr.generation.config import TemplateConfig
from omr.generation.config.elements.parents import PageConfig

tpl = TemplateConfig()
tpl.Name = "quiz"
page = PageConfig()
page.Children = []
tpl.Children = [page]

Question Elements

• ChoiceBoxConfig — a question with a fixed set of option bubbles (ChoiceBoxAnswerConfig), supporting multi-select and per-question validation.
• AnswerSheetConfig — a numbered answer-bubble matrix for exam-style sheets.
• CheckBoxConfig — a labeled group of blank boxes accepting any mark, with a tunable fill threshold.
• GridConfig / CompositeGridConfig — digit or custom-symbol matrices merged into one value.

from omr.generation.config.elements import AnswerSheetConfig

sheet = AnswerSheetConfig()
sheet.Name = "answers"
sheet.AnswersCount = 4    # bubbles per question (e.g. A-D)
sheet.ElementsCount = 20  # number of questions

Page-Wide Settings

GlobalPageSettings sets document-wide defaults (paper size, orientation, font, bubble size) that individual elements can override. PaperSize and Orientation are importable directly from omr.generation.

from omr.generation import GlobalPageSettings, Orientation, PaperSize

settings = GlobalPageSettings()
settings.PaperSize = PaperSize.A4
settings.Orientation = Orientation.Vertical

Layout, Overflow, and Writing Systems

BlockConfig is a bordered, padded box; ContainerConfig arranges child blocks into columns or a footer; PositionedBlockConfig places children at absolute coordinates. LongWordHandling, the OverflowAction subclasses (Clip, NoClip, Wrap), and the Arabic/Hebrew/Persian/Urdu/Bengali writing systems all parse and validate correctly for API fidelity with the Aspose.OMR surface, but none of them are yet honored by this release’s render engine: overflow behavior is not yet configurable, and rendering is LTR/Western-only. Both are tracked on the upstream roadmap as not-yet-implemented.

The Markup DSL

The same element tree can be written as plain text and passed directly to Generate().

from omr.api import OmrEngine

markup = ["?choicebox=Rate it", "(1) Poor (2) Fair (3) Good", "&choicebox"]
engine = OmrEngine()
result = engine.Generate(markup)

Tips and Best Practices

• Set shared defaults once on GlobalPageSettings rather than repeating them on every element.
• Use the markup DSL for quick iteration; switch to the code-first tree for programmatic generation.
• CompositeGridConfig.ExtraRow adds a leading row of custom symbols without changing ColumnsCount.

Common Issues

FAQ

Can I mix the markup DSL and code-first configs in the same template?

The two are alternative ways to build the same TemplateConfig tree; this release’s Generate() accepts either a markup source or a TemplateConfig instance, not a mix in one call.

How do multi-page templates work?

TemplateConfig.Children holds multiple PageConfig objects; GenerationResult.MultipageTemplateImages returns one image per page.

API Reference Summary

See Also

• Aspose.OMR — Enterprise Documentation