Merge branch 'v2/develop' into v2-main

2026-10-04 20:17:47 +08:00 · 2026-08-21 15:21:08 +08:00
parent 8e7cad2bfa 50fa1d20fe
commit cee38ebf5e
179 changed files with 23270 additions and 4686 deletions
@@ -5,47 +5,34 @@
  </a>
  <h1><a href="https://github.com/orbbec/OrbbecSDK_ROS2">OrbbecSDK ROS2 Wrapper v2</a></h1>

-<!-- Language: -->
-  <p align="center">
-    <a href="./README.MD">English</a> | <a href="./README_CN.MD">中文</a>
-  </p>
-
-<!-- Labels: -->
-  <!-- First row: -->
-  <a href="https://docs.ros.org/en/foxy/">
-    <img src="https://img.shields.io/badge/ROS-Foxy-f5792a?style=flat-square&amp;logo=ros&amp;logoColor=white" height="20" alt="ROS Foxy">
-  </a>
-  <a href="https://docs.ros.org/en/humble/">
-    <img src="https://img.shields.io/badge/ROS-Humble-f5792a?style=flat-square&amp;logo=ros&amp;logoColor=white" height="20" alt="ROS Humble">
-  </a>
-  <a href="https://docs.ros.org/en/jazzy/">
-    <img src="https://img.shields.io/badge/ROS-Jazzy-f5792a?style=flat-square&amp;logo=ros&amp;logoColor=white" height="20" alt="ROS Jazzy">
-  </a>
-  <img src="https://img.shields.io/badge/Ubuntu-20.04-0078d4?style=flat-square&amp;logo=ubuntu&amp;logoColor=white" height="20" alt="Ubuntu 20.04">
-  <img src="https://img.shields.io/badge/Ubuntu-22.04-0078d4?style=flat-square&amp;logo=ubuntu&amp;logoColor=white" height="20" alt="Ubuntu 22.04">
-  <img src="https://img.shields.io/badge/Ubuntu-24.04-0078d4?style=flat-square&amp;logo=ubuntu&amp;logoColor=white" height="20" alt="Ubuntu 24.04">
-
-  <!-- Second row: -->
-  <br>
-  <a href="https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main">
-    <img src="https://img.shields.io/badge/branch-v2--main-555555?style=flat-square" height="20" alt="branch v2-main">
-  </a>
-  <a href="http://www.apache.org/licenses/LICENSE-2.0">
-    <img src="https://img.shields.io/badge/license-Apache--2.0-6bcf00?style=flat-square" height="20" alt="license Apache-2.0">
-  </a>
-  <a href="https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2">
-    <img src="https://img.shields.io/badge/Gitee-mirror-c71d23?style=flat-square" height="20" alt="Gitee mirror">
-  </a>
-</div>
-
 ## 简介

-OrbbecSDK ROS2 Wrapper 提供 Orbbec 相机与 ROS 2 环境的无缝集成，支持 **ROS2 Foxy、Humble 和 Jazzy** 发行版。
+OrbbecSDK ROS2 Wrapper 提供 Orbbec 相机与 ROS 2 环境的无缝集成，支持 **ROS2 Foxy、Humble、Jazzy 和 Lyrical** 发行版，并提供对 **Rolling** 的实验性支持。

 - 默认推荐使用 **v2-main** 分支。
 - 对于旧的 **OpenNI** 设备（v2-main 不支持），请使用 **main** 分支。
 - 如果您在中国使用，建议使用 [gitee 仓库](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2)。

+## 从这里开始
+
+完整的使用方法、参数说明和故障排查统一维护在官方
+[OrbbecSDK ROS2 文档站](https://orbbec.github.io/OrbbecSDK_ROS2/zh/index.html)。
+请根据您的目标直接进入对应指南。
+
+| 我想要……                           | 请查看……                                                                                                             |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| 安装驱动并配置设备权限               | [安装指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/2_installation/installation.html)           |
+| 启动相机并在 RViz2 中查看图像        | [ROS 包快速入门](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/3_quickstarts/quickstart.html)        |
+| 确认设备支持、固件版本和启动文件     | [支持的硬件](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/1_overview/introduction.html)             |
+| 配置启动参数、话题、服务、TF 或点云  | [应用指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/4_application_guide/application_guide.html) |
+| 查找维护、诊断、性能测试或多相机工具 | [工具索引](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/6_benchmark/tools.html)                     |
+| 使用网络相机、GMSL、多相机或高级模式 | [高级指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/advanced_guide.html)       |
+| 排查故障或收集技术支持所需日志       | [常见问题](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/8_FAQ/FAQ.html)                             |
+| 将现有项目从 main (v1.x) 迁移        | [迁移指南](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/7_developer_guide/migration_guide.html)     |
+| 使用 Orbbec LiDAR                    | [LiDAR 文档](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/lidar_devices/index.html)                                |
+
+实用启动示例的源文件可在[示例索引](./orbbec_camera/examples/)中查找。
+
 ## 分支选择

 以下是 main 分支 (v1.x) 和 v2-main 分支 (v2.x) 的设备支持列表：
@@ -235,9 +222,17 @@ OrbbecSDK ROS2 Wrapper 提供 Orbbec 相机与 ROS 2 环境的无缝集成，支

 **环境配置**

-根据官方指南安装 ROS 2：
+根据相应的官方指南安装一个受支持的 ROS 2 发行版：

-* [ROS 2 安装指南（Ubuntu）](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html)
+* [Foxy](https://docs.ros.org/en/foxy/)
+* [Humble](https://docs.ros.org/en/humble/)
+* [Jazzy](https://docs.ros.org/en/jazzy/)
+
+执行后续命令前，请先加载 ROS 2 环境：
+
+```bash
+source /opt/ros/humble/setup.bash  # 根据需要将 humble 替换为 foxy 或 jazzy
+```

 安装依赖项：

@@ -265,10 +260,10 @@ sudo apt update
 apt list | grep orbbec
 ```

-安装 OrbbecSDK ROS2 包：
+如果当前 ROS 2 发行版提供二进制包，可使用以下命令安装 OrbbecSDK ROS2：

 ```bash
-sudo apt install ros-humble-orbbec-camera ros-humble-orbbec-description
+sudo apt install ros-${ROS_DISTRO}-orbbec-camera ros-${ROS_DISTRO}-orbbec-description
 ```

 安装完成后，直接使用即可，无需编译。
@@ -296,6 +291,7 @@ git checkout v2-main
 cd ~/ros2_ws
 colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
 ```
+
 ## 注册脚本（必需）

 为了让 Orbbec 相机在 Linux 上被正确识别，请安装 udev 规则。
@@ -312,12 +308,11 @@ sudo udevadm control --reload-rules && sudo udevadm trigger
 ```bash
 cd  ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
 sudo bash install_udev_rules.sh
-sudo udevadm control --reload-rules && sudo udevadm trigger
 ```

 此步骤对于 Linux 用户是**必需的**。

-`注意：` 如果不执行此脚本，由于权限问题，打开设备将会失败。您需要使用 sudo（管理员权限）运行示例程序。
+> **注意：** 如果未安装 udev 规则，可能因权限不足而无法打开设备。请正确安装规则并重新插拔相机，不建议使用 `sudo` 运行 ROS 2 节点。

 ## 快速开始

@@ -364,7 +359,7 @@ ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'

 ## 支持的设备

-目前 v2-main 分支支持以下设备。更多设备支持将陆续增加。如果没有找到您的设备，请尝试 [main](https://github.com/orbbec/OrbbecSDK_ROS2) 分支。
+目前 v2-main 分支支持以下设备。更多设备支持将陆续增加。如果没有找到您的设备，请尝试 [main](https://github.com/orbbec/OrbbecSDK_ROS2/tree/main) 分支。

 为获得最佳性能，强烈建议更新至最新固件版本，以确保您能获得最新的改进和 bug 修复。

@@ -486,17 +481,10 @@ ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString '{}'

 所有启动文件基本相似，主要区别在于针对不同型号的默认参数设置。不同的 USB 标准（如 USB 2.0 和 USB 3.0）可能需要调整这些参数。如果遇到启动失败，请仔细查看规格说明书，特别是启动文件中的分辨率设置以及其他参数，以确保兼容性和最佳性能。

-## 教程
-
-请参考官方 [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/zh/source/camera_devices/5_advanced_guide/advanced_guide.html)
-
-## 示例
-
-要查看更多实践示例并了解如何在 ROS 中使用相机，请参阅 [Examples](./orbbec_camera/examples/) 部分。
-
-## 其他有用链接
+## 相关链接

 - [OrbbecSDK ROS2 文档](https://orbbec.github.io/OrbbecSDK_ROS2/zh/index.html)
+- [示例索引](./orbbec_camera/examples/)
 - [OrbbecSDK_v2](https://github.com/orbbec/OrbbecSDK_v2/releases)
 - [Gemini 330 深度预设](https://www.orbbec.com/docs/g330-use-depth-presets/)