guqinlizhixian/jzpocr-atom-right

jzpOCR · 右手减字谱谱字识别（ATOM）

古琴减字谱右手谱字的单字识别模型。输入一个谱字的裁图，输出结构化读法。

输入：一个谱字的裁图（不是整页）
输出：ATOM|F:大;H:七八;R:抹;S:七
      └ 类型 └ 指法 └ 徽位 └ 右手动作 └ 弦序

⚠️ 先读这三条

1. 这不是整页 OCR。 输入必须是单个谱字的裁图。整页要先做版面检测把谱字框切出来， 再逐框送进来。直接把整页图丢进来不会得到有意义的结果。
2. 只认右手。 输出前缀恒为 ATOM。左手走手音（LC）、句读（MARK）、休止（REST） 不在本模型的能力范围内——训练数据里就没有这三类。
3. 预处理尺度是 [0, 1]，不是 [-1, 1]。 本权重训练时对像素只做了 /255， 没有再做 (x - 0.5) / 0.5。同一批 132 条上实测：[0, 1] 得 **57.58%**， [-1, 1] 掉到 **40.15%**。infer.py 里的那一步是故意的，别"顺手统一"。

用法

pip install -r requirements.txt

python infer.py 谱字裁图.png
# QJJC_v25_p0617_b0016.jpg	ATOM|F:大;H:七八;R:抹;S:七

python infer.py 图1.png 图2.png --show-confidence
python infer.py --device cuda 图.png

infer.py 只依赖本仓库内的 jzp_atom/（models.py / dsl.py / normalize.py 三个文件从 jzpOCR 主仓库逐字节照搬），不需要装 jzpOCR。

指标

评测集 fixed_dev = 两个正式冻结 benchmark 的子集拼成，共 132 条：

来源	条数	资产 ID
PackageA	72	BENCH-ATOM-PACKAGE-A-001 v1.0.0（benchmark_only=1 · training_eligible=0）
real110	60	同上体系的早期子包

两个子包都永久排除训练，且它们的 132 条与本模型的训练集交集为 0（sha256 逐条核过）。

whole_exact = 76/132 = 57.58%（一条读法的每个字段全对才算对）

字段	含义	准确率
F	指法	94.4%
S	弦序	89.9%
R	右手动作	87.0%
T	散 / 泛	83.3%
H	徽位	73.2%
D	修饰（注 / 绰 / 合…）	50.0%
S2	第二组弦序（多弦指法）	0/4

C、就、P 在评测集里没有样本，不给数字。

这个数的边界

• n=132，小。 p≈0.6 时标准误约 4.3pp，单轮 8 个百分点以下的差异不足以说明问题。 字段级那些数字更不可靠。
• S2 只有 4 条样本，0/4 说明不了任何事。
• 评测集是 crop 级，不是页级。本模型没有页级端到端数字。
• 训练那一轮同时改了三个变量（训练数据量、字段口径、训练机器）， 三者各占多少分不出来。
• 本模型未走 jzpOCR 项目的正式 release 流程；上面这个数是在本文所述的 132 条清单上、用本仓库内的 infer.py 同源代码复算得到的。

训练数据

26,914 张谱字裁图，全部来自《琴曲集成》（30 册，QJJC_v01–QJJC_v30）的扫描件裁图。

两部分拼成：

来源	条数	真值等级
01_F12右手读法_ATOM_3840	3,835	人工确认表层读法，DSL 为确定性派生
04_飞轮复核_28169	24,948	人工复核（飞轮工作态）

划分：训练 26,914 / 内部验证 1,868，按读法分组切分（同一读法的实例只进一侧）。

来源与许可

《琴曲集成》是今人整理影印本，不是公有领域刊本。 本模型的全部训练图像都来自它。 发布者未对模型权重是否构成该出版物的衍生作品作出法律判断，也未取得相关权利人授权。 本模型按未授予开源许可（license: other）发布：可以使用与评估，但不构成对训练数据 上游权利的任何许可。如需商业使用或再分发，请自行厘清上游权利。

底层琴谱本身（明清刻本）多属公有领域；受限的是这一版的影印与整理。

模型

• 结构：共享二维卷积 backbone → 每个字段一个空间注意力头 → 按字段序列化成 DSL
• 参数：3,127,855（约 12.5 MB，state_dict）
• 输入：192×192 RGB
• 训练：AdamW，lr 2e-3，30 epoch，batch 256（RTX 4090D，约 700 秒）

文件

文件	是什么
best_model.pt	权重（state_dict）
vocab.json	已冻结的推理词表——各字段的取值表。已按本权重的头裁好，运行时不再做任何迁移
infer.py	最小推理示例
jzp_atom/	模型定义、DSL 规则、图像归一化（自 jzpOCR 主仓库逐字节照搬）

jzp_atom/ 三个文件的来源与校验：

文件	上游路径（jzpOCR）	sha256（前 16 位）
models.py	src/jzpOCR-core/jzp_core/models.py	f5aae334a87d0b19
dsl.py	src/jzpOCR-core/jzp_core/dsl.py	b791344fc10a52ba
normalize.py	src/jzpOCR-core/jzp_core/normalize.py	083a521c9967058b

对应提交：94cd54acfb60a4a4715af21491b878d2b7947c68（2026-10-01）。

引用

jzpOCR — 古琴减字谱识别（右手 ATOM 谱字模型）
训练数据：《琴曲集成》影印本裁图