Python图像识别主板质检源码实战：从推理到PyQt界面部署

简介这是一套面向计算机视觉初学者与工业质检方向开发者的主板质量检测系统源码基于Python与图像识别技术实现可用于学习缺陷检测、目标跟踪与关键点分析等典型任务也适合作为课程设计或毕业设计的参考方案。压缩包共41个文件约102KB以34个Python脚本为核心涵盖推理、预处理、后处理与可视化等模块另含2个ui界面文件、2个说明文档、1个yml配置、1个备份文件与1个依赖清单结构紧凑便于快速上手。资源中整合了深度学习推理、SAHI切片检测、OpenCV图像处理及可视化工具等模块并配有界面文件与运行入口读者可据此理解从模型加载到结果展示的完整链路掌握检测流程的搭建与调试思路。目前已有447人学习下载适合希望以较小体量项目入门图像识别质检的开发者参考。1. 从一张主板照片到判定结果这套 Python 图像识别质检源码到底能跑出什么产线上最怕的不是没算法而是算法躺在论文里下不来。这套基于 Python 和图像识别的主板质量检测系统源码核心价值就在于它把「拍照 → 预处理 → 检测/关键点 → 后处理 → UI 展示」整条链路都写成了可运行的工程代码而不是一个只会跑 demo 的脚本。它适合两类人一类是想拿它做课程设计或毕设、需要一套完整可复现流程的学生另一类是想在工控机上快速验证主板外观缺陷检测可行性的工程师。源码里同时出现了 PaddleDetection 风格的推理脚本infer.py、mot_jde_infer.py、keypoint_infer.py、SAHI 切片推理工具、OpenCV 预处理以及 PyQt 的ui.ui/mainwindow.ui界面文件说明作者是奔着「能演示、能落地」去的而不是纯算法验证。下面我按实际拆包顺序把这份资源怎么用、参数怎么调、哪里最容易翻车讲清楚。2. 拆开压缩包先看结构哪些文件是主干哪些是脚手架拿到A10-main.zip之后别急着pip install先把目录结构摸清楚。这套源码的文件命名有明显分层主干推理、UI、工具链、配置各占一块认错了入口会白折腾半天。2.1 主干推理链路从infer.py到run.py从文件清单看推理相关脚本大致分三组。第一组是通用检测推理infer.py、det_keypoint_unite_infer.py、picodet_postprocess.py负责把模型输出解码成框和类别。第二组是多目标跟踪与关键点mot_jde_infer.py、mot_sde_infer.py、mot_keypoint_unite_infer.py、tracker_config.yml用于视频流里连续帧的关联。第三组是预处理与后处理preprocess.py、keypoint_preprocess.py、keypoint_postprocess.py、action_utils.py、attr_infer.py。run.py通常是总入口index.py和mainwindow.ui、Ui_mainwindow.py是界面层。infer.py.bak是备份文件说明作者改过推理逻辑遇到报错时可以对比.bak看改了什么。deeplearn、SAHI、tools、opencv这几个目录名暗示了依赖方向SAHI 做切片推理tools 放辅助脚本deeplearn 可能是模型封装。提示先打开README.md里面一般会写清模型权重放哪、入口命令是什么。如果 README 写得含糊就以run.py和index.py的if __name__ __main__为准。2.2 环境依赖requirements.txt怎么读才不踩版本坑requirements.txt是第一个要看的文件但不要无脑pip install -r。这类视觉项目最常见的翻车就是 PaddlePaddle、OpenCV、PyQt5 三者版本互相打架。常见做法是先建虚拟环境再按「框架 → 视觉库 → UI 库」的顺序装。# 建独立环境避免污染系统 Python python -m venv venv # Windows 激活 venv\Scripts\activate # Linux / macOS 激活 source venv/bin/activate # 先装深度学习框架版本以 requirements.txt 为准这里示意 pip install paddlepaddle2.5.2 -i https://pypi.tuna.tsinghua.edu.cn/simple # 再装视觉与工具库 pip install opencv-python PyQt5 numpy pyyaml -i https://pypi.tuna.tsinghua.edu.cn/simple # 最后装 SAHI 等切片推理依赖 pip install sahi -i https://pypi.tuna.tsinghua.edu.cn/simple逻辑说明先装框架是因为 Paddle 对 numpy 版本有硬约束后装的库如果先占了 numpy 高版本框架会报numpy.dtype size changed这类玄学错误。参数上-i指定国内镜像源能显著提速paddlepaddle分 CPU 和 GPU 版工控机没独显就装 CPU 版别硬上 GPU 版然后卡在cudnn缺失。2.3 模型权重与配置文件tracker_config.yml和deploy目录tracker_config.yml是跟踪器的配置文件里面通常有detector、tracker、match_threshold等字段。deploy目录一般放推理模型model.pdmodel、model.pdiparams和infer_cfg.yml。如果启动时报「模型文件不存在」九成是权重没放到deploy下或者路径写的是绝对路径而你的机器目录不同。# tracker_config.yml 关键字段示意以实际文件为准 detector: model_dir: deploy/ # 模型目录相对路径以 run.py 所在位置为基准 threshold: 0.5 # 检测置信度阈值主板缺陷建议 0.4~0.6 tracker: match_threshold: 0.8 # 帧间匹配阈值太高会丢目标参数说明threshold调低会召回更多疑似缺陷但误报上升调高则漏检增加。主板质检里划痕、虚焊这类小目标建议先设 0.4 观察再根据误报率微调。match_threshold只在视频流跟踪时生效单张图片检测可以忽略。3. 把检测跑起来预处理、推理与后处理的参数怎么设环境通了之后真正的活是让模型对一张主板图输出可用的缺陷框。这一章按「预处理 → 推理 → 后处理」三段拆每段都给可抄的命令和参数解释。3.1 预处理preprocess.py里的归一化与尺寸对齐preprocess.py和keypoint_preprocess.py负责把原始图像转成模型输入。主板图像通常分辨率高、细节多直接缩放到 640×640 会丢小缺陷。常见做法是保持长边缩放、短边填充或者用 SAHI 切片。import cv2 import numpy as np def preprocess_image(img_path, target_size640): img cv2.imread(img_path) if img is None: raise FileNotFoundError(f读不到图像: {img_path}) h, w img.shape[:2] # 等比例缩放长边对齐 target_size scale target_size / max(h, w) new_w, new_h int(w * scale), int(h * scale) resized cv2.resize(img, (new_w, new_h), interpolationcv2.INTER_LINEAR) # 填充到正方形避免形变 canvas np.zeros((target_size, target_size, 3), dtypenp.uint8) canvas[:new_h, :new_w] resized # 归一化到 [0,1] 并转 CHW blob canvas.astype(np.float32) / 255.0 blob blob.transpose(2, 0, 1)[np.newaxis, ...] return blob, scale逻辑说明等比例缩放加填充是为了不让主板的圆形电容被拉成椭圆否则关键点检测会偏。scale要保留后处理把框映射回原图时要用。参数target_size要和模型训练时一致改大了显存吃紧改小了小缺陷直接消失。3.2 推理入口infer.py与det_keypoint_unite_infer.py的分工infer.py是纯检测入口det_keypoint_unite_infer.py是检测加关键点联合推理。主板质检如果只判有无缺陷用infer.py就够如果要定位元件引脚位置才需要联合推理。# 单图检测具体参数名以 infer.py 的 argparse 为准 python infer.py \ --model_dir deploy/ \ --image_file test_board.jpg \ --threshold 0.45 \ --output_dir output/ # 检测关键点联合推理 python det_keypoint_unite_infer.py \ --det_model_dir deploy/det/ \ --keypoint_model_dir deploy/keypoint/ \ --image_file test_board.jpg逻辑说明--model_dir指向模型目录--threshold控制置信度。联合推理要分别给检测和关键点两个模型目录缺一个就报KeyError。如果脚本没有--output_dir结果一般直接cv2.imshow或存到当前目录跑之前先看 argparse 定义。3.3 后处理picodet_postprocess.py与框的还原后处理负责把模型输出的热图或 anchor 解码成[x1, y1, x2, y2, score, class]。picodet_postprocess.py是 PicoDet 的后处理keypoint_postprocess.py处理关键点。这里最容易出的问题是框坐标没除以预处理时的scale导致框整体偏大或偏移。def restore_boxes(boxes, scale, pad_w0, pad_h0): # boxes 是模型坐标系下的框需先减填充再除以缩放比 boxes[:, [0, 2]] (boxes[:, [0, 2]] - pad_w) / scale boxes[:, [1, 3]] (boxes[:, [1, 3]] - pad_h) / scale return boxes参数说明pad_w、pad_h是预处理时左右/上下填充的像素数。如果预处理是居中填充这两个值要按实际算如果是左上角填充pad为 0。这一步错了框会整体平移是血泪经验里最常见的「模型明明准但框飘了」。4. 界面与部署ui.ui、mainwindow.ui和run.py怎么串起来源码带了 PyQt 的.ui文件说明作者想做成桌面工具。这一章讲怎么把界面和推理接上以及部署到工控机时要注意什么。4.1 从.ui到Ui_mainwindow.py界面文件的编译.ui是 Qt Designer 的 XML 文件Python 不能直接跑要用pyuic5转成.py。源码里已经有Ui_mainwindow.py说明作者转过了。如果你改了mainwindow.ui要重新转。# 把 .ui 编译成 Python 类 pyuic5 mainwindow.ui -o Ui_mainwindow.py # 如果提示 pyuic5 找不到用模块方式 python -m PyQt5.uic.pyuic mainwindow.ui -o Ui_mainwindow.py逻辑说明Ui_mainwindow.py只定义控件布局不含业务逻辑。业务逻辑在window.py或mainwindow对应的类里通过setupUi(self)把控件挂上去。改界面后不重新编译跑的还是旧布局这是新手最常问的「为什么我改了 ui 没变化」。4.2run.py与index.py入口到底走哪个run.py和index.py都可能是入口。判断方法看哪个文件里有QApplication和MainWindow的实例化。通常run.py是命令行推理入口index.py是界面入口。# index.py 典型结构 import sys from PyQt5.QtWidgets import QApplication, QMainWindow from Ui_mainwindow import Ui_MainWindow class MainWindow(QMainWindow, Ui_MainWindow): def __init__(self): super().__init__() self.setupUi(self) self.pushButton.clicked.connect(self.on_detect) # 绑定检测按钮 def on_detect(self): # 这里调用 infer.py 里的推理函数 pass if __name__ __main__: app QApplication(sys.argv) win MainWindow() win.show() sys.exit(app.exec_())逻辑说明setupUi必须在__init__里调用否则控件不存在。按钮的clicked信号要绑到具体方法方法里再调推理。如果界面能开但点按钮没反应先查信号有没有绑上再查推理函数有没有抛异常被吞掉。4.3 部署到工控机路径、显存与启动方式工控机通常没显示器常驻或者用触摸屏。部署时三个点要注意模型路径用相对路径或环境变量别写死C:\Users\xxx显存不够就把target_size降到 416 或改用 CPU开机自启可以用systemd或 Windows 计划任务。# Linux 工控机后台启动界面需 X11 转发或本地显示 export DISPLAY:0 nohup python index.py run.log 21 # 看日志排查启动失败 tail -f run.log参数说明DISPLAY:0指定本地显示远程 SSH 没转发会报could not connect to display。nohup加让进程后台跑日志重定向到run.log方便排查。如果工控机是 ARM 架构Paddle 要装对应版本别直接拿 x86 的 whl。5. 避坑与排查这套源码最容易翻车的五个地方这一章是我实际拆这类视觉项目时踩过的坑按「现象 → 原因 → 解决」写遇到问题直接对号入座。5.1 现象ImportError: DLL load failed或libcudnn.so not found原因PaddlePaddle GPU 版依赖 CUDA 和 cuDNN版本不匹配或没装。解决先确认显卡驱动支持的 CUDA 版本再装对应paddlepaddle-gpu。实在搞不定就换 CPU 版主板质检单张推理 CPU 也能跑只是慢。5.2 现象推理结果框全部偏移或尺寸不对原因后处理没还原scale和pad或者预处理用了 letterbox 但后处理按直接 resize 算。解决在preprocess.py里把scale、pad_w、pad_h一起返回后处理严格按公式还原。跑之前拿一张已知缺陷位置的图验证。5.3 现象界面能打开点检测按钮程序直接退出原因推理函数抛异常但没被捕获Qt 事件循环里异常会导致进程退出。解决在按钮回调里加try/except把异常打到日志或弹QMessageBox。def on_detect(self): try: result run_infer(self.image_path) self.show_result(result) except Exception as e: from PyQt5.QtWidgets import QMessageBox QMessageBox.critical(self, 推理失败, str(e))5.4 现象tracker_config.yml改了不生效原因代码里可能硬编码了配置路径或者读的是另一个同名文件。解决全局搜tracker_config确认实际加载路径用print(cfg)打印加载后的配置看改的字段有没有进去。5.5 现象小缺陷漏检严重原因输入分辨率被压太低或者threshold设太高。解决改用 SAHI 切片推理把大图切成重叠小图分别检测再合并threshold先降到 0.3 看召回再逐步上调压误报。SAHI 的slice_height、slice_width、overlap_ratio按主板元件尺寸调一般 overlap 设 0.2~0.3。6. 进阶用 SAHI 切片推理把主板小缺陷召回拉上来主板质检的难点从来不是「有没有缺陷」而是「小缺陷别漏」。整图缩放到 640 跑一颗 0402 封装的电阻虚焊可能就几个像素模型根本看不见。SAHI 的思路是把大图切成带重叠的小图每张单独推理再把框映射回原图做 NMS 合并。这套源码里带了SAHI目录说明作者已经预留了这条路。我一般会这么接from sahi import AutoDetectionModel from sahi.predict import get_sliced_prediction # 加载检测模型model_path 指向 deploy 下的推理模型 detection_model AutoDetectionModel.from_pretrained( model_typepaddledetection, model_pathdeploy/, confidence_threshold0.35, devicecpu, # 工控机没独显就 cpu ) result get_sliced_prediction( test_board.jpg, detection_model, slice_height512, slice_width512, overlap_height_ratio0.25, overlap_width_ratio0.25, ) # 导出可视化结果方便人工复核 result.export_visuals(export_diroutput/)逻辑说明slice_height/slice_width决定切片大小主板元件密集就切小一点比如 512overlap_*_ratio是切片重叠比例设 0.25 能避免缺陷正好落在切缝上被切两半。confidence_threshold比整图推理时可以略低因为切片后小目标置信度本来就偏低。export_visuals会把框画到图上人工复核时一眼能看出漏没漏。参数怎么定我给个经验表参数建议值调大后果调小后果slice_height/width512小目标召回升速度降速度快小目标漏overlap_ratio0.25切缝漏检少重复框多切缝易漏confidence_threshold0.35误报多漏检多NMS IoU 阈值0.5重叠框合并少相邻缺陷被误合验证方法也简单挑十张已知有缺陷的主板图先用整图推理跑一遍记漏检数再用 SAHI 跑一遍对比。如果 SAHI 召回明显高但误报也涨就微调confidence_threshold和 NMS 阈值直到误报在可接受范围。别指望一次调到位我调这套参数来回改了七八轮才稳定。从那以后我每次拿到新的视觉质检源码都强制先用一张已知缺陷图跑通全链路再上产线图批量测绝不跳过单图验证直接批量跑。希望帮到你。本文还有配套的精品资源点击获取