从相机到轨迹预测：羽毛球机器人视觉链路的 ROS 2 工程拆解

这篇文章整理的是一份个人羽毛球机器人项目记录，不是已经完成的机器人产品。材料来自本机维护的项目技能文档，最后标注更新时间为 2026-07-22；我没有在本轮连接设备、运行节点或检查硬件，因此下文只能描述该快照记录的设计和状态，不能代表设备在今天仍处于相同阶段。机器地址、账号、无线网络名、本机路径和其他访问细节均不公开。

先区分两类羽毛球视觉项目

离线视频分析与实时对打机器人看起来都在“追羽毛球”，工程目标却不同。离线工具可以逐帧处理完整视频，重点是可复算的数据、可视化和复盘；机器人链路必须持续接收相机帧，在有限延迟内给出位置与速度估计，还要在数据过期、检测丢失或节点退出时让执行机构进入安全状态。

本项目借鉴了 Good-Badminton 视频分析流水线复盘，但没有把它当作实时机器人程序直接复用。

从传感器到预测的分层

项目笔记把软件拆成几个相互解耦的 ROS 2 包：

相机驱动
  └─ 图像消息
       └─ 视觉节点：ONNX 羽毛球检测
            └─ 二维检测点
                 └─ 跟踪节点：卡尔曼滤波与短时预测
                      └─ 规划中的控制节点
                           └─ 未来的舵机或底盘

视觉节点的职责是把图像变成结构化观测，而不是直接控制电机。记录中的检测主路径使用 YOLO 模型的 ONNX 格式和 ONNX Runtime；HSV 阈值是推理依赖不可用时的降级检测方案。降级方案只能帮助验证消息管线是否仍工作，颜色阈值的误检率、场馆灯光敏感度和检出质量不能等同于模型推理，系统应把当前检测模式显式显示在状态信息中。

跟踪节点把带时间信息的位置观测送入二维匀速卡尔曼滤波器，维护近期轨迹，并向下游提供有限步数的匀速外推。它适合先验证“检测抖动能否被平滑、短暂漏检能否连续、轨迹能否重置”这些软件问题；它不是完整的羽毛球飞行模型。空气阻力、重力、球拍碰撞、旋转和场地边界都会让长距离匀速预测失真。

容器解决的是依赖边界，不是硬件边界

这份项目记录选择在 ARM 设备的 Linux 宿主上运行容器化 ROS 2 环境，宿主负责设备和系统维护，容器负责 ROS 发行版及节点依赖；Mac 通过远程开发方式编辑和构建工作区。这样可以避免把不受目标发行版支持的 ROS 依赖散装到宿主系统，也能把与 ROS Python ABI 绑定的库集中在容器里。

模型推理采用 ONNX Runtime 而不是在小型设备上安装完整训练框架，可以缩小部署依赖面，但不会自动解决算力、内存和延迟问题。离线安装 wheel 时，必须匹配目标 Linux 架构、Python 版本和 ABI；Mac 上能安装的 ARM wheel 不一定适用于 Linux ARM。每次模型或运行库升级，都应记录模型哈希、输入尺寸、执行提供程序、帧率和端到端耗时，而不能只凭“节点启动成功”判断实时链路达标。

容器可以隔离用户态依赖，却不会替你配置摄像头设备权限、USB 访问、视频节点、DDS 发现和网络安全。宿主网络模式会扩大节点可见的网络范围；只在可信局域网使用，并避免把 ROS/DDS 或容器管理端口直接暴露到公网。设备升级、Docker 镜像重建和电源断开也需要可恢复方案，尤其要避免把唯一存储介质当作临时缓存。

消息格式要表达单位、时间和失效状态

项目记录中的早期接口以 Float32MultiArray 传递位置、半径、时间戳、速度、有效标记和展平后的轨迹。这个做法便于快速让两个 Python 节点互通，但数组本身没有字段名；发送方和接收方必须私下约定每个下标代表什么、单位是什么、缺测如何表示。以后只要一侧插入一个字段，另一侧就可能把半径误读成速度而不报类型错误。

尤其要把以下信息写入接口说明或具名消息：

图像像素坐标还是球场平面坐标；速度单位是像素/秒、像素/帧还是米/秒。
时间戳来自相机采集时刻、消息发布时间还是节点处理时刻；所有节点使用什么时钟。
valid=false、暂时无检测、节点断连和预测超时分别如何表示。
消息对应的图像分辨率、坐标系和模型/算法版本。

当接口稳定后，应迁移到具名 ROS 消息或带 Header 的标准几何消息，并为消息版本变更留出迁移策略。控制节点还应检查样本年龄、数值是否有限、坐标是否越界；超过超时时间就停止使用预测，进入定义好的安全状态。话题上出现一个 valid 数值，不足以替代底层控制器自己的 watchdog 和急停策略。

先测数据链，再接执行器

按风险从低到高推进，比同时接入摄像头、模型和电机更容易定位问题：

用录制帧或合成点验证消息字段、坐标单位、时间顺序和无效值处理。
用录制视频回放验证检测置信度、漏检恢复、卡尔曼滤波和轨迹重置。
接入真实相机，记录实际帧率、队列延迟、丢帧、设备重连和长时间运行状态。
在没有机械动作的情况下验证控制指令限幅、过期数据拒绝、节点退出和急停。
最后才接舵机或底盘，并先在无危险的低速、限力条件下逐级测试。

本机记录把视觉和跟踪列为已有代码阶段，把控制器与一键启动包列为后续工作；同一份记录当时还注明等待相机实测。它提到过节点编译/启动测试，但没有给出当前可复核的测试日志。本轮没有重新连接设备，因此不能据此断言相机推理、跨机 DDS、真实预测精度或任何电机控制已经通过验收。下一次更新状态时，应补充带日期的构建结果、topic 实测、相机型号、丢帧/延迟统计和安全测试记录。

可复用的工程结论

将视觉、跟踪和执行器控制分包，让算法调试不需要同时承担硬件风险。
小型边缘设备优先缩小运行依赖，并核对目标架构和 Python ABI；模型优化必须用真实视频测量。
预测值只是一种短时估计。控制动作必须受数据新鲜度、范围限制、看门狗和急停约束。
先验证数据契约和故障恢复，再验证画面效果，最后接通有危险的物理执行机构。
用录制数据、日志和模型版本建立可重复实验；编译通过不等于实时性能、视觉准确率或硬件安全已通过。