地铁轨道病害检测系统-软件开发日志-2-02

地铁轨道病害检测系统开发日志

一、通用YOLO模型适配器开发：解决定制化环境模型加载与可视化兼容问题

需求背景

系统运行环境为修改过ultralytics源码的定制版本，已新增StarNet、DySnakeConv、EMA等自定义模块，原有硬编码的模型加载方式仅适配固定架构，导致非标准YOLO模型权重加载时报错、属性丢失，且检测、分割、姿态类YOLO模型的输出结构差异会引发可视化崩溃。

核心挑战

模型架构的动态依赖问题：.pt权重文件中的架构定义，需要运行时环境存在对应的Python类定义，硬编码导入会导致环境不匹配时直接报错；
多类型模型可视化兼容问题：检测模型输出boxes、分割模型额外输出masks、姿态模型输出keypoints，直接固定解析某一属性会导致非对应模型运行时崩溃。

解决思路与实现细节

针对动态依赖和多模型兼容两大问题，采用解耦架构引用+通用推理渲染的方案，摆脱对特定模型架构的硬编码依赖：

移除所有from ultralytics.nn.tasks import ...等特定模块导入，仅依赖ultralytics.YOLO标准接口，让模型加载逻辑不绑定定制化源码；
为模型加载逻辑增加异常捕获，用try-except包裹加载代码，针对性捕获AttributeError和ModuleNotFoundError，加载失败时不崩溃程序，而是给出"环境代码一致性检查"的友好提示，保证系统鲁棒性；
放弃手动解析检测框画图的原有逻辑，改用Ultralytics原生的results[0].plot()方法，该方法会自动识别模型类型，适配检测框、掩码、关键点的可视化渲染，从底层解决多模型展示兼容问题；
数据提取做条件判断，仅在results[0].boxes存在且非空时，才提取坐标数据用于表格展示，避免非检测类模型因无boxes属性报错，核心代码实现如下：

python 复制代码

# app/core/image_processor.py try: # 自动适配检测、分割、姿态模型的可视化 

vis_image = results[0].plot() except Exception as e: # 降级处理，保证画面正常显示 

vis_image = frame.copy() # 仅在存在boxes时提取数据，避免非检测模型报错 

if hasattr(results[0], 'boxes') and results[0].boxes is not None: bbox_data =self._extract_bbox_info(results[0].boxes)

实现效果

系统不再依赖定制化ultralytics源码的特定模块，可正常加载检测、分割、姿态等各类YOLO模型，环境不匹配时仅给出提示而非崩溃，可视化渲染完全适配不同模型的输出结构。

二、交互优化：实现参数记忆与配置路径可视化，解决重复操作问题

需求背景

用户每次重启软件后，都需要重新浏览选择模型权重文件

核心挑战

跨会话的UI状态保存：需要在软件关闭后保留用户上次选择的文件路径，重启后自动恢复，且需适配跨平台（Windows/Linux/Mac）；
配置与权重的逻辑分离：用户需要明确区分并指定YAML配置文件（用于模型记录/构建）和PT权重文件（用于推理），但底层推理引擎仅需PT文件，需兼顾用户使用习惯和底层逻辑。

解决思路与实现细节

基于PySide6的原生组件实现状态持久化，同时重构UI和逻辑层，实现配置与权重的分离展示：

引入PySide6的QSettings类实现参数记忆，该类会根据系统自动选择存储方式（Windows注册表、Linux/Mac配置文件），无需手动处理文件读写；
在主窗口RailwayMainWindow中新增load_settings()和save_settings()方法，初始化时调用load_settings()恢复上次的文件路径，文件选择完成后和窗口关闭时调用save_settings()保存状态；
UI层重构，将原有"模型类型"下拉框替换为"模型配置(YAML)"文件选择框，让用户可手动指定配置文件，同时保留"模型权重(PT)"选择框，实现双路径独立选择；
调整底层ImageProcessor.load_model方法的入参，改为接收(model_path, config_path)两个参数，底层推理仍执行YOLO(model_path)，但在日志中显式打印YAML配置文件路径，满足用户的记录和核对需求。

实现效果

软件重启后自动加载上次使用的YAML配置和PT权重文件，无需重复选择；用户可直观看到当前配置文件和权重文件的完整路径，配置与权重的选择相互独立，符合实际使用中的参数管理习惯。

三、新增数据集批量检测模式：实现文件夹内图片的流式批量检测与预览

需求背景

实际检测场景中，用户需要对某一文件夹内的大量图片进行批量检测，且希望能像播放视频一样连续预览检测结果，而非单张图片逐个打开检测，提升批量处理效率。

核心挑战

静态图片的流式模拟：如何让文件夹内的静态图片列表，在现有VideoThread线程中实现类视频的平滑连续播放；
中文路径兼容：检测场景中文件夹和图片名常包含中文，OpenCV原生方法无法正常读取；
高效文件遍历：需要递归扫描文件夹，过滤非图片文件，保证批量检测的准确性。

解决思路与实现细节

基于现有视频处理线程，新增数据集处理分支，解决文件遍历、中文路径、流式播放三大问题：

在VideoThread中新增_process_dataset方法，作为数据集批量检测的核心逻辑，使用os.walk递归扫描用户选择的文件夹，通过后缀名（.jpg/.png/.jpeg等）过滤出图片文件，将有效路径存入image_files列表，保证遍历的高效性和准确性；
采用生成器式循环逻辑 实现流式播放，手动维护self.frame_index帧索引，通过while循环遍历image_files列表，每次循环读取一张图片并执行推理，之后通过time.sleep(0.01)设置帧间隔，模拟视频的连续播放效果；
解决中文路径读取问题，放弃OpenCV原生的cv2.imread方法，改用np.fromfile读取图片二进制流，再通过cv2.imdecode解码，核心代码如下：

python 复制代码

# VideoThread._process_dataset 内部 
import numpy as np import cv2 for img_path in self.image_files: # 解决中文路径无法读取问题 

img_array = np.fromfile(img_path, dtype=np.uint8) frame = cv2.imdecode(img_array,cv2.IMREAD_COLOR) if frame is None: continue # 执行推理和可视化

results = self.model(frame, **self.infer_params) vis_image = results[0].plot() # 发送帧数据
到UI层 
self.frame_signal.emit(vis_image) self.frame_index += 1 time.sleep(0.01)

实现效果

用户选择目标文件夹后，系统自动递归扫描并过滤出所有图片，实现批量自动检测，且检测结果以类视频的形式连续预览，支持播放、暂停、帧号显示等原有视频检测的交互操作，批量处理效率大幅提升。

四、深度交互优化：实现检测列表清空与帧号快速跳转，解决多线程同步问题

需求背景

用户在检测过程中会产生大量历史数据，需要快速清空列表；同时在查看检测结果列表时，希望能通过双击某条记录，立即回看对应帧的检测图片，实现帧号快速跳转，提升异常数据排查效率。

核心挑战

多线程同步：主线程（UI）与子线程（VideoThread）的帧号数据需要安全交互，避免数据竞争导致的程序异常；
暂停状态陷阱：若系统处于暂停状态，线程会阻塞在while paused: sleep()循环中，此时修改帧号无法立即刷新画面，导致跳转功能无响应；
任务结束状态处理：若批量检测或视频检测任务已执行完毕，线程已退出，此时双击列表无法触发任何画面更新。

解决思路与实现细节

针对多线程同步和不同运行状态的适配，采用互斥锁保护+标志位突破阻塞+UI层兜底的方案，实现安全、灵敏的帧号跳转和列表管理：

实现检测列表清空功能：在UI层为清空按钮绑定事件，点击时直接清空检测结果表格的所有数据，同时重置帧索引相关变量，操作简单直接，满足用户清理历史数据的需求；
线程安全的帧号跳转：引入PySide6的QMutex互斥锁，保护self.target_frame_index目标帧索引变量，UI层通过thread.seek(index)方法设置目标帧号，子线程通过互斥锁保证读取和修改的原子性，避免多线程数据竞争；
突破暂停状态的阻塞循环：新增jumped跳转标志位，修改原有暂停逻辑，若检测到目标帧号不为空，则执行帧号跳转并将jumped设为True，暂停判断时增加not jumped条件，即发生跳转时强制跳过暂停检查，立即读取并显示目标帧，破解暂停状态下跳转无响应的问题，核心逻辑如下：

python 复制代码

# VideoThread.run 内部主循环 
jumped = False # 互斥锁保护，读取并设置目标帧号 
self.mutex.lock() if self.target_frame_index is not None: self.frame_index = self.target_frame_index self.target_frame_index = None jumped = True # 标记发生跳转 

self.mutex.unlock() # 关键修改：跳转时跳过暂停，立即执行帧读取 
if self.is_paused and not jumped: time.sleep(0.1) continue # 读取并处理目标帧 
frame = self._get_current_frame()

任务结束后的静态兜底查看：针对数据集批量检测模式下任务已结束、线程已退出的情况，在UI层的_on_table_double_clicked双击事件中增加判断，若检测到VideoThread未在运行，则调用_show_static_dataset_image方法，重新扫描文件夹的图片列表，定位到双击记录对应的帧号，直接读取图片并渲染到展示窗口，无需重启线程，实现离线静态回看。

实现效果

支持一键清空检测结果列表，清理历史数据更便捷；双击列表任意记录可实现帧号快速跳转，无论系统处于播放、暂停状态，还是检测任务已结束，都能立即回看到对应帧的检测图片，异常数据排查效率大幅提升，且多线程交互过程中无数据竞争、程序崩溃等问题。

开发总结

本次开发围绕实际使用场景的痛点，完成了从底层模型适配到底层交互逻辑的全维度优化，首次修改如下：

通过解耦架构引用+通用推理渲染 ，实现了各类YOLO模型的兼容加载和可视化，让系统摆脱对定制化ultralytics环境的强依赖，鲁棒性大幅提升；
基于QSettings实现参数记忆，重构UI实现配置与权重分离，解决了重复操作问题，让参数管理更贴合实际使用习惯；
新增数据集批量检测模式，解决中文路径读取问题，实现静态图片的流式播放，满足了批量检测的实际需求；
引入互斥锁和标志位解决多线程同步问题，突破暂停状态阻塞陷阱，增加UI层兜底逻辑，实现了灵敏、稳定的帧号跳转和离线回看，让交互体验更流畅。

本次开发的所有优化均围绕"实用性"和"稳定性"展开，既解决了实际使用中的繁琐操作和功能缺失问题，又兼顾了多线程环境下的运行稳定性，让系统更贴合地铁轨道病害检测的实际业务场景。