# orbbec_camera

## [![stable](http://badges.github.io/stability-badges/dist/stable.svg)](http://github.com/badges/stability-badges) ![version](https://img.shields.io/badge/version-1.5.2-green)

**请注意：本文档为机器翻译，仅供参考。翻译可能存在遗漏或错误，且不会及时更新。请以英文原文为准。**

OrbbecSDK ROS 2 是一个用于 Orbbec 3D 相机的 ROS 2 环境无缝集成的包装器。它支持 ROS 2 Foxy、Galactic 和 Humble 版本。

## 安装说明

安装 ROS 2

- 请参考官方的 [ROS 2 安装指南](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html)

> 如果您的 ROS 2 命令没有自动补全，请将以下两行放入您的 `.bashrc` 或 `.zshrc` 中


```bash
eval "$(register-python-argcomplete3 ros2)"
eval "$(register-python-argcomplete3 colcon)"

创建 colcon 工作区

mkdir -p ~/ros2_ws/src

获取源代码

cd ~/ros2_ws/src
git clone https://github.com/orbbec/OrbbecSDK_ROS2.git

安装 deb 依赖项

# 假设您已经 source 了 ROS 环境，下同
sudo apt install libgflags-dev nlohmann-json3-dev libgoogle-glog-dev \
ros-$ROS_DISTRO-image-transport ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \
ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs

安装 udev 规则

cd  ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger

入门

cd ~/ros2_ws/
# 构建 Release 版本，默认为 Debug
colcon build --event-handlers  console_direct+  --cmake-args  -DCMAKE_BUILD_TYPE=Release

启动相机节点

• 在终端 1 中

. ./install/setup.bash
ros2 launch orbbec_camera astra.launch.py # 或者其他启动文件，参见下表

• 在终端 2 中

. ./install/setup.bash
rviz2

选择要显示的主题

• 列出主题 / 服务 / 参数（在终端 3 中）

ros2 topic list
ros2 service list
ros2 param list

• 获取设备信息

ros2 service call /camera/get_device_info orbbec_camera_msgs/srv/GetDeviceInfo '{}'

• 获取 SDK 版本

ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'

• 获取曝光

ros2 service call /camera/get_color_exposure orbbec_camera_msgs/srv/GetInt32 '{}'

如果您查看的是 ir 或 depth，请将 /camera/get_color_exposure 改为 /camera/get_ir_exposure 或 /camera/get_depth_exposure，下同。

• 获取增益

ros2 service call /camera/get_color_gain orbbec_camera_msgs/srv/GetInt32 '{}'

• 获取白平衡

ros2 service call /camera/get_white_balance orbbec_camera_msgs/srv/GetInt32 '{}'

• 设置自动曝光

ros2 service call /camera/set_color_auto_exposure std_srvs/srv/SetBool '{data: false}'

• 设置白平衡

ros2 service call /camera/set_white_balance orbbec_camera_msgs/srv/SetInt32 '{data: 4600}'

• 设置激光器启用

ros2 service call  /camera/set_laser_enable std_srvs/srv/SetBool "{data: true}"

• 切换传感器

ros2 service call /camera/toggle_ir std_srvs/srv/SetBool "{data : true}"

• 保存点云

ros2 service call /camera/save_point_cloud std_srvs/srv/Empty "{}"

所有可用的相机控制服务

以下服务的名称已经表明了它的功能。但是，需要注意的是，相应的 set_[ir|depth|color]* 和 get[ir|depth|color]* 服务只有在启动文件的对应流的参数中将 enable[ir|depth|color] 设置为 true 时才可用。

• /camera/get_auto_white_balance
• /camera/get_color_exposure
• /camera/get_color_gain
• /camera/get_depth_exposure
• /camera/get_depth_gain
• /camera/get_device_info
• /camera/get_ir_exposure
• /camera/get_ir_gain
• /camera/get_ldp_status
• /camera/get_sdk_version
• /camera/get_white_balance
• /camera/set_auto_white_balance
• /camera/set_color_auto_exposure
• /camera/set_color_exposure
• /camera/set_color_gain
• /camera/set_depth_auto_exposure
• /camera/set_depth_exposure
• /camera/set_depth_gain
• /camera/set_fan_work_mode
• /camera/set_floor_enable
• /camera/set_ir_auto_exposure
• /camera/set_ir_exposure
• /camera/set_ir_gain
• /camera/set_laser_enable
• /camera/set_ldp_enable
• /camera/set_white_balance
• /camera/toggle_color
• /camera/toggle_depth
• /camera/toggle_ir

所有可用的话题

• /camera/color/camera_info : 彩色相机信息。
• /camera/color/image_raw: 彩色流图像。
• /camera/depth/camera_info: 深度流图像。
• /camera/depth/image_raw: 深度流图像。
• /camera/depth/points : 点云，仅在 enable_point_cloud 为 true 时可用。
• /camera/depth_registered/points: 彩色点云，仅在 enable_colored_point_cloud 为 true 时可用。
• /camera/ir/camera_info: 红外相机信息。
• /camera/ir/image_raw: 红外流图像。
• /camera/accel/sample: 加速度数据流，enable_sync_output_accel_gyro 关闭，enable_accel 打开。
• /camera/gyro/sample: 陀螺仪数据流，enable_sync_output_accel_gyro 关闭，enable_gyro 打开。
• camera/gyro_accel/sample: 加速度和陀螺仪同步数据流，enable_sync_output_accel_gyro 打开。

网络设备枚举

目前，网络设备枚举功能仅由 Femto Mega 设备支持。当通过网络访问此设备时，如果将 enumerate_net_device 设置为 true，则设备将自动枚举，无需预先配置 IP 地址或将启用开关设置为 true。具体配置方法如下：

• enumerate_net_device：自动枚举网络设备，仅 Femto Mega 支持。如果将 enumerate_net_device 设置为 true，设备将自动枚举，无需设置 net_device_ip 和 net_device_port 参数。
• net_device_ip：设备的 IP 地址。
• net_device_port：设备的端口号。

多相机

• 要获取相机的 usb_port，请插入相机并在终端中运行以下命令：

ros2 run orbbec_camera list_devices_node

• 将 device_num 参数设置为您拥有的相机数量。
• 转到 OrbbecSDK_ROS2/launch/multi_xxx.launch.py 文件并更改 usb_port。
• 不要忘记将 include 标签放在 group 标签内。否则，不同相机的参数值可能会被污染。

from launch import LaunchDescription
from launch.actions import DeclareLaunchArgument, IncludeLaunchDescription, GroupAction, ExecuteProcess
from launch.launch_description_sources import PythonLaunchDescriptionSource
from launch_ros.actions import Node
from ament_index_python.packages import get_package_share_directory
import os


def generate_launch_description():
    # 包含启动文件
    package_dir = get_package_share_directory('orbbec_camera')
    launch_file_dir = os.path.join(package_dir, 'launch')
    launch1_include = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(
            os.path.join(launch_file_dir, 'gemini2L.launch.py')
        ),
        launch_arguments={
            'camera_name': 'camera_01',
            'usb_port': '6-2.4.4.2',  # 在此替换您的 USB 端口
            'device_num': '2'
        }.items()
    )

    launch2_include = IncludeLaunchDescription(
        PythonLaunchDescriptionSource(
            os.path.join(launch_file_dir, 'gemini2L.launch.py')
        ),
        launch_arguments={
            'camera_name': 'camera_02',
            'usb_port': '6-2.4.1',  # 在此替换您的 USB 端口
            'device_num': '2'
        }.items()
    )

    # 如果您需要更多相机，只需在此处添加更多 launch_include，并更改 usb_port 和 device_num

    # 启动描述
    ld = LaunchDescription([
        GroupAction([launch1_include]),
        GroupAction([launch2_include]),
    ])

    return ld

• 要启动相机，请运行以下命令：

ros2 launch orbbec_camera multi_camera.launch.py

使用硬件解码器解码 JPEG

瑞芯微和晶晨

依赖于 rockchip-mpp-dev 和 rockchip-rga-dev，并非所有系统都有这两个包，名称可能不同，请自行搜索。 打开 CMakeLists.txt 并将 USE_RK_HW_DECODER 设置为 ON。

Nvidia Jetson

依赖于：jetson_multimedia_api、libyuv。 打开 CMakeLists.txt 并将 USE_NV_HW_DECODER 设置为 ON。

启动参数

以下是可用的启动参数：

• connection_delay：重新打开设备的延迟时间，单位为毫秒。一些设备（如 Astra mini）需要较长时间才能初始化，立即重新打开设备会导致固件崩溃。
• enable_point_cloud：启用点云。
• enable_colored_point_cloud：启用 RGB 点云。
• point_cloud_qos、[color|depth|ir]_qos、[color|depth|ir]_camera_info_qos：ROS 2 消息服务质量 (QoS) 设置。可能的值为 SYSTEM_DEFAULT、DEFAULT、PARAMETER_EVENTS、SERVICES_DEFAULT、PARAMETERS 和 SENSOR_DATA，不区分大小写。它们分别对应于 rmw_qos_profile_system_default、rmw_qos_profile_default、rmw_qos_profile_parameter_events、rmw_qos_profile_services_default、rmw_qos_profile_parameters 和 SENSOR_DATA。
• enable_d2c_viewer：发布 D2C 叠加图像（仅用于测试）。
• device_num：设备数量。如果需要多个相机，则必须填写此参数。
• color_width、color_height、color_fps：彩色流的分辨率和帧率。
• ir_width、ir_height、ir_fps：红外流的分辨率和帧率。
• depth_width、depth_height、depth_fps：深度流的分辨率和帧率。
• enable_color：启用 RGB 相机。
• enable_depth：启用深度相机。
• enable_ir：启用红外相机。
• depth_registration：启用将深度帧对齐到彩色帧的硬件。当设置 enable_colored_point_cloud 为 true 时，需要此字段。
• usb_port：相机的 USB 端口。使用多个相机时需要此参数。
• enable_accel：启用加速度计。
• accel_rate：加速度计的频率，可选值为 1.5625hz、3.125hz、6.25hz、12.5hz、25hz、50hz、100hz、200hz、500hz、1khz、2khz、4khz、8khz、16khz、32khz。具体值取决于当前相机。
• accel_range：加速度计的范围，可选值为 2g、4g、8g、16g。具体值取决于当前相机。
• enable_gyro：是否启用陀螺仪。
• gyro_rate：陀螺仪的频率，可选值为 1.5625hz、3.125hz、6.25hz、12.5hz、25hz、50hz、100hz、200hz、500hz、1khz、2khz、4khz、8khz、16khz、32khz。具体值取决于当前相机。
• gyro_range：陀螺仪的范围，可选值为 16dps、31dps、62dps、125dps、250dps、500dps、1000dps、2000dps。具体值取决于当前相机。
• enumerate_net_device：是否启用枚举网络设备的功能。True 表示启用，false 表示禁用。此功能仅由 Femto Mega 和 Gemini 2 XL 设备支持。当通过网络访问这些设备时，需要预先配置设备的 IP 地址。启用开关需要设置为 true。
• depth_filter_config：配置深度过滤配置文件的加载路径。默认情况下，深度过滤配置文件位于 /config/depthfilter 目录下，仅 Gemini2 支持。
• depth_precision：深度精度，格式应为 1mm。默认值为 1mm。
• enable_laser：是否启用激光器。默认值为 true。
• laser_on_off_mode：激光器开关交替模式，0：关闭，1：开-关交替，2：关-开交替。默认值为 0。
• device_preset：设备预设选项为 Default 或 High Accuracy。
• enable_decimation_filter：此滤波有效地降低了深度场景的复杂度。滤波以 [2x2] 到 [8x8] 像素的内核大小运行。图像大小在两个维度上按比例缩小，以保持长宽比。
• enable_hdr_merge：此滤波与深度 HDR 功能一起使用。通过合并连续的具有交替曝光值的深度图像，我们可以同时克服获取低照度和过度照明物体的深度值的挑战。
• enable_sequence_id_filter：此滤波与深度 HDR 功能一起使用，仅输出具有指定序列 ID 的序列。
• enable_threshold_filter：此滤波保留感兴趣的深度值，并忽略超出范围的深度值。
• enable_noise_removal_filter：此滤波以簇的形式去除斑点噪声，并产生一个填充较少的深度图。
• enable_spatial_filter：此滤波根据幅度参数指定的多次迭代处理，以增强深度数据的平滑度。它还能够填充深度图中的小孔。
• enable_temporal_filter：此滤波旨在通过基于先前帧操纵每像素值来改善深度数据的持久性。该滤波对数据执行单次处理，调整深度值的同时更新跟踪历史。
• enable_hole_filling_filter：此滤波使用指定的模式填充深度图中的所有孔。
• retry_on_usb3_detection_failure：如果相机连接到 USB 2.0 端口且未被检测到，系统将尝试最多三次重置相机。此设置旨在防止 USB 3.0 设备被错误地识别为 USB 2.0。建议在使用 USB 2.0 连接时将此参数设置为 false，以避免不必要的重置。

深度工作模式切换

• 在启动相机之前，可以为相应的 xxx.launch.py 文件支持配置深度工作模式（depth_work_mode）。
• Gemini 2、Gemini 2 L 和 Gemini 2 XL 相机支持深度工作模式切换。
• xxx.launch.py 的默认深度工作模式配置是相机的默认配置。如果需要修改，可以根据需要切换到相应的模式。
• 具体相机深度工作模式支持类型可以在深度模式的注释中找到。

# 深度工作模式支持如下：
# Unbinned Dense Default
# Unbinned Sparse Default
# Binned Sparse Default
# Obstacle Avoidance
DeclareLaunchArgument('depth_work_mode', default_value='')

• 查看深度工作模式：

ros2 run orbbec_camera list_depth_work_mode_node

深度 NFOV 和 WFOV 模式的配置

对于 Femto Mega 和 Femto Bolt 设备，NFOV 和 WFOV 模式是通过在启动文件中配置 Depth 和 IR 的分辨率来实现的。 在启动文件中，depth_width、depth_height、ir_width、ir_height 分别表示深度的分辨率和 IR 的分辨率。 IR 的帧率和分辨率必须与深度一致。不同模式与分辨率的对应关系如下：

• NFOV unbinned：640 x 576。
• NFOV binned：320 x 288。
• WFOV unbinned：1024 x 1024。
• WFOV binned：512 x 512。

检查相机支持的配置文件

ros2 run orbbec_camera list_camera_profile_mode_node

构建 Debian 包

准备环境

在开始之前，请安装所需的工具：

sudo apt install debhelper fakeroot python3-bloom

配置 ROS 依赖项

将以下 YAML 文件添加到系统的 /etc/ros/rosdep/sources.list.d/00-orbbec.yaml 中。确保将 focal 替换为您的 Ubuntu 版本的代号，将 humble 替换为您的 ROS2 发行版名称：

orbbec_camera_msgs:
  ubuntu:
    focal: [ros-humble-orbbec-camera-msgs]

接下来，创建一个新文件 /etc/ros/rosdep/sources.list.d/50-orbbec.list，并添加这一行以指定 YAML 文件的路径：

yaml file:///etc/ros/rosdep/sources.list.d/00-orbbec.yaml

更新 rosdep 数据库以反映这些更改：

rosdep update

构建包

导航到您的工作区并构建项目：

cd ~/ros2_ws/
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
. install/setup.bash
cd src/OrbbecSDK_ROS2/
bash .make_deb.sh

启动文件

所有启动文件本质上都是相似的，主要区别在于为同一系列中不同型号设置的参数的默认值。USB 标准的差异，例如 USB 2.0 与 USB 3.0，可能需要调整这些参数。如果遇到启动失败，请仔细查看规格手册。特别注意启动文件中的分辨率设置以及其他参数，以确保兼容性和最佳性能。

产品支持

DDS 调优

默认的 DDS 设置（Galactic）可能不是数据传输的最佳选择。不同的 DDS 设置可能具有不同的性能。在此示例中，我们使用 CycloneDDS。有关更多详细信息，请参阅 ROS DDS 调优。

● 编辑 cyclonedds 配置文件

sudo gedit /etc/cyclonedds/config.xml

添加

<?xml version="1.0" encoding="UTF-8"?>
<CycloneDDS xmlns="https://cdds.io/config" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://cdds.io/confighttps://raw.githubusercontent.com/eclipse-cyclonedds/cyclonedds/master/etc/cyclonedds.xsd">
    <Domain id="any">
        <General>
            <NetworkInterfaceAddress>lo</NetworkInterfaceAddress>
            <AllowMulticast>false</AllowMulticast>
        </General>
        <Internal>
            <MinimumSocketReceiveBufferSize>16MB</MinimumSocketReceiveBufferSize>
        </Internal>
        <Discovery>
            <ParticipantIndex>auto</ParticipantIndex>
            <MaxAutoParticipantIndex>30</MaxAutoParticipantIndex>
            <Peers>
                <Peer address="localhost"/>
            </Peers>
        </Discovery>
    </Domain>
</CycloneDDS>

● 设置环境变量，添加到 .zshrc 或 .bashrc

export ROS_DOMAIN_ID=42 # 0 到 232 之间的数字
export ROS_LOCALHOST_ONLY=1
export CYCLONEDDS_URI=file:///etc/cyclonedds/config.xml

提示：要了解为什么最大 ROS_DOMAIN_ID 为 232，请访问 ROS 域 ID ● 增加 UDP 接收缓冲区大小 编辑

/etc/sysctl.d/10-cyclone-max.conf

添加

net.core.rmem_max=2147483647
net.core.rmem_default=2147483647

常见问题

多个相机无图像

• 可能是电源供应不足。为避免这种情况，请不要将所有相机连接到同一个集线器，并使用带电源的集线器。

• 也可能是分辨率太高。要解决此问题，请尝试降低分辨率。

为什么这里有那么多启动文件

• 存在多个启动文件的原因是不同相机的默认分辨率和图像格式不同。为了方便使用，为每个相机单独设置了启动文件。

许可证

版权所有 2023 Orbbec Ltd。

根据 Apache 许可证 2.0 版（”许可证”）获得许可；除非遵守许可证，否则您不得使用此项目。您可以在以下网址获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

```