此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 快速入门
  • 经典安装
  • 预构建 Docker 镜像
  • 参数
  • 启动文件
  • 从外参发布 TF
  • 自定义管道
  • 特定摄像头配置
  • ToF 摄像头
  • 停止/启动摄像头以节省电量/重新配置
  • RealSense 兼容性
  • 示例
  • 带有 RealSense 兼容性的 RTABMap 示例
  • 重新校准
  • 开发者指南
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

DepthAI 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 及更高版本

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 版本之间发布数据。即,在 Kitled 容器中运行的驱动程序的数据应该可以在使用 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还可以设置自定义 URDF 路径(目前只支持绝对路径)和自定义 xacro 参数,使用 driver.i_tf_custom_urdf_path 和 driver.i_tf_custom_xacro_args。请注意,robot_state_publisher 必须正在运行。

自定义管道

由于所有类型都定义为插件,因此也可以创建自定义管道。为此,您可以创建一个自定义包(例如 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>这是一个方形插件。</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。

带有 RealSense 兼容性的 RTABMap 示例

让我们看看 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

开发者指南

为了在隔离工作区中更轻松地进行开发,可以使用带有 DevContainers 插件的 Visual Studio Code,为此:
  • 创建单独的工作区
  • 将仓库克隆到 src
  • 将 .devcontainer 目录复制到主工作区目录
  • 在 VSCode 中打开工作区目录