sp_vision_25软件架构图解:3分钟看懂四层模块化视觉框架设计

原创2026-11-01 22:10:401,360 阅读

sp_vision_25软件架构图解:3分钟看懂四层模块化视觉框架设计

sp_vision_25 是同济大学 SuperPower 战队为 RoboMaster 25 赛季开源的 RoboMaster 视觉框架,核心功能是实现机器人自瞄(自动瞄准与火控)。整套框架采用四层模块化架构——应用层、功能层、硬件抽象层、工具层,各层职责清晰、互相解耦,新同学无需 ROS 基础即可快速上手。

sp_vision_25 自瞄视觉框架中用于打符功能的标准风扇叶识别图案

为什么需要分层:一个相机引发的架构思考

机器人上往往要同时实现多种功能:步兵需要自瞄和打符,但相机同一时间只能被一个程序打开。如果每个功能都写成一个独立程序,就会互相抢占相机,无法共存。

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 为例,主循环只做五件事:

  1. 从相机读取图像和时间戳;
  2. 用同一时间戳从 C 板取云台姿态四元数,保证图像与姿态对齐;
  3. 依次调用识别器、估计器、决策器;
  4. 把瞄准指令通过 C 板发给下位机;
  5. 根据电控档位信号在 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/ 提供跨兵种复用的基础组件,是团队协作出错率低的关键:

数据流:一帧图像穿过四层的路径

把四层串起来看,一帧图像的流动路径是:

相机线程产生图像 + 时间戳 → 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 自瞄视觉系统。

登录后查看全文
sp_vision_25