WSL2 + Orbbec Gemini 336L + RTAB-Map ROS2 RGB-D SLAM 教程
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可以临时放开权限：
sudochmod666/dev/bus/usb/002/002注意：相机 reset、拔插、重新 attach 后，Device 号可能变化。比如变成Bus 002 Device 003，就要改成：
sudochmod666/dev/bus/usb/002/0034. 启动 Orbbec 相机驱动
打开第一个 WSL 终端：
source/opt/ros/jazzy/setup.bashsource~/ros2_ws/install/setup.bash ros2 launch orbbec_camera gemini_330_series.launch.pyGemini 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.bashsource~/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/points6. 检查话题类型和频率
查看 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 topicecho/camera/color/image_raw--once关注：
header:frame_id:xxx也可以查看深度图：
ros2 topicecho/camera/depth/image_raw--once如果后面 RTAB-Map 报 TF 错误，通常需要根据这里的frame_id调整启动参数。
8. 安装 RTAB-Map ROS2
如果还没有安装 RTAB-Map：
source/opt/ros/jazzy/setup.bashsudoaptupdatesudoaptinstallros-jazzy-rtabmap-ros确认安装成功：
ros2 pkg list|greprtabmap常见包包括：
rtabmap_launch rtabmap_odom rtabmap_slam rtabmap_sync rtabmap_viz查看 RTAB-Map launch 参数：
ros2 launch rtabmap_launch rtabmap.launch.py --show-args9. 启动 RTAB-Map RGB-D SLAM
保持第一个终端中的 Orbbec 相机驱动继续运行。
打开新的 WSL 终端：
source/opt/ros/jazzy/setup.bashsource~/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:=true11. 两个可视化界面分别是什么
启动后通常会出现两个界面：
RTAB-Map 自带界面 rtabmap_viz RViz2rtabmap_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 FrameFixed Frame 可以先设置成点云消息里的frame_id。
查看点云 frame：
ros2 topicecho/camera/depth/points--once关注：
header:frame_id:xxx然后在 RViz2 中：
Add -> By display type -> PointCloud2 Topic -> /camera/depth/points如果看不到点云，可以把 PointCloud2 的：
Reliability Policy改成：
Best Effort13. Fixed Frame 是什么
Fixed Frame是 RViz2 的世界参考坐标系。
可以理解为：
RViz2 以哪个坐标系作为固定不动的世界例如点云消息的坐标系是：
camera_depth_optical_frame如果 RViz2 的 Fixed Frame 设置为：
camera_depth_optical_frame点云可以直接显示。
如果 Fixed Frame 设置为：
mapRViz2 需要 TF 中存在：
map -> camera_depth_optical_frame否则会报：
No transform from camera_depth_optical_frame to mapRTAB-Map 正常运行后，常见 TF 链路是：
map -> odom -> camera_link -> camera optical frame此时 RViz2 的 Fixed Frame 通常设置为：
map14. 移动相机时的注意事项
为了让 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:=2RViz2 报 Fixed Frame / TF 错误
查看点云或图像的frame_id：
ros2 topicecho/camera/depth/points--onceros2 topicecho/camera/color/image_raw--once将 RViz2 的 Fixed Frame 设成消息中的frame_id，或者确保 TF 中存在从map到该 frame 的变换。
深度图中有黑色区域
黑色区域通常表示：
无效深度 低置信度深度 双目匹配失败常见原因：
物体太近或太远 低纹理 黑色/反光/透明表面 边缘遮挡 光照不足少量黑洞是正常现象。
运行一段时间后里程计丢失
常见原因：
移动太快 画面模糊 纹理太少 深度空洞太多 光照变化太大 相机对着纯墙或反光面解决方式：
放慢移动 增加环境纹理 改善光照 避免强反光 保持相机稳定17. 推荐终端布局
建议至少开三个终端：
终端 1：相机驱动
source/opt/ros/jazzy/setup.bashsource~/ros2_ws/install/setup.bash ros2 launch orbbec_camera gemini_330_series.launch.py终端 2：RTAB-Map
source/opt/ros/jazzy/setup.bashsource~/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.bashsource~/ros2_ws/install/setup.bash ros2 topic list ros2 topic hz /camera/color/image_raw ros2 topic hz /camera/depth/image_raw18. 后续方向
当前已经跑通：
RGB-D SLAM后续可以继续学习：
保存 RTAB-Map 数据库 rosbag 录制和回放 接入 IMU 接入激光雷达 导出点云/PLY 接 Nav2 导航 多 session 建图建议下一步优先学习：
ros2 bag record / play RTAB-Map 数据库保存和复盘 RViz2 中查看 MapGraph / TF / PointCloud2