ZED 2i + ROS 2 配置记录

ZED 2i + ROS 2 配置记录

更新日期：2026-08-15
主机：idsse-MU72-SU0-00

1. 本机软硬件基线

操作系统

Ubuntu 26.04 的 GNOME 使用 Wayland。ZED Explorer 和 RViz 在本机的原生
Wayland/NVIDIA 图形路径上会闪烁，因此需要针对这两个程序使用兼容启动方式。

主要硬件

本机同时具有 ASPEED 板载显卡和四张 RTX 4090。桌面显示、Wayland、XWayland
和 NVIDIA PRIME 跨 GPU 渲染同时存在，是 RViz 使用 4090 渲染时闪烁的主要背景。

摄像头

ZED 2i 的左右图像是硬件同步后以左右并排形式输出的，并不等同于两台完全
独立的普通 USB 摄像头。常用的 HD720 模式输出为 2560×720，左右各 1280×720。

2. 已安装的软件版本

ROS 2 Lyrical 是与 Ubuntu 26.04 对应的 LTS 版本。不要在该系统上直接混装面向
Ubuntu 22.04 的 Humble 或面向 Ubuntu 24.04 的 Jazzy 软件包。

3. 目录布局

/opt/ros/lyrical/                       ROS 2 Lyrical
/usr/local/zed/                         ZED SDK 5.4.1
/usr/local/cuda-13.3/                   CUDA Toolkit
~/ros2_ws/                              ROS 2 工作空间
├── src/
│   ├── zed-ros2-wrapper/
│   └── zed-ros2-examples/
├── build/
├── install/
└── log/

4. ROS 2 与 ZED 工作空间构建

避免 Conda 干扰 ROS

本机 Miniconda 位于 ~/miniconda3，其 Python 3.9 曾被 CMake 自动选中，导致：

ModuleNotFoundError: No module named 'catkin_pkg'

ROS 2 Lyrical 应使用 Ubuntu 系统 Python。每次构建前执行：

conda deactivate
source /opt/ros/lyrical/setup.bash
which python3

最后一条应显示：

/usr/bin/python3

建议关闭 Conda base 自动激活：

conda config --set auto_activate_base false

源码准备

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src

git clone --recursive https://github.com/stereolabs/zed-ros2-wrapper.git
git clone https://github.com/stereolabs/zed-ros2-examples.git

安装依赖：

source /opt/ros/lyrical/setup.bash
cd ~/ros2_ws

rosdep update
rosdep install \
  --from-paths src \
  --ignore-src \
  -r -y \
  --skip-keys scout_description

推荐构建命令

只构建 ZED Wrapper 和 RViz 显示所需包，避免无关教程的兼容问题：

conda deactivate
source /opt/ros/lyrical/setup.bash
cd ~/ros2_ws

colcon build \
  --packages-up-to zed_display_rviz2 \
  --symlink-install \
  --cmake-clean-cache \
  --cmake-args \
    -DCMAKE_BUILD_TYPE=Release \
    -DPython3_EXECUTABLE=/usr/bin/python3

构建成功后加载环境：

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

检查关键包：

ros2 pkg prefix zed_wrapper
ros2 pkg prefix zed_display_rviz2

5. 稳定启动方式

ZED Explorer

直接在 Wayland 下启动时，ZED Explorer 会闪烁且不显示画面。使用 XWayland
后已经验证能够稳定显示：

pkill -f ZED_Explorer
QT_QPA_PLATFORM=xcb /usr/local/zed/tools/ZED_Explorer

当前 ~/.bashrc 已配置 zed-explorer 别名，因此日常可直接执行：

zed-explorer

ROS 节点与 RViz 分开启动

推荐分开启动，便于排障，并避免重复占用相机。

终端一，启动 ZED 2i 节点：

conda deactivate
source /opt/ros/lyrical/setup.bash
source ~/ros2_ws/install/setup.bash

ros2 launch zed_wrapper zed_camera.launch.py camera_model:=zed2i

终端二，启动 RViz：

conda deactivate
source /opt/ros/lyrical/setup.bash
source ~/ros2_ws/install/setup.bash

QT_QPA_PLATFORM=xcb \
LIBGL_ALWAYS_SOFTWARE=1 \
rviz2 -d "$(ros2 pkg prefix zed_display_rviz2)/share/zed_display_rviz2/rviz2/zed_stereo.rviz"

当前 ~/.bashrc 已配置 zed-rviz 别名，可直接执行：

zed-rviz

为什么 RViz 使用软件渲染

测试结论如下：

因此当前采用：

ZED 深度、点云、AI/CUDA 计算 → RTX 4090
RViz 窗口/OpenGL 显示          → 软件渲染

LIBGL_ALWAYS_SOFTWARE=1 只控制 RViz 的 OpenGL 显示，不会关闭 ZED SDK 的
CUDA 深度计算。显示高密度点云时软件渲染可能较慢，可在 RViz 中降低点大小、
降低点云发布频率，或不需要时关闭 fused cloud。

6. 今天遇到的问题与处理结果

6.1 ZED Explorer 闪烁且没有画面

现象包括：

qt.qpa.wayland: Wayland does not support QWindow::requestActivate()

原因：ZED Explorer 的 Qt/OpenGL 界面与本机 Wayland 图形路径兼容不佳。

解决：

QT_QPA_PLATFORM=xcb /usr/local/zed/tools/ZED_Explorer

6.2 请求的帧率不受当前分辨率支持

日志：

The requested FPS (30 fps) is not supported at the current resolution.
Using 15 fps instead.

这不是故障。ZED 2i 常用模式如下：

机器人实时应用建议先使用 HD720 30 FPS。

6.3 ROS 构建找不到 catkin_pkg

原因：CMake 缓存了 Miniconda 的 Python：

/home/idsse/miniconda3/bin/python3

解决：退出 Conda、清理 CMake 缓存，并显式指定：

-DPython3_EXECUTABLE=/usr/bin/python3

6.4 找不到 zed_display_rviz2

原因：该包不在核心 zed-ros2-wrapper 仓库中，而位于独立的
zed-ros2-examples 仓库。

解决：克隆示例仓库并重新构建：

cd ~/ros2_ws/src
git clone https://github.com/stereolabs/zed-ros2-examples.git

6.5 local_setup.bash 不完整

错误：

not found: .../zed_tutorial_pos_tracking/local_setup.bash

真正的上游编译错误是 Lyrical 中 TF2 头文件由 .h 改为 .hpp，而示例教程
仍引用旧名称。构建失败后留下了不完整的 install 索引。

当前方案是不构建无关教程，只执行：

colcon build --packages-up-to zed_display_rviz2 ...

6.6 rviz_plugin_zed_od 的 Qt MOC 编译失败

原因：ROS 2 Lyrical 的 RViz 使用 Qt 6，而当前示例插件 CMake 文件仍显式查找
Qt 5，导致 Qt 5/Qt 6 头文件和 Qt 6 MOC 代码混合。

该插件只用于目标检测结果显示，不是查看普通图像、深度和点云所必需。
如确实需要，可将插件 CMake 文件中的 Qt5 全部改为 Qt6 后单独重建。

6.7 RViz 闪烁并以 exit code -11 崩溃

原因：本机 ASPEED + 四张 RTX 4090 + Wayland/XWayland + PRIME Offload 的
OpenGL 显示路径不稳定。

已验证的解决方式：

QT_QPA_PLATFORM=xcb LIBGL_ALWAYS_SOFTWARE=1 rviz2

6.8 Nav2 插件缺失

日志：

nav2_rviz_plugins/Navigation 2 failed to load

ZED 的预设 RViz 文件包含 Nav2 面板，但当前环境没有该插件。它不影响 ZED
图像、深度和点云显示，可以忽略，也可以复制 RViz 配置后删除下面两行：

- Class: nav2_rviz_plugins/Navigation 2
  Name: Navigation 2

6.9 Stereo is NOT SUPPORTED

这是 OGRE 关于专业四缓冲立体显示器的提示，与 ZED 双目摄像头无关，可以忽略。

7. 常用检查命令

检查 USB 和摄像头：

lsusb
lsusb -t
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --list-formats-ext

检查 GPU 和 CUDA：

nvidia-smi
/usr/local/cuda/bin/nvcc --version

检查 ROS 环境：

echo "$ROS_DISTRO"
which python3
ros2 pkg prefix zed_wrapper
ros2 pkg prefix zed_display_rviz2

检查节点和话题：

ros2 node list
ros2 topic list | grep zed
ros2 topic hz /zed/zed_node/left/image_rect_color
ros2 topic hz /zed/zed_node/point_cloud/cloud_registered

检查摄像头是否被占用：

sudo fuser -v /dev/video0 /dev/video1

8. 使用注意事项

1. 摄像头应直接连接主板 USB 3.x 接口，避免低质量 Hub 和延长线。
2. 同一时间不要让 ZED Explorer 和 ROS ZED 节点同时占用摄像头。
3. ROS 构建前退出 Conda，并确认 python3 是 /usr/bin/python3。
4. 启动 ZED Explorer 时使用 QT_QPA_PLATFORM=xcb。
5. 当前 RViz 使用软件 OpenGL 最稳定；ZED 的 CUDA 计算仍使用 RTX 4090。
6. 先以 HD720 30 FPS 调试，系统稳定后再提高分辨率或帧率。
7. 正式采集前检查镜头清洁、机械固定、曝光和白平衡。
8. 建议先录制一段 SVO，后续可在没有实机时重复回放和调试算法。

9. 当前建议的日常工作流

1. 连接 ZED 2i，确认 USB 3.0 / 5000 Mbps
2. 必要时用 zed-explorer 检查画面和相机状态
3. 关闭 ZED Explorer
4. 在终端一启动 zed_wrapper
5. 在终端二执行 zed-rviz
6. 用 ros2 topic hz 检查实际发布频率
7. 开始订阅图像、深度、点云或 IMU 数据

常用数据话题包括：

/zed/zed_node/left/image_rect_color
/zed/zed_node/depth/depth_registered
/zed/zed_node/point_cloud/cloud_registered
/zed/zed_node/mapping/fused_cloud

具体话题名称以运行时的 ros2 topic list 为准。