1. 引言

1.1 编写目的

本文档为昇腾机械臂-垃圾分拣软件项目的软件需求规格说明书（Software Requirements Specification，SRS），旨在完整、准确地描述本软件系统的功能需求、非功能需求、外部接口需求及数据需求，明确系统的功能边界与性能指标。

本文档的预期读者包括：

• 项目开发人员：作为系统设计、编码实现和单元测试的依据；
• 项目测试人员：作为制定测试计划、设计测试用例和验收测试的基准；
• 项目管理人员：用于项目范围确认、进度规划和风险控制；
• 最终用户/客户：用于确认系统功能是否符合预期需求。

1.2 项目背景

随着工业自动化和人工智能技术的快速发展，智能分拣系统在制造业、物流业及环保领域的应用日益广泛。本项目依托工业互联网平台课程实训背景，以积木块模拟不同类别的垃圾（按颜色区分），构建一套完整的"视觉识别 + 机械臂分拣"自动化系统原型。

在当前垃圾分类的普及化趋势下，采用机器视觉与机械臂协同工作的方式替代人工分拣，可大幅提高分拣效率与准确性，降低人力成本。本项目旨在通过实践方式，完整经历从机械臂仿真控制→相机校准→数据采集→目标检测模型训练→系统集成的全流程，加深对工业互联网与人工智能技术在智能制造场景中应用的理解。

1.3 项目名称与范围

项目	内容
项目名称	昇腾机械臂-垃圾分拣
英文名称	Garbage Sorting Assistant
项目目标	基于 ROS2 机械臂与 YOLOv5 视觉检测技术，实现对四种颜色积木（Blue、Green、Red、Yellow）的自动识别与分拣。

项目范围包括以下五大子系统模块：

1. 机械臂仿真与控制子系统：基于 ROS2 Humble 与 KDL 运动学库，实现五自由度 DOFBOT 机械臂的正向/逆向运动学解算、URDF 模型可视化与关节控制。
2. 相机标定子系统：基于 OpenCV 实现相机透视变换标定，获取机械臂工作平面到图像平面的映射参数。
3. 数据采集子系统：通过多线程机制实现实时摄像头画面显示与异步图像保存，构建积木检测数据集。
4. 目标检测子系统：基于 YOLOv5s 模型进行目标检测训练与推理，支持 PyTorch → ONNX → Ascend OM 模型转换，并在昇腾边缘设备上部署。
5. 系统集成与演示：将以上子系统集成为完整的"检测—定位—抓取—分类"闭环分拣流程。

不在本项目范围内的内容：积木的物理抓取力学分析、多机械臂协同控制、复杂背景下的通用垃圾识别。

1.4 术语与定义

术语	英文	定义
正向运动学	Forward Kinematics (FK)	根据机械臂各关节角度，计算末端执行器在空间中的位置与姿态。
逆向运动学	Inverse Kinematics (IK)	根据末端执行器的目标位置和姿态，求解各关节的驱动角度。
URDF	Unified Robot Description Format	统一机器人描述格式，用于描述机器人模型的连杆、关节和运动学属性。
ROS2	Robot Operating System 2	第二代机器人操作系统，提供分布式通信、硬件抽象和工具链支持。
KDL	Kinematics and Dynamics Library	运动学与动力学库，提供机器人的运动学正反解算法实现。
透视变换	Perspective Transform	将图像投影到一个新的视平面，用于将倾斜拍摄的图像校正为俯视正视图。
YOLOv5	You Only Look Once v5	一种基于深度学习的一阶段目标检测算法，兼具检测精度与实时性。
ONNX	Open Neural Network Exchange	开放神经网络交换格式，用于深度学习模型的跨框架互转。
Ascend OM	Ascend OM Model	华为昇腾AI处理器的离线模型格式，经 ATC 工具转换后可在昇腾 NPU 上高效推理。
ACL	Ascend Computing Language	昇腾AI处理器的底层计算语言与运行时接口。
DeepSORT	Deep Simple Online and Realtime Tracking	一种结合外观特征的多目标跟踪算法，用于跟踪视频中多个目标的行踪。
mAP	Mean Average Precision	平均精度均值，目标检测任务中衡量模型性能的核心指标。
LabelMe	—	一种开源的图像标注工具，支持矩形框、多边形等多种标注形式，输出 JSON 格式标注文件。

1.5 参考文献

编号	文献名称	作者/来源	说明
[1]	IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications	IEEE	软件需求规格说明书编写标准
[2]	GB/T 9385-2008 计算机软件需求规格说明规范	中国国家标准化管理委员会	软件需求规格说明国家标准
[3]	ROS2 Humble Documentation	Open Robotics	ROS2 官方文档
[4]	YOLOv5: An Improved Version of YOLO	Ultralytics	YOLOv5 算法论文与实现
[5]	OpenCV-Python Tutorials	OpenCV Team	OpenCV 视觉库官方教程
[6]	Simple Online and Realtime Tracking (DeepSORT)	Wojke et al., 2017	多目标跟踪算法论文
[7]	昇腾 CANN 应用开发指南	华为技术有限公司	昇腾AI处理器应用开发文档
[8]	DOFBOT 机械臂用户手册	大象机器人	五自由度机械臂硬件手册

2. 项目概述

2.1 产品功能概述

本系统以"视觉识别 + 机械臂分拣"为核心，构建了一套完整的自动化分拣原型系统。系统集成了机械臂运动控制、相机标定与图像采集、深度学习目标检测以及自动分拣与分类四大功能模块，覆盖从感知到执行的全链路流程。

2.1.1 机械臂运动控制

机械臂运动控制是系统的执行层核心，基于 ROS2 Humble 框架与 KDL 运动学库，实现对 DOFBOT 五自由度机械臂的精确运动控制。具体包括：

• 正向运动学（FK）：输入当前 5 个关节角度（joint1 ~ joint5），通过 KDL 运动学链解算，输出末端执行器在三维空间中的位置坐标（x, y, z）和姿态角（roll, pitch, yaw），用于实时监测机械臂末端状态。
• 逆向运动学（IK）：输入目标位置坐标（tar_x, tar_y, tar_z）和期望姿态（roll, pitch, yaw），通过 Levenberg-Marquardt 优化算法求解各关节目标角度，使得机械臂末端能够到达指定的抓取/放置位置。
• 自定义 ROS2 服务接口（Kinemarics.srv）：将 FK 和 IK 封装为标准的 ROS2 服务（Service），支持客户端以请求-响应模式调用，便于上层决策模块集成调用。
• URDF 模型可视化：通过 robot_state_publisher 发布 URDF 模型状态，结合 joint_state_publisher_gui 和 RViz2 实现机械臂的实时三维可视化，方便调试与观察。

2.1.2 相机标定与图像采集

相机标定与图像采集是系统的感知层基础，负责建立图像坐标系到机械臂工作平面坐标系的映射关系，并采集训练所需的积木图像数据集。具体包括：

• 图像预处理：对摄像头采集的原始图像依次执行灰度化、高斯滤波去噪、自适应二值化、形态学开运算等操作，提取清晰的标定区域。
• 标定框检测与透视变换：通过轮廓检测算法识别工作区域中的标定方框，提取四个角点坐标，计算并应用透视变换矩阵，将倾斜拍摄的图像校正为 640×480 的标准俯视图。
• 标定参数持久化：将机械臂关节角度阈值参数（XYT_config.txt）和透视变换边点参数（dp.bin）保存到配置文件，支持后续运行中直接加载复用。
• 实时视频采集与交互控制：通过多线程架构（摄像头采集线程、交互控制线程、文件保存线程），实现实时视频流显示与异步图像保存，支持用户通过点击按钮随时采集积木样本。

2.1.3 积木目标检测

积木目标检测是系统的智能识别核心，基于 YOLOv5s 深度学习模型，实现对四种颜色积木（Blue、Green、Red、Yellow）的实时检测与定位。具体包括：

• 数据集构建：使用 LabelMe 工具对采集的积木图像进行矩形框标注，生成 JSON 格式标注文件，并转换为 YOLO 格式（类别 ID + 归一化边界框坐标），按照一定比例（约 146:55）划分为训练集和验证集。
• 模型训练：采用 YOLOv5s 架构，输入尺寸 640×640，使用 SGD 优化器训练 100 个 epoch，通过迁移学习策略冻结前 10 层网络，实现快速收敛。
• 模型转换：支持完整的模型转换流水线 PyTorch（.pt）→ ONNX（.onnx）→ Ascend OM（.om），确保模型可在不同推理平台上部署。
• 多模式推理：支持单张图像推理、实时摄像头视频流推理、视频文件推理三种运行模式，适配不同使用场景。
• 多目标跟踪：集成 DeepSORT 多目标跟踪算法，在视频流中对每个检测到的积木分配唯一 ID 并持续跟踪其运动轨迹，为后续抓取决策提供时序信息。

2.1.4 自动分拣与分类

自动分拣与分类是系统的最终执行环节，将视觉检测结果与机械臂控制相融合，完成完整的"检测—定位—抓取—分类"闭环流程。具体包括：

• 检测结果驱动抓取决策：根据目标检测模型输出的积木类别（颜色）和边界框位置，计算积木在工作平台上的物理坐标。
• 坐标映射与逆运动学解算：利用相机标定获得的透视变换参数，将图像坐标映射为机械臂基坐标系下的三维空间坐标，调用 ROS2 逆运动学服务解算目标关节角。
• 按颜色分类放置：系统根据检测到的颜色类别，规划不同的放置位置路径（如红色放左侧区、蓝色放右侧区等），实现自动分类分拣。
• 异常处理机制：对检测不到目标、逆运动学无解、抓取失败等异常情况进行检测与处理，确保系统运行的稳定性与鲁棒性。

2.2 用户特征

本系统的目标用户群体为工业互联网平台课程的实训学习者，具体特征如下：

用户类型	特征描述
实训学员	具备一定的编程基础（Python/C++），了解基本的机器视觉与机器人控制概念，但不要求具备深度学习或 ROS2 的深入知识。需要通过本项目的完整流程，理解从数据采集到模型部署再到机械臂控制的全链路工业互联网应用。
实训指导教师	具备工业互联网、机器视觉和机器人领域的专业知识，能够指导学员完成各模块的配置、调试与集成。可通过系统提供的可视化界面和中间日志快速定位问题。
评估/演示人员	关注系统的最终效果与演示流畅性，对模型精度、机械臂响应速度、分拣成功率等宏观性能指标感兴趣，不关心底层实现细节。

2.3 运行环境

2.3.1 硬件环境

2.3.1.1 DOFBOT 五自由度机械臂

DOFBOT 是一款面向教育和科研场景的五自由度串联机械臂，具体参数如下：

参数项	规格
自由度	5 个旋转关节（joint1 ~ joint5）
关节限位	joint1 ~ joint5：±1.5708 rad（±90°）；joint5 可旋转至 180°
连杆结构	base_link → link1 → link2 → link3 → link4 → link5
驱动方式	串口总线舵机控制
末端夹爪	支持开合控制，夹爪长度补偿参数 tool_param = 0.12m
通信接口	USB 转串口

2.3.1.2 USB 摄像头

参数项	规格
类型	USB 即插即用摄像头
分辨率	640×480（采集与推理统一尺寸）
安装方式	固定安装于机械臂工作平台上方，俯视拍摄
帧率	≥ 30 FPS（原始采集）

2.3.1.3 昇腾（Ascend）AI 边缘计算设备

参数项	规格
处理器	昇腾 310（Ascend 310）AI 处理器
架构	ARM（aarch64）
NPU算力	支持 FP16 / INT8 推理加速
模型格式	Ascend OM 离线模型
推理接口	ACL（Ascend Computing Language）
运行路径	/home/HwHiAiUser/RobotArm/

2.3.2 软件环境

2.3.2.1 操作系统（Ubuntu / openEuler）

• 机械臂控制与开发环境：Ubuntu 22.04 LTS（ROS2 Humble 官方支持版本）或 openEuler（ARM 架构适配版本）
• 昇腾边缘推理环境：基于 ARM（aarch64）架构的 Linux 系统，预装 Ascend 驱动与 CANN 软件包

2.3.2.2 ROS2 Humble 中间件

组件	用途
ROS2 Humble	机器人操作系统中间件，提供分布式通信（DDS）
rclcpp	ROS2 C++ 客户端库，用于实现服务端节点
robot_state_publisher	发布 URDF 机器人模型状态至 /tf 和 /robot_description
joint_state_publisher_gui	提供图形化关节角度控制滑块
MoveIt	运动规划框架（可选用于碰撞避免）
RViz2	三维可视化工具，用于机械臂模型与状态显示
KDL	运动学与动力学库，提供 FK/IK 解算算法支持

2.3.2.3 Python 与 OpenCV 环境

组件	版本/用途
Python	≥ 3.8
OpenCV-Python	图像采集、预处理、透视变换、轮廓检测
NumPy	数值计算与矩阵运算
Matplotlib	可视化与调试图像显示
Jupyter Notebook	交互式开发与实验记录
Arm_Lib	DOFBOT 机械臂 Python 驱动库

2.3.2.4 PyTorch / ONNX / Ascend CANN 推理框架

组件	用途
PyTorch	YOLOv5 模型训练框架
TorchVision	图像预处理与数据增强工具
ONNX	模型中间表示格式，用于跨框架转换
onnxsim	ONNX 模型精简优化工具
Ascend CANN	昇腾AI计算架构，提供 ATC 模型转换工具和 ACL 推理运行时
ATC（Ascend Tensor Compiler）	将 ONNX 模型转换为昇腾 OM 离线模型

2.4 约束与假设

设计约束：

1. 硬件约束：机械臂为五自由度，受限于关节限位（±90°），无法覆盖全部三维空间位置，抓取范围限定在机械臂工作空间内。
2. 运行平台约束：目标检测模型需部署在昇腾边缘设备上，模型须经过 ONNX → OM 转换，推理接口受 ACL 框架限制。
3. 操作系统约束：ROS2 Humble 依赖于 Ubuntu 22.04 或兼容 Linux 发行版，不支持 Windows 原生运行。
4. 开发工具约束：交互式开发依赖 Jupyter Notebook，不适合生产级持续运行场景。

假设与依赖：

1. 环境假设：假设工作平台光照条件相对稳定，无明显反光或阴影干扰；摄像头与机械臂的相对位置固定，标定后不再移动。
2. 检测场景假设：假设每次工作区域中仅放置一块积木（单目标场景），积木表面颜色均匀且与背景形成明显对比。
3. 数据假设：假设标注数据的边界框准确覆盖目标积木，标注类别仅有 Blue、Green、Red、Yellow 四种。
4. 通信假设：假设 ROS2 DDS 通信网络稳定，服务端响应延迟在可接受范围内（< 100ms）。
5. 第三方依赖：系统正常运行依赖于 ROS2 Humble、OpenCV、PyTorch、Ascend CANN 等第三方软件的正确安装与配置。

3. 外部接口需求

3.1 用户接口

3.1.1 Jupyter Notebook 交互界面

系统采用 Jupyter Notebook 作为主要的交互式开发与操作界面，提供以下用户交互能力：

• 相机标定界面（camera.ipynb）：通过 OpenCV 的 cv2.imshow() 窗口实时显示摄像头画面，叠加绘制检测到的标定框轮廓和角点；提供滑块控件（Trackbar）用于实时调整机械臂 joint1/joint2 角度和二值化阈值，实现交互式标定参数调优。
• 数据采集界面（data.ipynb）：实时显示透视变换校正后的俯视图像；提供"保存图片"按钮，用户放置积木后点击即可将当前帧异步保存到磁盘；界面显示当前已采集的图像数量和文件编号。
• 推理演示界面（yolov5_infer.ipynb / yolov5_camera.ipynb）：实时显示检测结果，在视频帧上绘制检测框、类别标签和置信度分数；支持切换检测模型和调整置信度阈值。
• 目标跟踪界面（yolov5s_v6.1_track.ipynb）：在检测基础上叠加跟踪 ID 和轨迹线，可视化多目标跟踪效果。

3.1.2 RViz2 可视化界面

RViz2 是 ROS2 的三维可视化工具，在本系统中用于：

• 机械臂模型显示：加载 DOFBOT 的 URDF 模型，以三维形式展示各连杆和关节的几何形状与位姿关系。
• 关节状态监视：实时显示 5 个关节的当前角度值，支持通过 joint_state_publisher_gui 面板的滑块手动控制各关节角度。
• TF 坐标系显示：可视化各连杆坐标系（base_link → link1 → ... → link5）的变换关系，便于调试运动学解算结果。
• 末端轨迹显示：可记录并显示末端执行器的运动轨迹路径，辅助评估运动规划的平滑性。

3.1.3 命令行接口

系统提供以下命令行操作方式：

• ROS2 命令行工具：通过 ros2 service call 直接调用 Kinemarics 服务进行 FK/IK 解算测试；通过 ros2 topic echo 订阅关节状态话题进行实时监控。
• 模型训练脚本：通过 python run.py 执行 YOLOv5 模型训练，支持通过命令行参数配置 --epochs、--batch-size、--weights 等训练参数。
• 模型转换脚本：通过 python onnx2om.py 执行 ONNX 到 OM 的格式转换，支持指定输入输出路径和量化配置。
• 推理运行脚本：通过 python om_infer.py 执行批量推理评估，输出检测结果和 mAP 指标。

3.2 硬件接口

3.2.1 机械臂串口/USB 通信接口

参数项	规格说明
物理层	USB 转串口（UART）
通信协议	串口总线舵机协议
通信速率	115200 bps（默认）
数据位	8 位
停止位	1 位
校验位	无
驱动方式	Arm_Lib Python 库封装串口读写指令
控制指令	关节角度控制指令、夹爪开合指令
状态反馈	关节当前角度、舵机温度、电压状态

3.2.2 摄像头 USB 视频采集接口

参数项	规格说明
物理层	USB 2.0 / 3.0
驱动协议	Video4Linux2（V4L2）
采集方式	OpenCV cv2.VideoCapture() 接口
分辨率	640×480（采集与透视变换后统一尺寸）
色彩格式	BGR（OpenCV 默认格式）
帧率	≥ 30 FPS（原始采集）
设备索引	/dev/video0（默认摄像头设备节点）

3.2.3 昇腾 NPU 推理接口（ACL）

参数项	规格说明
接口框架	Ascend Computing Language（ACL）
模型格式	Ascend OM 离线模型（.om）
数据类型	FP16（半精度浮点），支持 INT8 量化
模型加载	aclmdlLoadFromFile() 从文件加载 OM 模型
输入数据集	aclmdlCreateDataset() 创建模型输入数据集
输出数据集	aclmdlCreateDataset() 获取推理输出结果
资源管理	aclModel 类封装模型加载与卸载
资源初始化	aclResource 类封装 ACL 初始化与设备管理

3.3 软件接口

3.3.1 ROS2 自定义服务接口（Kinemarics.srv）

系统定义了一个自定义 ROS2 服务 Kinemarics.srv，用于封装机械臂正向和逆向运动学解算功能：

服务定义文件： dofbot_info/srv/Kinemarics.srv

# 请求（Request）
float64 tar_x          # 目标位置 X 坐标（m）
float64 tar_y          # 目标位置 Y 坐标（m）
float64 tar_z          # 目标位置 Z 坐标（m）
float64 roll           # 目标横滚角
float64 pitch          # 目标俯仰角
float64 yaw            # 目标偏航角
float64 cur_joint1     # 当前关节1角度（rad）
float64 cur_joint2     # 当前关节2角度（rad）
float64 cur_joint3     # 当前关节3角度（rad）
float64 cur_joint4     # 当前关节4角度（rad）
float64 cur_joint5     # 当前关节5角度（rad）
float64 cur_joint6     # 当前关节6角度（预留）
string  kin_name       # 运动学类型："fk"（正向）或 "ik"（逆向）
---
# 响应（Response）
float64 joint1         # 解算后关节1角度（rad）
float64 joint2         # 解算后关节2角度（rad）
float64 joint3         # 解算后关节3角度（rad）
float64 joint4         # 解算后关节4角度（rad）
float64 joint5         # 解算后关节5角度（rad）
float64 joint6         # 解算后关节6角度（预留）
float64 x              # 末端 X 坐标（m）
float64 y              # 末端 Y 坐标（m）
float64 z              # 末端 Z 坐标（m）
float64 roll           # 末端横滚角
float64 pitch          # 末端俯仰角
float64 yaw            # 末端偏航角

调用方式：

• 服务名：/dofbot_kinemarics
• 通信模式：ROS2 Service（同步请求-响应）
• 服务端实现：dofbot_server.cpp（C++ 实现，基于 KDL 库）

3.3.2 相机标定参数接口（配置文件的读写）

标定参数通过配置文件持久化存储，格式如下：

文件	格式	内容
XYT_config.txt	文本文件	机械臂关节角度阈值（X/Y 坐标对应 joint1/joint2）和二值化阈值参数
dp.bin	二进制文件	透视变换的 4 个边点坐标（以 pickle 序列化存储）

标定流程中的参数交互：

1. 写入：camera.ipynb 中标定完成后，将透视变换角点坐标序列化为 dp.bin，将角度与阈值参数写入 XYT_config.txt。
2. 读取：data.ipynb 启动时从配置文件读取参数，初始化机械臂位置和透视变换矩阵。
3. 索引文件：data_collect_idx.txt 记录当前图像采集的序号，每次保存后自增。

3.3.3 数据集标注格式接口（LabelMe JSON）

系统使用 LabelMe 工具进行图像标注，标注文件为 JSON 格式，结构如下：

{
  "version": "5.0.1",
  "flags": {},
  "shapes": [
    {
      "label": "Blue",
      "points": [[234.6, 202.8], [397.0, 324.3]],
      "group_id": null,
      "shape_type": "rectangle",
      "flags": {}
    }
  ],
  "imagePath": "193.jpg",
  "imageHeight": 480,
  "imageWidth": 640
}

标注规范：

字段	说明
label	目标类别，取值范围："Blue"、"Green"、"Red"、"Yellow"
points	矩形框的两个对角点坐标 [[x1, y1], [x2, y2]]
shape_type	固定为 "rectangle"（矩形框标注）
imageHeight / imageWidth	图像尺寸，固定为 480 × 640

数据转换：训练前通过脚本将 LabelMe JSON 格式转换为 YOLO 训练格式（每个图像对应一个 .txt 文件，每行格式为 class_id x_center y_center width height，坐标归一化到 [0, 1]）。

3.3.4 模型文件接口（.pt / .onnx / .om）

系统涉及三种模型文件格式，其接口定义如下：

格式	来源	用途	加载方式
.pt（PyTorch）	YOLOv5 训练输出	训练后保存的权重文件，包含完整模型结构	torch.load()
.onnx（ONNX）	.pt 转换得到	中间表示格式，用于跨平台交换和部署	onnxruntime.InferenceSession()
.om（Ascend OM）	.onnx 经 ATC 转换	昇腾 NPU 离线推理模型	aclmdlLoadFromFile()

模型转换流水线接口：

yolov5s.pt  ──[export.py]──→  yolov5s.onnx  ──[ATC工具]──→  yolov5s.om

3.4 通信接口

3.4.1 ROS2 DDS 通信协议

系统基于 ROS2 Humble 的 DDS（Data Distribution Service）中间件实现模块间通信，主要通信模式包括：

通信模式	用途	具体实现
Service（同步请求-响应）	运动学解算调用	客户端发送目标位姿参数，服务端返回解算后的关节角或末端位姿
Topic（发布-订阅）	机器人状态发布	robot_state_publisher 发布 /joint_states 和 /tf 话题
Parameter（参数服务器）	模型参数与配置	机器人描述参数、运动学参数等

主要话题与服务列表：

名称	类型	方向	说明
/dofbot_kinemarics	dofbot_info/srv/Kinemarics	Service	运动学解算服务
/joint_states	sensor_msgs/JointState	Topic	发布各关节当前角度
/tf	tf2_msgs/TFMessage	Topic	发布各连杆坐标系变换
/robot_description	std_msgs/String	Topic	发布 URDF 模型描述

3.4.2 机械臂控制指令协议

机械臂控制通过串口总线协议实现，指令格式如下：

指令类型	功能码	数据格式	说明
关节角度控制	舵机写指令	[ID, 角度值(高字节), 角度值(低字节)]	设置指定 ID 舵机的目标角度
夹爪控制	舵机写指令	[ID, 开合值]	控制夹爪张开/闭合
角度读取	舵机读指令	[ID]	读取指定 ID 舵机的当前角度
批量控制	同步写指令	[ID1, 角度1, ID2, 角度2, ...]	同时控制多个关节运动

通信时序：

1. 上位机（Jupyter Notebook / ROS2 节点）计算目标关节角度。
2. 通过 Arm_Lib 库封装为串口协议指令帧。
3. 经 USB 转串口发送至机械臂舵机控制板。
4. 舵机执行角度控制并返回状态反馈。

---

4. 系统功能需求

4.1 模块一：相机标定子系统

相机标定子系统负责建立图像坐标系到机械臂工作平面坐标系的映射关系，为后续的数据采集和精确定位提供基础。

4.1.1 图像预处理功能

系统对摄像头采集的原始图像执行以下预处理流水线：

4.1.1.1 灰度化与高斯滤波

• 灰度化：将 BGR 三通道彩色图像转换为单通道灰度图像，降低后续处理的计算量。
• 高斯滤波：采用高斯核（如 5×5）对灰度图像进行平滑滤波，抑制图像中的高频噪声。

4.1.1.2 二值化与形态学处理

• 自适应二值化：根据用户通过滑块设定的阈值，将灰度图像二值化，使标定框区域与背景分离。
• 形态学开运算：先腐蚀后膨胀，去除二值图像中的细小噪点区域，同时保持目标区域的形状不变。

4.1.2 标定框检测与轮廓提取

• 轮廓检测：使用 OpenCV 的 cv2.findContours() 检测二值图像中的所有连通区域轮廓。
• 轮廓筛选：根据面积、周长、外接矩形长宽比等几何特征，筛选出标定方框对应的最大轮廓。
• 角点提取：提取筛选轮廓的四个顶点坐标，作为透视变换的源点。

4.1.3 透视变换与图像校正

• 变换矩阵计算：以标定框四个顶点为源点，预设的 640×480 矩形四个角点为目标点，计算透视变换矩阵。
• 图像校正：应用 cv2.warpPerspective() 将原始倾斜图像校正为标准俯视图，消除透视畸变。

4.1.4 标定参数保存与加载

• 参数持久化：将透视变换的四个边点坐标序列化为 dp.bin 文件，将机械臂角度和二值化阈值保存为 XYT_config.txt。
• 参数加载：在数据采集和系统集成阶段读取已保存的标定参数，避免重复标定。

4.2 模块二：数据采集子系统

数据采集子系统实现实时视频显示和积木样本图像的采集保存功能。

4.2.1 实时视频显示功能

• 视频采集：通过 OpenCV 读取摄像头实时视频流。
• 透视变换叠加：在显示之前，对标定后的每一帧图像应用透视变换校正。
• 实时显示：在 Jupyter Notebook 窗口中显示校正后的俯视画面，帧率不低于 15 FPS。

4.2.2 机械臂位置控制功能

• 位置调整：通过滑块控件调整机械臂 joint1 和 joint2 的角度，使标定框位于摄像头视野中心区域。
• 参数联动：角度调整参数与 XYT_config.txt 中的阈值参数联动，确保实验环境的一致性。

4.2.3 图像异步保存功能（多线程）

为保证画面流畅度和保存可靠性，采用三线程架构：

线程	功能	说明
thread1（采集线程）	摄像头实时采集、透视变换、画面显示	主循环，持续运行
thread2（控制线程）	监听按钮事件	点击"保存图片"时将当前帧加入保存队列
thread3（保存线程）	从队列取出图像，异步写入磁盘	避免磁盘 I/O 阻塞采集流程

4.2.4 数据集自动编号管理

• 自动命名：采集的图像按递增序号自动命名（如 193.jpg、194.jpg、...）。
• 序号持久化：当前序号记录在 data_collect_idx.txt 文件中，支持断点续采。
• 文件夹管理：每次采集会话自动创建以时间戳命名的文件夹，避免不同批次数据混淆。

4.3 模块三：机械臂仿真与控制子系统

机械臂仿真与控制子系统是系统的执行核心，提供运动学解算与机械臂状态管理能力。

4.3.1 正向运动学解算（FK）

• 输入：5 个关节角度值（joint1 ~ joint5）。
• 处理：通过 KDL 运动学链的 FKPos() 方法，沿 URDF 定义的连杆变换链依次传递。
• 输出：末端执行器在基坐标系下的三维坐标（x, y, z）和 RPY 姿态角（roll, pitch, yaw）。
• 夹爪补偿：在末端位置中叠加 tool_param = 0.12m 的夹爪长度补偿。

4.3.2 逆向运动学解算（IK）

• 输入：目标位置坐标（tar_x, tar_y, tar_z）和目标姿态角（roll, pitch, yaw）。
• 求解器：KDL 的 Levenberg-Marquardt 优化求解器（LMA）。
• 处理：以当前关节角为初始猜测，迭代搜索满足目标位姿的关节角度解。
• 输出：5 个关节的目标角度值（joint1 ~ joint5）。
• 约束：解算结果须在各关节限位（±1.5708 rad）范围内，否则返回求解失败状态。

4.3.3 ROS2 服务端通信

• 服务节点：dofbot_server.cpp 实现 ROS2 Service 服务端节点。
• 服务注册：注册 /dofbot_kinemarics 服务，监听客户端的 FK/IK 请求。
• 请求处理：根据 kin_name 字段值（"fk" 或 "ik"）分发到对应的解算分支。
• 结果返回：将解算结果填充到响应消息中返回客户端。

4.3.4 URDF 模型加载与可视化

• 模型文件：dofbot.urdf 定义 5 个连杆和 5 个旋转关节的几何、惯量和运动学参数。
• 网格文件：6 个 .STL 文件分别为 base 和各连杆的三维网格模型。
• 模型发布：robot_state_publisher 加载 URDF 并发布 /tf 和 /robot_description 话题。
• 可视化：RViz2 加载 URDF 模型显示三维机械臂形态。

4.3.5 关节状态发布与监视

• 状态发布：joint_state_publisher 发布包含 5 个关节名称和角度值的 /joint_states 话题。
• GUI 控制：joint_state_publisher_gui 提供滑块界面，支持手动调节各关节角度进行调试。
• 状态监视：通过 ros2 topic echo /joint_states 或 RViz2 面板实时查看关节状态。

4.4 模块四：目标检测子系统

目标检测子系统提供从数据集构建、模型训练到推理部署的完整深度学习流水线。

4.4.1 YOLOv5 模型训练功能

4.4.1.1 LabelMe 标注转 YOLO 格式

• 输入：LabelMe JSON 格式标注文件（包含矩形框坐标和类别标签）。
• 转换：将 JSON 解析为 YOLO 格式的 .txt 文件，每行格式为 class_id x_center y_center width height，所有坐标归一化到 [0, 1]。
• 类别映射：Blue→0、Green→1、Red→2、Yellow→3。

4.4.1.2 训练集/验证集/测试集划分

• 划分比例：约 146 张训练集、55 张验证集、剩余为测试集。
• 划分策略：随机划分，确保各类别在各子集中分布均衡。
• 数据配置文件：data.yaml 定义训练/验证路径、类别数量和类别名称。

4.4.1.3 模型训练与超参数配置

超参数	配置值	说明
模型架构	YOLOv5s	轻量级版本，适合边缘部署
输入尺寸	640×640	训练与推理统一分辨率
训练轮数	100 epochs	含早停机制
Batch Size	12	根据 GPU 显存调整
优化器	SGD	momentum=0.937
学习率	lr0=0.01	余弦退火衰减
冻结层数	10	迁移学习，加速收敛
数据增强	Mosaic、MixUp、HSV 扰动等	默认 YOLOv5 增强策略

4.4.1.4 训练过程监控与指标输出

• 实时指标：每 epoch 输出 box_loss、cls_loss、obj_loss、Precision、Recall、mAP@0.5、mAP@0.5:0.95。
• 可视化曲线：results.png 展示各指标随训练轮数的变化曲线。
• 混淆矩阵：confusion_matrix.png 展示各类别的分类混淆情况。
• CSV 日志：results.csv 记录每 epoch 的完整指标数据，支持后续分析。

4.4.2 模型转换功能

4.4.2.1 PyTorch 转 ONNX

• 工具：YOLOv5 自带的 export.py 导出脚本。
• 输出：yolov5s.onnx，包含模型结构和权重。
• 精简优化：通过 onnxsim 对 ONNX 模型进行常量折叠和算子融合，减小模型体积。

4.4.2.2 ONNX 转 Ascend OM（ATC 工具）

• 工具：Ascend CANN 的 ATC（Ascend Tensor Compiler）。
• 输出：yolov5s.om，昇腾 NPU 可加载的离线模型。
• 配置参数：输入节点名称、输出节点名称、输入数据格式（NCHW）、数据类型（FP16）。
• 执行脚本：onnx2om.sh 封装 ATC 转换命令。

4.4.3 模型推理功能

4.4.3.1 单张图像推理

• 输入：单张 JPEG 图像（640×480）。
• 预处理：缩放填充至 640×640，归一化到 [0, 1]。
• 推理：加载 .pt / .onnx / .om 模型进行前向传播。
• 后处理：非极大值抑制（NMS）去除重复检测框。
• 输出：检测结果图像（绘制边界框、类别标签和置信度分数）。

4.4.3.2 实时摄像头推理

• 流程：摄像头逐帧采集 → 透视变换校正 → 缩放至 640×640 → 模型推理 → 绘制检测结果 → 显示。
• 性能要求：推理帧率 ≥ 15 FPS，确保实时交互体验。
• 部署平台：昇腾边缘设备（.om 模型）或本地 GPU 环境（.pt 模型）。

4.4.3.3 视频文件推理

• 输入：预录制的视频文件（如演示视频）。
• 流程：逐帧解码 → 缩放至 640×640 → 模型推理 → 绘制检测框 → 输出带标注的视频。
• 输出：带检测标注的处理后视频文件。

4.4.4 多目标跟踪功能（DeepSORT）

• 算法：DeepSORT（Deep Simple Online and Realtime Tracking）。
• 输入：YOLOv5 检测结果（边界框、置信度、类别）。
• 核心机制：
  • 卡尔曼滤波：对每个跟踪目标进行运动状态预测和更新。
  • 匈牙利匹配：将当前帧检测结果与已有跟踪轨迹进行最优匹配。
  • 外观特征匹配：使用深度特征提取网络计算目标的外观相似度，改善遮挡和交叉场景下的跟踪鲁棒性。
• 输出：每个检测目标携带唯一的跟踪 ID 和轨迹历史。

4.5 模块五：系统集成与自动分拣

系统集成与自动分拣模块将视觉检测、机械臂控制和分类逻辑整合为完整的闭环分拣流程。

4.5.1 相机-机械臂联合标定

• 坐标统一：将相机检测到的图像坐标通过透视变换和手眼标定，映射到机械臂基坐标系下。
• 参数融合：综合使用相机标定参数（透视变换矩阵）和机械臂运动学参数，建立从像素坐标到物理空间坐标的完整映射链。

4.5.2 积木检测-定位-抓取闭环控制

分拣流程的完整闭环控制步骤如下：

1. 检测：摄像头采集图像，YOLOv5 模型检测积木位置和颜色类别。
2. 定位：将检测框中心像素坐标通过透视变换映射到机械臂工作平面物理坐标。
3. 解算：将物理坐标作为目标位置，调用 ROS2 Kinemarics 服务的 IK 接口解算关节角度。
4. 移动：通过串口总线向机械臂发送关节角度控制指令，移动到积木上方。
5. 抓取：控制夹爪闭合，抓取积木。
6. 放置：根据颜色类别将机械臂移动到对应的放置区域，控制夹爪松开释放积木。
7. 复位：机械臂回到初始位置，等待下一次分拣指令。

4.5.3 按颜色分类放置逻辑

积木颜色	放置区域	对应目标坐标（示意）
Blue（蓝色）	区域 A	预设放置坐标 1
Green（绿色）	区域 B	预设放置坐标 2
Red（红色）	区域 C	预设放置坐标 3
Yellow（黄色）	区域 D	预设放置坐标 4

放置区域坐标在标定阶段预先设定并保存，运行时可调整。

4.5.4 异常检测与错误处理

系统需处理以下异常情况：

异常类型	检测方式	处理策略
未检测到积木	检测框数量为 0	等待并重试，超时后提示用户放置积木
检测置信度过低	最高置信度 < 阈值	调整相机焦距或光照条件后重试
逆运动学无解	IK 求解器返回失败	调整目标位置至机械臂工作空间内
抓取失败	夹爪状态反馈异常	重新执行抓取流程，最多重试 3 次
通信超时	ROS2 服务调用超时	检查网络/串口连接，重启对应节点

5. 非功能需求

5.1 性能需求

5.1.1 检测精度（mAP ≥ 95%）

系统在积木检测任务上须满足以下精度指标：

指标	要求值	说明
mAP@0.5	≥ 99%	在 IoU 阈值为 0.5 时的平均精度均值
mAP@0.5:0.95	≥ 95%	在 IoU 阈值 0.5~0.95（步长 0.05）范围内的平均精度均值
Precision（精确率）	≥ 99%	检测结果中被正确识别的比例
Recall（召回率）	≥ 99%	所有真实目标中被检测出来的比例
各类别检测精度	≥ 98%	Blue、Green、Red、Yellow 四个类别各自的检测精度均不低于 98%

上述指标已在当前 YOLOv5s 模型的训练结果中得到验证（Precision 99.77%、Recall 100%、mAP@0.5 99.5%、mAP@0.5:0.95 95.54%）。

5.1.2 推理实时性（帧率 ≥ 15 FPS）

系统在实时推理场景下须满足以下帧率要求：

部署平台	最低帧率	目标帧率	说明
昇腾边缘设备（.om 模型）	15 FPS	≥ 20 FPS	使用 FP16 推理
本地 GPU 环境（.pt 模型）	30 FPS	≥ 60 FPS	使用 FP16 或 FP32 推理
本地 CPU 环境（.onnx 模型）	5 FPS	≥ 10 FPS	仅用于调试和验证

帧率测量范围涵盖从图像采集、预处理、模型推理到结果绘制的全链路耗时。

5.1.3 机械臂响应延迟

指标项	要求值	说明
ROS2 服务调用响应时间	≤ 100 ms	从发送 FK/IK 请求到收到响应的往返时间
关节角度指令传输延迟	≤ 50 ms	从计算完成到指令到达舵机控制板的时间
机械臂运动到位时间	≤ 3 s	从发送目标角度到各关节到达目标位置的时间（视运动幅度而定）
单次分拣全流程耗时	≤ 15 s	从检测到抓取再到放置完成的完整闭环时间

5.1.4 图像采集与处理吞吐量

指标项	要求值
摄像头原始采集帧率	≥ 30 FPS
透视变换校正帧率	≥ 25 FPS（640×480 分辨率）
图像保存吞吐量	≥ 10 张/秒（异步写入磁盘）
训练数据预处理吞吐量	≥ 100 张/秒（缩放、归一化、数据增强）

---

5.2 可靠性需求

5.2.1 系统连续运行稳定性

• 连续运行时长：系统在正常条件下应能稳定运行 ≥ 4 小时，无崩溃或死锁。
• 内存泄漏控制：长时间运行后，内存占用不应超过初始值的 120%。
• 线程安全：多线程数据采集模块须使用线程安全队列（如 queue.Queue），确保采集线程和保存线程之间数据不冲突。
• ROS2 节点稳定性：机械臂服务端节点在持续接收请求时应保持稳定，无服务响应超时或节点崩溃。

5.2.2 数据采集不丢帧

• 队列容量：图像保存队列的最大容量须 ≥ 100 帧，防止瞬时大量保存请求导致溢出。
• 丢帧率：在正常采集速度下，图像丢帧率应为 0%。
• 数据完整性：保存到磁盘的 JPEG 图像文件须完整可读，无截断或损坏。
• 标注对应性：采集的图像文件名与后续标注的 JSON 文件名须一一对应，不出现缺失或错位。

5.2.3 异常断电与恢复

• 采集序号持久化：data_collect_idx.txt 在每次保存图像后实时更新，异常断电后重新启动时可从最近序号继续采集。
• 配置文件保护：标定参数文件（dp.bin、XYT_config.txt）在写入过程中采取原子写入策略，防止写一半时断电导致文件损坏。
• 模型文件校验：模型加载前检查文件完整性，对损坏的模型文件给出明确错误提示。

---

5.3 可用性需求

5.3.1 交互界面易用性

• 中文化界面：代码注释、Notebook 中的 Markdown 说明、控制面板标签均使用中文，降低学习门槛。
• 实时反馈：图像预处理过程中，标定框轮廓、角点、二值化结果等中间状态均以可视化方式实时呈现，帮助用户理解处理流程。
• 错误提示友好：当检测失败、保存失败或通信异常时，在界面中以醒目方式（颜色、弹窗）给出中文错误提示和解决建议。
• 操作一致性：各 Jupyter Notebook 的操作按钮、滑块控件的布局和交互风格保持一致。

5.3.2 操作引导与提示

• 步骤引导：每个 Jupyter Notebook 以 Markdown 单元格标注操作步骤顺序，引导用户按流程操作。
• 参数说明：界面中每个滑块和按钮旁边标注其功能说明和推荐取值范围。
• 状态指示：界面中显示当前系统状态（如"标定完成"、"采集中"、"推理中"），让用户清晰了解系统当前所处阶段。
• 帮助文档：提供 README 或帮助文档，说明各模块的启动方法、操作流程和常见问题解答。

---

5.4 可维护性需求

5.4.1 模块化设计

系统按功能划分为五个独立模块，遵循高内聚低耦合原则：

模块	依赖关系	独立部署能力
相机标定子系统	无外部模块依赖	可独立运行和测试
数据采集子系统	依赖相机标定参数	加载已有标定参数后可独立运行
机械臂仿真与控制子系统	无外部模块依赖	可独立运行和测试
目标检测子系统	无外部模块依赖	可独立运行和测试
系统集成与自动分拣	依赖上述四个模块	集成测试时使用

各模块之间通过明确定义的接口（配置文件、ROS2 服务、文件格式）进行交互，替换或升级单个模块不影响其他模块。

5.4.2 代码注释与文档规范

• 代码注释率：关键函数和类须有 docstring 注释，注释覆盖率 ≥ 30%。
• 命名规范：变量和函数命名采用 snake_case（Python）或 camelCase（C++），名称应反映其功能和用途。
• 版本管理：项目代码使用 Git 进行版本管理，关键提交须附带有意义的提交信息。
• Notebook 文档化：每个 Jupyter Notebook 中的代码单元格须配有 Markdown 说明单元格，解释代码功能和预期输出。

5.4.3 配置文件外部化

系统中所有可变参数均通过外部配置文件管理，无需修改代码即可调整运行参数：

配置文件	管理参数	所在位置
XYT_config.txt	机械臂角度阈值、二值化阈值	Camera_Cal/config/
dp.bin	透视变换边点坐标	Camera_Cal/config/
data_collect_idx.txt	数据采集当前序号	Camera_Cal/config/
data.yaml	数据集路径与类别配置	infer_project/
config.yaml	模型训练与推理配置	infer_project/
hyp.yaml	训练超参数	训练输出目录

---

5.5 可扩展性需求

5.5.1 支持新增积木类别

系统应支持在不修改核心代码的前提下新增积木类别：

• 数据层面：在 LabelMe 标注中使用新的类别名称进行标注，自动转换脚本能识别新类别并分配新的类别 ID。
• 配置层面：更新 data.yaml 中的类别列表，新增类别名称。
• 模型层面：调整 YOLOv5 模型输出层类别数，使用迁移学习在新数据集上微调。
• 控制层面：在分类放置逻辑中为新增颜色配置对应的放置区域坐标。
• 扩展成本：新增一种积木类别的预期工作量 ≤ 2 人天。

5.5.2 支持替换不同机械臂模型

系统应支持替换为不同型号的机械臂：

• URDF 替换：替换 dofbot.urdf 和对应的 STL 网格文件，即可加载新机械臂模型。
• 运动学参数更新：在 URDF 中更新各连杆的尺寸、关节限位和运动学参数。
• KDL 链重建：系统在启动时自动根据新的 URDF 构建 KDL 运动学链。
• 夹爪补偿调整：修改 tool_param 参数以适应新机械臂的夹爪尺寸。
• 通信协议适配：如新机械臂使用不同的通信协议，需实现对应的 Arm_Lib 适配层。

5.5.3 支持切换不同检测算法

系统应支持在 YOLOv5 之外切换为其他目标检测算法：

• 统一推理接口：定义标准的检测器基类接口，包含 preprocess()、infer()、postprocess() 三个核心方法。
• 算法插件化：不同检测算法（YOLOv5、YOLOv8、Faster R-CNN 等）作为插件实现统一接口，可即插即用。
• 模型格式兼容：支持加载不同格式的模型文件（.pt、.onnx、.om、.engine 等）。
• 配置切换：通过 config.yaml 中的 detector_type 字段指定当前使用的检测算法。
• 扩展成本：集成一种新检测算法的预期工作量 ≤ 3 人天。

---

6. 数据需求

6.1 数据类型与格式

6.1.1 图像数据（JPEG, 640×480）

参数项	规格
文件格式	JPEG（.jpg）
分辨率	640 × 480 像素
色彩空间	BGR（OpenCV 采集默认）
文件大小	约 50~150 KB/张
数据集总规模	约 200 张（含原始采集 + 标注后）
存储路径	任务4_训练积木检测模型/images/

6.1.2 标注数据（LabelMe JSON）

参数项	规格
文件格式	JSON（.json）
标注工具	LabelMe v5.0.1
标注类型	矩形框（rectangle）
类别标签	Blue、Green、Red、Yellow
坐标格式	绝对像素坐标 [[x1, y1], [x2, y2]]
文件命名	与对应图像同名，如 193.json ↔ 193.jpg

YOLO 格式转换后的标注文件：

参数项	规格
文件格式	纯文本（.txt）
每行格式	class_id x_center y_center width height
坐标范围	归一化到 [0, 1]
类别 ID	Blue=0, Green=1, Red=2, Yellow=3
存储路径	任务4_训练积木检测模型/output/trans_output/

6.1.3 标定参数数据（透视变换矩阵）

参数项	规格
透视变换边点	4 个点坐标，序列化为 dp.bin（pickle 格式）
机械臂角度与阈值	XYT_config.txt，文本格式
采集序号	data_collect_idx.txt，单行整数
存储路径	任务3_相机校准与数据采集/Camera_Cal/config/

6.1.4 模型权重数据（.pt / .onnx / .om）

格式	文件示例	文件大小	说明
PyTorch（.pt）	yolov5s.pt	约 14 MB	训练输出权重，包含完整模型结构
ONNX（.onnx）	yolov5s.onnx	约 28 MB	开放神经网络交换格式
Ascend OM（.om）	yolov5s.om	约 14 MB	昇腾离线模型，FP16 量化

6.1.5 训练日志与指标数据（CSV）

参数项	规格
文件格式	CSV（.csv）
记录内容	epoch、box_loss、cls_loss、obj_loss、Precision、Recall、mAP@0.5、mAP@0.5:0.95、lr
记录粒度	每 epoch 一行
存储路径	任务4_训练积木检测模型/output/train_output/results.csv

6.2 数据流向

系统各模块间的数据流向如下图所示

┌──────────────────┐     标定参数 (dp.bin, XYT_config.txt)
│  相机标定子系统   │─────────────────────────────────┐
│  (camera.ipynb)  │                                   │
└──────────────────┘                                   ▼
                                                     ┌──────────────────┐
┌──────────────────┐     原始图像 (193.jpg, ...)      │  数据采集子系统   │
│   USB 摄像头      │────────────────────────────────▶│  (data.ipynb)    │
│   (实时视频流)    │                                  └──────────────────┘
└──────────────────┘                                         │
                                                              │ 原始图像
                                                              ▼
┌──────────────────┐     标注 JSON (193.json, ...)    ┌──────────────────┐
│   LabelMe 标注    │────────────────────────────────▶│  目标检测子系统   │
│   (人工标注)      │                                  │  (YOLOv5训练)    │
└──────────────────┘                                  └──────────────────┘
                                                              │
                                                              │ 模型权重 (.pt)
                                                              ▼
┌──────────────────┐     目标位置 + 颜色类别          ┌──────────────────┐
│  系统集成与分拣   │◀────────────────────────────────│ 模型推理与跟踪    │
│  (闭环控制)      │                                  │  (om_infer.py)   │
└──────────────────┘                                  └──────────────────┘
         │
         │ 关节角度指令
         ▼
┌──────────────────┐
│  ROS2 机械臂控制   │
│  (dofbot_server)  │
└──────────────────┘

6.3 数据存储与管理

数据类型	存储位置	管理方式
原始采集图像	任务4_训练积木检测模型/images/	按文件名编号管理，与标注 JSON 文件一一对应
标注 JSON 文件	任务4_训练积木检测模型/images/	与对应图像文件同目录、同名
YOLO 格式数据集	任务4_训练积木检测模型/output/trans_output/	划分为 train/valid/test 子目录
训练输出	任务4_训练积木检测模型/output/train_output/	包含权重文件、曲线图、CSV 日志
标定配置	任务3_相机校准与数据采集/Camera_Cal/config/	文本和二进制混合存储
演示视频	演示视频	按视频文件名管理

数据备份策略：关键数据（标注 JSON 文件、训练权重、标定参数）建议定期备份至外部存储或云端，防止误删或磁盘故障导致数据丢失。

7. 系统约束与假设

7.1 硬件约束

约束项	具体描述
机械臂自由度限制	DOFBOT 为五自由度串联机械臂，关节 1~5 限位为 ±1.5708 rad（±90°），工作空间有限，无法覆盖所有三维空间位置。夹爪仅支持简单的开/合控制，不具备力反馈能力。
末端夹爪补偿	夹爪长度补偿参数固定为 tool_param = 0.12m，更换不同规格的夹爪后需重新标定该参数。
摄像头安装固定	USB 摄像头须固定安装于机械臂工作平台上方俯视拍摄，标定后摄像头与工作平台的相对位置不得移动，否则需重新标定透视变换参数。
摄像头分辨率限制	采集和推理统一使用 640×480 分辨率，更高分辨率虽可提供更多细节，但会增加推理延迟，可能影响实时性。
昇腾 NPU 算力限制	昇腾 310 处理器的 NPU 算力有限，模型须经过 FP16 量化或 INT8 量化以适配边缘推理性能，不支持 FP32 全精度推理。推理帧率受模型大小和输入分辨率影响。
USB 总线带宽	摄像头与机械臂共用 USB 总线时，带宽可能存在竞争，需确保总线带宽满足视频流和串口通信的同时传输需求。
存储空间	数据集采集和模型训练输出需要足够的磁盘空间（预计 ≥ 2 GB），昇腾边缘设备的存储空间可能有限，需提前规划。

7.2 软件约束

约束项	具体描述
ROS2 版本约束	系统基于 ROS2 Humble 开发，不保证与 ROS2 Galactic、Foxy 或其他版本的二进制兼容性。ROS2 Humble 仅官方支持 Ubuntu 22.04 LTS（Jammy）。
C++ 标准约束	机械臂控制服务端（dofbot_server.cpp）使用 C++17 标准编译，依赖 rclcpp 和 orocos-kdl 库，编译器须支持 C++17。
Python 版本约束	YOLOv5 训练和推理环境要求 Python ≥ 3.8，推荐 3.9 或 3.10。依赖 OpenCV-Python、NumPy、PyTorch 等第三方库，版本须兼容。
昇腾 CANN 版本约束	ONNX → OM 转换依赖特定版本的 Ascend CANN 软件包（含 ATC 工具），不同 CANN 版本之间的模型格式可能不兼容，转换后的 OM 模型须在相同版本的 CANN 运行时下加载推理。
PyTorch 版本约束	YOLOv5 对 PyTorch 版本有特定要求（推荐 1.9~2.0），过高或过低版本可能导致模型导出或训练异常。
操作系统架构约束	昇腾边缘设备基于 ARM（aarch64）架构，在该平台上编译和运行的程序必须使用交叉编译工具链或在 ARM 设备上原生编译。x86 平台上编译的二进制文件无法在 ARM 平台运行。
Jupyter Notebook 约束	交互式操作依赖 Jupyter Notebook 环境，无法直接移植为独立桌面应用程序。实时视频显示依赖 OpenCV 的 cv2.imshow()，在远程 SSH 或无图形界面的环境中可能无法正常工作。

7.3 场景约束（光照、背景、积木摆放等）

约束项	具体描述
光照条件	系统假设工作平台处于稳定的室内光照环境下，无明显阳光直射、频闪或剧烈阴影变化。过强或过弱的光照会影响二值化阈值的稳定性，进而影响标定精度。建议环境照度在 300~1000 lux 范围内。
背景条件	工作平台背景须为单一颜色且与积木颜色形成明显对比（推荐黑色或深色背景），避免背景中存在与积木颜色相近的物体干扰检测。背景中不应有反光材料。
积木摆放	每次分拣仅放置一块积木在工作区域内（单目标场景）。积木应平放在工作平台上（不允许竖立或倾斜），且位于透视变换校正后的视野中央区域。积木表面无明显污渍、划痕或遮挡。
积木颜色固定	积木颜色限定为 Blue（蓝色）、Green（绿色）、Red（红色）、Yellow（黄色）四种纯色，不包含渐变色、花纹或透明积木。四种颜色之间色差明显，易于区分。
环境稳定性	假设标定完成后摄像头、机械臂和工作平台的相对位置不会发生改变。若设备被移动或碰撞，须重新执行标定流程。工作平台应水平放置，避免倾斜影响定位精度。
噪声干扰	假设实验环境中无明显电磁干扰影响串口通信，无其他无线信号干扰摄像头数据传输。多人同时操作时应注意避免遮挡摄像头视野。

7.4 假设与依赖

设计假设：

1. 使用对象假设：假设使用者具备基本的 Linux 命令行操作能力（如文件操作、运行脚本），了解 Python 编程基础，但不要求具备 ROS2 或深度学习专业知识。
2. 网络假设：在涉及昇腾边缘设备推理的场景中，假设开发主机与边缘设备处于同一局域网内，可通过 SSH 或 SCP 进行文件传输和远程调试。
3. 单目标假设：假设每次分拣任务中工作区域内仅存在一个积木目标，系统不处理多目标情况下抓取优先级判定的复杂逻辑。
4. 检测与抓取位置一致性假设：假设积木在检测时的位置与机械臂抓取时的位置一致，积木在抓取过程中不会发生移动（如被气流吹动）。
5. 训练数据充分性假设：假设采集的训练数据覆盖了各类积木在不同光照角度下的典型表现，模型训练后可达到预期精度指标。
6. 标定一次、多次使用假设：假设标定参数一经确定，在持续运行过程中无需重新标定，除非硬件相对位置发生改变。

外部依赖：

依赖项	依赖类型	说明
ROS2 Humble	运行时依赖	机械臂控制服务端的运行基础，须正确安装和配置
OpenCV-Python	运行时依赖	图像采集、预处理、透视变换的核心依赖
PyTorch	训练时依赖	YOLOv5 模型训练必须的深度学习框架
Ascend CANN	运行时依赖	昇腾 NPU 推理必须的软件栈
KDL（orocos-kdl）	编译时依赖	机械臂运动学解算库
Arm_Lib	运行时依赖	DOFBOT 机械臂 Python 驱动库
LabelMe	工具依赖	图像标注工具，需提前安装
Jupyter Notebook	运行时依赖	交互式开发环境
USB 摄像头驱动	系统依赖	须确保 Linux 系统已识别摄像头设备节点

---

8. 验收标准

8.1 功能验收清单

编号	验收项	所属模块	验收标准
F-01	相机图像实时采集	相机标定	能正常打开 USB 摄像头并实时显示视频画面，帧率 ≥ 25 FPS
F-02	图像灰度化与滤波	相机标定	能正确将彩色图像转换为灰度图，并应用高斯滤波去噪
F-03	二值化与形态学处理	相机标定	能根据滑块阈值对灰度图进行二值化，并通过开运算去除噪点
F-04	标定框检测与轮廓提取	相机标定	能正确检测标定方框轮廓并提取四个顶点坐标
F-05	透视变换校正	相机标定	能正确将倾斜图像校正为 640×480 标准俯视图
F-06	标定参数保存与加载	相机标定	标定参数可保存到配置文件，重启后能正确加载复用
F-07	实时视频显示	数据采集	透视变换校正后的画面实时显示，帧率 ≥ 15 FPS
F-08	图像异步保存	数据采集	点击"保存图片"后图像可异步保存到磁盘，文件名递增编号
F-09	采集序号持久化	数据采集	当前采集序号记录在配置文件中，重启后序号连续
F-10	正向运动学解算（FK）	机械臂控制	输入关节角度能正确解算出末端位姿，误差 ≤ 1mm
F-11	逆向运动学解算（IK）	机械臂控制	输入目标位姿能正确解算出关节角度，解在关节限位内
F-12	ROS2 服务通信	机械臂控制	Kinemarics 服务能正确响应 FK/IK 请求，响应时间 ≤ 100ms

F-13	URDF 模型加载与可视化	机械臂控制	RViz2 中能正确加载并显示 DOFBOT 三维模型
F-14	关节状态发布与监视	机械臂控制	/joint_states 话题正常发布，各关节角度实时更新
F-15	LabelMe 标注转 YOLO 格式	目标检测	能正确将 JSON 标注文件转换为 YOLO 格式的 .txt 文件
F-16	数据集划分	目标检测	能自动按比例划分训练集、验证集，各类别分布均衡
F-17	YOLOv5 模型训练	目标检测	训练流程完整可运行，100 个 epoch 内正常收敛
F-18	训练过程监控	目标检测	训练过程中实时输出指标，生成 results.png 和 confusion_matrix.png
F-19	PyTorch 转 ONNX	目标检测	能正确将 .pt 模型导出为 .onnx 格式
F-20	ONNX 转 Ascend OM	目标检测	能通过 ATC 工具将 .onnx 转换为 .om 格式并在昇腾设备上正确加载
F-21	单张图像推理	目标检测	能对单张图像进行检测并正确绘制边界框和标签
F-22	实时摄像头推理	目标检测	能对摄像头视频流进行实时检测，帧率 ≥ 15 FPS
F-23	视频文件推理	目标检测	能对视频文件逐帧检测并输出带标注的结果视频
F-24	DeepSORT 多目标跟踪	目标检测	能对检测目标分配跟踪 ID 并保持轨迹稳定性
F-25	检测-定位-抓取闭环控制	系统集成	能完整执行检测→定位→解算→移动→抓取→放置的闭环流程
F-26	按颜色分类放置	系统集成	四种颜色的积木能正确分拣到对应的预设放置区域
F-27	异常检测与处理	系统集成	当检测失败、IK 无解等异常发生时，系统能正确提示并处理

8.2 性能验收指标

编号	验收项	指标要求	测试方法
P-01	目标检测 mAP@0.5	≥ 99%	在测试集上运行评估脚本，输出 COCO mAP 指标
P-02	目标检测 mAP@0.5:0.95	≥ 95%	在测试集上运行评估脚本，输出 COCO mAP 指标
P-03	检测 Precision	≥ 99%	在测试集上运行评估脚本，输出 Precision 指标
P-04	检测 Recall	≥ 99%	在测试集上运行评估脚本，输出 Recall 指标
P-05	昇腾推理帧率	≥ 15 FPS	运行实时摄像头推理，使用帧率计数器测量 60 秒平均帧率
P-06	GPU 推理帧率	≥ 30 FPS	运行实时摄像头推理，使用帧率计数器测量 60 秒平均帧率
P-07	IK 服务响应时间	≤ 100 ms	连续调用 Kinemarics 服务 100 次，统计平均响应时间
P-08	单次分拣全流程时间	≤ 15 s	从放置积木到完成分类放置，计时 10 次取平均值
P-09	图像保存吞吐量	≥ 10 张/秒	连续保存 50 张图像，计算平均保存耗时
P-10	系统连续运行稳定性	≥ 4 小时	系统连续运行 4 小时，记录崩溃次数和内存增长情况
P-11	数据采集丢帧率	0%	采集 100 张图像后核验文件名连续性和文件完整性
P-12	模型转换成功率	100%	执行完整模型转换流水线，验证输出的 .onnx 和 .om 文件可加载