奥比中光 / TECHNICAL WIKI

在机器人中接入奥比中光深度相机（ROS 2）

深度相机 / ROS 2

说明如何在 Ubuntu 与 ROS 2 环境中接入奥比中光深度相机：先确定驱动、ROS 2 发行版和设备启动文件，再完成驱动安装、数据流验证、RViz2 可视化、话题与坐标系确认，最后把相机正确挂接到机器人机体坐标系

ROS 2UbuntuRViz2TFPointCloud2ROS 2 Humble / Jazzy / Lyrical

02 / DOCUMENTATION

内容概述

ROS 2 Humble / Jazzy / Lyrical

本文说明如何在 Ubuntu 与 ROS 2 环境中接入奥比中光深度相机：先确定驱动、ROS 2 发行版和设备启动文件，再完成驱动安装、数据流验证、RViz2 可视化、话题与坐标系确认，最后把相机正确挂接到机器人机体坐标系。

示例以 Astra 2 为主。ROS 2 驱动、发行版、CPU 架构和相机型号必须相互匹配；正式部署前请以奥比中光官方仓库与当前设备固件的最新说明为准。

03 / DOCUMENTATION

基础知识

ROS 2 Humble / Jazzy / Lyrical

✅ 深度相机接入 ROS 2 的方式是使用 OrbbecSDK ROS2 Wrapper：它把 SDK 的取流能力封装成一个相机节点，按标准 ROS 2 消息发布图像、点云、IMU 与相机内参，机器人其余节点只需订阅话题。

✅ ROS 2 驱动与独立 SDK 是两个独立发行物。驱动包内已自带 SDK 运行库，按任务一安装过独立 SDK 的主机无需卸载，两者可以共存，但版本应保持一致。

04 / DOCUMENTATION

接入后的数据形态

ROS 2 Humble / Jazzy / Lyrical

相机节点启动后，数据以话题形式输出，各类数据分别对应不同的上层用途：

数据	话题（默认命名空间 `/camera`）	消息类型	典型用途
深度图	`/camera/depth/image_raw`	`sensor_msgs/msg/Image`	距离测量、避障、地面检测
彩色图	`/camera/color/image_raw`	`sensor_msgs/msg/Image`	目标识别、可视化
红外图	`/camera/ir/image_raw`	`sensor_msgs/msg/Image`	暗光成像、结构光散斑调试
点云	`/camera/depth/points`	`sensor_msgs/msg/PointCloud2`	三维感知、建图、抓取定位
IMU	`/camera/gyro_accel/sample`	`sensor_msgs/msg/Imu`	运动估计、与视觉融合（仅具备 IMU 的型号有数据，见通用 02）
相机内参	`/camera/depth/camera_info`	`sensor_msgs/msg/CameraInfo`	像素与三维坐标互相换算

完整话题清单、编码格式与坐标系定义见通用 02 话题与坐标系。

05 / DOCUMENTATION

版本与发行版对应关系

ROS 2 Humble / Jazzy / Lyrical

驱动通过 GitHub Releases 发布预编译 deb 包，每个 zip 对应「一种 ROS 2 发行版 + 一种主机架构」：

项目	取值	说明
ROS 2 发行版	Humble / Jazzy / Lyrical	发行包覆盖这三种；Foxy 与 Rolling 需从源码构建
主机架构	`amd64` / `arm64`	由主机决定，与相机型号无关

发布页的文件名为 orbbec-ros2-debs-<发行版>-<架构>.zip，解压后得到两个 deb：

1ros-<发行版>-orbbec-camera-msgs_<版本>_<架构>.deb   消息与服务定义2ros-<发行版>-orbbec-camera_<版本>_<架构>.deb        相机节点本身

⚠️ 驱动版本应与任务一所用 SDK 版本对应（示例环境两者均为 v2.10.6）。主机上若已有版本不一致的独立 SDK，/usr/local/lib 下的库可能先于驱动自带的库被加载。

06 / DOCUMENTATION

型号与启动文件

ROS 2 Humble / Jazzy / Lyrical

每种型号对应一个启动文件，参数默认值按该型号的传感器能力设定。启动文件随 orbbec_camera 包安装，位于 share/orbbec_camera/launch/。

型号系列	启动文件
Astra 2	`astra2.launch.py`
Astra Mini Pro / Astra Mini S Pro	`astra.launch.py`
Gemini 2 / Gemini 2 L	`gemini2.launch.py` / `gemini2L.launch.py`
Gemini 210 / 215	`gemini210.launch.py`
Gemini 301 系列（305 / 305g）	`gemini_301_series.launch.py`
Gemini 330 系列	`gemini_330_series.launch.py`
Gemini 340 系列	`gemini345.launch.py` / `gemini345_lg.launch.py`
Gemini 430 系列	`gemini435_le.launch.py`
Femto Bolt	`femto_bolt.launch.py`
Femto Mega / Femto Mega I	`femto_mega.launch.py`
DaBai 系列	`dabai_a.launch.py` 等对应型号文件
LiDAR 系列	`lidar.launch.py`

示例环境（Astra 2）使用 astra2.launch.py。型号不在上表时，可在 share/orbbec_camera/launch/ 目录中按型号名查找。

07 / DOCUMENTATION

环境要求

ROS 2 Humble / Jazzy / Lyrical

项目	要求
操作系统	Ubuntu；x64 平台已验证 Ubuntu 22.04
ROS 2	已安装且能 `source` 对应发行版的 `setup.bash`
架构	`amd64` 或 `arm64`
磁盘	驱动与依赖约占数百 MB
权限	不需要 `sudo` 运行节点（由 udev 规则授予设备访问权限）

⚠️ ARM64 的支持范围：受支持的 ARM64 平台为 NVIDIA Jetson 系列。其他 ARM64 平台在架构上可以安装 arm64 包，但不在受支持平台列表内，兼容性需自行验证。

08 / DOCUMENTATION

环境准备与驱动安装

ROS 2 Humble / Jazzy / Lyrical

✅ 驱动以预编译 deb 形式发布：按「ROS 2 发行版 + 主机架构」取一个压缩包，解压后安装其中的两个 deb，不需要编译。

✅ 安装包自带 udev 规则与 SDK 运行库，节点以普通用户运行即可，不需要 sudo。

09 / DOCUMENTATION

系统要求

ROS 2 Humble / Jazzy / Lyrical

项目	要求
操作系统	Ubuntu；x64 平台已验证 Ubuntu 22.04
ROS 2	Humble / Jazzy / Lyrical（发行包覆盖这三种）
主机架构	`amd64` 或 `arm64`
磁盘空间	驱动与依赖合计数百 MB

10 / DOCUMENTATION

安装 ROS 2

ROS 2 Humble / Jazzy / Lyrical

机器上已有可用的 ROS 2 时，跳过本节。未安装时按 ROS 2 Ubuntu 安装说明安装桌面版（含 RViz2，用于后续查看图像与点云）：

1sudo apt install ros-<ROS 发行版>-desktop

安装完成后，每个终端使用前都需要 source 环境：

1source /opt/ros/<ROS 发行版>/setup.bash

建议把该命令写入 ~/.bashrc，避免每次手动执行。

11 / DOCUMENTATION

下载驱动

ROS 2 Humble / Jazzy / Lyrical

驱动发布页：OrbbecSDK_ROS2 Releases。国内网络可改用 Gitee 镜像。

发布页的 Windows 无关，Linux 包统一命名为 orbbec-ros2-debs-<发行版>-<架构>.zip，一个压缩包对应一种发行版与一种架构的组合：

文件	适用环境
`orbbec-ros2-debs-humble-amd64.zip`	Humble · x64
`orbbec-ros2-debs-humble-arm64.zip`	Humble · ARM64
`orbbec-ros2-debs-jazzy-amd64.zip`	Jazzy · x64
`orbbec-ros2-debs-jazzy-arm64.zip`	Jazzy · ARM64
`orbbec-ros2-debs-lyrical-amd64.zip`	Lyrical · x64
`orbbec-ros2-debs-lyrical-arm64.zip`	Lyrical · ARM64

✅ 按上表的两个字段（发行版、架构）即可唯一确定应下载的文件。发行版用 printenv ROS_DISTRO 确认，架构用 uname -m 确认（x86_64 对应 amd64，aarch64 对应 arm64）。

若所用 ROS 2 发行版的软件源中已收录该驱动（apt list | grep orbbec 可确认），也可直接用系统包管理器安装。发行包版本通常落后于 Releases 的最新版，需要最新功能时仍以 Releases 为准。

下载后解压：

1unzip orbbec-ros2-debs-<发行版>-<架构>.zip -d orbbec_ros22ls orbbec_ros2

解压结果包含两个文件：

1ros-<发行版>-orbbec-camera-msgs_<版本>_<架构>.deb2ros-<发行版>-orbbec-camera_<版本>_<架构>.deb

12 / DOCUMENTATION

安装依赖与驱动

ROS 2 Humble / Jazzy / Lyrical

先装驱动所需的系统与 ROS 依赖：

1sudo apt install -y libgflags-dev libgoogle-glog-dev nlohmann-json3-dev 2  ros-<ROS 发行版>-image-transport ros-<ROS 发行版>-image-transport-plugins 3  ros-<ROS 发行版>-compressed-image-transport ros-<ROS 发行版>-image-publisher 4  ros-<ROS 发行版>-camera-info-manager ros-<ROS 发行版>-diagnostic-updater 5  ros-<ROS 发行版>-diagnostic-msgs ros-<ROS 发行版>-statistics-msgs 6  ros-<ROS 发行版>-backward-ros ros-<ROS 发行版>-xacro7sudo apt install -y libdw-dev libssl-dev python3-tabulate

再安装两个 deb：

1cd orbbec_ros22sudo dpkg -i ros-<发行版>-orbbec-camera-msgs_<版本>_<架构>.deb 3             ros-<发行版>-orbbec-camera_<版本>_<架构>.deb

⚠️ 若 dpkg 提示依赖未满足，执行 sudo apt-get install -f 补齐依赖后再确认包状态：

1dpkg -l | grep orbbec

两行状态应为 ii。

需要在机器人 URDF 中引用相机模型时，再安装机型描述包：

1sudo apt install -y ros-<ROS 发行版>-orbbec-description

该包提供 share/orbbec_description/urdf/ 下各型号的 xacro 模型与网格文件，用法见通用 03 第 1 节。

安装后的文件位置（以 ROS 2 安装根目录 /opt/ros/<ROS 发行版>/ 为基准）：

路径	内容
`share/orbbec_camera/launch/`	各型号的启动文件
`share/orbbec_camera/config/`	参数配置文件
`share/orbbec_camera/udev/`	udev 规则源文件
`share/orbbec_camera/examples/`	示例代码
`lib/orbbec_camera/`	节点与工具的可执行文件（`orbbec_camera_node`、`list_devices_node` 等）
`lib/liborbbec_camera.so`	相机节点插件
`lib/libOrbbecSDK.so.<版本>`	驱动自带的 SDK 运行库
`lib/extensions/`	深度引擎与后处理扩展库

查询本机实际安装的全部文件：

1dpkg -L ros-<ROS 发行版>-orbbec-camera | less

⚠️ 上述路径属于 ROS 2 的安装根目录，与任务一安装的独立 SDK（/opt/OrbbecSDK_<版本>/）是两套独立的目录结构，两者互不替代。

13 / DOCUMENTATION

设备权限（udev 规则）

ROS 2 Humble / Jazzy / Lyrical

Linux 下访问 USB 设备需要权限规则，否则打开设备会失败、只能用 sudo 运行节点。安装包会把规则文件安装到系统目录：

1/etc/udev/rules.d/99-obsensor-libusb.rules

规则对已连接的设备需要重新触发才能生效，重新插拔相机也可以：

1sudo udevadm control --reload-rules && sudo udevadm trigger

确认规则文件存在：

1ls /etc/udev/rules.d/ | grep obsensor

14 / DOCUMENTATION

验证设备识别

ROS 2 Humble / Jazzy / Lyrical

1source /opt/ros/<ROS 发行版>/setup.bash2ros2 run orbbec_camera list_devices_node

正常输出示例：

1[INFO] [...] [list_device_node]: name: Orbbec Astra22[INFO] [...] [list_device_node]: pid: 0x06603[INFO] [...] [list_device_node]: serial: <序列号>4[INFO] [...] [list_device_node]: connection: USB3.05[INFO] [...] [list_device_node]: firmware version: <固件版本>6[INFO] [...] [list_device_node]: usb port: <端口号>

connection 应为 USB3.0。若显示 USB2.0，深度图的分辨率与帧率将受限，应改用 USB 3.0 端口与线材。

⚠️ 列表为空时，依次检查：相机是否插在 USB 3.0 端口、lsusb 是否能看到设备、udev 规则是否生效（见第 5 节）。lsusb 看不到设备属于硬件连接问题，与驱动无关。

15 / DOCUMENTATION

从源码构建（发行版不在发行包覆盖范围时）

ROS 2 Humble / Jazzy / Lyrical

发行包只覆盖 Humble / Jazzy / Lyrical。使用 Foxy、Rolling 或需要修改驱动代码时，从源码构建：

1mkdir -p ~/ros2_ws/src2cd ~/ros2_ws/src3git clone https://github.com/orbbec/OrbbecSDK_ROS2.git4cd OrbbecSDK_ROS2 && git checkout v2-main5cd ~/ros2_ws6colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release7source install/setup.bash

源码构建方式下，udev 规则需手动安装：

1sudo bash ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts/install_udev_rules.sh

⚠️ 源码构建使用 v2-main 分支；main 分支对应 SDK v1 世代，仅用于 v2 已不支持的旧型号。

16 / DOCUMENTATION

启动与查看数据流

ROS 2 Humble / Jazzy / Lyrical

✅ 启动只需一条命令：ros2 launch orbbec_camera astra2.launch.py；型号与启动文件的对应关系见通用 01 第 3 节。

✅ 查看数据用 RViz2：加 Image 显示订阅 /camera/color/image_raw 与 /camera/depth/image_raw，加 PointCloud2 显示订阅 /camera/depth/points。

17 / DOCUMENTATION

启动相机节点

ROS 2 Humble / Jazzy / Lyrical

1source /opt/ros/<ROS 发行版>/setup.bash2ros2 launch orbbec_camera astra2.launch.py

启动过程约需两秒，日志中的关键行如下：

1[camera.camera]: Device Orbbec Astra 2 connected2[camera.camera]: Serial number: <序列号>3[camera.camera]: Firmware version: <固件版本>4[camera.camera]: ROS Wrapper version: <驱动版本>5[camera.camera]: SDK version: <SDK 版本>6[camera.camera]: usb connect type: USB3.07[camera.camera]: depth Frame - Width: 800 Height: 600 fps: 30 Format: Y168[camera.camera]: ir Frame - Width: 800 Height: 600 fps: 30 Format: Y89[camera.camera]: color Frame - Width: 1280 Height: 720 fps: 30 Format: MJPG10[camera.camera]: Initialize device cost: <毫秒数> ms

三行 Frame - Width … 表示各路流已按该分辨率与格式启动。出现这三行即可进入下一步；若缺少某一路，检查启动参数中对应的 enable_* 与分辨率是否落在设备支持的组合内。

18 / DOCUMENTATION

确认数据流

ROS 2 Humble / Jazzy / Lyrical

新开一个终端（同样先 source），逐项确认：

1ros2 topic list2ros2 topic hz /camera/depth/image_raw3ros2 topic hz /camera/color/image_raw

ros2 topic hz 会输出统计帧率；统计需要等待数帧，中途没有输出属正常。

查看节点自报的各流帧率、延迟与订阅者状态：

1ros2 topic echo /camera/device_status --once

其中每路流的 publish_rate_hz 为该流最近的实际发布频率，delay_ms_avg 为平均延迟。设备在线状态由 device_online 给出。

19 / DOCUMENTATION

在 RViz2 中查看

ROS 2 Humble / Jazzy / Lyrical

1rviz2

在 RViz2 中依次添加显示项：

显示类型	话题	看到的内容
`Image`	`/camera/color/image_raw`	彩色图像
`Image`	`/camera/depth/image_raw`	深度图（默认按原始 16 位显示，灰度随距离变化）
`PointCloud2`	`/camera/depth/points`	由深度图生成的三维点云
`Image`	`/camera/ir/image_raw`	红外图像

PointCloud2 的 Size (m) 调小到 0.01 左右、Style 选 Points 更容易观察。

图为 PointCloud2 显示 /camera/depth/points 的效果：Fixed Frame 设为 camera_depth_optical_frame，Color Transformer 设为 AxisColor、Axis 设为 Z，颜色随深度变化（近处偏红、远处偏蓝）。画面左侧 Displays 中的 Global Status: Ok 表示 TF 与话题均正常。

⚠️ Global Options → Fixed Frame 必须与消息的 frame_id 属于同一棵 TF 树。只看相机数据时设为 camera_depth_optical_frame 即可；若设为 base_link 而尚未发布机体到相机的变换，RViz2 会提示 No transform from ...，此时按通用 03 第 1 节补静态变换。

轻量查看单路图像也可用 rqt_image_view（需先安装）：

1sudo apt install ros-<ROS 发行版>-rqt-image-view2ros2 run rqt_image_view rqt_image_view /camera/depth/image_raw

图为 rqt_image_view 订阅 /camera/depth/image_raw 的效果：窗口顶部下拉框为当前话题，深色区域为有效深度（灰度随距离变化），黑色为无效值。深度图以原始 16 位灰度显示，不做伪彩色映射。

20 / DOCUMENTATION

常用启动参数

ROS 2 Humble / Jazzy / Lyrical

参数在启动命令后以 名称:=值 形式覆盖，可叠加多个。示例环境（Astra 2）的默认值如下：

参数	默认值	说明
`camera_name`	`camera`	话题命名空间
`serial_number`	空	多相机时指定设备
`enable_depth` / `enable_color` / `enable_ir`	`true`	各路流开关
`depth_width` / `depth_height` / `depth_fps`	`800` / `600` / `30`	深度流参数
`color_width` / `color_height` / `color_fps`	`1280` / `720` / `30`	彩色流参数
`color_format`	`MJPG`	彩色采集格式
`ir_width` / `ir_height` / `ir_fps`	`800` / `600` / `30`	红外流参数
`enable_point_cloud`	`true`	是否生成点云
`enable_colored_point_cloud`	`false`	是否生成彩色点云
`depth_registration`	`false`	深度是否注册到彩色帧
`publish_tf`	`true`	是否发布相机内部 TF
`color_frame_queue_max_frames`	`1`	彩色帧队列长度
`uvc_backend`	`libuvc`	采集后端
`time_domain`	`global`	时间戳基准

只保留深度流并降低分辨率：

1ros2 launch orbbec_camera astra2.launch.py 2  enable_color:=false enable_ir:=false 3  depth_width:=400 depth_height:=300 depth_fps:=15

为相机改名（多相机场景）：

1ros2 launch orbbec_camera astra2.launch.py camera_name:=camera_front

参数完整的取值与含义可用以下命令查看：

1ros2 launch orbbec_camera astra2.launch.py --show-args

21 / DOCUMENTATION

深度滤波

ROS 2 Humble / Jazzy / Lyrical

深度图常出现空洞（黑色区域）、边缘飞点或帧间抖动，由深度后处理滤波器处理。启动文件已为各滤波器定义了参数，默认多数关闭，仅噪声去除默认开启。

参数	默认值	作用
`enable_noise_removal_filter`	`true`	去除离散噪声点；`noise_removal_filter_min_diff` 与 `noise_removal_filter_max_size` 控制判定阈值与邻域范围
`enable_spatial_filter`	`false`	空间滤波，平滑单帧图像，减少边缘飞点；参数 `spatial_filter_alpha` `spatial_filter_diff_threshold` `spatial_filter_magnitude` `spatial_filter_radius`
`enable_temporal_filter`	`false`	时域滤波，抑制帧间抖动；参数 `temporal_filter_diff_threshold` `temporal_filter_weight`
`enable_hole_filling_filter`	`false`	填补深度空洞；参数 `hole_filling_filter_mode`
`enable_threshold_filter`	`false`	按距离阈值裁剪；参数 `threshold_filter_min` / `threshold_filter_max`
`enable_decimation_filter`	`false`	降采样，降低数据量；参数 `decimation_filter_scale`

示例：为近距离抓取场景打开时域滤波与空洞填补：

1ros2 launch orbbec_camera astra2.launch.py 2  enable_temporal_filter:=true enable_hole_filling_filter:=true

⚠️ 滤波器在深度流上逐帧运算，全部开启会增加主机负载；参数取 -1 或空值时表示沿用设备当前值，而非关闭滤波器。各滤波器的完整参数与算法说明见驱动文档的深度过滤器章节。

22 / DOCUMENTATION

停止与重启

ROS 2 Humble / Jazzy / Lyrical

在启动节点的终端按 Ctrl+C 正常退出。节点会释放设备，之后可立即重新启动。

⚠️ 若进程被强制结束（kill -9、终端异常关闭），UVC 设备可能处于残留状态，再次启动时话题存在但始终收不到数据。此时重新插拔相机（或对 USB 端口执行复位）后再启动即可恢复。

23 / DOCUMENTATION

故障处理

ROS 2 Humble / Jazzy / Lyrical

现象	原因与处理
启动报找不到设备 / 设备数为 0	相机未接在 USB 3.0 端口、线材不支持 USB 3.0，或 udev 规则未生效；先 `lsusb` 确认设备存在
启动报参数不支持 / profile 无效	分辨率、帧率或格式不在设备支持列表内；用 `ros2 run orbbec_camera list_camera_profile_mode_node` 查询
话题存在但收不到数据	上次进程异常退出导致设备残留；按第 5 节重新插拔后重启
启动瞬间出现 `Color frame queue overflow`	首帧到达速度超过队列长度（默认 1 帧），属启动瞬态；持续出现时降低分辨率或帧率
RViz2 报 `No transform`	Fixed Frame 与消息坐标系不在同一 TF 树；改 Fixed Frame 或补机体到相机的静态变换
RViz2 中点云不显示	未开启 `enable_point_cloud`，或 `Size (m)` 过大；同时确认 Fixed Frame 正确
CPU 占用过高	关闭不用的流、降低分辨率或帧率、关闭点云输出（见通用 03 第 3 节）
深度图大面积空白	场景超出量程、表面反光或过暗；`0` 为无效值属正常现象

24 / DOCUMENTATION

话题与坐标系

ROS 2 Humble / Jazzy / Lyrical

✅ 相机节点默认以 /camera 为命名空间发布深度、彩色、红外三路图像，外加点云、内参与状态话题；图像话题仅在对应流使能时发布，IMU 话题仅在实际具备 IMU 的型号上产生数据。

✅ 深度图编码为 16UC1，单位毫米，像素值 0 表示无效（超量程或无回波），不需要再乘比例系数。

25 / DOCUMENTATION

话题清单

ROS 2 Humble / Jazzy / Lyrical

相机节点在默认命名空间 /camera 下的话题：

话题	类型	内容
`/camera/depth/image_raw`	`sensor_msgs/msg/Image`	深度图，`16UC1`，毫米
`/camera/depth/camera_info`	`sensor_msgs/msg/CameraInfo`	深度相机内参与畸变模型
`/camera/depth/points`	`sensor_msgs/msg/PointCloud2`	由深度图生成的点云（需 `enable_point_cloud`）
`/camera/color/image_raw`	`sensor_msgs/msg/Image`	彩色图，`rgb8`
`/camera/color/image_raw/compressed`	`sensor_msgs/msg/CompressedImage`	彩色压缩流（随发布插件使能出现）
`/camera/color/camera_info`	`sensor_msgs/msg/CameraInfo`	彩色相机内参
`/camera/ir/image_raw`	`sensor_msgs/msg/Image`	红外图，`mono8`
`/camera/ir/camera_info`	`sensor_msgs/msg/CameraInfo`	红外相机内参
`/camera/gyro_accel/sample`	`sensor_msgs/msg/Imu`	陀螺仪与加速度计融合输出
`/camera/accel/imu_info`	`orbbec_camera_msgs/msg/IMUInfo`	加速度计标定参数
`/camera/gyro/imu_info`	`orbbec_camera_msgs/msg/IMUInfo`	陀螺仪标定参数
`/camera/device_status`	`orbbec_camera_msgs/msg/DeviceStatus`	设备在线状态与各流实际发布帧率
`/camera/depth_filters/status`	`orbbec_camera_msgs/msg/DepthFiltersStatus`	深度后处理滤波器状态
`/tf` `/tf_static`	`tf2_msgs/msg/TFMessage`	相机内部坐标系变换

⚠️ 未使能的流不会发布对应话题。例如关闭红外流后，/camera/ir/image_raw 不再出现，依赖它的订阅端会一直等不到数据。

⚠️ IMU 话题只在实际具备 IMU 的型号上产生数据：节点会为 IMU 相关话题建立发布者，但设备没有对应传感器时不会有消息。示例设备 Astra 2 的传感器只有深度、彩色、红外三路（可用 ros2 run orbbec_camera list_camera_profile_mode_node 确认），其 IMU 话题始终为空。具备 IMU 的型号需同时开启对应流：

1ros2 launch orbbec_camera astra2.launch.py enable_accel:=true enable_gyro:=true

26 / DOCUMENTATION

图像编码与取值

ROS 2 Humble / Jazzy / Lyrical

流	编码	典型分辨率	取值含义
深度	`16UC1`	800 × 600	每像素 16 位无符号整数，单位毫米；`0` 为无效值
彩色	`rgb8`	1280 × 720	三通道 8 位；设备侧为 MJPG 时由驱动解码后发布
红外	`mono8`	800 × 600	单通道 8 位灰度

深度值的读取方式（C++）：

1auto depth = msg->data;                       // sensor_msgs::msg::Image::_data_type2uint16_t d = depth[row * width + col];        // 单位：毫米，0 表示无效

Python 侧建议用 numpy.frombuffer 转为 uint16 数组后按二维索引访问，避免逐像素处理带来的开销。

⚠️ 彩色图默认以 MJPG 采集、在主机侧解码为 rgb8 后发布。带宽允许时也可将 color_format 设为 YUYV 或 RGB，省去解码开销，但占用更高。

27 / DOCUMENTATION

相机内参

ROS 2 Humble / Jazzy / Lyrical

camera_info 提供该流的内参与畸变模型，用于像素坐标与相机三维坐标互算：

字段	含义
`k`	3 × 3 内参矩阵，包含焦距 `fx` `fy` 与主点 `cx` `cy`
`d`	畸变系数；模型由 `distortion_model` 给出
`distortion_model`	示例设备的深度流为 `rational_polynomial`
`frame_id`	与该流图像一致的坐标系名，如 `camera_depth_optical_frame`

反投影公式（深度图，单位毫米→米）：

1Z = 深度像素值 / 10002X = (u - cx) * Z / fx3Y = (v - cy) * Z / fy

28 / DOCUMENTATION

坐标系与 TF

ROS 2 Humble / Jazzy / Lyrical

节点默认发布相机内部各传感器之间的静态变换（publish_tf 默认开启）。坐标系分两类：

类型	示例	轴向约定
机体坐标系	`camera_depth_frame`、`camera_color_frame`	ROS 约定：X 向前、Y 向左、Z 向上
光学坐标系	`camera_depth_optical_frame`、`camera_color_optical_frame`	相机约定：Z 向前（光轴）、X 向右、Y 向下

图像与点云消息的 frame_id 均为光学坐标系。相机节点默认发布的坐标系包括：

1camera_depth_frame ─┬─ camera_depth_optical_frame2                    ├─ camera_ir_frame ── camera_ir_optical_frame3                    ├─ camera_color_frame ── camera_color_optical_frame4                    ├─ camera_accel_frame ── camera_accel_optical_frame5                    └─ camera_gyro_frame ── camera_gyro_optical_frame

⚠️ 这些是相机内部的坐标系，根节点 camera_depth_frame 与机器人机体之间没有变换。接入机器人时必须补一条机体到相机的静态变换，否则 RViz2 中会报 No transform from [camera_depth_optical_frame] to [base_link]。做法见通用 03 机器人集成要点。

29 / DOCUMENTATION

话题与坐标系 · QoS

ROS 2 Humble / Jazzy / Lyrical

图像话题的默认 QoS 为 RELIABLE / VOLATILE / KEEP_LAST(10)。订阅端使用 ROS 2 默认 QoS 即可匹配；若订阅端显式改为 BEST_EFFORT，与 RELIABLE 发布端仍可通信，但反向不成立。

30 / DOCUMENTATION

服务接口

ROS 2 Humble / Jazzy / Lyrical

除话题外，节点还提供服务用于查询与控制。常用服务：

服务	作用
`/camera/get_device_info`	查询型号、序列号、固件版本、SDK 版本
`/camera/get_sdk_version`	查询当前 SDK 版本
`/camera/get_streams_enable`	查询各流使能状态
`/camera/set_color_exposure` / `/camera/set_color_gain`	设置彩色曝光与增益
`/camera/set_depth_exposure` / `/camera/set_depth_gain`	设置深度曝光与增益
`/camera/set_color_flip` / `/camera/set_depth_flip`	翻转图像
`/camera/set_color_rotation` / `/camera/set_depth_rotation`	旋转图像
`/camera/save_images`	保存当前帧到磁盘
`/camera/save_point_cloud`	保存当前点云
`/camera/set_bag_recording`	开始或停止设备级录制
`/camera/send_software_trigger`	软触发一次采集
`/camera/reboot_device`	重启设备

查询设备信息：

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

完整服务列表用 ros2 service list | grep -v parameters 查看。

31 / DOCUMENTATION

最小订阅示例

ROS 2 Humble / Jazzy / Lyrical

以下为一个可直接运行的 Python 示例：订阅深度图，取画面中心区域，输出其中的最小与最大有效距离。示例仅用于说明数据如何取出，不涉及具体业务逻辑。

1# depth_probe.py —— 读取深度图中心区域的有效距离范围2import rclpy3from rclpy.node import Node4from rclpy.qos import QoSProfile, ReliabilityPolicy, HistoryPolicy5from sensor_msgs.msg import Image6import numpy as np7
8
9class DepthProbe(Node):10    def __init__(self):11        super().__init__("depth_probe")12        qos = QoSProfile(depth=10, reliability=ReliabilityPolicy.RELIABLE,13                         history=HistoryPolicy.KEEP_LAST)14        self.create_subscription(Image, "/camera/depth/image_raw", self.on_image, qos)15        self.count = 016        self.done = False17
18    def on_image(self, msg):19        self.count += 120        if self.count <= 5:          # 跳过启动初期的前几帧21            return22        # 深度图为 16UC1，按行宽还原成二维数组，取值单位毫米23        depth = np.frombuffer(msg.data, dtype=np.uint16).reshape(msg.height, msg.width)24        h, w = depth.shape25        roi = depth[h // 3: h * 2 // 3, w // 3: w * 2 // 3]   # 画面中心 1/3 区域26        valid = roi[roi > 0]         # 0 为无效像素27        if valid.size:28            print("有效像素 %d 个，最小距离 %d mm，最大距离 %d mm"29                  % (valid.size, valid.min(), valid.max()))30        else:31            print("该区域内没有有效深度值")32        self.done = True33
34
35def main():36    rclpy.init()37    node = DepthProbe()38    while rclpy.ok() and not node.done:39        rclpy.spin_once(node, timeout_sec=0.5)40    node.destroy_node()41    rclpy.shutdown()42
43
44if __name__ == "__main__":45    main()

启动相机节点后运行：

1python3 depth_probe.py

输出示例：

1有效像素 49275 个，最小距离 1679 mm，最大距离 3695 mm

要点：

位置	说明
`QoSProfile`	与发布端的 `RELIABLE / KEEP_LAST(10)` 保持一致
`np.frombuffer(...).reshape(h, w)`	深度数据是一维字节流，需按 `height` × `width` 还原
`dtype=np.uint16`	对应 `16UC1`；彩色图应改用 `uint8` 并按三通道还原
`roi > 0`	过滤无效像素，避免 `0` 值参与统计

32 / DOCUMENTATION

常用调试命令

ROS 2 Humble / Jazzy / Lyrical

目的	命令
列出话题	`ros2 topic list`
查看某路实际帧率	`ros2 topic hz /camera/depth/image_raw`
查看消息结构	`ros2 topic echo /camera/depth/camera_info --once`
查看带宽	`ros2 topic bw /camera/depth/image_raw`
查看各流帧率与延迟	`ros2 topic echo /camera/device_status --once`
录制数据	`ros2 bag record -o <目录> /camera/depth/image_raw /camera/color/image_raw`
查看节点与参数	`ros2 node list` · `ros2 param list /camera/camera`

⚠️ ros2 topic hz 与 ros2 topic echo 依赖订阅端，第一次统计需要等待数帧。同时运行多个订阅端会增加主机负载，排查结束后应及时关闭。

33 / DOCUMENTATION

机器人集成要点

ROS 2 Humble / Jazzy / Lyrical

✅ 接入机器人的三个要点：发布机体到相机的静态 TF、按任务选择点云或图像的深度形态、控制分辨率与流数以约束 CPU 与带宽占用。

34 / DOCUMENTATION

机体到相机的静态变换

ROS 2 Humble / Jazzy / Lyrical

相机节点发布的根坐标系是 camera_depth_frame，它对应相机外壳的几何原点。要让机器人其他节点能用这份数据，必须从机体 base_link 补一条静态变换直接指向它：

1ros2 run tf2_ros static_transform_publisher 2  --frame-id base_link --child-frame-id camera_depth_frame 3  --x 0.15 --y 0.0 --z 0.08 --qx 0 --qy 0 --qz 0 --qw 1

若机器人已有 URDF 模型，也可以把相机作为一个固定连接的部件写进模型，再让模型的相机基座与 camera_depth_frame 对齐：

1<link name="camera_link"/>2<joint name="camera_joint" type="fixed">3  <parent link="base_link"/>4  <child link="camera_link"/>5  <origin xyz="0.15 0 0.08" rpy="0 0 0"/>6</joint>

使用 orbbec_description 包中的型号模型（Astra 2 对应 urdf/astra_2.urdf.xacro）时，模型的根坐标系为 camera_link，其下已包含与驱动一致的 camera_depth_frame、camera_color_frame 等坐标系。只需把 camera_link 固定连接到机体即可，无需再补内部变换。

⚠️ 平移与旋转取值对应相机的实际安装位置与朝向，务必量测后填入，否则点云在机体坐标系中会整体偏移。

35 / DOCUMENTATION

深度图与彩色图的帧对齐

ROS 2 Humble / Jazzy / Lyrical

深度流与彩色流属于不同的光学坐标系，两者之间有固定的外参。若要直接读取彩色图与深度图同一像素位置，可在启动时开启深度到彩色的对齐（参数 depth_registration、align_mode、enable_d2c_viewer，见 Ubuntu平台 / 02）。对齐后图像与点云使用彩色相机坐标系。

在不对齐的情况下，深度图与彩色图按同样的像素坐标读取时，不指向同一空间点。

36 / DOCUMENTATION

数据形态选择

ROS 2 Humble / Jazzy / Lyrical

任务	首选数据	原因
避障、距离检测	深度图直接订阅，或 `depth/points` 点云	点云更直观、可在 RViz2 直接看，但更耗带宽
目标检测、语义分割	彩色图	颜色与纹理信息完整
建图、抓取、位姿估计	点云 `depth/points` 或彩色点云	需要三维几何
暗光环境成像	红外图	红外指令存在时适用

点云是按需生成的：默认 enable_point_cloud:=true，若机器人自研节点不需要三维点，可关闭以节省 CPU 与带宽：

1ros2 launch orbbec_camera astra2.launch.py enable_point_cloud:=false

彩色点云（深度注册到彩色帧）由 enable_colored_point_cloud:=true 控制，生成开销高于普通点云，仅在确实需要带颜色点云时开启。

37 / DOCUMENTATION

分辨率、帧率与带宽

ROS 2 Humble / Jazzy / Lyrical

相机按启动参数输出指定分辨率与帧率。分辨率与帧率越高，占用的 USB 带宽、主机 CPU（解码、点云生成）与发布带宽越大。按算力调节的主要参数：

参数	作用
`depth_width` / `depth_height` / `depth_fps`	深度流分辨率与帧率
`color_width` / `color_height` / `color_fps`	彩色流分辨率与帧率
`ir_width` / `ir_height` / `ir_fps`	红外流分辨率与帧率
`enable_depth` / `enable_color` / `enable_ir`	关闭不需要的流
`color_format`	`MJPG`（默认，省带宽）或 `YUYV` / `RGB`
`enable_point_cloud`	关闭点云生成

示例：嵌入式主机上只保留避障所需的深度流，降低分辨率：

1ros2 launch orbbec_camera astra2.launch.py 2  enable_color:=false enable_ir:=false 3  depth_width:=400 depth_height:=300 depth_fps:=15

⚠️ 流的分辨率与帧率必须在 list_camera_profile_mode_node 列出的组合内取值，否则节点启动失败。查询该产品支持的所有流组合：

1ros2 run orbbec_camera list_camera_profile_mode_node

38 / DOCUMENTATION

其它机器人相关参数

ROS 2 Humble / Jazzy / Lyrical

参数	取值 / 作用
`camera_name`	命名空间；多相机时改为各自独立命名，避免话题冲突
`serial_number`	多相机时指定具体设备；单相机可留空
`usb_port`	多相机时指定设备所在 USB 端口
`time_domain`	`global` 用系统时间戳，`device` 用设备时间戳
`enable_frame_sync`	深度与彩色帧同步；同版本下按启动文件默认即可
`publish_tf`	是否发布相机内部 TF（默认开启）

多相机场景的参数组织方式，见驱动文档的多相机章节。

39 / DOCUMENTATION

机器人开发流程建议

ROS 2 Humble / Jazzy / Lyrical

先在主机确认出图：跑通 Ubuntu平台 / 02 的 RViz2 查看流程，确认相机本身正常。
再接到机器人：把相机装到机器人、量测安装位姿，写入 URDF 静态变换。
调资源：用 ros2 topic hz 观察实际帧率，用 ros2 topic bw 观察带宽，必要时降分辨率、关点云。
写感知节点：订阅所需话题，按通用 02 的编码与坐标系说明取数。
录制回归：用 ros2 bag record 录制一份数据，便于不接相机时离线调试与回放。

返回品牌技术文档

浏览同品牌产品和相关 Wiki。

40 / SUPPORT

讨论、纠错与持续维护

Forum / GitHub / Community

FORUM产品讨论

提交硬件、版本、日志和复现步骤。

进入 Forum GITHUBIssue 与任务

跟踪驱动、SDK 和示例代码问题。

打开 GitHub