i/OrbbecSDK_ROS2
1
0
Fork 0
mirror of https://github.com/orbbec/OrbbecSDK_ROS2.git synced 2026-09-12 19:20:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add initial project setup and documentation for OrbbecSDK V2 ROS2 Wrapper

Browse Source
This commit is contained in:
obyalian
2025-09-09 22:04:38 +08:00
commit 2d2a4e0ec6
14 changed files with 1453 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/source/1_overview/introduction.md
+68
View File
@@ -0,0 +1,68 @@
# Introduction
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, and Jazzy distributions.
With a major update in October 2024, we release the [OrbbecSDK ROS2 Wrapper v2](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main) connected to the open source [OrbbecSDK v2](https://github.com/orbbec/OrbbecSDK_v2/releases) with enhanced flexibility and extensibility. This update ensures compatibility with all Orbbec USB products adhering to UVC standard. However, it no longer supports Orbbec's traditional OpenNI protocol devices. We strongly encourage you to use the v2-main branch if your device is supported.
If you are a user in China, it is recommended to use [gitee Repo](https://gitee.com/orbbecdeveloper/OrbbecSDK_ROS2).
## Support Hardware Products
This document is based on the v2-main branch code, which is a Python Wrapper built on Orbbec SDK v2. It supports the following devices.
If your device is included in this supported list, we recommend using the v2-main branch. If not, you can use the main branch instead.
| **Products List** | **Minimal Firmware Version** |
|-------------------|------------------------------|
| Gemini 435Le | 1.2.04 |
| Gemini 335Le | 1.5.31 |
| Gemini 330 | 1.2.20 |
| Gemini 330L | 1.2.20 |
| Gemini 335 | 1.2.20 |
| Gemini 335L | 1.2.20 |
| Gemini 336 | 1.2.20 |
| Gemini 336L | 1.2.20 |
| Gemini 335Lg | 1.3.46 |
| Femto Bolt | 1.1.2 |
| Femto Mega | 1.3.0 |
| Femto Mega I | 2.0.4 |
| Astra 2 | 2.8.20 |
| Gemini 2 L | 1.4.53 |
| Gemini 2 | 1.4.92 |
| Gemini 215 | 1.0.9 |
| Gemini 210 | 1.0.9 |
the main branch supports the following devices:
| **Products List** | **Minimal Firmware Version** |
|-------------------|-----------------------------|
| Gemini 330 | 1.2.20 |
| Gemini 330L | 1.2.20 |
| Gemini 335 | 1.2.20 |
| Gemini 335L | 1.2.20 |
| Gemini 336 | 1.2.20 |
| Gemini 336L | 1.2.20 |
| Femto Bolt | 1.0.6 |
| Femto Mega | 1.1.7 |
| Femto Mega I | 2.0.2 |
| Gemini 2 XL | Obox: V1.2.5 VL:1.4.54 |
| Astra 2 | 2.8.20 |
| Gemini 2 L | 1.4.32 |
| Gemini 2 | 1.4.60 |
| Astra+ | 1.0.19 |
| Femto | 1.6.7 |
| Femto W | 1.1.8 |
| DaBai | 2436 |
| DaBai DCW | 2460 |
| DaBai DW | 2606 |
| Astra Mini Pro | 1007 |
| Gemini E | 3460 |
| Gemini E Lite | 3606 |
| Gemini | 3018 |
| Astra Mini S Pro | 1005 |
## Support Platforms
- Linux: 18.04/20.04/22.04/24.04 (x64)
- Arm64: Ubuntu18.04/20.04/22.04
docs/source/1_overview/orbbecsdk_overview.md
+117
View File
@@ -0,0 +1,117 @@
# Orbbec SDK Overview
This section introduces the Orbbec SDK in C++. Its architecture and concepts are consistent with those of the Python Wrapper.
## Terms
| ID | Name | Explain |
| --- | --- | --- |
| 1 | USB | Universal Serial Bus |
| 2 | UVC | USB Video Class |
| 3 | Firmware | Firmware of 3D camera |
| 4 | Disparity | Disparity is to observe the direction difference of the same target from two points with a certain distance. |
| 5 | D2D (Disparity to depth) | Disparity to depth is an image processing technique used to convert disparity information into depth information. |
| 6 | Hardware D2D | Disparity to depth is implemented internally in the device, without occupying the computational power of the host computer. |
| 7 | Software D2D | Disparity to depth, implemented in Orbbec SDK |
| 8 | Depth point cloud | Depth point cloud, the coordinates of points in a three-dimensional world coordinate system, can be transformed into a point cloud using the intrinsic parameters of a Depth camera. |
| 9 | RGBD point cloud | Point cloud with overlaid RGB information |
| 10 | D2C | The translation of "Depth to Color" is a feature that performs per-pixel geometric transformation on a depth image. Its result is aligning the depth image with its corresponding color image through the D2C transformation, allowing us to locate the depth information of a color pixel by using the same image coordinate position of that pixel in the transformed depth image. After the D2C transformation, we generate a depth image of the same size as the target color image, where the image content represents depth data in the coordinate system of the color camera. In other words, it reconstructs a depth image "captured" using the origin and dimensions of the color camera, where each pixel matches the corresponding pixel coordinates of the color camera. |
| 11 | Hardware D2C | Hardware D2C refers to the functionality of performing Depth to Color transformation within the camera itself, with the camera directly outputting the result of the D2C transformation. |
| 12 | Software D2C | Performing D2C computation on the host computer side using an SDK. |
| 13 | Frame aggregation (FrameSet) | Combining Depth, IR, and Color frames into a Frameset and invoking it through a pipeline. |
| 14 | C2D | The translation of "Color to Depth" is a feature that performs per-pixel geometric transformation on a color image. Its result is aligning the color image with its corresponding depth image through the C2D transformation. |
| 15 | MetaData | Frame metadata is a set of parameters (or attributes) that provide a snapshot of the sensor configuration and/or system state present during the frame’s generation. |
| 16 | HDR | High Dynamic Range (HDR) imaging allows imaging systems to capture images in extremely dark and bright scenes alike. We propose a software solution running on the host CPU to implement this feature. It utilizes data from two consecutive frames and directly synthesizes these two depth images, thereby enhances the dynamic range of 16-bit depth images. |
| 17 | LDP | Laser close-range protection |
| | | |
## Orbbec SDK v2 Architecture Overview
![OrbbecSDK v2 Soft Architecture](../image/Soft_Architecture.png)
- Application
OrbbecViewer, Sample, and User Application Implementation.
- Interfaces and Encapsulation Layer
OrbbecSDK Interface Encapsulation and Wrapper Encapsulation.
- High-level Layer
HighLevel encapsulates the core business components and provides interfaces to the outside using a pipeline.
- Basic business layer
The realization of the core business logic framework.
- Platform abstraction layer
Cross-platform components abstract operating system differences and provide a unified access interface.
- Platform implementation layer
The driver implementation of each platform.
## SDK Concept Overview
- Context
Context which provides a set of settings includes settings such as device state change callbacks, log levels, and more. The Context can access multiple devices.
- Device
One actual hardware device corresponds to one Device object, which is used to obtain relevant information of the device and control its attributes.
- Pipeline
The HighLevel corresponding object encapsulates the interface for quick access to the SDK. It has simple functions that allow users to quickly get started and use the SDK.
- Config
Provides configuration for enabling data streams, alignment modes, and frame aggregation modes, It is used to control the behavior of the data output.
- StreamProfile
Stream configuration that defines parameters such as resolution, frame rate, and encoding format, It also provides management of camera parameters.
- Frame
Represents a frame of data in the Stream, and also contains relevant information about that frame of data, such as timestamp, type, etc.
- Filter
It mainly refers to some algorithmic processing modules for the composite stream FrameSet, such as point cloud algorithm processing.
- Record
Recording functionality that captures data streams and saves them as files for later analysis or playback.
- Playback
Playback functionality that plays recorded files and supports control over playback speed and other related parameters.
## SDK Programming Model
Here is the C++ programming logic flow chart. Python's programming logic is the same as it.
- Standard Flowchart:
![image.png](../image/Standard_Flowchart.png)
The standard flowchart demonstrates how to create a device from the device list, set and get parameters, and apply post-processing filters.
- Flowchart using default configuration (stream acquisition based on the default settings in OrbbecSDKConfig.xml):
![image](../image/Default_Flowchart.png)
docs/source/2_installation/build_the_package.md
+52
View File
@@ -0,0 +1,52 @@
### 2.2. Build from Source
If no wheel package is available, or if you want to build with the latest source code, follow these steps:
#### 2.2.1. Environment
Install ROS 2 according to the official guide:
* [ROS 2 installation (Ubuntu)](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html)
Enable ROS 2 auto-completion:
```bash
eval "$(register-python-argcomplete3 ros2)"
eval "$(register-python-argcomplete3 colcon)"
```
Create a `colcon` workspace:
```bash
mkdir -p ~/ros2_ws/src
```
#### 2.2.2. Linux ROS2 Wrapper Compilation
Clone source and checkout `v2-main` branch:
```bash
cd ~/ros2_ws/src
git clone https://github.com/orbbec/OrbbecSDK_ROS2.git
cd OrbbecSDK_ROS2
git checkout v2-main
```
Install dependencies:
```bash
sudo apt install libgflags-dev nlohmann-json3-dev libgoogle-glog-dev libgoogle-glog0v5 libssl-dev \
ros-$ROS_DISTRO-image-transport ros-${ROS_DISTRO}-image-transport-plugins ros-${ROS_DISTRO}-compressed-image-transport \
ros-$ROS_DISTRO-image-publisher ros-$ROS_DISTRO-camera-info-manager \
ros-$ROS_DISTRO-diagnostic-updater ros-$ROS_DISTRO-diagnostic-msgs ros-$ROS_DISTRO-statistics-msgs \
ros-$ROS_DISTRO-backward-ros libdw-dev
```
Build:
```bash
cd ~/ros2_ws
colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
```
docs/source/2_installation/registration_script.md
+13
View File
@@ -0,0 +1,13 @@
## 2.1. Registration script (required)
To allow the Orbbec cameras to be recognized correctly on Linux, install the udev rules:
```bash
cd ~/ros2_ws/src/OrbbecSDK_ROS2/orbbec_camera/scripts
sudo bash install_udev_rules.sh
sudo udevadm control --reload-rules && sudo udevadm trigger
```
This step is **mandatory** for Linux users.
`Notes:` If this script is not executed, open the device will fail due to permission issues. You need to run the sample with sudo (administrator privileges).