使用普通 USB 摄像头体验 Linker Hand L30/O6 实时手势同步的 ROS 2 仿真项目
点击图片播放 MediaPipe → 角度重定向 → RViz 同步演示
LinkerHand Gesture Control Sim 是一个可直接运行的视觉手势仿真项目。它让用户通过 普通 USB 摄像头快速体验 Linker Hand L30 和 O6 的实时手势同步、角度重定向与仿真 交互。
系统从摄像头获取画面，使用 MediaPipe 检测左右手关键点并计算人体关节角，再经过 左右手独立标定、角度重定向、One Euro、死区/迟滞、EMA 和速度限制，最终驱动 RViz 2 或 Gazebo Sim 中的 Linker Hand 模型。RViz 支持 L30/O6 单手，以及任意左右 型号组合；Gazebo 支持 L30/O6 单左手和单右手，并均已完成 GUI 动作验收。
项目以“优先体验 Linker Hand 实时手势同步”为核心定位。用户可以通过 RViz 2 和 Gazebo Sim 直观体验摄像头手势驱动灵巧手模型的完整过程，同时用于 ROS 2 学习、 角度映射调试和手势算法验证。项目完整覆盖摄像头采集、MediaPipe 感知、角度处理到 仿真显示的数据链路。
- 普通 USB 摄像头驱动的实时灵巧手仿真体验。
- RViz 支持 L30/O6 单手和四种左右型号组合。
- 参数式核心入口与常用组合快捷 launch 同时提供。
- Gazebo 提供 L30/O6 单左手、单右手参数式和快捷入口。
- 双手模式只打开一次摄像头，左右识别、标定、话题和 TF 完全隔离。
- 左右手使用独立的实测输入范围与机械手角度映射。
- Qt 个人标定上位机统一显示 MediaPipe 画面、检测状态和四姿态手动采样流程。
- 标定采样支持取消、独立重采、有效率检查和基于 P90-P10 的稳定度检查。
- 个人配置支持关节范围联合检查、默认目录保存、更新、另存为和外部 YAML 导入。
- Qt 可使用当前个人配置一键启动单手 RViz/Gazebo 验证，并自动交接摄像头占用。
- 调试画面支持镜像显示，不改变左右手判定和输出数据。
- 3D 关键点短时退化时回退到图像关键点，避免控制链误判丢失。
- One Euro、关节死区/迟滞、EMA 和关节速度限制。
- 目标丢失后短暂保持，并平滑返回安全开掌姿态。
- L30 左右手 URDF、mesh、RViz 2 和 Gazebo Sim 描述包。
- O6 左右手官方 URDF、mesh、六主动自由度 profile 和 RViz/Gazebo 描述适配。
- Gazebo 视觉同步与 60 Hz 实际关节状态反馈。
- Gazebo 输入完整性检查、关节限速和左右手独立模型参数校正。
- Gazebo 默认掌心近景、柔和环境光以及自定义
world覆盖入口。 - 中文源码注释、中文运行日志以及中英双语项目文档。
flowchart LR
CAM[USB Camera] --> IMG["/usb_camera/image_raw"]
IMG --> MPL[MediaPipe Left]
IMG --> MPR[MediaPipe Right]
MPL --> FL[One Euro Filter]
MPR --> FR[One Euro Filter]
FL --> RL[Left Retargeting]
FR --> RR[Right Retargeting]
RL --> TL["/left/linkerhand/target_joint_states"]
RR --> TR["/right/linkerhand/target_joint_states"]
TL --> RVIZ[RViz 2 Adapter]
TR --> RVIZ
TL --> GZA[Gazebo Trajectory Adapter]
TR --> GZA
GZA --> GZP[Online Joint Plugin]
GZP --> GZ[Gazebo Sim]
GZ --> JS[60 Hz Joint States]
摄像头 -> MediaPipe -> One Euro -> 人体关节角 -> 左右手标定映射
-> 死区/迟滞 + EMA + 限速 -> RViz 2 或 Gazebo Sim
- Ubuntu 22.04
- ROS 2 Humble
- Python 3.10
- MediaPipe、OpenCV、NumPy
- 可用的
/dev/video*USB 摄像头 - RViz 2
- Gazebo Sim 6、
ros_gz_sim和ros_gz_bridge（运行 Gazebo 模式时）
git clone https://github.com/2303886347/linkerhand_gesture_control_sim.git \
~/linkerhand_ros2_ws
cd ~/linkerhand_ros2_ws
source /opt/ros/humble/setup.bash
rosdep install --from-paths src --ignore-src -r -y
python3 -m pip install 'mediapipe==0.10.9'
colcon build --symlink-install
source install/setup.bash准备电脑、USB 摄像头和 ROS 2 图形环境后，即可运行完整手势仿真链路。
| 显示端 | 模式 | 命令 |
|---|---|---|
| 标定 | Qt 个人标定上位机 | ros2 launch linkerhand_bringup calibration_gui.launch.py |
| RViz 2 | 任意双手组合 | ros2 launch linkerhand_bringup mediapipe_rviz.launch.py left_model:=l30 right_model:=o6 |
| RViz 2 | 参数式单手 | ros2 launch linkerhand_bringup mediapipe_rviz_single.launch.py model_id:=o6 side:=left |
| RViz 2 | L30 左手 | ros2 launch linkerhand_retargeting mediapipe_rviz_left.launch.py |
| RViz 2 | L30 右手 | ros2 launch linkerhand_retargeting mediapipe_rviz_right.launch.py |
| RViz 2 | O6 左手 | ros2 launch linkerhand_retargeting mediapipe_rviz_o6_left.launch.py |
| RViz 2 | O6 右手 | ros2 launch linkerhand_retargeting mediapipe_rviz_o6_right.launch.py |
| Gazebo Sim | L30 左手 | ros2 launch linkerhand_gazebo_control mediapipe_gazebo_left.launch.py |
| Gazebo Sim | L30 右手 | ros2 launch linkerhand_gazebo_control mediapipe_gazebo_right.launch.py |
| Gazebo Sim | O6 左手 | ros2 launch linkerhand_bringup mediapipe_gazebo_o6_left.launch.py |
| Gazebo Sim | O6 右手 | ros2 launch linkerhand_bringup mediapipe_gazebo_o6_right.launch.py |
双手模式默认每侧以 10 FPS 运行一个 MediaPipe 实例。CPU 余量充足时可以提高：
ros2 launch linkerhand_bringup mediapipe_rviz.launch.py \
left_model:=l30 right_model:=o6 \
processing_fps:=12.0更完整的设备检查、参数解释、标定范围、滤波调节和故障排查见 GUIDE.md。
Gazebo 入口会同时打开 MediaPipe 预览和 Gazebo GUI。摄像头不是 /dev/video0 时，
在任意启动命令后追加 device:=/dev/video2。默认 world 会以掌心方向的近景打开；
如需自己的场景，可追加 world:=/absolute/path/to/custom.sdf。
| 包 | 作用 | 文档 |
|---|---|---|
usb_camera_demo |
打开 USB 摄像头并发布 ROS 2 图像 | README |
hand_pose_msgs |
定义手部关键点和语义关节角消息 | README |
mediapipe_hand_pose |
MediaPipe 检测、骨架显示和 One Euro 滤波 | README |
linkerhand_bringup |
L30/O6 参数式和快捷多型号启动入口 | README |
linkerhand_model_profiles |
统一校验型号、手侧、关节、限位和描述包 | README |
linkerhand_calibration |
Qt 手动标定、质量检查和个人 YAML 档案 | README |
linkerhand_retargeting |
标定映射、EMA、限速、回零和双手 RViz | README |
linkerhand_l30_left_description |
L30 左手 URDF、mesh、RViz/Gazebo 启动 | README |
linkerhand_l30_right_description |
L30 v6 右手 URDF、mesh、RViz/Gazebo 启动 | README |
linkerhand_o6_left_description |
O6 左手官方 URDF、mesh 和 RViz 启动 | README |
linkerhand_o6_right_description |
O6 右手官方 URDF、mesh 和 RViz 启动 | README |
linkerhand_gazebo_control |
轨迹适配、动态 URDF、状态节流和 Gazebo 启动 | README |
linkerhand_gazebo_plugin |
Gazebo 在线多关节运动学位置同步插件 | README |
main 是完整、稳定的项目基线，包含所有已交付功能。以下分支用于突出对应演示入口，
核心代码仍从 main 同步，避免左右手实现分叉。
| 分支 | 用途 |
|---|---|
main |
完整稳定版本 |
left-hand |
左手演示配置 |
right-hand |
右手演示配置 |
both-hands |
双手演示配置 |
手势链路不是简单的固定低通，而是四层稳定化处理：
- One Euro 对调试骨架关键点和人体关节角进行自适应滤波。
- 关节死区与迟滞锁住静止小噪声，并在真实动作越过启动阈值后恢复跟随。
- EMA 对消抖后的机械手目标再次平滑。
- 速度限制抑制异常的大幅跳变，并单独控制目标丢失后的回零速度。
同一套稳定化结果同时供 RViz 和 Gazebo 使用，因此两种显示端具有一致的动作响应。
推荐从以下参数开始调整静止抖动：
ros2 launch linkerhand_bringup mediapipe_rviz.launch.py \
left_model:=l30 right_model:=o6 \
one_euro_min_cutoff:=0.5 \
one_euro_beta:=0.4cd ~/linkerhand_ros2_ws
source /opt/ros/humble/setup.bash
source install/setup.bash
colcon test
colcon test-result --verbose当前验证基线：176 tests, 0 errors, 0 failures, 0 skipped。
- USB 摄像头 ROS 2 图像发布
- MediaPipe 左右手关键点与关节角
- 左手、右手、双手 RViz 同步
- L30/O6 型号 profile 与 O6 六主动自由度重定向
- L30/O6 任意左右组合和统一 bringup 入口
- 独立标定、One Euro、EMA 和回零限速
- 可配置的左右手独立关节死区与迟滞消抖
- Gazebo 单左手、单右手运动学位置反馈同步
- O6 左右手 Gazebo 控制链与 GUI 动作验收
- Qt 四姿态手动采样、取消/重采与采样质量检查
- Qt 个人配置生成、更新/另存为、导入和配置档案
- Qt 一键 RViz/Gazebo 验证、摄像头交接与进程清理
- L30/O6 左右手 RViz/Gazebo 实际画面、方向、动作与稳定性现场验收
以上功能构成项目的完整交付范围。项目专注于“普通摄像头驱动灵巧手仿真显示”，适合 手势可视化、ROS 2 学习、角度映射调试和交互演示。Gazebo 使用运动学位置反馈同步； 面向接触物理的应用可以在现有接口上扩展简化碰撞体和 effort 控制器。
提交代码前请阅读 CONTRIBUTING.md。问题报告请包含 ROS 2 版本、 摄像头设备、启动命令、终端日志以及可复现步骤。
仓库采用包级许可证：自主开发的 ROS 2/Python 包声明为 Apache-2.0，左右手模型描述包
声明为 BSD-3-Clause。各目录中的 package.xml 是对应包许可证的权威来源。模型和
mesh 的使用还应遵循原始 Linker Hand 资源的授权与署名要求。