从书写轨迹到结构化反馈：汉字书法评测算法拆解

这篇是对公开仓库 cdyforever/calligraphy-evaluation-algorithm 的源码阅读笔记，不是复现报告，也不代表算法经过了当前环境下的安装、数据集验证或准确率评测。分析固定在 commit b45218b。

项目关注的不是“把一张字的照片丢进分类器”，而是将待评字迹和标准字的书写轨迹进行比较：解析轨迹与字库模板，尝试匹配笔画，再从整字、部件、笔画和笔段等尺度计算差异，最后组织分数、标签和评语。这个拆法把识别、度量、解释分成了可以分别调整的阶段。

先看输入：轨迹和标准字

主流程以书写数据对象和标准字模板为中心。轨迹解析会把原始点阵/笔画序列整理成统一的 WritingData；标准字对象还携带字名、部件组成和已经存储的参考特征。项目也有字帖照片与页面处理模块，但不能因此把整套评测误解为只凭静态图片完成：笔顺、速度之外的动态轨迹信息来自输入数据，不是从单张成品照片中自动还原出来的。

这样的输入选择很重要。用户写字和模板必须先落到兼容的坐标、笔画切分和字符 ID 约定里。模板不存在、轨迹为空或笔画数明显异常时，主流程会走有效性判断与提示分支，而不是硬算一个看似精确的总分。

笔画匹配：先解决“哪一笔对应哪一笔”

不同书写者的点数、采样密度和轨迹形状会有差别，直接按数组下标比较并不可靠。源码先构造模板笔画与用户笔画之间的代价矩阵，综合笔画特征相似度和几何距离，再用 Munkres/Hungarian 指派求一组整体匹配。相比每一笔各自找最近邻，这种全局分配更能避免多个用户笔画都抢同一个模板笔画。

这一步也暴露出评测系统的边界：一对一分配只是候选对应关系，不等于真实笔顺或语义上一定正确。连笔、拆笔、缺笔和多笔会让矩阵中的“最佳匹配”仍然是错误解释。项目的匹配分析代码也注明，同时存在多余与缺失笔画时仍有未解决情况，所以异常书写应优先给出可理解的校验提示，而不是继续输出过度自信的细粒度分数。

几何特征：把“好不好看”拆成能比较的量

特征提取按层次组织，而不是只比较整字像素：

层级	关注内容	能回答的问题
整字	轮廓、外接范围、重心与凸包	字是否明显偏斜、偏大或整体位置不合适？
部件	部件边界、中心、尺寸及部件关系	左右/上下结构是否失衡，部件间距是否异常？
笔画	长度、重心、方向、拐点和轨迹关系	单笔是否过长、过短、位置偏移或方向不自然？
笔段	分段长度比例、弯曲与角度	一笔内部的转折和节奏是否接近模板？

几何比较前，代码会依据模板和用户字的中心、矩形范围做对齐，尽量把“整字整体平移/缩放”与局部笔画差异分开。对齐只消除特定几何差异，不会自动让不同字体、书写风格或模板质量变得可比；模板的书写风格和分解方式仍会影响结果。

多维评价与评分

Evaluator 将整体轮廓、笔顺、部件结构、笔画和笔画关系等结果放进 Evaluation。评分器 Rater 再按配置的统计量、系数和缺陷影响因子聚合出维度分与总分；另外还会把总分映射成星级区间。评语生成器读取评价标签和特征，产出整体、结构、笔画、笔顺等文字反馈。

这种分层有两个工程优点：一是可以返回原始标签/指标与可选详情，调参时能定位分数由什么差异造成；二是评分权重和文案不必耦合在图像预处理代码里。但“分数可解释”不等于“分数已被证明客观”：权重、阈值、模板选择和星级边界都需要真实样本、专家标注和跨人群评估校准。没有这类评测证据时，适合把分数作为练习反馈线索，而不是能力排名或竞赛裁判结论。

输出接口和数据边界

核心调用可按需返回评价标签、指标、分数、评语、细节、特征、笔画轨迹和图片数据。默认不必把每一种调试信息都塞进响应；启用轨迹、特征或图像详情会增加响应体和数据暴露面。若把它封装成在线服务，应明确输入轨迹与图片的保留期限、访问控制、日志脱敏、上传限制和删除方式，尤其不能把用户书写样本默默当作训练数据。

阅读源码时应继续验证的点

采样差异：点数、采样频率、设备坐标和笔画切分改变时，匹配距离是否稳定？
模板覆盖：异体字、字体风格、连笔、少数派书写习惯是否会被模板偏好误判？
异常匹配：缺笔与多笔同时出现时，能否给出确定、可解释的定位，而不只是一个总代价？
评分校准：各维度阈值是否有专家标注和跨设备样本支持？星级是否会随字种难度不公平地变化？
复现实验：建立固定样本集、逐维指标和人工复核流程，再比较修改前后的误差；不要只看几张演示图。
现代环境兼容：仓库依赖清单中的不少版本较旧，README 安装/使用章节仍含模板占位内容；在隔离环境核实 Python、OpenCV、ONNX Runtime 与模型文件组合后再考虑运行。

本次审阅范围

本篇对固定 commit 的 Python 主流程、笔画匹配、特征提取、评价/评分模块做了静态阅读；没有安装依赖、下载模型、连接任何数据库、处理真实用户书写数据或执行项目。仓库没有声明明确的开源许可证，因此这里只写原创分析并链接源仓库，不复制其代码或 README。使用者应在复用代码前先向权利人确认许可。