【目标检测软件 02】AirsPy 目标检测系统操作指南

项目	要求
操作系统	Windows 10/11（推荐 64 位）、Ubuntu 20.04+、macOS 12+
CPU	Intel Core i5 或更高（建议支持 AVX2 指令集）
内存	≥16 GB
GPU（支持）	NVIDIA 显卡，支持 CUDA 11+（如 RTX 3060/4060 及以上）

GPU 非必需，但如果硬件支持可显著提升推理速度。

3.2、软件依赖

Python 版本：3.11（推荐）
核心依赖包 （详见 requirements.txt）：
- PyQt5 ≥ 5.15
- OpenCV-Python (cv2)
- NumPy
- ONNX Runtime（CPU 或 GPU 版）
- Ultralytics 8.3.160（用于 .pt 模型加载）
- Pandas、openpyxl（用于 Excel 导出）

3.3、安装步骤

安装 Python 3.11（确保添加至系统 PATH）
克隆或解压软件包至本地目录
打开终端，进入项目根目录
执行以下命令安装依赖：

CPU 模式：
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

GPU 模式（需已安装 CUDA）：
pip install -r requirements_gpu.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

操作步骤如下：

Python 下载地址 www.python.org

下载完成，直接点击安装。

使用PyCharm IDE 打开工程，创建虚拟环境。

安装依赖库

安装完成 python 解析器会显示所有依赖库

四、主界面布局

AirsPy 主窗口采用三栏式布局，结构清晰，操作便捷。

4.1、顶部栏

系统标题：居中显示 "YOLO识别系统"
窗口控制按钮：右上角提供最小化（Ctrl+M）、最大化/还原（Ctrl+F）、关闭（Alt+F4）功能

4.2、左侧功能区

包含三大子区域：

（1）功能按钮区（快捷键支持）

系统配置（Ctrl+S）：打开参数设置对话框
图片文件（Ctrl+I）：选择图像文件夹
视频文件（Ctrl+V）：选择本地视频
网络视频（Ctrl+H）：输入 HTTP 视频流地址
本地摄像（Ctrl+C）：启用本地摄像头
远程摄像（Ctrl+R）：输入 RTSP 流地址

（2）系统信息显示区

实时展示当前状态：

模型文件：当前加载的模型名称
抑制 IoU：当前 IoU 阈值
置信度 Conf：当前置信度阈值
类别数：类别文件中定义的类别总数
文件数：当前选中的媒体文件数量

（3）控制按钮区

上一张（Ctrl+←）：切换至上一条检测结果
运行/暂停（Ctrl+Space）：启动或暂停检测
停止（Ctrl+Q）：终止当前任务
下一张（Ctrl+→）：切换至下一条检测结果
导入（Ctrl+E）：加载历史 Excel 检测结果
导出（Ctrl+O）：将当前结果保存为 Excel 文件

4.3、中间显示区

视频/图像显示区域：主画面展示带检测框的实时或静态内容
检测结果表格：下方表格列出所有检测记录，支持点击选中行高亮对应画面

4.4、右侧信息区

目标信息：显示当前鼠标悬停目标的类别名称与置信度
位置信息：精确坐标（xmin, ymin, xmax, ymax）
进度可视化：圆形进度条动态显示检测完成比例

4.5、交互特性

窗口拖拽：在非边框区域按住左键可移动窗口
窗口缩放：边缘或角落可调整大小
表格联动：点击表格行 → 自动定位并显示对应检测画面
悬停提示：鼠标移至检测框内 → 右侧实时更新目标信息

窗口拖拽

窗口缩放：

五、功能操作指南

5.1、系统配置（首次使用必做）

点击 "系统配置" 按钮
模型配置 ：
- 点击"打开"，选择 .pt 或 .onnx 模型文件
- 成功后主界面"模型文件"区域显示文件名
类别文件配置 ：
- 选择 JSON 格式类别文件（格式见第6章）
- 系统自动解析并更新"类别数"
参数调节 ：
- 拖动滑块或直接输入数值设置 IoU（范围：0.01-1.00）、置信度（范围：0.01-1.00）、帧间隔（范围：1-100帧）
保存选项 ：
- 勾选"图片/视频"和/或"表格"以启用自动保存
关闭窗口，配置自动写入 config.json

操作展示

1、点击"系统配置"，选择模型、类文件、设置IoU、置信度、帧间隔、勾选"图片/视频"和/或"表格"

2、展示系统设置

5.2、图片文件检测

点击 "图片文件" → 选择包含图像的文件夹
点击 "运行" 开始批量检测
检测过程中：
- 中间区域逐张显示结果
- 表格实时追加记录
- 进度条反映完成比例
可随时 暂停/恢复/停止
完成后，结果自动保存（若启用）

操作展示

1、选择图片文件夹

2、展示图片文件数

3、图片检测结果

4、自动保存的检测图片、表格

5、鼠标移动目标检测框，光标成十字光标，同时在右侧显示目标信息。

6、上下按钮切换或者表格选中行，自动展示检测的对应检测图片

5.3、视频文件检测

点击 "视频文件" → 选择视频
点击 "运行" 开始检测
系统按"帧间隔"跳帧处理，其余帧正常播放（无检测）
支持全程暂停、停止、结果导航

操作展示

1、选择视频文件

2、显示文件数

3、开始运行、显示检测进程、检测结果

4、检测过程可以按暂停或者停止检测键。暂停或者停止播放后也可以支持鼠标悬停显示目标信息。

5、检测结果保存

6、播放检测保存的视频效果

5.4、本地摄像头检测

点击 "本地摄像"
若存在多个设备，弹出选择对话框 → 选择摄像头 ID
点击 "运行" 启动实时检测
可在运行中动态调整参数，效果即时体现

操作展示

1、找到一个本地摄像头

2、找到多个本地摄像头

3、开始播放摄像头、本地视频没有进度显示

4、摄像头检测保存

5、播放摄像头检测保存视频

5.5、网络视频流检测

HTTP 流 ：点击"网络视频" → 输入如 http://ip:port/video.mp4
RTSP 流 ：点击"远程摄像" → 输入如 rtsp://user:pass@ip:554/stream
系统尝试连接，成功后点击"运行"开始检测
具备基础断线重连机制

操作展示

1、填写http视频URL

2、开始或暂停或停止播放http视频，暂停或停止播放时也支持鼠标悬停目标信息显示

3、保存检测结果

4、播放检测http检测保存的视频效果

5、RTSP 同样的操作步骤

6、RTSP 播放效果，没有进度显示，同样支持鼠标悬停显示，上下键和表格选中行。

7、RTSP 检测保存的视频名称规则跟HTTP一致。

8、RTSP 检测视频播放

5.6、检测结果管理

查看：表格中每行包含编号、目标数、详细结果、原始路径、保存路径
导航：使用"上一张/下一张"或点击表格行切换画面
导出：点击"导出" → 选择路径 → 生成带格式的 Excel 文件
导入：加载历史 Excel → 数据回填至表格，支持回看

操作展示

1、导出检测结果成 Excel 文件

2、查看导出的Excel 文件，包含编码、检测数、检测结果、原文件路径、检测文件路径

3、导入，选中之前保存的Excel 文件作为导入文件。

4、导航查看、使用"上一张/下一张"或点击表格行切换画面

5.7、模型管理

切换模型：重新打开配置窗口，选择新模型文件即可
模型转换 ：运行 convert_pt_to_onnx.py 将 .pt 转为 .onnx（提升部署效率）
性能提示：首次加载较慢，后续使用缓存；GPU 可用时自动加速

操作展示

1、模型格式转换

六、配置文件详解

6.1、config.json 结构

软件使用JSON格式的配置文件（config.json）保存所有用户设置，位于软件根目录。

复制代码

{
    "model_path": "model/yolov8s.onnx",
    "class_file_path": "model/class.json",
    "img_path": "media/img/",
    "video_path": "media/video/",
    "http_url": "http://example.com/stream.mp4",
    "rtsp_url": "rtsp://192.168.1.64:554/stream",
    "camera_id": 0,
    "iou_threshold": 0.75,
    "conf_threshold": 0.25,
    "frame_interval": 10,
    "save_media": true,
    "save_table": true
}

6.2、关键配置项说明

6.2.1、路径配置

model_path：模型文件的绝对路径，支持.pt和.onnx格式
class_file_path：类别定义JSON文件路径，格式要求见下文
img_path：默认图片文件夹路径，用于快速选择图片文件夹
video_path：默认视频文件路径，用于快速选择视频文件

6.2.2、设备配置

camera_id：默认摄像头ID，0表示第一个可用摄像头
http_url：默认HTTP视频流URL，用于快速配置网络视频
rtsp_url：默认RTSP视频流URL，用于快速配置远程摄像

6.2.3、检测参数

iou_threshold：交并比阈值，范围0.01-1.00，默认0.75
conf_threshold：置信度阈值，范围0.01-1.00，默认0.5
frame_interval：视频帧采样间隔，正整数，默认10

6.2.4、保存选项

save_media：是否自动保存处理后的媒体文件，布尔值
save_table：是否自动保存检测结果为Excel，布尔值

6.3、类别文件格式要求

6.3.1、文件格式

类别文件必须是JSON格式的字典文件，基本结构如下：

复制代码

json

{
    "key1": "value1",
    "key2": "value2",
    ...
}

6.3.2、格式要求

键值对应关系：

键（key）：英文类别名称，必须与训练模型时使用的类别名完全一致
值（value）：中文类别名称，显示在软件界面中

顺序要求：

字典的顺序必须与训练模型的类别顺序完全对应
例如COCO数据集的80个类别，第一个是"person"，那么字典的第一个键必须是"person"

完整性要求：

必须包含模型支持的所有类别
不能缺少任何类别，否则可能导致显示错误
可以包含额外的类别，但多余的类别不会被使用

6.3.3、示例文件

COCO数据集80类别示例（前几个类别）：

复制代码

json

{
    "person": "人",
    "bicycle": "自行车",
    "car": "汽车",
    "motorcycle": "摩托车",
    "airplane": "飞机",
    "bus": "公共汽车",
    "train": "火车",
    "truck": "卡车",
    "boat": "船",
    "traffic light": "交通灯",
    "fire hydrant": "消防栓",
    "stop sign": "停车标志",
    "parking meter": "停车计时器",
    "bench": "长椅",
    "bird": "鸟",
    "cat": "猫",
    "dog": "狗",
    "horse": "马",
    "sheep": "羊",
    "cow": "牛",
    "...": "其余类别..."
}

6.3.4、自定义类别文件

对于自定义训练的模型，需要根据训练时使用的类别创建对应的类别文件：

创建步骤：

获取训练模型的类别列表（按顺序）
为每个类别准备英文名称和中文翻译
按照训练顺序创建JSON字典
保存为UTF-8编码的JSON文件

验证方法：

在软件中加载类别文件
查看显示的类别数量是否正确
测试检测结果的中文显示是否正常

七、软件打包部署

7.1、打包工具介绍

软件使用PyInstaller工具进行打包，将Python脚本和相关资源打包成可执行文件，方便在没有Python环境的计算机上使用。

7.2、打包脚本说明

7.2.1、目录打包脚本（build.bat）

此脚本生成一个包含所有依赖文件的目录结构，适合需要灵活部署的场景。

脚本内容：

复制代码

pyinstaller --name=AirsPyqt5v1.0 --windowed --onedir ^
    --add-data="config.json;." ^
    --icon=./ui/icons/logo.ico ^
    --distpath=../version/AirsPyqt5v1.0/onedir/dist ^
    --workpath=../version/AirsPyqt5v1.0/onedir/build ^
    --specpath=. ^
    --hidden-import=PyQt5.QtCore ^
    --hidden-import=PyQt5.QtGui ^
    --hidden-import=PyQt5.QtWidgets ^
    --hidden-import=cv2 ^
    main.py

pause

参数说明：

--name：指定生成的可执行文件名称
--windowed：不显示控制台窗口（纯图形界面）
--onedir：打包为目录形式（多个文件）
--add-data：添加额外的数据文件（配置文件）
--icon：设置应用程序图标
--distpath：指定输出目录路径
--hidden-import：显式包含可能自动检测不到的模块

输出结果 ：

生成一个包含以下内容的目录：

复制代码

text

dist/AirsPyqt5v1.0/
├── AirsPyqt5v1.0.exe    # 主可执行文件
├── config.json          # 配置文件
├── _internal/           # 依赖库目录
│   ├── PyQt5/
│   ├── cv2/
│   ├── ultralytics/
│   └── 其他依赖库...
└── 其他运行时文件...

7.2.2、单文件打包脚本（build_onefile.bat）

此脚本生成单个可执行文件，适合简单分发和部署。

脚本内容：

复制代码

pyinstaller --name=AirsPyqt5v1.0 --windowed --onefile ^
    --add-data="config.json;." ^
    --icon=./ui/icons/logo.ico ^
    --distpath=../version/AirsPyqt5v1.0/onefile/dist ^
    --workpath=../version/AirsPyqt5v1.0/onefile/build ^
    --specpath=. ^
    main.py

pause

参数说明：

--onefile：打包为单个可执行文件
其他参数与目录打包相同

输出结果 ：

生成单个可执行文件：

复制代码

text

dist/AirsPyqt5v1.0.exe

特点：

所有依赖都打包在一个文件中
启动时需要解压到临时目录
文件体积较大但部署简单

7.3、打包操作

八、常见问题与解决方案

问题现象	可能原因	解决方案
模型加载失败	路径含中文/空格；文件损坏；格式不支持	使用纯英文路径；验证模型完整性；确认为 .pt 或 .onnx
摄像头无法打开	被其他程序占用；ID 错误	关闭微信、Zoom 等；在配置中修改 `camera_id` 为 1 或 2
RTSP 连接超时	网络不通；账号密码错误；端口阻塞	用 VLC 测试流是否可达；检查防火墙设置
检测框无标签	未加载类别文件；类别数不匹配	加载正确的 class.json；确保类别数量与模型一致
软件运行卡顿	帧间隔过小；未使用 ONNX；硬件不足	提高帧间隔（如设为 10）；转换为 ONNX 模型；关闭保存功能

九、版本信息

软件名称：AirsPy YOLO 目标检测系统
版本号：v1.0
最后更新日期：2024 年 12 月
版本特性：基础功能完整，支持多种检测模式和结果管理

十、技术支持

如遇无法解决的问题，或需定制开发服务，请联系：

QQ：1029421735

视频演示：

https://www.bilibili.com/video/BV18VqSB7ETz/?share_source=copy_web\&vd_source=814d88cbf7c14e8a7604ad564517469a

软件地址：

目标检测软件AirsPy (YOLO识别)