WSL2 + Orbbec Gemini 336L + RTAB-Map ROS2 RGB-D SLAM 教程

本文记录在 Windows + WSL2 Ubuntu + ROS2 Jazzy 环境中，使用奥比中光 Gemini 336L 相机启动 RTAB-Map，运行 RGB-D SLAM，并在 RViz2 / rtabmap_viz 中查看建图结果的完整流程。

1. 整体流程

当前系统链路是：

Orbbec Gemini 336L
  -> usbipd-win 透传到 WSL2
  -> OrbbecSDK_ROS2 发布 RGB / Depth / PointCloud / TF
  -> RTAB-Map 订阅 RGB + Depth + CameraInfo
  -> RGB-D Odometry + 图优化 + 回环检测
  -> RViz2 / rtabmap_viz 显示地图、点云、TF、轨迹

这套流程跑的是：

RTAB-Map RGB-D SLAM

注意：当前命令使用的是相机驱动发布的 RGB 图像和 Depth 深度图，不是直接使用左右目图像，也没有使用 IMU。

2. 前提环境

已安装：

WSL2 Ubuntu
ROS2 Jazzy
OrbbecSDK_ROS2
RTAB-Map ROS2

相机已经通过 usbipd-win 透传到 WSL2，并且在 WSL 中可以被识别：

lsusb

正常输出应包含：

Bus 002 Device 002: ID 2bc5:0807 Orbbec 3D Technology International, Inc Orbbec Gemini 336L

其中 2bc5:0807 是 Gemini 336L 的 USB VID/PID。

3. 启动前检查 USB 权限

根据 lsusb 中的 Bus 和 Device，检查 USB 设备文件权限。

例如相机是：

Bus 002 Device 002

对应路径是：

/dev/bus/usb/002/002

查看权限：

ls -l /dev/bus/usb/002/002

如果后面启动相机时报：

openUsbDevice failed
Failed to initialize device usbEnumerator openUsbDevice failed! status:113

可以临时放开权限：

sudo chmod 666 /dev/bus/usb/002/002

注意：相机 reset、拔插、重新 attach 后，Device 号可能变化。比如变成 Bus 002 Device 003，就要改成：

sudo chmod 666 /dev/bus/usb/002/003

4. 启动 Orbbec 相机驱动

打开第一个 WSL 终端：

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch orbbec_camera gemini_330_series.launch.py

Gemini 336L 属于 Gemini 330 系列，所以使用：

gemini_330_series.launch.py

启动过程中如果出现：

Device reset complete
startDevice called
Connecting to the default device

随后没有错误，并且相机开始发布话题，就说明驱动基本正常。

5. 检查相机 ROS2 话题

打开第二个 WSL 终端：

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 topic list

当前已经确认可以看到这些话题：

/camera/color/camera_info
/camera/color/image_raw
/camera/color/metadata
/camera/depth/camera_info
/camera/depth/image_raw
/camera/depth/metadata
/camera/depth/points
/camera/depth_filter_status
/camera/depth_filters/status
/camera/device_status
/diagnostics
/parameter_events
/rosout
/tf
/tf_static

其中 RTAB-Map 最重要的是：

/camera/color/image_raw
/camera/color/camera_info
/camera/depth/image_raw
/camera/depth/camera_info
/tf
/tf_static

点云查看常用：

/camera/depth/points

6. 检查话题类型和频率

查看 RGB 图像类型：

ros2 topic info /camera/color/image_raw

正常应为：

sensor_msgs/msg/Image

查看深度图类型：

ros2 topic info /camera/depth/image_raw

正常应为：

sensor_msgs/msg/Image

查看点云类型：

ros2 topic info /camera/depth/points

正常应为：

sensor_msgs/msg/PointCloud2

查看发布频率：

ros2 topic hz /camera/color/image_raw
ros2 topic hz /camera/depth/image_raw

如果频率稳定，说明相机数据流正常。

7. 查看相机坐标系 frame_id

RTAB-Map 和 RViz2 都依赖坐标系。可以查看图像消息中的 frame_id：

ros2 topic echo /camera/color/image_raw --once

关注：

header:
  frame_id: xxx

也可以查看深度图：

ros2 topic echo /camera/depth/image_raw --once

如果后面 RTAB-Map 报 TF 错误，通常需要根据这里的 frame_id 调整启动参数。

8. 安装 RTAB-Map ROS2

如果还没有安装 RTAB-Map：

source /opt/ros/jazzy/setup.bash
sudo apt update
sudo apt install ros-jazzy-rtabmap-ros

确认安装成功：

ros2 pkg list | grep rtabmap

常见包包括：

rtabmap_launch
rtabmap_odom
rtabmap_slam
rtabmap_sync
rtabmap_viz

查看 RTAB-Map launch 参数：

ros2 launch rtabmap_launch rtabmap.launch.py --show-args

9. 启动 RTAB-Map RGB-D SLAM

保持第一个终端中的 Orbbec 相机驱动继续运行。

打开新的 WSL 终端：

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash

运行 RTAB-Map：

ros2 launch rtabmap_launch rtabmap.launch.py \
  rgb_topic:=/camera/color/image_raw \
  depth_topic:=/camera/depth/image_raw \
  camera_info_topic:=/camera/color/camera_info \
  frame_id:=camera_link \
  approx_sync:=true \
  rtabmap_args:="--delete_db_on_start" \
  rviz:=true

这条命令的含义：

rgb_topic                 彩色图像输入
depth_topic               深度图输入
camera_info_topic         彩色相机内参输入
frame_id                  RTAB-Map 使用的参考坐标系
approx_sync               允许 RGB、Depth、CameraInfo 近似时间同步
--delete_db_on_start      每次启动删除旧地图数据库，重新建图
rviz:=true                自动启动 RViz2

这条命令启动的是：

RGB-D SLAM

不是 stereo-inertial SLAM。当前没有使用 IMU。

10. 如果需要 QoS 兼容

如果 RTAB-Map 没有收到图像或深度，可能是 QoS 不匹配。可以增加：

qos:=2

完整命令：

ros2 launch rtabmap_launch rtabmap.launch.py \
  rgb_topic:=/camera/color/image_raw \
  depth_topic:=/camera/depth/image_raw \
  camera_info_topic:=/camera/color/camera_info \
  frame_id:=camera_link \
  approx_sync:=true \
  qos:=2 \
  rtabmap_args:="--delete_db_on_start" \
  rviz:=true

11. 两个可视化界面分别是什么

启动后通常会出现两个界面：

RTAB-Map 自带界面 rtabmap_viz
RViz2

rtabmap_viz

窗口标题类似：

RTAB-Map* [ROS]

它主要用于查看 RTAB-Map 内部状态：

当前 RGB 图像
当前深度图
Odometry 状态
回环检测
地图节点 ID
3D Map
RTAB-Map 数据库状态

界面中常见区域：

Loop closure detection
Odometry
3D Map

如果看到：

New ID = 53

说明 RTAB-Map 已经创建了地图节点。

RViz2

RViz2 是 ROS2 的通用可视化工具。

它可以查看：

TF
点云
地图
轨迹
相机云
RTAB-Map 输出的 map graph

常见 Display：

Grid
MapCloud
MapGraph
TF
Map
Odom Local Map
Camera Cloud

两者区别：

rtabmap_viz 看 RTAB-Map 内部状态
RViz2 看 ROS2 系统输出结果

12. RViz2 中查看点云

如果只想看 Orbbec 相机点云，可以单独启动：

rviz2

在 RViz2 中设置：

Global Options -> Fixed Frame

Fixed Frame 可以先设置成点云消息里的 frame_id。

查看点云 frame：

ros2 topic echo /camera/depth/points --once

关注：

header:
  frame_id: xxx

然后在 RViz2 中：

Add -> By display type -> PointCloud2
Topic -> /camera/depth/points

如果看不到点云，可以把 PointCloud2 的：

Reliability Policy

改成：

Best Effort

13. Fixed Frame 是什么

Fixed Frame 是 RViz2 的世界参考坐标系。

可以理解为：

RViz2 以哪个坐标系作为固定不动的世界

例如点云消息的坐标系是：

camera_depth_optical_frame

如果 RViz2 的 Fixed Frame 设置为：

camera_depth_optical_frame

点云可以直接显示。

如果 Fixed Frame 设置为：

map

RViz2 需要 TF 中存在：

map -> camera_depth_optical_frame

否则会报：

No transform from camera_depth_optical_frame to map

RTAB-Map 正常运行后，常见 TF 链路是：

map -> odom -> camera_link -> camera optical frame

此时 RViz2 的 Fixed Frame 通常设置为：

map

14. 移动相机时的注意事项

为了让 RTAB-Map 更稳定：

移动慢一点
不要快速甩动相机
尽量看有纹理的区域
避免纯白墙、玻璃、强反光、黑色大面积物体
保持画面有重叠
平移和小角度旋转结合

适合测试的场景：

桌子
椅子
书架
地图海报
门框
键盘
墙角

不适合一开始测试的场景：

纯白墙
玻璃
镜面
黑色衣服
强反光桌面
快速移动的人

15. 怎么判断 SLAM 正在正常运行

观察 rtabmap_viz：

New ID 是否持续增加
Odometry 是否有图像更新
3D Map 是否逐渐扩展

观察 RViz2：

点云地图是否变大
TF 坐标轴是否平滑移动
MapGraph 是否增加节点
Fixed Frame 状态是否 OK

观察终端：

是否有 Odometry lost
是否有 TF error
是否有 sync warning
是否持续收到 RGB / Depth 数据

如果节点增加、地图变大、没有频繁丢失里程计，说明 RTAB-Map 正在正常跑 SLAM。

16. 常见问题

RTAB-Map 没有画面或没建图

检查相机话题是否存在：

ros2 topic list

检查频率：

ros2 topic hz /camera/color/image_raw
ros2 topic hz /camera/depth/image_raw

尝试加 QoS：

qos:=2

RViz2 报 Fixed Frame / TF 错误

查看点云或图像的 frame_id：

ros2 topic echo /camera/depth/points --once
ros2 topic echo /camera/color/image_raw --once

将 RViz2 的 Fixed Frame 设成消息中的 frame_id，或者确保 TF 中存在从 map 到该 frame 的变换。

深度图中有黑色区域

黑色区域通常表示：

无效深度
低置信度深度
双目匹配失败

常见原因：

物体太近或太远
低纹理
黑色/反光/透明表面
边缘遮挡
光照不足

少量黑洞是正常现象。

运行一段时间后里程计丢失

常见原因：

移动太快
画面模糊
纹理太少
深度空洞太多
光照变化太大
相机对着纯墙或反光面

解决方式：

放慢移动
增加环境纹理
改善光照
避免强反光
保持相机稳定

17. 推荐终端布局

建议至少开三个终端：

终端 1：相机驱动

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch orbbec_camera gemini_330_series.launch.py

终端 2：RTAB-Map

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch rtabmap_launch rtabmap.launch.py \
  rgb_topic:=/camera/color/image_raw \
  depth_topic:=/camera/depth/image_raw \
  camera_info_topic:=/camera/color/camera_info \
  frame_id:=camera_link \
  approx_sync:=true \
  qos:=2 \
  rtabmap_args:="--delete_db_on_start" \
  rviz:=true

终端 3：检查话题

source /opt/ros/jazzy/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 topic list
ros2 topic hz /camera/color/image_raw
ros2 topic hz /camera/depth/image_raw

18. 后续方向

当前已经跑通：

RGB-D SLAM

后续可以继续学习：

保存 RTAB-Map 数据库
rosbag 录制和回放
接入 IMU
接入激光雷达
导出点云/PLY
接 Nav2 导航
多 session 建图

建议下一步优先学习：

ros2 bag record / play
RTAB-Map 数据库保存和复盘
RViz2 中查看 MapGraph / TF / PointCloud2