📚 课程目录第2章视觉NG结果的数据结构解析

2. 视觉NG结果的数据结构解析

视觉检测系统在判定一个产品为NG时，输出的并不是一句“不合格”，而是一条结构化的检测记录。这条记录要能被MES接收、存储、检索，并最终与工单、批次、设备、人员关联起来，前提是每个字段都有明确的语义、格式和取值约定。本节围绕一条典型的视觉NG结果记录，逐字段拆解其含义、常见格式以及在实际对接中容易踩的坑。

一条完整的NG记录长什么样

下面是一条典型的视觉NG结果JSON示例，字段命名参考常见视觉软件（如Halcon、VisionPro、康耐视In-Sight或自研平台）的导出风格，实际项目中字段名可能不同，但语义基本一致：

{
  "resultId": "VIS-20240517-000238",
  "stationId": "AOI-03",
  "deviceId": "CAM-03-02",
  "timestamp": "2024-05-17T14:23:07.482+08:00",
  "productSN": "SN240517A00931",
  "workOrder": "WO-2405-1187",
  "judge": "NG",
  "defectType": "SOLDER_BRIDGE",
  "defectCode": "D-102",
  "confidence": 0.973,
  "bbox": { "x": 812, "y": 456, "w": 64, "h": 38 },
  "imagePath": "/ng/2024/05/17/AOI-03/VIS-20240517-000238.jpg",
  "roiId": "ROI-07",
  "algorithm": "YOLOv8-solder-v3.2"
}

这条记录里，judge是最终判定，defectType和defectCode描述缺陷是什么，confidence说明算法有多确信，bbox指出缺陷在图像中的位置，imagePath指向可回看的证据图，timestamp和deviceId则回答“什么时候、哪台设备拍的”。下面逐项展开。

缺陷类型与缺陷代码：语义与编码要分开

defectType是给人看的缺陷名称，如SOLDER_BRIDGE（连锡）、MISSING_PART（缺件）、SCRATCH（划伤）、POLARITY_REVERSE（极性反）、FOREIGN_MATERIAL（异物）。命名建议使用大写下划线风格，避免中文、空格和特殊字符，便于跨系统传输和数据库存储。

defectCode是给系统用的稳定编码，如D-102。它的价值在于：当缺陷名称因业务调整而修改时，历史数据仍能通过编码正确归类。实际项目中常见做法是维护一张缺陷字典表，把defectCode、defectType、中文描述、严重等级、责任工序绑定在一起。MES侧做SPC统计时，通常按defectCode聚合，而不是按名称字符串匹配。

如果视觉系统只输出中文缺陷名，建议在对接层做一次映射，转成稳定的英文编码再写入MES，否则后续改名会导致历史数据断裂。

坐标：bbox与中心点，以及坐标系约定

缺陷位置最常见的表示是边界框bbox，包含左上角坐标x、y和宽高w、h，单位是像素。也有系统输出中心点cx、cy加宽高，或输出多边形顶点数组（用于不规则缺陷）。

这里必须先明确坐标系定义，否则同一组数字在不同系统里含义完全不同。本节统一约定：原点在图像左上角，x轴向右为正，y轴向下为正，单位为像素。这是OpenCV、Halcon（默认）和绝大多数工业相机的通用约定。若某台设备使用原点在左下角的数学坐标系，必须在对接文档中显式标注，并在转换时做y' = H - y处理。

坐标还有一个容易被忽略的问题：它属于哪张图。同一缺陷在原始大图、ROI裁剪图、缩放后的推理图上的坐标是不同的。工程上推荐统一记录“原始全分辨率图像坐标系”下的bbox，并额外记录roiId和该ROI的偏移量，这样既能精确定位，又能在需要时还原到ROI局部坐标。若算法在缩放图上推理，需按缩放比例反算回原图坐标，例如推理图为原图的0.5倍，则x_orig = x_infer / 0.5。

置信度：取值范围、阈值与业务含义

confidence是模型对本次判定的确信程度，常见格式是0到1之间的小数，如0.973；也有系统输出0到100的百分数。对接时必须确认量纲，避免把97.3当成0.973写入，导致阈值判断全部失效。

置信度的业务用法主要有三类：一是判定阈值，低于阈值的NG可能被降级为“疑似”转人工复判；二是排序，复判工位优先处理高置信度NG，或优先复核低置信度NG；三是质量趋势，某缺陷类型平均置信度持续下降，往往意味着来料或工艺在漂移。需要注意的是，置信度是模型输出，不是真实概率，不同模型版本之间不可直接横向比较，因此记录中应同时保留algorithm版本字段。

图像路径：证据链的关键

imagePath指向该次NG对应的图像文件。它决定了MES里能不能“点开看现场”。常见格式有三种：本地绝对路径、相对路径、以及对象存储URL。生产环境更推荐相对路径或URL，因为绝对路径在服务器迁移后会全部失效。

路径设计建议包含日期、工位、结果ID等层级，例如/ng/2024/05/17/AOI-03/VIS-20240517-000238.jpg，这样既便于人工排查，也便于按时间清理。同时要考虑：图像是只存NG，还是NG和OK都存？只存NG可节省大量存储，但无法回溯误判；建议至少对NG全存，并对OK按比例抽样留存。此外要明确图像的保留周期，MES追溯通常要求与产品保质期或客户要求对齐，常见为3到12个月。

时间戳：格式、时区与精度

timestamp记录检测发生的时刻。推荐使用ISO 8601格式并带时区，如2024-05-17T14:23:07.482+08:00，精度到毫秒。原因有三：跨时区工厂不会混淆；毫秒精度足以区分同一秒内的多条记录；字符串格式可直接被多数数据库和日志系统解析。

要区分三个时间：拍照时间、算法判定时间、数据入库时间。三者可能相差几十毫秒到数秒。追溯分析通常以拍照时间为准，因此建议记录中至少保留拍照时间，必要时再增加入库时间字段用于排查链路延迟。

设备ID与工位ID：定位到具体资源

deviceId标识产生该结果的相机或视觉控制器，如CAM-03-02；stationId标识工位，如AOI-03。两者是层级关系：一个工位可能有多台相机，一个相机也可能在不同工位复用。MES做设备维度和工位维度的良率分析时，依赖的正是这两个字段。

命名建议采用“区域-线体-工位-序号”的可读编码，并与设备台账保持一致。切忌使用IP地址或临时分配的序号作为deviceId，因为设备更换或网络调整后会导致历史数据无法对应。

字段关系总览

下图把上述字段按“标识—判定—证据—时空”四类关系组织起来，帮助理解一条NG记录内部各字段如何协同支撑MES追溯。

对接时的常见格式陷阱

第一，时间格式不统一。视觉软件常输出2024/05/17 14:23:07这类本地格式，缺少时区和毫秒，入库前应统一转换。第二，置信度量纲不一致，0-1与0-100混用。第三，坐标未标注参考图，导致复判时框错位置。第四，缺陷类型用中文或自由文本，无法稳定聚合。第五，imagePath使用绝对路径，迁移后全部失效。第六，deviceId用IP，设备换网后历史数据断链。

在正式对接前，建议先用一批已知NG样本做字段级校验：检查时间能否解析、置信度是否在预期区间、bbox是否落在图像尺寸范围内、imagePath能否实际打开。这四项通过后，再进入MES联调，可避免大量返工。

把字段语义、格式和坐标系约定在对接文档中固化下来，视觉NG结果才能真正成为MES里可检索、可统计、可追溯的质量数据，而不是一堆无法解释的数字和路径。