i/OrbbecSDK_ROS2
1
0
Fork 0
mirror of https://github.com/orbbec/OrbbecSDK_ROS2.git synced 2026-10-04 03:57:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add Chinese documentation for camera and lidar devices

Browse Source
This commit is contained in:
ob-yalian
2025-12-31 17:42:46 +08:00
parent c59af3d328
commit fd13aba31f
172 changed files with 466 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/source/camera_devices/1_overview/introduction.md
+267
View File
@@ -0,0 +1,267 @@
# 引言
OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它支持 ROS2 Foxy、Humble 和 Jazzy 发行版。
默认推荐使用 **v2-main** 分支。对于 v2-main 尚不支持的旧 OpenNI 设备，请使用 **main** 分支。仅由 main 分支支持的设备型号列在下表中。
如果您是中国用户，推荐使用 [gitee 仓库](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2)。
下面是 main 分支 (v1.x) 与 v2-main 分支 (v2.x) 的设备支持列表：
<table border="1" style="border-collapse: collapse; text-align: left; width: 100%;">
<thead>
<tr style="background-color: #1f4e78; color: white; text-align: center;">
<th>产品系列</th>
<th>产品</th>
<th><a href="https://github.com/orbbec/OrbbecSDK_ROS2/tree/main" style="color: black; text-decoration: none;">main 分支</a></th>
<th><a href="https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main" style="color: black; text-decoration: none;">v2-main 分支</a></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center; font-weight: bold;">Gemini 435Le</td>
<td>Gemini 435Le</td>
<td>not supported</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td rowspan="8" style="text-align: center; font-weight: bold;">Gemini 330</td>
<td>Gemini 335Le</td>
<td>not supported</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 335</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 336</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 330</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 335L</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 336L</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 330L</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 335Lg</td>
<td>not supported</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td rowspan="5" style="text-align: center; font-weight: bold;">Gemini 2</td>
<td>Gemini 2</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 2 L</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 2 XL</td>
<td>recommended for new designs</td>
<td>to be supported</td>
</tr>
<tr>
<td>Gemini 215</td>
<td>not supported</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Gemini 210</td>
<td>not supported</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td rowspan="3" style="text-align: center; font-weight: bold;">Femto</td>
<td>Femto Bolt</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Femto Mega</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Femto Mega I</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td rowspan="3" style="text-align: center; font-weight: bold;">Astra</td>
<td>Astra 2</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
<tr>
<td>Astra+</td>
<td>limited maintenance</td>
<td>not supported</td>
</tr>
<tr>
<td>Astra Pro Plus</td>
<td>limited maintenance</td>
<td>not supported</td>
</tr>
<tr>
<td style="text-align: center; font-weight: bold;">Astra Mini</td>
<td>Astra Mini (S) Pro</td>
<td>full maintenance</td>
<td>recommended for new designs</td>
</tr>
</tbody>
</table>
**注意**: 如果未找到您的设备，请联系我们的 FAE 或销售代表获取帮助。
**术语定义**:
1. 建议用于新设计：我们将提供完整支持，包括新特性、缺陷修复与性能优化；
2. 完整维护：我们将提供缺陷修复支持；
3. 限制维护：我们仅提供关键缺陷修复支持；
4. 不支持：当前版本不支持该设备；
5. 即将支持：近期将添加支持。
## 支持的硬件产品
以下设备由 OrbbecSDK ROS2 封装 v2-main 分支支持。后续将增加更多设备支持。如果您在下表中未找到设备，请尝试 [main](https://github.com/orbbec/OrbbecSDK_ROS2) 分支。
为获得最佳性能，强烈建议升级到最新固件版本，以确保获得最新的改进与缺陷修复。
关于如何获取与升级最新固件，[请点击这里](../3_quickstarts/orbbecviewer.md)。
| **产品列表** | **推荐固件版本** | **启动文件** |
| ----------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Astra Mini Pro | [2.0.03](https://github.com/orbbec/OrbbecFirmware/releases/tag/Astra-Mini-Pro) | astra.launch.py |
| Astra Mini S Pro | [2.0.03](https://github.com/orbbec/OrbbecFirmware/releases/tag/Astra-Mini-S-Pro) | astra.launch.py |
| Gemini 435Le | [1.3.2](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemin435Le-Firmware) | gemini435_le.launch.py |
| Gemini 330 series | [1.6.00](https://orbbec-debian-repos-aws.s3.amazonaws.com/product/Gemini330_Release_1.6.00.zip) | gemini_330_series.launch.py |
| Gemini 215 | [1.0.9](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini215-Firmware) | gemini210.launch.py |
| Gemini 210 | [1.0.9](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini210-Firmware) | gemini210.launch.py |
| Gemini 2 | [1.4.98](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini2-Firmware) | gemini2.launch.py |
| Gemini 2 L | [1.5.2](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini2L-Firmware) | gemini2L.launch.py |
| Femto Bolt | [1.1.2](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Bolt-Firmware) | femto_bolt.launch.py |
| Femto Mega | [1.3.1](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Mega-Firmware) | femto_mega.launch.py |
| Femto Mega I | [2.0.4](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Mega-I-Firmware) | femto_mega.launch.py |
| Astra 2 | [2.8.20](https://orbbec-debian-repos-aws.s3.amazonaws.com/product/Astra2_Release_2.8.20.zip) | astra2.launch.py |
所有启动文件本质上是类似的，主要区别在于同系列不同型号设置的参数默认值。USB 标准差异（如 USB 2.0 与 USB 3.0）可能需要调整这些参数。如果遇到启动失败，请仔细查看规格说明书，特别关注启动文件中的分辨率设置以及其他参数，以确保兼容与最佳性能。
## Orbbec 相机规格书
更多信息请参考相机规格书。
<style>
table {
border-collapse: collapse;
width: 100%;
}
th, td {
border: 1px solid #ccc;
padding: 8px;
text-align: left;
vertical-align: middle;
}
thead th {
background-color: #1f4e78;
color: white;
text-align: center;
vertical-align: middle;
}
</style>
<table>
<thead>
<tr>
<th>产品系列</th>
<th>产品</th>
<th>规格书</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: center;">Gemini 435Le</td>
<td>Gemini 435Le</td>
<td><a href="https://new-orbbec3d-s3.s3.amazonaws.com/wp-content/uploads/2025/06/04011158/Orbbec-Gemini-435Le-Datasheet-V1.pdf">Orbbec Gemini 435Le 规格书</a></td>
</tr>
<tr>
<td style="text-align: center;" rowspan="6">Gemini 330</td>
<td>Gemini 335</td>
<td rowspan="4"><a href="https://new-orbbec3d-s3.s3.amazonaws.com/wp-content/uploads/2025/04/22062452/Gemini-330-series-Datasheet-V1.6.pdf">Gemini 330 系列 USB 设备规格书</a></td>
</tr>
<tr><td>Gemini 336</td></tr>
<tr><td>Gemini 335L</td></tr>
<tr><td>Gemini 336L</td></tr>
<tr>
<td>Gemini 335Lg</td>
<td><a href="https://new-orbbec3d-s3.s3.amazonaws.com/wp-content/uploads/2024/10/22030914/Gemini-335Lg-Datasheet-V1.0-241022.pdf">Gemini 330 系列 GMSL 设备规格书</a></td>
</tr>
<tr>
<td>Gemini 335Le</td>
<td><a href="https://new-orbbec3d-s3.s3.amazonaws.com/wp-content/uploads/2025/03/24023151/Orbbec-Gemini-335Le-Datasheet-V1-2.pdf">Gemini 330 系列 以太网设备规格书</a></td>
</tr>
<tr>
<td style="text-align: center;" rowspan="3">Gemini 2</td>
<td>Gemini 2</td>
<td rowspan="2"><a href="https://xm917ch2uk.feishu.cn/file/Khxfb2vdioUghexIMqJcAyL3nXf">Orbbec Gemini 2 系列规格书</a></td>
</tr>
<tr><td>Gemini 2 L</td></tr>
<tr>
<td>Gemini 2 XL</td>
<td><a href="https://xm917ch2uk.feishu.cn/file/QW2vbNvwxoocRIxSL6Zcvut2npS">Orbbec Gemini 2 XL 规格书</a></td>
</tr>
<tr>
<td style="text-align: center;" rowspan="3">Femto</td>
<td>Femto Bolt</td>
<td><a href="https://d1cd332k3pgc17.cloudfront.net/wp-content/uploads/2024/08/ORBBEC_Datasheet_Femto-Bolt-v1.0.pdf">Orbbec Femto Bolt 规格书</a></td>
</tr>
<tr>
<td>Femto Mega</td>
<td><a href="https://d1cd332k3pgc17.cloudfront.net/wp-content/uploads/2023/04/ORBBEC_Datasheet_Femto-Mega1.pdf">Orbbec Femto Mega 规格书</a></td>
</tr>
<tr>
<td>Femto Mega I</td>
<td><a href="https://d1cd332k3pgc17.cloudfront.net/wp-content/uploads/2023/08/ORBBEC_Datasheet_Femto-Mega-I.pdf">Orbbec Femto Mega I 规格书</a></td>
</tr>
<tr>
<td style="text-align: center;" rowspan="3">Astra</td>
<td>Astra 2</td>
<td><a href="https://d1cd332k3pgc17.cloudfront.net/wp-content/uploads/2023/04/ORBBEC_Datasheet_Astra-2_V1.2.pdf">Orbbec Astra 2 规格书</a></td>
</tr>
<tr>
<td>Astra+</td>
<td><a href="https://xm917ch2uk.feishu.cn/file/Qk0zbx26Doh8XMxw0rIcOgQYnff">Orbbec Astra+ 规格书</a></td>
</tr>
<tr>
<td>Astra Mini Pro</td>
<td><a href="https://d1cd332k3pgc17.cloudfront.net/wp-content/uploads/2023/04/ORBBEC_Datasheet_Astra-Mini-Pro-1.pdf">Orbbec Astra Mini Pro 规格书</a></td>
</tr>
</tbody>
</table>
---
## 支持的平台
- Linux x64：已在 Ubuntu 22.04 上测试
- Linux ARM64：已在 NVIDIA Jetson AGX Orin、NVIDIA Jetson Orin NX、NVIDIA Jetson Orin Nano、NVIDIA Jetson AGX Xavier、NVIDIA Jetson Xavier NX 上测试
docs/zh/source/camera_devices/1_overview/orbbecsdk_overview.md
+106
View File
@@ -0,0 +1,106 @@
# Orbbec SDK 概述
本节介绍 C++ 版本的 Orbbec SDK。其架构和概念与 Python 包装器一致。
## 术语
| 序号 | 名称 | 说明 |
| --- | --- | --- |
| 1 | USB | 通用串行总线（Universal Serial Bus） |
| 2 | UVC | USB 视频类（USB Video Class） |
| 3 | Firmware | 3D 相机的固件 |
| 4 | Disparity | 视差是指从两个有一定距离的点观察同一目标时的方向差异。 |
| 5 | D2D (Disparity to depth) | 视差转深度是一种图像处理技术，用于将视差信息转换为深度信息。 |
| 6 | Hardware D2D | 视差转深度在设备内部实现，不占用主机的计算能力。 |
| 7 | Software D2D | 视差转深度，在 Orbbec SDK 中实现 |
| 8 | Depth point cloud | 深度点云，三维世界坐标系中点的坐标，可以使用深度相机的内参转换为点云。 |
| 9 | RGBD point cloud | 叠加了 RGB 信息的点云 |
| 10 | D2C | "深度到彩色"（Depth to Color）是一种对深度图像进行逐像素几何变换的功能。其结果是通过 D2C 变换将深度图像与其对应的彩色图像对齐，使我们能够通过在变换后的深度图像中使用相同图像坐标位置来定位彩色像素的深度信息。经过 D2C 变换后，我们生成一个与目标彩色图像大小相同的深度图像，其中图像内容表示彩色相机坐标系中的深度数据。换句话说，它重建了一个使用彩色相机的原点和尺寸"拍摄"的深度图像，其中每个像素与彩色相机的相应像素坐标匹配。 |
| 11 | Hardware D2C | 硬件 D2C 是指在相机内部执行深度到彩色变换的功能，相机直接输出 D2C 变换的结果。 |
| 12 | Software D2C | 使用 SDK 在主机端执行 D2C 计算。 |
| 13 | Frame aggregation (FrameSet) | 帧聚合，将深度、红外和彩色帧组合成一个帧集（Frameset），并通过管道调用。 |
| 14 | C2D | "彩色到深度"（Color to Depth）是一种对彩色图像进行逐像素几何变换的功能。其结果是通过 C2D 变换将彩色图像与其对应的深度图像对齐。 |
| 15 | MetaData | 帧元数据是一组参数（或属性），提供了帧生成时传感器配置和/或系统状态的快照。 |
| 16 | HDR | 高动态范围（High Dynamic Range，HDR）成像允许成像系统在极暗和极亮的场景中拍摄图像。我们提出了一种在主机 CPU 上运行的软件解决方案来实现此功能。它利用两个连续帧的数据，直接合成这两个深度图像，从而增强 16 位深度图像的动态范围。 |
| 17 | LDP | 激光近距离保护（Laser close-range protection） |
## Orbbec SDK v2 架构概述
![OrbbecSDK v2 软件架构](../image/Soft_Architecture.png)
- 应用层（Application）
OrbbecViewer、示例程序和用户应用程序实现。
- 接口和封装层（Interfaces and Encapsulation Layer）
OrbbecSDK 接口封装和包装器封装。
- 高级层（High-level Layer）
HighLevel 封装了核心业务组件，并使用管道（pipeline）向外部提供接口。
- 基础业务层（Basic business layer）
核心业务逻辑框架的实现。
- 平台抽象层（Platform abstraction layer）
跨平台组件抽象操作系统差异，提供统一的访问接口。
- 平台实现层（Platform implementation layer）
各平台的驱动实现。
## SDK 概念概述
- Context（上下文）
上下文提供一组设置，包括设备状态更改回调、日志级别等设置。Context 可以访问多个设备。
- Device（设备）
一个实际的硬件设备对应一个 Device 对象，用于获取设备的相关信息并控制其属性。
- Pipeline（管道）
HighLevel 对应的对象，封装了快速访问 SDK 的接口。它具有简单的功能，使用户能够快速上手并使用 SDK。
- Config（配置）
提供启用数据流、对齐模式和帧聚合模式的配置，用于控制数据输出的行为。
- StreamProfile（流配置）
流配置定义分辨率、帧率和编码格式等参数，还提供相机参数的管理。
- Frame（帧）
表示流中的一帧数据，还包含该帧数据的相关信息，如时间戳、类型等。
- Filter（滤镜）
主要指用于复合流 FrameSet 的一些算法处理模块，如点云算法处理。
- Record（录制）
录制功能，捕获数据流并将其保存为文件，以便后续分析或回放。
- Playback（回放）
回放功能，播放录制的文件，并支持控制回放速度和其他相关参数。
## SDK 编程模型
以下是 C++ 编程逻辑流程图。Python 的编程逻辑与之相同。
- 标准流程图：
![image.png](../image/Standard_Flowchart.png)
标准流程图演示了如何从设备列表创建设备、设置和获取参数，以及应用后处理滤镜。
- 使用默认配置的流程图（基于 OrbbecSDKConfig.xml 中的默认设置获取流）：
![image](../image/Default_Flowchart.png)
docs/zh/source/camera_devices/1_overview/overview.rst
+11
View File
@@ -0,0 +1,11 @@
概述
======================================================
本章节提供 Orbbec SDK 的概述，包括支持的产品、主要功能和架构。
.. toctree::
:maxdepth: 2
introduction.md
orbbecsdk_overview.md