Generation

Generation

生成层（omr.generation）构建一个模板——元素配置的树状结构——并通过 OmrEngine.Generate() 将其渲染为页面图像以及一个 .omr 描述符。

模板树

TemplateConfig 是文档根，包含一个或多个 PageConfig 对象。页面下的每个元素都是 BaseConfig 的子类，携带一个 Name 和一个 Type 鉴别符（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]

问题元素

• ChoiceBoxConfig — 一个具有固定选项气泡集合（ChoiceBoxAnswerConfig）的问题，支持多选和每题验证。
• AnswerSheetConfig — 用于考试式试卷的编号答案气泡矩阵。
• CheckBoxConfig — 一个带标签的空白框组，可接受任意标记，并具有可调节的填充阈值。
• GridConfig / CompositeGridConfig — 将数字或自定义符号矩阵合并为单一值。

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

页面范围设置

GlobalPageSettings 设置文档范围的默认值（纸张大小、方向、字体、气泡大小），各个元素可以覆盖这些默认值。PaperSize 和 Orientation 可以直接从 omr.generation 导入。

from omr.generation import GlobalPageSettings, Orientation, PaperSize

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

布局、溢出和书写系统

BlockConfig 是带边框和内边距的盒子；ContainerConfig 将子块排列成列或页脚；PositionedBlockConfig 将子元素放置在绝对坐标上。LongWordHandling、OverflowAction 子类（Clip、NoClip、Wrap）以及 Arabic/Hebrew/Persian/Urdu/Bengali 书写系统都能正确解析和验证，以实现与 Aspose.OMR 表面的 API 保真度，但它们在本次发布的渲染引擎中尚未被支持：溢出行为尚未可配置，且渲染仅限左到右/西方语言。上述两点已在上游路线图上标记为未实现。

标记 DSL

相同的元素树可以写成纯文本并直接传递给 Generate()。

from omr.api import OmrEngine

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

技巧与最佳实践

• 在 GlobalPageSettings 上一次性设置共享默认值，而不是在每个元素上重复设置。
• 使用 markup DSL 进行快速迭代；切换到 code-first 树以实现编程生成。
• CompositeGridConfig.ExtraRow 在不更改 ColumnsCount 的情况下添加一行自定义符号。

常见问题

FAQ

我可以在同一个模板中混合使用 markup DSL 和 code-first 配置吗？

这两种方式是构建相同 TemplateConfig 树的替代方案；此版本的 Generate() 接受 markup 源或 TemplateConfig 实例，但不接受在一次调用中混合使用。

多页模板如何工作？

TemplateConfig.Children 包含多个 PageConfig 对象；GenerationResult.MultipageTemplateImages 每页返回一张图像。

API Reference 摘要

另请参阅

• Aspose.OMR — Enterprise Documentation