DepthAI ROS驱动程序

版本说明

此页面涵盖 ROS v3 驱动程序。

Humble / Jazzy: ROS包名称使用 _v3 后缀，例如 depthai_ros_driver_v3 和 Debian 包 ros-$ROS_DISTRO-depthai-ros-v3。
Kilted 及更新版本: v3 是默认驱动程序，因此包名称没有后缀，例如 depthai_ros_driver 和 Debian 包 ros-$ROS_DISTRO-depthai-ros。

如果您想在 ROS apt 仓库同步稳定版本之前获取最新的 Humble/Jazzy ROS 二进制文件，请启用 ROS 测试仓库。

快速入门

经典安装

安装 ROS 后，安装与您的发行版匹配的 DepthAI ROS 包。

Humble/Jazzy

Command Line

1sudo apt install ros2-testing-apt-source
2sudo apt update
3sudo apt install ros-$ROS_DISTRO-depthai-ros-v3

使用以下命令运行驱动程序：

Command Line

1ros2 launch depthai_ros_driver_v3 driver.launch.py

要在 RViz 中可视化数据：

Command Line

1ros2 launch depthai_ros_driver_v3 driver.launch.py use_rviz:=true

要将可组合驱动程序包作为单独的节点运行：

Command Line

1ros2 run depthai_ros_driver_v3 driver_node

Kilted and newer

Command Line

1sudo apt install ros-$ROS_DISTRO-depthai-ros

使用以下命令运行驱动程序：

Command Line

1ros2 launch depthai_ros_driver driver.launch.py

要在 RViz 中可视化数据：

Command Line

1ros2 launch depthai_ros_driver driver.launch.py use_rviz:=true

要将可组合驱动程序包作为单独的节点运行：

Command Line

1ros2 run depthai_ros_driver driver_node

use_rviz:=true 将适用于所有使用 driver.launch.py 的启动文件。

请注意，此启动文件针对 OAK-D 系列设备，对于具有不同配置的设备（如 OAK-D-PoE-SR 或 OAK-FFC），您可能需要使用不同的启动文件或参数组合。每个启动文件都在其自己的可组合节点容器中启动 ROS 驱动程序作为可组合节点。

预构建的 Docker 镜像

您也可以使用我们预构建的 Docker 镜像，虽然它们主要用于测试和调试，但可以作为不同项目版本之间的参考点。它们还可以用于在不同的 ROS 版本之间发布数据。例如，在 Kilted 容器中运行的驱动程序的数据应该可以在使用 Jazzy 发行版的主机上访问（尽管此功能取决于发行版之间的差异，可能并非在所有情况下都有效）。要运行带有 Rviz 支持的驱动程序，您需要先运行以下命令，以便生成 GUI 窗口。

Command Line

1xhost +local:docker

然后，像在构建文章中描述的那样运行容器。

Command Line

1docker run -it -v /dev/:/dev/ --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix luxonis/depthai-ros:kilted-latest

将运行一个交互式 Docker 会话。您也可以尝试：

Command Line

1docker run -it -v /dev/:/dev/  --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix luxonis/depthai-ros:kilted-latest [CMD]

要运行特定版本的容器，您可以使用 v{VERSION}-kilted，其中版本格式为 x.x.x，如下所示：

Command Line

1docker run -it -v /dev/:/dev/ --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix luxonis/depthai-ros:v3.0.9-kilted

我们还提供 ARM64 的容器，它们的名称略有不同，但用法相同。

Command Line

1docker run -it -v /dev/:/dev/ --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix luxonis/depthai-ros:kilted-arm64-latest

Command Line

1docker run -it -v /dev/:/dev/ --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix luxonis/depthai-ros:v3.0.9-kilted-arm64

您也可以将外部 YAML 文件作为驱动程序的配置传递。您可以直接在容器内编辑它们，或者在主机上创建一个 .yaml 文件（例如 /home/YOUR_USERNAME_HERE/params/example_config.yaml），然后将其作为参数传递给可执行文件，如下所示：

Command Line

1docker run -it -v /dev/:/dev/ -v /home/YOUR_USERNAME_HERE/params:/params --network host --privileged -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix depthai-ros ros2 launch depthai_ros_driver driver.launch.py params_file:=/params/example_config.yaml

参数

完整参数列表可在此处找到。

启动文件

driver.launch.py 以 RGBD 模式启动相机，并以空间模式（使用 Yolo V6）启动 NN。
rgbd_pcl.launch.py 以基本的 RGBD 配置启动相机，不加载任何 NN。还加载用于 RGBD 点云的 ROS 深度处理节点。
example_multicam.launch.py 同时启动多个相机，每个相机都在不同的容器中。编辑 config 目录中的 multicam_example.yaml 配置文件以更改参数（目前仅适用于 RVC2）。
example_segmentation.launch.py 以 RGBD + 语义分割模式启动相机（管道类型=RGBD，nn_type=rgb）。
pointcloud.launch.py - 类似于 rgbd_pcl.launch.py，但不使用 RGB 组件进行点云处理。注意，这里的点云发布在不同的主题上。
rtabmap.launch.py 启动相机和 RTAB-MAP RGBD SLAM（您需要先安装它 - sudo apt install ros-$ROS_DISTRO-rtabmap-ros）。您可能需要通过参数手动设置焦点。
sr_rgbd_pcl.launch.py - 由于只有两个传感器，应将其用作 SR 相机的基线。
sr_poe_rgbd_pcl.launch.py - 应将其用作 SR PoE 相机的基线。
oak_t.launch.py - 专为 OAK-T 系列设计的启动文件。
calibration.launch.py - 用于启动 ROS 校准工具，这主要用于测试。如果您发现相机校准无效，请使用我们的内部校准工具或直接联系我们。
vio.launch.py - 默认启用 VIO 管道来启动相机。

从外部参数发布 TF

帧默认名称：

parent_frame: "oak_parent_frame"
base_frame: "oak"（或节点名称）

在驱动程序中，所有帧都以节点名称作为前缀，以便在使用多个相机时更容易区分，例如 oak_imu_frame。默认情况下，相机变换是根据设备的相机校准数据发布的。当使用 driver.launch.py 时，您可以设置 pass_tf_args_as_params:=true，以便 TF 参数用于填充这些参数。例如

ros2 launch depthai_ros_driver driver.launch.py pass_tf_args_as_params:=true parent_frame:=map cam_pos_x:=1.0 imu_from_descr:=true

。还可以使用 driver.i_tf_custom_urdf_path 和 driver.i_tf_custom_xacro_args 设置自定义 URDF 路径（目前仅支持绝对路径）和自定义 xacro 参数。请注意，robot_state_publisher 必须正在运行。

关于外部参数的说明

如果您的相机具有未校准的 IMU，将显示警告，并且 IMU 将以零旋转和零平移发布。您可以设置 driver.i_tf_imu_from_descr: true 来覆盖此行为。这将根据相机型号从 URDF 发布默认 IMU 外部参数。

自定义管道

由于所有类型都定义为插件，因此也可以创建自定义管道。为此，您可以创建一个自定义包（例如 dai_ros_plugins），在该包中创建一个可执行文件（dai_ros_plugins.cpp）。在该文件中，定义一个继承自 depthai_ros_driver::pipeline_gen::BasePipeline 并重写 createPipeline 方法的自定义插件。例如

C++

1std::vector<std::unique_ptr<depthai_ros_driver::dai_nodes::BaseNode>> DaiRosPlugins::createPipeline(
2    std::shared_ptr<rclcpp::Node> node,
3    std::shared_ptr<dai::Device> device,
4    std::shared_ptr<dai::Pipeline> pipeline,
5    std::shared_ptr<depthai_ros_driver::param_handlers::PipelineGenParamHandler> ph,
6    const std::string& deviceName,
7    bool rsCompat,
8    const std::string& /*nnType*/) {
9    namespace dai_nodes = depthai_ros_driver::dai_nodes;
10    std::vector<std::unique_ptr<dai_nodes::BaseNode>> daiNodes;
11    auto left = std::make_unique<dai_nodes::SensorWrapper>("left", node, pipeline, deviceName, rsCompat, dai::CameraBoardSocket::CAM_B);
12    auto right = std::make_unique<dai_nodes::SensorWrapper>("right", node, pipeline, deviceName, rsCompat, dai::CameraBoardSocket::CAM_C);
13    daiNodes.push_back(std::move(left));
14    daiNodes.push_back(std::move(right));
15    return daiNodes;
16}

之后导出插件，例如：

C++

1#include <pluginlib/class_list_macros.hpp>
2
3PLUGINLIB_EXPORT_CLASS(dai_ros_plugins::DaiRosPlugins, depthai_ros_driver::pipeline_gen::BasePipeline)

在包内的 plugins.xml 文件中添加插件定义：

Xml

1<library path="dai_ros_plugins">
2  <class type="dai_ros_plugins::DaiRosPlugins" base_class_type="depthai_ros_driver::pipeline_gen::BasePipeline">
3    <description>This is a square plugin.</description>
4  </class>
5</library>

现在您可以将创建的插件用作管道，只需将 pipeline_gen.i_pipeline_type 设置为 test_plugins::Test 即可。您可以在我们的应用示例中查看包含插件的最终软件包的外观。

特定相机配置

PoE 相机

由于 PoE 相机使用的协议吞吐量低于 USB，因此运行默认驱动程序启动可能会导致延迟，具体取决于所选的分辨率/帧率。为了解决此问题，您可以使用编码帧，这可以让您在图像质量因压缩而降低的情况下保持所需的分辨率/帧率。另一个不同之处在于，此模式下禁用了 subpixel 深度过滤。要启用低带宽，例如用于 RGB 相机，请更改参数：

rgb.i_low_bandwidth - 设置为 true 以启用
rgb.i_low_bandwidth_quality - 所需的质量百分比（默认为 50）请参阅 low_bandwidth.yaml 文件，其中包含所有流的示例参数。

ToF 相机

OAK-D-SR-PoE 由于其特定配置，需要一个单独的启动文件 - sr_poe_rgbd_pcl.launch.py。该文件还利用了 OAK-D-SR 特定的管道配置，您可以在上方找到有关管道类型的更多信息。请注意，目前 ToF 相机会由于传感器插槽命名约定而以 rgb 帧发布图像。

停止/启动相机以节省电量/重新配置

停止相机也可用于节省电量，因为管道已从设备中移除。主题在相机停止时也会被移除。还有一个选项可以在相机遇到错误时启用自动重启。为此，请设置 pipeline_gen.i_enable_diagnostics: true driver.i_restart_on_diagnostics_error: true

RealSense 兼容性

为了进行快速集成测试，您可以使用 driver.launch.py 并带有 rs_compat:=true 参数来模拟 Realsense 相机行为。这将使用 RGBD 管道设置相机，并发布与 Realsense 相机兼容的主题名称。 TF 坐标系也将以 Realsense 格式提供。类似于 RS 节点的工作方式，您可以使用 pointcloud.enable:=true 参数启用点云发布。请注意，驱动程序将以不同的名称和命名空间以及不同的 DAI 节点名称启动，因此您可能需要相应地调整配置文件。命名约定如下：

命名空间：'' -> camera
节点名称：oak -> camera
rgb -> color
stereo -> depth
'left' -> infra_2
'right' -> infra_1
坐标系 oak -> camera_link

示例

让我们看一下启动文件需要进行的更改：

Python

1# 包含 RealSense 驱动程序的示例
2rs_camera_launch_include = IncludeLaunchDescription(
3  PythonLaunchDescriptionSource([
4      PathJoinSubstitution([
5          FindPackageShare('realsense2_camera'),
6          'launch',
7          'rs_launch.py',
8      ])
9  ]),
10  launch_arguments={
11      'pointcloud.enable': true,
12  }.items()
13)

以下启动描述将以 RGBD 模式运行相机驱动程序，并启用点云。现在要调整为使用 OAK 相机，您需要进行以下更改：

Python

1# 包含 OAK 驱动程序的示例
2oak_driver_launch_include = IncludeLaunchDescription(
3  PythonLaunchDescriptionSource([
4      PathJoinSubstitution([
5          FindPackageShare('depthai_ros_driver'),
6          'launch',
7          'driver.launch.py',
8      ])
9  ]),
10  launch_arguments={
11      'rs_compat': true,
12      'pointcloud.enable': true,
13  }.items()
14)

这将以相同的主题启动相机，唯一的变化是深度的默认配置文件是从 1280x720x30 变为 848x480x30。

RTABMap 示例与 RealSense 兼容性

让我们看一下 rtabmap_ros 包中的一个示例，realsense_d435i_color.launch.py。注意此示例在此时（2024-08-27）需要针对 RS 主题名称进行调整，如下所示：

之前

Python

1remappings=[
2('imu', '/imu/data'),
3('rgb/image', '/camera/color/image_raw'),
4('rgb/camera_info', '/camera/color/camera_info'),
5('depth/image', '/camera/realigned_depth_to_color/image_raw')]

之后

Python

1remappings=[
2('imu', '/imu/data'),
3('rgb/image', '/camera/camera/color/image_raw'),
4('rgb/camera_info', '/camera/camera/color/camera_info'),
5('depth/image', '/camera/camera/depth/image_rect_raw')]

现在要使用 RS 相机启动示例，根据说明，您需要运行以下命令：

Command Line

1ros2 launch realsense2_camera rs_launch.py enable_gyro:=true enable_accel:=true unite_imu_method:=1 enable_sync:=true

要使用 OAK 相机启动相同的示例，您需要运行以下命令：

Command Line

1ros2 launch depthai_ros_driver driver.launch.py rs_compat:=true

请注意，ROS2 节点的推荐方法是使用组件来提高性能并减少延迟。 RS 相机驱动程序不提供用于在组件容器中运行相机节点的专用启动文件（intra_process_demo 除外），因此您需要为此创建一个自定义容器。 DepthAI ROS 驱动程序的默认启动文件默认在组合模式下运行，因此您可以在运行时向同一容器添加更多节点。您还可以参考 depthai_ros_driver 包中的 rtabmap.launch.py 示例，以使用 OAK 相机运行 RTABMap。您还可以进行一些小的修改以启用此示例的 RS 模式。

重新校准

如果您想使用设备提供的校准值以外的其他校准值，可以通过以下方式进行：

使用每个图像流可用的 set_camera_info 服务
使用 i_calibration_file 参数指向校准文件。注意相机名称必须以 / 开头，例如 /rgb。请参阅 depthai_ros_driver/config/calibration 获取示例校准文件。提供了 calibration.launch 文件来启动单目和立体配置中的 ROS 相机校准器节点。校准文件语法（来自 camera_info_manager）：

Yaml

1- file:///full/path/to/local/file.yaml
2- file:///full/path/to/videre/file.ini
3- package://camera_info_manager/tests/test_calibration.yaml
4- package://ros_package_name/calibrations/camera3.yaml

开发人员指南

为了在隔离的工作空间中更轻松地进行开发，可以使用 Visual Studio Code 配合 DevContainers 插件。操作步骤如下：

创建一个单独的工作空间
将存储库克隆到 src 目录
将 .devcontainer 目录复制到主工作空间目录
在 VSCode 中打开工作空间目录

本页目录

DepthAI ROS驱动程序View as Markdown

快速入门

经典安装

Humble/Jazzy

Kilted and newer

预构建的 Docker 镜像

参数

启动文件

从外部参数发布 TF

自定义管道

特定相机配置

PoE 相机

ToF 相机

停止/启动相机以节省电量/重新配置

RealSense 兼容性

示例

RTABMap 示例与 RealSense 兼容性

之前

之后

重新校准

开发人员指南

DepthAI ROS驱动程序