条码识别调参数有一个共同的困境：改了一个参数，当前这张图过了，但你不知道它有没有把别的场景改坏；换一批图，问题又回来了。根因在于绝大多数调试只看到最终结果——解出来了或者没解出来——中间发生了什么完全是黑盒。在线条码参数调优器（英文名 Online Barcode Reader Parameter Tuner）针对的就是这个：把 SDK 自己的扫描模板读回来逐项编辑，把管线里每一级的中间结果按顺序画出来，再用一组带标注的困难样本给每次修改打分——参数改得对不对，以漏掉的码有没有被找回为准。

在线演示

在线条码参数调优器（英文名 Online Barcode Reader Parameter Tuner）：打开就能用，不需要注册；模板读取、参数编辑、中间结果渲染和基准评分全部在浏览器内完成，图片不会上传服务器。

配合本文验证时可以这样走一遍：选一张内置的困难样本，先跑一次默认模板记下漏检；到定位阶段把某个阈值放松，再跑一次，对比漏掉的码有没有回来、有没有把不该检的区域也检出来。

关键要点

• 模板不手写：页面用 readTemplateDocuments() 把 SDK 注册表里的模板文档原样读回来，再构建成可编辑模型，从源头避开手写 JSON 被拒收的坑。
• 每个参数都可改：定位、去模糊（deblur）、二值化、抗形变、灰度增强、格式列表、ROI，枚举参数给选项、范围参数给滑杆和数字框。
• 中间结果按管线顺序展示，同一阶段的重复图像用指纹去重，每次运行开始前清空上一轮证据（clearStageEvidence）。
• 定位卡片显示「N hypotheses · M decoded」，M 由页面侧用 IoU 把解码结果关联回候选区域统计出来。
• 10 张内置困难照片全部带真值标注，改参数前后都能按同一把尺子算召回。
• 导出两份产物：完整模板 JSON 和只含改动项的 diff JSON。

先读模板，再改参数

调优器的第一原则是：不发明模板，只修改 SDK 给的。页面加载后把 SDK 注册表里的模板文档读出来列在下拉框里，Default 和 ReadBarcodes_Default 是两个不同的入口，各有各的用途，界面上按原名区分而不是当成重复项合并。

选中一个模板后，页面把它构建成一棵可编辑的参数树。每个字段都带元数据：枚举参数渲染成选项列表（显示枚举含义而不是裸数字），范围参数渲染成数字框加取值范围，模式数组（ModeArray）逐项开关。所有改动都记录路径，界面上能直接看到「这一项和原值不一样」。

// 参数树按 SDK 文档结构递归渲染，每个字段带路径，改动可追踪
function renderValue(container, obj, key, path, meta) { /* ... */ }
function isChanged(path) { /* 与读回的原始模板比对 */ }

这个设计换来两个能力：一是改坏了可以逐项回退；二是导出 diff 时知道哪些路径动过。

中间结果：漏检发生在哪一级

识别失败不是一种失败。定位阶段没给出候选、候选给了但二值化糊掉、定位成功但解码失败——处理方式完全不同。调优器把 SDK 的中间结果按管线顺序接出来，每一级单独成卡：

每张定位卡片标注「N hypotheses · M decoded」。N 大 M 小，说明定位泛滥但解码不上去，该去看二值化和去模糊；N 小甚至为 0，问题在定位之前，格式列表、对比度、 ROI 都值得怀疑。候选区域的裁剪图是失败驱动的——只把「没解出来」的候选放大给你看，而不是把每个候选都铺一遍。

一个容易踩的坑值得单独说：缩小格式列表可能让定位候选一起消失。有些定位算法按格式族选择特征，把格式收窄到只剩一种码时，定位假设可能从十几个掉到零，看起来像「定位坏了」，其实是候选生成依赖了被你关掉的格式族。中间结果视图能直接暴露这种连锁反应。

用标注打分，而不是用眼睛

调参最大的陷阱是过拟合到眼前这张图。调优器内置 10 张真实拍摄的困难样本——阴影、弱光、强光、褶皱、印刷不良、出画边缘、极小条码、多码制混排——每张都带数据集自己的标注文件（annotations.json），由 prepare-samples.py 统一生成，样本、标注和评分三处联动。

每次运行结束后，页面把识别结果和标注逐张比对：漏掉的码回来了没有，新增的识别是不是误检。参数改动的好坏由这套基准回答，而不是由「当前这张图看起来过了」回答。

摄像头也是一种输入，但它被设计成取景器而不是连续扫描：按一次快门跑一次，跑完释放，不进入识别循环——因为连续识别会让中间结果面板不停地被冲掉，没法盯住一次运行看。

把参数带走

调完之后有两个出口：

1. 完整模板导出：整份模板 JSON，直接交给 SDK 的 initSettings 使用。
2. diff 导出：只含修改项的 JSON，附改动前后的值对照，用来合回你自己项目的模板，或者在团队里评审「这次到底改了什么」。

配合在线条码可扫性分析器使用效果更好：先用分析器确认图像质量没有硬伤，再带过来调参数；分析器页面也提供了一键跳转。