企业官网建设流程全解析

• 桌面应用
• 计算机视觉
• 图像处理
• OCR

本篇技术指南聚焦 Audiveris OMR 引擎中一类特殊的输出产物——.zip归档文件。它们不是乐谱的最终交付格式（那是.omr、.pdf、.mxl），而是服务于字形分类器（Glyph classifier）训练的容器：本书的BOOK-samples.zip、BOOK-images.zip、BOOK-annotations.zip，以及全局训练目录TRAIN_FOLDER下的samples.zip与images.zip。读完本文，你将掌握这五种归档的职责边界、存放位置、生成/合并/推送流程，以及如何在 SampleRepository.java 等源码中印证它们的内部实现。

为什么是 .zip：训练材料的容器设计

Audiveris 的.omr输出是乐谱工程的内部数据序列化，.pdf与.mxl是面向演奏者和打谱软件的结果，而本文讨论的.zip则完全是另一类用途：它们是"容器"，主要服务于训练材料（原文明确："These files are containers mainly used for training material"）。

从 SampleRepository.java 的类注释可以看到，SampleRepository负责存储Sample实例，每个 sample 本质上是一个"字形 + 形状"（glyph + shape）的组合；其中还有一类特殊的字体合成样本（font-based samples），由 Audiveris 的音乐字体与文本字体直接生成，虽然它们是人工构造的，但同样被计入训练样本集合。这些样本天然需要以"按 sheet、按 shape"组织的归档方式来存放，.zip因此成为默认容器格式。

本地 Book 归档（Book 级）

对于一个名为BOOK的书籍文件夹，其中可能出现三个.zip归档，各自的定位完全不同：

本地归档的命名规律

从 SampleRepository.java 中的正则可以看出命名约束：

private static final Pattern SAMPLES_PATTERN = Pattern.compile("(.*-)?(samples\\.zip)");

即本地归档采用BOOK_NAME-samples.zip形式，全局归档则是纯samples.zip。在 SampleRepository.java 中，构造器会从samples.zip文件名推导出配套的images.zip路径：

this.samplesFile = samplesFile; this.imagesFile = samplesFile.resolveSibling(prefix + IMAGES_FILE_NAME);

其中IMAGES_FILE_NAME定义为"images.zip"（见 SampleRepository.java），SAMPLES_FILE_NAME为"samples.zip"（见 SampleRepository.java）。也就是说，只要给出foo-samples.zip，程序就能自动推导foo-images.zip的存在与路径。

生成本地归档的操作路径

在 指南 samples.md 中有明确的生成方式：

• 对单张 sheet 满意后，使用Sheet → Sample下拉菜单保存该 sheet 的样本；
• 对整本书满意后，使用Book → Sample下拉菜单保存整本书的样本。

数据会以两个 zip 归档保存在 book 文件夹下，例如foo书会生成foo-samples.zip（样本集合）与foo-images.zip（包含的 sheet 图像）。一个良好的实践是：一次只处理一本书，只有当本书数据被彻底验证、样本被仔细过滤后，才把书仓库合并进全局仓库。

工作区中的对应物

仓库自带的示例数据与配置也体现了这套命名与存放约定：

• app/res/basic-classifier.zip —— 随发行版提供的训练模型（glyph classifier 的 trained model + norms），其默认位置就在TRAIN_FOLDER；
• data/examples/ —— 提供可供采样、验证的示例乐谱图片（如BachInvention5.jpg、D0392410-1.256.png等）。

全局归档（Global 级）

与 Book 级归档相对的是存放于TRAIN_FOLDER中的全局归档。TRAIN_FOLDER是CONFIG_FOLDER下直接的train子目录（见 essential.md）。CONFIG_FOLDER的具体位置随操作系统而异：

因此TRAIN_FOLDER即上述目录下的train子文件夹，其中包含：

（详见 essential.md 的表格。）

全局 samples.zip：训练的唯一数据源

全局samples.zip是训练 glyph classifier 的唯一来源（原文："It is the only source for training the glyph classifier"）。其内容建立于所有被推送（pushed）进来的本地仓库之上。

从 SampleRepository.java 可以看到全局仓库的获取逻辑：

if (GLOBAL == null) { GLOBAL = getInstance(WellKnowns.TRAIN_FOLDER.resolve(SAMPLES_FILE_NAME), load); } if (load && (GLOBAL != null) && !GLOBAL.isLoaded()) { GLOBAL.loadRepository(null); }

即全局仓库就是TRAIN_FOLDER/samples.zip对应的SampleRepository单例；它是懒加载的——只有真正执行loadRepository()时才会访问磁盘上的 zip 文件（见 SampleRepository.java 的注释：构造时并不会访问 samples 文件，直到调用loadRepository()或storeRepository()）。

全局 images.zip：体积大、仅供目检

images.zip归档包含随样本从本地仓库推送上来的图像。它可能变得相当大（原文档提示"It can get fairly big"），并且只用于视觉检查（visual check），不用于训练。这也在源码中得到印证：

• 图像文件通过ZipFileSystem.open(imagesFile)打开，按 sheet descriptor 的folderPath解析到对应的 sheet 图像（见 SampleRepository.java）；
• 提供isImagesAvailable()之类的检查，判断 sheet 图像文件是否存在（见 SampleRepository.java）。

下载初始材料

在 samples.md 中给出了初始材料的获取与布置建议：官方提供samples.zip（约 4 MB，约 15000 个样本）、images.zip（约 453 MB，约 3500 张 sheet 图像）与basic-classifier.zip（约 0.3 MB，训练结果模型）。做法是**直接下载归档（无需解压）**放入自己的config/train目录，之后即可在此基础上扩充自己的样本集。注意：images.zip对训练不是必需的，但有助于在 sheet 上下文中目检大部分样本。

从采集到推送：本地仓库如何进入全局

结合 samples.md 的完整流程，.zip 归档的完整生命周期如下：

1. 采样（Sampling）

对已校正满意的 sheet（Sheet → Sample）或 book（Book → Sample）生成BOOK-samples.zip与BOOK-images.zip，落在 book 文件夹中。

2. 目检与编辑（Repository UI）

通过Tools → Browse Global Repository...打开GLOBAL仓库（读取config/train下的samples.zip/images.zip），或通过Book → View Book Repository...打开某本书的仓库。界面左侧是 Shapes 选择器，中间是 Sheets 选择器 + Sample board + Classifier board，右侧是 Samples 选择器与 Sample context（上下文面板）：

• 依次选择 sheets → shapes → samples 三级联动；
• 特殊 sheet# SYMBOLS FROM FONT #汇集所有字体合成样本，以绿色背景显示；
• 对选中样本可执行Remove（DELETE键 /Remove按钮 / 右键菜单）或Assign to（重新指定 shape）。

目检的核心动机是：一个被错误指派 shape 的样本若混入训练集，会严重损害 Audiveris 的识别效率，因此要么删除、要么纠正其 shape。

3. 合并 / 推送（Merge / Push）

当本地仓库验收通过后，在 book 仓库界面通过Repository → Push to Global把内容推送进全局仓库。源码层面对应SampleRepository.includeRepository(...)与includeSamplesFile(...)：

public synchronized void includeSamplesFile (Path samplesFile) { SampleRepository repo = getInstance(samplesFile, true); ... includeRepository(repo); ... }

（见 SampleRepository.java）。合并后调用storeRepository()（见 SampleRepository.java）将更新写回samples.zip。由于训练过程只使用 GLOBAL 仓库（见 samples.md），推送是本地样本进入训练流程的唯一通道。

4. 训练（Training）

全局仓库就绪后，即可通过Tools → Train菜单启动字形分类器训练（详见 training.md）。训练基于全局仓库的样本随机选择（Select按钮），训练期间可利用False Positives/Weak Positives/Weak Negatives三类视图继续回到仓库界面修正样本，形成"采样 → 目检 → 推送 → 训练 → 再修正"的闭环。

归档内部实现要点

从源码可以确认几个值得注意的实现细节：

• zip 访问方式：无论是加载 sheet 图像还是存储样本，均通过java.nio.file的ZipFileSystem直接以文件系统视图访问归档内容（SampleRepository.java、SampleRepository.java），使用完毕后关闭对应的文件系统句柄。这意味着你可以把 zip 当作一个"目录"来组织 sheet 子目录与样本条目，而无需在磁盘上解压展开。
• 本地/全局命名区分：samples.zip（全局，位于WellKnowns.TRAIN_FOLDER）与BOOK_NAME-samples.zip（本地，位于某个 book 文件夹）由正则(.*-)?(samples\.zip)统一识别（SampleRepository.java），isGlobal()通过this == GLOBAL判断（SampleRepository.java）。
• 质量自检：仓库内置对冲突样本（conflicting，同一 run table 被标成不同 shape）与冗余样本（redundant）的检查，并在冗余字体样本上打上 "ignored" 标记后重新storeRepository()（SampleRepository.java），避免劣质样本污染训练数据。
• annotations 的命名扩展：整本书的标注归档扩展名为.annotations.zip，单 sheet 的标注则是.annotations.xml（Annotations.java），印证了BOOK-annotations.zip属于 5.x 为未来分类器预留的结构化输出。

小结

一句话总结：samples.zip是训练链路的数据核心，images.zip是它的目检配套，annotations.zip是面向未来的标注储备；理解它们的分层（本地 Book 级 → 全局 TRAIN_FOLDER 级）与流转（采样 → 过滤 → Push to Global → Train），即可在 Audiveris 中建立可控、可复现的训练样本管线。相关文档可继续参阅 Outputs 总览、Essential folders 与 Samples 指南。

• 桌面应用
• 计算机视觉
• 图像处理
• OCR