yolo_ros

针对 Ultralytics 提供的 YOLO 模型的 ROS 2 封装，用于执行目标检测与跟踪、实例分割、人体姿态估计以及定向边界框（OBB）任务。此外，还支持基于深度图像的目标检测、实例分割和人体姿态估计的 3D 版本。

ROS 2 发行版	分支	构建状态	Docker 镜像
Humble	main
Iron	main
Jazzy	main
Kilted	main
Rolling	main

目录

1. 安装
2. Docker
3. 模型
4. 使用
5. 生命周期节点
6. 演示

安装

cd ~/ros2_ws/src
git clone https://github.com/mgonzs13/yolo_ros.git
pip3 install -r yolo_ros/requirements.txt
cd ~/ros2_ws
rosdep install --from-paths src --ignore-src -r -y
colcon build
source ~/ros2_ws/install/setup.bash"

Docker

构建 yolo_ros 的 Docker 镜像。

docker build -t yolo_ros .

运行 Docker 容器。如果需要使用 CUDA，必须先安装 NVIDIA Container Toolkit，并在运行命令中添加 --gpus all。

docker run -it --rm --gpus all yolo_ros

模型

yolo_ros 支持以下模型：

• YOLOv3
• YOLOv4
• YOLOv5
• YOLOv6
• YOLOv7
• YOLOv8
• YOLOv9
• YOLOv10
• YOLOv11
• YOLOv12
• YOLO-World
• YOLOE

使用

ros2 launch yolo_bringup yolov5.launch.py

ros2 launch yolo_bringup yolov8.launch.py

ros2 launch yolo_bringup yolov9.launch.py

ros2 launch yolo_bringup yolov10.launch.py

ros2 launch yolo_bringup yolov11.launch.py

ros2 launch yolo_bringup yolov12.launch.py

ros2 launch yolo_bringup yolo-world.launch.py

ros2 launch yolo_bringup yoloe.launch.py

Topics

• /yolo/detections: 使用 RGB 图像由 YOLO 检测到的物体。每个物体包含一个边界框和类别名称，也可能包括标记或关键点列表。
• /yolo/tracking: 基于 YOLO 结果检测并跟踪的物体。每个物体都会被分配一个跟踪 ID。
• /yolo/detections_3d: 检测到的 3D 物体。利用 YOLO 的结果裁剪深度图像，生成 3D 边界框和 3D 关键点。
• /yolo/debug_image: 显示检测和跟踪物体的调试图像。这些图像可以通过 rviz2 进行可视化。

Parameters

以下是来自 yolo.launch.py 的参数，用于启动所有模型。更多详细信息请参阅 Ultralytics 官网。

• model_type: Ultralytics 模型类型（默认：YOLO）
• model: YOLO 模型（默认：yolov8m.pt）
• tracker: 跟踪器文件（默认：bytetrack.yaml）
• device: GPU/CUDA（默认：cuda:0）
• fuse_model: 是否融合 YOLO 模型以优化推理性能（默认：False）
• yolo_encoding: 在使用 YOLO 之前对输入图像进行编码的格式（默认：bgr8）
• enable: 是否启用 YOLO（默认：True）
• threshold: 检测阈值（默认：0.5）
• iou: 非极大值抑制 (NMS) 的交并比 (IoU) 阈值（默认：0.7）
• imgsz_height: 推理时使用的图像高度（默认：480）
• imgsz_width: 推理时使用的图像宽度（默认：640）
• half: 是否启用半精度 (FP16) 推理，以在对精度影响最小的情况下加速模型推理（默认：False）
• max_det: 每张图像允许的最大检测数量（默认：300）
• augment: 是否启用测试时增强 (TTA)，以提高检测鲁棒性，但会牺牲部分速度（默认：False）
• agnostic_nms: 是否启用类别无关的非极大值抑制 (NMS)，将不同类别的重叠框合并（默认：False）
• retina_masks: 是否使用高分辨率分割掩码（如果模型中可用），以提升分割掩码的质量（默认：False）
• input_image_topic: RGB 图像的相机话题（默认：/camera/rgb/image_raw）
• image_reliability: 图像话题的可靠性：0=系统默认，1=可靠，2=尽力而为（默认：1）
• input_depth_topic: 清晰度图像的相机话题（默认：/camera/depth/image_raw）
• depth_image_reliability: 深度图像话题的可靠性：0=系统默认，1=可靠，2=尽力而为（默认：1）
• input_depth_info_topic: 深度信息的相机话题（默认：/camera/depth/camera_info）
• depth_info_reliability: 深度信息话题的可靠性：0=系统默认，1=可靠，2=尽力而为（默认：1）
• target_frame: 用于变换 3D 框架的坐标系（默认：base_link）
• depth_image_units_divisor: 将深度图像转换为米的除数。取决于所使用的相机（默认：1000）
• use_tracking: 检测后是否激活跟踪功能（默认：True）
• use_3d: 是否激活 3D 检测功能（默认：False）
• use_debug: 是否激活调试节点（默认：True）

生命周期节点

之前的更新为包中所有节点添加了生命周期节点支持。该实现尝试通过仅在活动状态加载模型并激活订阅者来减少未配置和非活动状态下的工作负载。

以下是在 30fps 视频流上使用默认 yolov8m.pt 模型的一些资源比较。

演示

物体检测

这是 yolo_ros 的标准行为，包含物体跟踪功能。

ros2 launch yolo_bringup yolo.launch.py

实例分割

实例掩码是检测到的物体的边界，而不是掩码内部的所有像素。

ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-seg.pt

人体姿态

检测到可见的人及其骨骼关键点。

ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-pose.pt

3D 物体检测

3D 边界框是通过使用 2D 边界框从 RGB-D 相机的深度图像数据中筛选出来的。只有具有 3D 边界框的物体才会在 2D 图像中显示。

ros2 launch yolo_bringup yolo.launch.py use_3d:=True

3D 物体检测（使用实例分割掩码）

在此过程中，深度图像数据会根据实例掩码获取的最大和最小值进行筛选。只有具有 3D 边界框的物体才会在 2D 图像中显示。

ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-seg.pt use_3d:=True

3D 人体姿态

每个关键点都会投影到深度图像中，并用紫色球体表示。只有具有 3D 边界框的物体才会在 2D 图像中显示。

ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-pose.pt use_3d:=True

yolo_ros 快速上手指南

yolo_ros 是一个基于 ROS 2 的封装工具，集成了 Ultralytics 的 YOLO 系列模型。它支持目标检测、跟踪、实例分割、人体姿态估计以及带方向的目标框（OBB），并提供了基于深度图像的 3D 检测功能。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Ubuntu 20.04/22.04/24.04 (取决于 ROS 2 版本)
• ROS 2 版本: 支持 Humble, Iron, Jazzy, Kilted, Rolling 等主流发行版。
• Python: Python 3.x (通常随 ROS 2 安装)
• GPU 加速 (可选): 如需使用 CUDA 加速，请确保已安装 NVIDIA 驱动及对应的 CUDA Toolkit。
• 工作空间: 拥有一个标准的 ROS 2 工作空间 (例如 ~/ros2_ws)。

提示: 如果您在中国大陆地区，建议在安装依赖时配置国内镜像源（如清华源或阿里源）以加速下载。

2. 安装步骤

请在您的 ROS 2 工作空间源码目录下执行以下命令：

# 进入工作空间源码目录
cd ~/ros2_ws/src

# 克隆仓库
git clone https://github.com/mgonzs13/yolo_ros.git

# 安装 Python 依赖
# 建议先配置 pip 国内镜像加速，例如：
# pip3 install -r yolo_ros/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
pip3 install -r yolo_ros/requirements.txt

# 返回工作空间根目录
cd ~/ros2_ws

# 安装系统依赖
rosdep install --from-paths src --ignore-src -r -y

# 编译项目
colcon build

# 加载环境变量
source ~/ros2_ws/install/setup.bash

Docker 方式 (可选)

如果您希望使用容器化部署，特别是为了隔离环境或使用 GPU：

# 构建镜像
docker build -t yolo_ros .

# 运行容器 (如需启用 GPU，请确保已安装 NVIDIA Container Toolkit 并添加 --gpus all)
docker run -it --rm --gpus all yolo_ros

3. 基本使用

yolo_ros 提供了针对不同 YOLO 版本的启动文件。以下是最简单的启动示例。

启动默认模型 (YOLOv8)

默认情况下，工具会加载 yolov8m.pt 模型并进行目标检测与跟踪。请确保您有一个摄像头话题发布 RGB 图像（默认为 /camera/rgb/image_raw）。

ros2 launch yolo_bringup yolov8.launch.py

切换其他模型

您可以通过修改启动参数轻松切换不同的 YOLO 版本或任务类型：

• YOLOv5:

  ros2 launch yolo_bringup yolov5.launch.py
  

• 实例分割 (Segmentation):

  ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-seg.pt
  

• 人体姿态估计 (Pose):

  ros2 launch yolo_bringup yolo.launch.py model:=yolov8m-pose.pt
  

• YOLO-World (开放词汇检测):

  ros2 launch yolo_bringup yolo-world.launch.py
  

核心话题说明

启动后，您可以关注以下主要话题：

• /yolo/detections: 检测结果（包含边界框、类别、置信度）。
• /yolo/tracking: 带有追踪 ID 的目标结果。
• /yolo/debug_image: 可视化调试图像，可直接在 rviz2 中查看。
• /yolo/detections_3d: 如果启用了深度相机并设置 use_3d:=true，将输出 3D 检测结果。

常用参数调整

您可以在启动命令中通过 := 覆盖默认参数，例如指定设备或调整阈值：

# 指定使用 CPU 运行，并将检测阈值设为 0.6
ros2 launch yolo_bringup yolov8.launch.py device:=cpu threshold:=0.6

主要可用参数包括：

• model: 模型权重文件路径或名称 (默认: yolov8m.pt)
• device: 推理设备 (默认: cuda:0, 可选 cpu)
• threshold: 检测置信度阈值 (默认: 0.5)
• input_image_topic: 输入图像话题 (默认: /camera/rgb/image_raw)
• use_3d: 是否启用 3D 检测 (默认: False)