PCB 检测可视化实战：从坐标陷阱到状态同步的踩坑记录
作为工业视觉领域的开发者，在 PCB（印刷电路板）检测系统的可视化模块中，经常会遇到一些看似简单、实则暗藏玄机的技术问题。今天这篇博客，就结合近期实际开发经历，聊聊在钻孔检测变色、编辑树联动、以及设定开关开发中踩过的坑和思考。
一、业务背景：什么是背钻检测？
在 PCB 制造中，背钻（Backdrill） 是一道关键工序。简单来说，多层 PCB 中有些通孔（贯穿所有层的孔）在信号传输中，多余的那段金属柱体会产生"残桩效应"，像一根多余的天线一样干扰高频信号。背钻就是用电钻把这段多余的金属反钻掉。
而我们做的检测系统，就是要在制造完成后，自动判断每个钻孔的加工质量------是合格（OK）、不合格（NG）、还是仍在检测中。其中，让钻孔跟着它所属的元件一起变色，是这次迭代的核心需求。
一句话概括：一个钻孔属于哪个元件，当元件状态变了，钻孔的颜色也要同步变化。
二、坐标空间之坑：物理坐标 vs 像素坐标
问题现象
开发中最让人头疼的一类 Bug，就是"明明逻辑是对的，但结果就是不对"。这次遇到的情况是：代码构建了元件到钻孔的映射关系，按理说每个元件都能找到它包含的钻孔，但运行时映射结果始终为零------一个都匹配不上。
根因分析
问题的根源在于坐标空间不一致。
在视觉检测系统中，坐标至少存在两层含义：
- 物理坐标（µm）：以微米为单位的真实物理尺寸，描述 PCB 上某个点的实际位置。这个值通常来自钻孔文件（如 drill.xml），是制造设备的"世界坐标"。
- 像素坐标（px）：在 CCD 相机拍摄的图像上，每个像素点在图像中的行列位置。不同相机、不同视野（FOV）下，同样的物理位置对应不同的像素坐标。
打个比方：物理坐标就像地球上的经纬度，像素坐标就像一张照片上某个人的位置------同一栋建筑，你站在不同角度拍，它在照片里的位置完全不一样。
代码中钻孔使用的是 Panel（全景）像素空间，而元件边界使用的是 FOV（视野）像素空间。两者虽然都叫"像素坐标"，但其实是两个不同的坐标系。用一个坐标系的值去另一个坐标系里做包含判断（点在矩形内吗？），就如同用英寸当厘米用，自然永远匹配不上。
修复思路
核心解法是把**所有坐标统一到物理空间（µm）**进行匹配。与其在两个像素空间之间做转换，不如回到"世界坐标"这个公共基准。具体做法是：钻孔坐标的 PixelCenter 之前用了错误的像素空间值，修正为在物理坐标空间中计算即可。
这里有一个容易被忽视的细节：在图像坐标系中，坐标变换是通过一个叫**逆矩阵（InvertMatrix）**的变换实现的，它能把图像坐标映射到画布坐标。代码中虽然做了这个变换得到了画布像素坐标，但在后续赋值时却丢弃了，错误地沿用了原始物理坐标。这就好比你已经把英里换算成公里了，却还是把英里数填进了公里那一栏。
三、状态同步：如何让钻孔跟着元件变色
三层架构
整个变色功能采用经典的三层架构：
1. 数据层 ------ 建立元件到钻孔的映射
在检测开始时，遍历所有钻孔和所有元件，判断每个钻孔的物理坐标落在哪个元件的像素边界内，建立一张"元件 ID → 钻孔列表"的映射表。有了这张表，任意一个元件的状态变了，就能立刻找到它下属的所有钻孔。
这里还有一个兜底策略：如果元件列表为空（比如某些特殊的检测模式），则通过元件的像素边界参数反算其物理范围，保证映射逻辑不会因数据缺失而崩溃。
2. 状态同步层 ------ 同步协程
当元件的检测状态发生变化时（检测中 → OK / 检测中 → NG），触发一个异步同步流程：遍历该元件映射到的所有钻孔，逐个更新它们的状态，然后打包成一条消息广播出去。消息里携带的是"钻孔ID → 新状态"的映射关系。
3. UI 层 ------ 画布刷新颜色
画布控件收到状态刷新消息后，递归遍历所有绘制节点，找到匹配的钻孔图形对象，替换其边框色和填充色。颜色方案如下：
| 状态 | 颜色 | 含义 |
|---|---|---|
| 检测中 | 青色 | 正在处理 |
| OK | 绿色 | 质量合格 |
| NG | 红色 | 质量不合格 |
为了让钻孔控件能响应多种状态，界面模板中使用了**多重绑定（MultiBinding）**技术------控件的颜色不再写死，而是同时绑定多个检测状态属性，由转换器根据当前状态动态返回对应的颜色值。
预存代码的"幽灵Bug"
排查过程中还发现了一个隐蔽的问题：打开钻孔文件时，画布上自动显示了所有钻孔点（黄点、红点等），但按照需求设计，导入后钻孔应该默认隐藏，由用户手动点击"显示通孔"或"显示背钻"按钮后才出现。
追踪代码发现，负责绘制钻孔轮廓的方法注释里明确写了"导入的点先隐藏，按下显示通孔或显示检测孔再显示"，但实际上发送消息时把全部钻孔数据一股脑发出去了，而且钻孔的 IsVisible 默认就是 true。更诡异的是，这个方法在代码仓库的全部历史中从未被修改过------说明这是一个从一开始就存在的预存 Bug，只是之前的业务场景没有暴露它。
修复很简单：导入后遍历所有钻孔数据，把 IsVisible 批量设为 false。
四、编辑树的自动滚动定位问题
场景描述
用户点击画布上的某个元件（比如电路板板材、区域轮廓等），左侧的编辑树应该自动展开并滚动到该元件的节点位置。但实际情况是：树节点确实高亮了，却没有滚到可视区域------用户还得手动去树上找。
两个时序陷阱
陷阱 1：闭包捕获的变量已被置空
为了实现平滑的动画效果，滚动操作被放到了一个延迟调度里执行。问题出在：变量被捕获时还是有效的，等调度真正执行时，它可能已经被其他事件置为空了。
这就像你叫快递员 10 分钟后上门取件，但 5 分钟后你把包裹挪走了------快递员来了只能空手而归。
修复方式是：在调度之前，先把目标引用保存到一个局部变量里，延迟执行时使用这个"快照"值，而不是去读可能已经变化的最新值。
陷阱 2：布局还没稳定就滚动了
展开树节点不是瞬间完成的------新展开的子节点需要经历一次布局（Layout）过程才能确定自己在滚动区域中的实际位置。如果在节点展开后立即调用滚动方法，滚动容器可能还没更新自己的可滚动范围，导致滚到了错误的位置甚至完全不滚动。
解决办法是：在展开所有祖先节点后，再等一帧，用比普通延迟更低优先级的调度等布局完全稳定后，才执行滚动。同时还强制调用了一次布局更新方法，确保万无一失。
这两个修复用到的核心技术概念是调度器优先级（DispatcherPriority）：
Background优先级：在普通操作完成后执行ContextIdle优先级：在系统完全空闲时才执行，比 Background 更低
五、设定开关的功能设计
最后聊一个相对轻量但值得记录的功能：在设定界面新增一个开关，控制是否自动生成 Board 子节点，以及是否显示对应的工具栏按钮。
需求逻辑
- 开关关闭 （默认行为）：扫图完成后自动创建一个 Board 子节点（大小等于 Panel 区域），该节点在画布上可见但不可选中；工具栏显示"Panel 窗"和"Board 窗"两个按钮。
- 开关打开：不自动生成 Board，工具栏隐藏这两个按钮。数据树和画布的其他表现不受影响。
设计要点
不可选中的实现 ：在图形对象的基类中新增一个 IsLocked（锁定）属性。当该属性为 true 时，鼠标左键点击和焦点处理逻辑直接返回，不执行任何选中操作。这是一种很常见的"装饰"模式------不修改核心交互逻辑，只在入口处加一道过滤。
按钮可见性绑定：工具栏按钮的显示隐藏通过数据绑定控制，绑定的源就是那个开关配置。这种做法的好处是代码改动最少------你不需要写"开关变化时手动隐藏按钮"的事件处理，框架自动帮你搞定。
涉及改动：配置类新增属性、图形基类新增锁定属性、检测流程中条件创建 Board、界面模板中绑定可见性------总共 5 个文件，职责分明，改动清晰。
六、开发中的经验总结
回顾这一天的开发工作，有几个值得记录的教训：
1. 坐标空间是视觉检测的头号陷阱
任何涉及多个坐标系的操作（物理坐标、Panel 像素坐标、FOV 像素坐标、画布坐标），必须在心中有一张清晰的坐标转换图。建议在代码注释中显式标注每个坐标变量的空间类型，比如 // 单位: µm, 物理坐标空间。
2. 异步调度中的变量捕获
在 UI 开发中，Dispatcher.BeginInvoke 这类延迟调度非常常用，但闭包捕获的变量值在调度执行时可能已经变了。铁律：调度前就把值"拍照"存到局部变量，而不是延迟读取。
3. 预存代码也要怀疑
不要因为"这段代码从来没被改过"就默认它是正确的。很多 Bug 之所以长期潜伏，只是因为之前的业务路径没有走到那里。新功能上线时，所有相关的历史代码都应该重新审视。
4. 兜底策略必不可少
无论是"数据为空时递归查找"还是"参数缺失时反算兜底"，兜底逻辑是一个健壮系统的基本配置。它不能让系统在异常情况下依然完美运行，但至少能让它不崩溃，并给出有意义的诊断信息。
5. 诊断日志 = 你的眼睛
在复杂的检测流程中，光靠断点调试效率极低。在关键节点输出带标签的结构化日志（比如 来源:JobOption、匹配数:14），能大幅加速问题定位。日志不是累赘，是投资。
七、写在最后
工业视觉软件中的可视化模块，看似只是"画几个框、变几个颜色"，但背后涉及坐标变换、状态同步、异步调度、数据绑定等大量技术细节。每一个"理所当然"的 UI 效果，背后都有一群开发者在和各种隐蔽的 Bug 斗智斗勇。
希望能给做类似方向的同学一些参考。如果你也在做 PCB 检测相关开发，欢迎在评论区交流踩坑经验！