sp_vision_25软件架构图解:3分钟看懂四层模块化视觉框架设计
sp_vision_25软件架构图解:3分钟看懂四层模块化视觉框架设计
sp_vision_25 是同济大学 SuperPower 战队为 RoboMaster 25 赛季开源的 RoboMaster 视觉框架,核心功能是实现机器人自瞄(自动瞄准与火控)。整套框架采用四层模块化架构——应用层、功能层、硬件抽象层、工具层,各层职责清晰、互相解耦,新同学无需 ROS 基础即可快速上手。
为什么需要分层:一个相机引发的架构思考
机器人上往往要同时实现多种功能:步兵需要自瞄和打符,但相机同一时间只能被一个程序打开。如果每个功能都写成一个独立程序,就会互相抢占相机,无法共存。
sp_vision_25 的解法是:只保留一个运行程序(一个 main 函数),它负责从相机取图,再根据电控发来的档位信号(自瞄档 or 打符档)动态切换功能组。不同兵种只是不同的 main,共享同一套功能库。这就是框架设计的出发点。
总览:四层结构一张图读懂
| 层级 | 目录 | 职责 | 典型模块 |
|---|---|---|---|
| 应用层 | src/ | 各兵种的 main 入口,决定执行逻辑 | standard.cpp、sentry.cpp、uav.cpp |
| 功能层 | tasks/ | 自瞄、打符、全向感知等算法实现 | auto_aim/、auto_buff/、omniperception/ |
| 硬件抽象层 | io/ | 相机、C 板、云台、IMU、ROS2 通信 | camera.cpp、cboard.cpp、gimbal/ |
| 工具层 | tools/ | 日志、录制、队列、滤波等通用工具 | logger.cpp、recorder.cpp、thread_safe_queue.hpp |
此外,calibration/ 提供相机内参标定与手眼标定程序,configs/ 存放每台机器人的 YAML 配置,tests/ 则为每个模块提供独立测试程序——"赛前问题排查、赛后问题复现"全靠它。
应用层(src/):不同兵种,不同 main
应用层是最薄的一层。以步兵程序 src/standard.cpp 为例,主循环只做五件事:
- 从相机读取图像和时间戳;
- 用同一时间戳从 C 板取云台姿态四元数,保证图像与姿态对齐;
- 依次调用识别器、估计器、决策器;
- 把瞄准指令通过 C 板发给下位机;
- 根据电控档位信号在 idle / 自瞄 / 打符之间切换。
整个目录覆盖了步兵(standard.cpp、mt_standard.cpp、standard_mpc.cpp)、哨兵(sentry.cpp、sentry_multithread.cpp)、无人机(uav.cpp)等全部兵种的入口程序,以及对应的调试版本。
功能层(tasks/):三大功能组的核心算法
这是整个框架"含金量"最高的部分,按功能拆成三个子库:
auto_aim:自瞄功能组
tasks/auto_aim/ 实现了自瞄的完整感知—决策链路,每个模块独立成类,方便单独替换和测试:
- detector(detector.cpp):融合神经网络与图像处理,输出装甲板四个顶点坐标和图案类别,其中 yolos/ 目录内置了 yolov5、yolov8、yolo11 三种推理实现;
- tracker(tracker.cpp):基于扩展卡尔曼滤波的整车目标状态估计器;
- solver(solver.cpp):装甲板位姿解算、坐标变换;
- aimer(aimer.cpp):瞄准位置与开火决策;
- shooter(shooter.cpp):射击指令生成;
- planner(planner/planner.cpp):25 赛季的亮点——自瞄轨迹规划器,内部集成了第三方库 TinyMPC,用模型预测控制思想让云台轨迹更容易跟随,实测求解耗时小于 1ms。
auto_buff:打符功能组
tasks/auto_buff/ 负责打风扇叶。识别时既可以用神经网络(yolo11_buff.cpp),也可以用模板匹配——上文配图 assets/standard_fanblade.jpg 正是标准风扇叶的轮廓模板,在 configs/demo.yaml 的 standard_fanblade_path 参数中被引用。
omniperception:全向感知功能组
tasks/omniperception/ 面向哨兵的"全向感知":perceptron.cpp 同时挂载 4 个 USB 相机,通过线程池 + 线程安全队列并行推理,再由 decider.cpp 汇总决策。
硬件抽象层(io/):相机和串口都被"藏"起来了
io/ 层把硬件细节全部封装,让上层代码完全不关心具体设备型号:
- 相机:camera.cpp 是统一门面,内部通过
unique_ptr持有具体实现,可在 hikrobot/(海康)、mindvision/(迈德威视)工业相机和 usbcamera/(USB 相机)之间按配置切换,同时自动适配 amd64 / arm64 的 SDK 库; - C 板通信:cboard.cpp 负责与 STM32 下位机的串口/CAN 数据交互,读取四元数、发送瞄准指令;
- IMU 与云台:dm_imu/ 支持达妙 IMU 采集,gimbal/ 直接通过虚拟串口驱动云台,可用于测试程序;
- ROS2 接口:ros2/ 为哨兵预留了与导航通信的发布/订阅接口,CMake 检测到 ROS2 环境才会编译这部分,无 ROS 依赖照样可用。
工具层(tools/):不重复造轮子的通用件
tools/ 提供跨兵种复用的基础组件,是团队协作出错率低的关键:
- logger.cpp:日志记录;
- recorder.cpp:类 rosbag 录制(时间戳 + 视频 + 四元数),支撑离线调试;
- thread_safe_queue.hpp 与 thread_pool.hpp:多线程基础设施;
- extended_kalman_filter.cpp、trajectory.cpp、pid.cpp:估计与控制的数学组件;
- plotter.cpp:配合 PlotJuggler 输出调试曲线。
数据流:一帧图像穿过四层的路径
把四层串起来看,一帧图像的流动路径是:
相机线程产生图像 + 时间戳 → io 层按时间戳对齐云台姿态 → 功能层识别器输出装甲板顶点 → 估计器算出目标运动状态 → 决策器/规划器预测轨迹、生成瞄准与开火指令 → io 层发给 C 板 → 下位机电控执行。
整个流程在 src/standard.cpp 的主循环里只有十几行代码,因为所有复杂度都被下沉到了功能层和工具层。
3分钟验证:编译并跑通 Demo
想亲眼看看架构是否如文章所描述,两步即可(环境要求见 readme.md 3.1/3.2 节):
cmake -B build
make -C build/ -j`nproc`
./build/auto_aim_test
auto_aim_test 会读取 assets/demo/demo.avi 的录制视频走完整条自瞄流水线——注意它只链接了 auto_aim 功能库 + io + tools,没有接任何真实硬件,这就是分层的红利:脱离机器人也能验证算法。各模块还有独立的测试程序,例如 tests/camera_thread_test.cpp、tests/planner_test_offline.cpp、tests/gimbal_test.cpp,可按需运行。
每台机器人的差异参数(相机型号、曝光、标定矩阵、规划器参数等)统一放在 configs/ 的 YAML 中,如 standard3.yaml、sentry.yaml,换机器人只改配置不改代码。
小结
sp_vision_25 的四层架构可以概括为一句话:一个 main 负责调度,功能库负责算法,io 层屏蔽硬件,tools 层消除重复。这种设计让自瞄、打符、全向感知可以共存于同一台电脑,也让新人能从 tests/ 的独立测试程序切入,逐层读懂整个 RoboMaster 自瞄视觉系统。
