基于 PySide6 + OpenCV + NumPy 的 PCB AOI 桌面应用,覆盖从项目建立、图像预处理、标注、ROI 提取、黄金样本生成到在线验证的完整流程。
本仓库提供两类使用方式:
- 统一应用(推荐):通过工作流串联全部模块,适合实际业务使用。
- 独立模块工具:单独打开某个 GUI,适合调参、排查和算法验证。
入口文件:main.py
| 模块 | 主要职责 | 关键文件 |
|---|---|---|
| 统一应用壳 | 工作流编排、步骤导航、项目上下文、进度恢复 | modules/unified_app/main_application.py |
| PCB 提取 | 从原始整图提取有效板区,产出图 A | modules/pcb_extractor/pcb_extractor_gui.py |
| 标注编辑 | 标注 Fiducial / ROI / Exclusion,并保存 annotation.json |
modules/pcb_annotator/pcb_annotator_gui.py |
| ROI 提取 | 在图 B 中定位 ROI(局部查找 / 基准点仿射),保存 ROI 图块 | modules/roi_extractor/roi_extractor_gui.py |
| 黄金样本生成 | 对多张 B 图 ROI 对齐融合,生成 ROI 黄金样本 | modules/golden_sample/golden_sample_gui.py |
| 黄金样本验证 | 图 B ROI 对齐 + 缺陷评分与结果可视化 | modules/golden_sample_verifier/golden_sample_verifier_gui.py |
工作流定义在 modules/unified_app/core/workflow_manager.py:
- 选择项目目录
- 图像导入(单张原始整图)
- PCB 提取
- 标注编辑
- ROI 提取
- 黄金样本生成
- 完成确认
- 打开项目
- 导入待检测图片(图 B)
- 特征提取与检测(验证)
- 输出缺陷信息
- 工作流进度文件:
<project_path>/.workflow_progress.json - 相关实现:
modules/unified_app/module_pages.py - 项目上下文(路径/状态)对象:
modules/unified_app/core/project_context.py
统一常量定义:modules/alignment_constants.py
- 粗对齐:
orb/sift/brisk/kaze/akaze/fiducial - 局部查找:
template_matchingrotated_template_matchingedge_template_matchinglocal_feature_matchingphase_correlation_matching
- 精对齐:
ecc_translation/ecc_euclidean/ecc_affine/shitomasi_lk
modules/golden_sample/core/golden_sample_core.py 中包含:
- 平均融合
- 中值融合
- 最大值融合
- 最小值融合
- 加权融合
- 金字塔融合
modules/golden_sample_verifier/core/verifier_core.py:
- 绝对差值
- 结构化相似度(SSIM)
- 峰值信噪比(PSNR)
- 平均绝对误差(MAE)
- 均方误差(MSE)
当前已接入 Qt 原生线程池(QThreadPool + QRunnable),用于避免 GUI 卡顿:
- 通用任务执行器:
modules/unified_app/core/task_runner.py - ROI 提取 GUI:后台任务 + 取消 + 进度提示
modules/roi_extractor/roi_extractor_gui.py
- 验证 GUI:后台任务 + 取消 + 进度提示
modules/golden_sample_verifier/golden_sample_verifier_gui.py
- ROI 匹配器支持多 ROI 并行与取消令牌
modules/roi_extractor/core/roi_matcher.py
说明:当前取消属于协作式取消,正在执行的底层单次 OpenCV 调用会在返回后结束。
推荐 Python 3.10+(Windows 中文路径已在项目中做过兼容处理)。
pip install -r requirements.txtrequirements.txt 当前内容:
opencv-pythonnumpymatplotlibpyyamlPySide6Pillow
verifier_core.py 的 SSIM 路径使用 skimage:
pip install scikit-imagepython main.py# ROI 提取
python -c "from modules.roi_extractor.roi_extractor_gui import main; main()"
# 黄金样本验证
python -c "from modules.golden_sample_verifier.golden_sample_verifier_gui import main; main()"
# 黄金样本生成
python -c "from modules.golden_sample.golden_sample_gui import main; main()"
# PCB 标注
python -c "from modules.pcb_annotator.pcb_annotator_gui import main; main()"
# PCB 提取
python -c "from modules.pcb_extractor.pcb_extractor_gui import main; main()"# 粗对齐算法可视化验证
python tools/coarse_align_verifier_gui.py
# 基准点 ROI 提取实验工具
python tools/roi_extractor_fiducial_experiment.py测试框架:unittest
python tests/run_tests.pypython tests/run_tests.py -k "workflow_manager"
python tests/run_tests.py -k "project_context"
python tests/run_tests.py -k "module_pages"python -m unittest tests.test_unified_app.test_workflow_manager.TestWorkflowManager.test_resetpython -m unittest tests.test_unified_app.test_task_runner.TestTaskRunner.test_cancel_token若本地未安装
PySide6,部分 GUI/任务相关测试会被跳过或导入失败。
annotation.json:标注数据(fiducials / rois / exclusion_regions)original_image_*.png:原图(统一壳和 ROI 提取模块会按规则查找).workflow_progress.json:工作流恢复文件
images/fiducials/<fid_id>/<fid_id>.pngimages/rois/<roi_id>/<roi_id>.pngimages/rois/<roi_id>/<roi_id>_golden_sample.png
相关严格门禁实现:modules/unified_app/module_pages.py。
项目中常见两种格式,核心代码均有兼容:
[[x1, y1], [x2, y2]][x1, y1, x2, y2]
.
├── main.py
├── modules/
│ ├── unified_app/
│ │ ├── main_application.py
│ │ ├── module_pages.py
│ │ ├── navigation_panel.py
│ │ ├── step_navigator.py
│ │ ├── core/
│ │ │ ├── workflow_manager.py
│ │ │ ├── project_context.py
│ │ │ └── task_runner.py
│ │ └── utils/
│ │ ├── logger.py
│ │ └── file_lock.py
│ ├── pcb_extractor/
│ ├── pcb_annotator/
│ ├── roi_extractor/
│ ├── golden_sample/
│ ├── golden_sample_verifier/
│ ├── alignment_constants.py
│ ├── template_matcher.py
│ └── matchment_algorithms.py
├── tools/
├── tests/
└── doc/
- 工作流与步骤状态:
modules/unified_app/core/workflow_manager.py - 页面编排与产物门禁:
modules/unified_app/module_pages.py - ROI 定位主流程:
modules/roi_extractor/roi_extractor_gui.py - ROI 匹配核心:
modules/roi_extractor/core/roi_matcher.py - 验证主流程:
modules/golden_sample_verifier/golden_sample_verifier_gui.py - 验证核心算法:
modules/golden_sample_verifier/core/verifier_core.py
doc/ 目录包含架构、改造和测试清单文档,例如:
doc/GoldenSample_System_Architecture.mddoc/Fiducial_Based_ROI_Integration_Plan.mddoc/Unified_App_Manual_Test_Checklist.mddoc/多线程改造方案.mddoc/多线程与CUDA改造影响分析.md