# unitree_go2_ros2

**Repository Path**: tryhardjackma/unitree_go2_ros2

## Basic Information

- **Project Name**: unitree_go2_ros2
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Unitree Go2 RGB-D Person Following

基于 ROS 2 Jazzy 和 Gazebo Harmonic 的 Unitree Go2 视觉人物跟随仿真。
系统仅使用前置 RGB-D 相机和机器人本体 IMU，实现人物检测、单目标跟踪、
距离控制和视觉避障，不依赖激光雷达、SLAM、Nav2 或额外传感器。

## 功能

- Gazebo Harmonic 中的 Unitree Go2 四足机器人仿真
- CHAMP 步态控制和 `ros2_control` 关节控制
- 对齐的 RGB 图像、深度图像、点云和相机内参
- YOLOv8 人物检测及检测画面显示
- OSTrack 单目标跟踪，支持 YOLO 自动初始化和鼠标手动框选
- 基于目标框深度的前进、后退和转向控制
- 基于 RGB-D 相机左、中、右深度区域的障碍物避让
- IMU 倾倒保护、目标丢失停车和传感器超时停车
- 开放测试场、4 个障碍物和 `5 x 5 m` 移动人物矩形轨迹

## 工作空间

```text
src/
├── champ/                       CHAMP 核心库
├── champ_base/                  四足机器人运动与状态估计
├── champ_msgs/                  CHAMP 消息定义
├── unitree_go2_description/     Go2 URDF、模型、RGB-D 相机和 Gazebo 世界
├── unitree_go2_sim/             仿真启动、控制器和移动人物插件
├── go2_yolov8_detector/         YOLOv8 人物检测
├── go2_ostrack_tracker/         OSTrack 单目标跟踪
└── go2_visual_follower/         RGB-D 人物跟随和视觉避障
```

## 环境要求

- Ubuntu 24.04
- ROS 2 Jazzy
- Gazebo Harmonic
- Python 3.12（ROS 系统 Python）
- 支持 CUDA 的 NVIDIA GPU（推荐，CPU 也可运行）

退出 Conda 后安装 ROS 依赖：

```bash
conda deactivate
sudo apt update
sudo apt install \
  python3-pip \
  ros-jazzy-cv-bridge \
  ros-jazzy-gz-ros2-control \
  ros-jazzy-joint-state-broadcaster \
  ros-jazzy-joint-trajectory-controller \
  ros-jazzy-ros-gz \
  ros-jazzy-rviz2 \
  ros-jazzy-teleop-twist-keyboard \
  ros-jazzy-vision-msgs \
  ros-jazzy-xacro
```

安装视觉算法依赖：

```bash
cd ~/unitree_go2_ros2
/usr/bin/python3 -m pip install --user --break-system-packages \
  -r src/go2_yolov8_detector/requirements.txt \
  -r src/go2_ostrack_tracker/requirements.txt
```

## 模型权重

模型权重不提交到 Git 仓库。运行前准备：

```text
src/go2_yolov8_detector/weights/yolov8n.pt
src/go2_ostrack_tracker/weights/OSTrack_ep0300.pth.tar
```

YOLOv8 在本地没有打包权重时会尝试通过 Ultralytics 获取
`yolov8n.pt`。OSTrack 权重需要手动下载并放入上述目录，也可以在启动时通过
`checkpoint_path:=/absolute/path/to/OSTrack_ep0300.pth.tar` 指定。

## 编译

```bash
cd ~/unitree_go2_ros2
conda deactivate
source /opt/ros/jazzy/setup.bash
colcon build --symlink-install
source install/setup.bash
```

## 启动

终端 1，启动 Gazebo、Go2、RGB-D 相机和移动人物：

```bash
cd ~/unitree_go2_ros2
conda deactivate
source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 launch unitree_go2_sim unitree_go2_launch.py rviz:=false
```

终端 2，启动 YOLOv8、OSTrack 和视觉跟随控制：

```bash
cd ~/unitree_go2_ros2
conda deactivate
source /opt/ros/jazzy/setup.bash
source install/setup.bash
ros2 launch go2_visual_follower person_following.launch.py
```

首次测试建议禁用运动，只验证检测和跟踪：

```bash
ros2 launch go2_visual_follower person_following.launch.py enabled:=false
```

无图形界面运行：

```bash
ros2 launch go2_visual_follower person_following.launch.py \
  tracker_viewer:=false
```

## 控制服务

```bash
# 停止机器人跟随
ros2 service call /visual_follower/enable \
  std_srvs/srv/SetBool "{data: false}"

# 开启机器人跟随
ros2 service call /visual_follower/enable \
  std_srvs/srv/SetBool "{data: true}"

# 清除 OSTrack 目标，等待手动框选
ros2 service call /ostrack/reset std_srvs/srv/Trigger "{}"

# 恢复 YOLO 自动选择人物
ros2 service call /ostrack/enable_auto_initialization \
  std_srvs/srv/Trigger "{}"
```

OSTrack 窗口中可以按住鼠标左键框选目标。按 `A` 恢复 YOLO 自动选择，
按 `R` 清除目标，按 `Q` 或 `Esc` 关闭窗口。

## 主要话题

| 话题 | 类型 | 用途 |
| --- | --- | --- |
| `/camera/color/image_raw` | `sensor_msgs/Image` | RGB 图像 |
| `/camera/depth/image_raw` | `sensor_msgs/Image` | 对齐深度图 |
| `/camera/depth/points` | `sensor_msgs/PointCloud2` | RGB-D 点云 |
| `/camera/camera_info` | `sensor_msgs/CameraInfo` | 相机内参 |
| `/imu/data` | `sensor_msgs/Imu` | 本体姿态 |
| `/yolo/detections` | `vision_msgs/Detection2DArray` | YOLO 检测结果 |
| `/yolo/annotated_image` | `sensor_msgs/Image` | YOLO 标注画面 |
| `/ostrack/tracking` | `vision_msgs/Detection2D` | 当前跟踪框 |
| `/ostrack/annotated_image` | `sensor_msgs/Image` | OSTrack 标注画面 |
| `/visual_follower/status` | `std_msgs/String` | JSON 控制状态 |
| `/cmd_vel` | `geometry_msgs/Twist` | Go2 运动命令 |

## 安全行为

以下情况会发布零速度命令：

- OSTrack 未初始化或目标丢失
- RGB-D、跟踪结果或 IMU 消息超时
- 目标深度无效或距离过近
- 机器人横滚或俯仰超过限制
- 用户通过服务禁用跟随

控制参数位于
`src/go2_visual_follower/config/visual_follower.yaml`。

## 仿真场景

默认世界是 `30 x 30 m` 开放地面，包含 4 个相机可见障碍物。人物沿
`5 x 5 m` 矩形闭环以约 `0.10 m/s` 运动，启动后等待 20 秒再开始移动，
为 YOLO 和 OSTrack 留出初始化时间。

- 世界配置：`src/unitree_go2_description/worlds/default.sdf`
- 人物配置：`src/unitree_go2_description/models/person_target/model.sdf`
- 移动插件：`src/unitree_go2_sim/src/moving_person_system.cpp`

## 开发记录

项目变更历史和验证结果记录在 [log.md](log.md)。每次修改代码、配置、
依赖或仿真场景后，都应在该文件顶部增加一条记录。