mirror of
https://github.com/orbbec/OrbbecSDK_ROS2.git
synced 2026-10-04 20:17:47 +08:00
deploy: orbbec/OrbbecSDK_ROS2@5a6dd5d1b6
This commit is contained in:
obyalian
@@ -15,5 +15,6 @@ OrbbecSDK V2 ROS2 Wrapper documentation
|
||||
source/3_quickstarts/quickstarts.rst
|
||||
source/4_application_guide/application_guide.rst
|
||||
source/5_advanced_guide/advanced_guide.rst
|
||||
source/6_developer_guide/developer_guide.rst
|
||||
source/7_FAQ/FAQ.rst
|
||||
source/6_benchmark/benchmark.rst
|
||||
source/7_developer_guide/developer_guide.rst
|
||||
source/8_FAQ/FAQ.rst
|
||||
|
||||
@@ -122,7 +122,6 @@ Here is the device support list of main branch (v1.x) and v2-main branch (v2.x):
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
**Note**: If you do not find your device, please contact our FAE or sales representative for help.
|
||||
|
||||
**Definition**:
|
||||
@@ -139,8 +138,10 @@ The following devices are supported by the OrbbecSDK ROS2 Wrapper v2-main branch
|
||||
|
||||
For optimal performance, we strongly recommend updating to the latest firmware version. This ensures that you benefit from the most recent enhancements and bug fixes.
|
||||
|
||||
| Product List | Minimal Firmware Version | **Launch File** |
|
||||
| :------------- | :----------------------- | :-------------------------- |
|
||||
To learn how to obtain and upgrade the latest firmware, [please click here](../3_quickstarts/orbbecviewer.md).
|
||||
|
||||
| Product List | Minimal Firmware Version | **Launch File** |
|
||||
|:-------------- |:------------------------ |:--------------------------- |
|
||||
| Gemini 435Le | 1.2.04 | gemini435_le.launch.py |
|
||||
| Gemini 335 | 1.2.20 | gemini_330_series.launch.py |
|
||||
| Gemini 336 | 1.2.20 | gemini_330_series.launch.py |
|
||||
@@ -160,6 +161,100 @@ For optimal performance, we strongly recommend updating to the latest firmware v
|
||||
All launch files are essentially similar, with the primary difference being the default values of the parameters set
|
||||
for different models within the same series. Differences in USB standards, such as USB 2.0 versus USB 3.0, may require adjustments to these parameters. If you encounter a startup failure, please carefully review the specification manual. Pay special attention to the resolution settings in the launch file, as well as other parameters, to ensure compatibility and optimal performance.
|
||||
|
||||
## Orbbec camera datasheet
|
||||
|
||||
Refer to the camera datasheet for more information.
|
||||
|
||||
<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>Product Series</th>
|
||||
<th>Product</th>
|
||||
<th>Datasheet</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 Datasheet</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 Series Datasheet for USB Devices</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 Series Datasheet for GMSL Devices</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 Series Datasheet for Ethernet Devices</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 Series Datasheet</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 Datasheet</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 Datasheet</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 Datasheet</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 Datasheet</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 Datasheet</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Astra+</td>
|
||||
<td><a href="https://xm917ch2uk.feishu.cn/file/Qk0zbx26Doh8XMxw0rIcOgQYnff">Orbbec Astra+ Datasheet</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 Datasheet</a></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## Support Platforms
|
||||
|
||||
- Linux x64: tested on Ubuntu 22.04
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# OrbbecViewer tutorial
|
||||
|
||||
## Download
|
||||
|
||||
**Repository link：**[OrbbecViewer Download](https://github.com/orbbec/OrbbecSDK_v2/releases)
|
||||
|
||||
Select the appropriate version of OrbbecViewer according to your device type.
|
||||
|
||||
|
||||
|
||||
## Connect the device
|
||||
|
||||
When the Orbbec Viewer is open, the current device connection status will be prominently displayed in the top left corner of the application window. This area provides instant feedback about whether the camera is connected and functioning properly.
|
||||
|
||||
|
||||
|
||||
## Camera Control
|
||||
|
||||
You can quickly view the image using the buttons at the top of the window, and adjust image parameters in the camera panel on the left side of the window.
|
||||
|
||||
|
||||
|
||||
## Device information and firmware upgrade
|
||||
|
||||
Click the icon at the bottom left corner of the window to view the current camera information and upgrade the firmware.
|
||||
|
||||
|
||||
|
||||
Please refer to the list below for the latest camera firmware. [For more information, please click here.](https://www.orbbec.com/docs/g330-explore-camera-functions-in-orbbec-viewer/)
|
||||
|
||||
|
||||
|
||||
**Repository link：**[Firmware Download](https://github.com/orbbec/OrbbecFirmware?tab=readme-ov-file#firmware-download)
|
||||
|
||||
| **Products list** | **Download link** | Latest version |
|
||||
| ----------------- | ---------------------------------------------------------------------------------------------------- | -------------- |
|
||||
| Femto Bolt | [Femto Bolt Firmware](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Bolt-Firmware) | v1.1.2 |
|
||||
| Femto Mega | [Femto Mega Firmware](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Mega-Firmware) | v1.3.1 |
|
||||
| Gemini 2 | [Gemini 2 Firmware](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini2-Firmware) | v1.4.98 |
|
||||
| Gemini 2 L | [Gemini 2L Firmware](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini2L-Firmware) | v1.5.02 |
|
||||
| Femto Mega I | [Femto Mega I Firmware](https://github.com/orbbec/OrbbecFirmware/releases/tag/Femto-Mega-I-Firmware) | v2.0.4 |
|
||||
| Gemini 330 series | [Gemini 330 series Firmware](https://www.orbbec.com/docs/g330-firmware-release/?_gl=1) | |
|
||||
| Gemini 215 | [Gemini 215](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini215-Firmware) | v1.0.9 |
|
||||
| Gemini 210 | [Gemini 210](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemini210-Firmware) | v1.0.9 |
|
||||
| Gemini 435Le | [Gemini 435Le](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemin435Le-Firmware) | v1.3.2 |
|
||||
@@ -7,4 +7,5 @@ This chapter provides quick start guides for the SDK, allowing users to run basi
|
||||
:maxdepth: 2
|
||||
|
||||
quickstart.md
|
||||
orbbecviewer.md
|
||||
|
||||
|
||||
@@ -1,18 +1,7 @@
|
||||
Advanced Guide
|
||||
======================================================
|
||||
|
||||
This chapter covers advanced features of the SDK, including multi-camera usage, performance tuning, and special configuration modes.
|
||||
|
||||
Performance & Optimization
|
||||
------------------------------------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
performance/benchmark.md
|
||||
performance/lower_cpu_usage.md
|
||||
performance/efficient_intra_process_communication.md
|
||||
performance/fastdds_tuning.md
|
||||
This chapter covers advanced features of the SDK, including multi-camera usage, and special configuration modes.
|
||||
|
||||
|
||||
Multi-Camera
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
> This section describes how to use Net camera in OrbbecSDK_ROS2.Currently, only Femto_Mega, Gemini 335Le and Gemini 435Le devices are supported, and other Net devices will be supported in the near future.
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
## Femto Mega & Gemini 435Le
|
||||
|
||||
**Parameter Introduction**
|
||||
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
> This section describes how to use GMSL camera in OrbbecSDK_ROS2.Currently, only Gemini 335Lg GMSL devices are supported, and other GMSL devices will be supported in the near future.
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
## Single GMSL camera
|
||||
|
||||
The usage of GMSL camera in OrbbecSDK_ROS2 is the same as that of Gemini 330 series camera via USB.
|
||||
|
||||
+2
@@ -4,6 +4,8 @@
|
||||
>
|
||||
> First, please see how to use [multi_camera_synced](./multi_camera_synced.md).
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```plaintext
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
Benchmark
|
||||
======================================================
|
||||
|
||||
This chapter introduces how to use the benchmark tool and provides test results for different cameras.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction.md
|
||||
benchmark_usage.md
|
||||
benchmark_data.md
|
||||
performance.md
|
||||
@@ -0,0 +1,6 @@
|
||||
# Benchmark Data
|
||||
|
||||
This section records the data of using the benchmark tool to test different cameras
|
||||
|
||||
- [ROS2 Service Benchmark Data cpp](../service_benchmark_data/ros2_service_benchmark_cpp.xlsx)
|
||||
- [ROS2 Service Benchmark Data python](../service_benchmark_data/ros2_service_benchmark_python.xlsx)
|
||||
@@ -0,0 +1,119 @@
|
||||
# Benchmark Usage
|
||||
|
||||
This section introduces how to use the benchmark tool in C++ and Python, and provides an example YAML configuration file.
|
||||
|
||||
## Using common benchmark node
|
||||
|
||||
```
|
||||
ros2 run orbbec_camera common_benchmark_node.py \
|
||||
--run_time 2h \
|
||||
--csv_file /path/to/log.csv
|
||||
```
|
||||
|
||||
|
||||
|
||||
* **Parameters**
|
||||
* **--run_time**: Duration for monitoring, specified as time strings like `"10s"`, `"5m"`, `"1h"`, `"2d"`. Default is 10 seconds.
|
||||
* **--csv_file**: Path to the output CSV file. By default, it is saved in the workspace directory with the name "camera_monitor_log.csv".
|
||||
|
||||
## Using service benchmark node
|
||||
|
||||
### ROS2 C++
|
||||
|
||||
* **Single service benchmark**
|
||||
|
||||
```
|
||||
ros2 run orbbec_camera service_benchmark_node \
|
||||
--ros-args \
|
||||
-p service_name:=/camera/get_depth_gain \
|
||||
-p service_type:=orbbec_camera_msgs/srv/GetInt32 \
|
||||
-p count:=10
|
||||
```
|
||||
|
||||
* ****Multiple services benchmark (YAML config)****
|
||||
|
||||
```
|
||||
ros2 run orbbec_camera service_benchmark_node \
|
||||
--ros-args \
|
||||
-p yaml_file:=/path/to/default_service_cpp.yaml
|
||||
```
|
||||
|
||||
### ROS2 Python
|
||||
|
||||
* **Single service benchmark**
|
||||
|
||||
```
|
||||
ros2 run orbbec_camera service_benchmark_node.py --service /camera/get_depth_gain --count 10
|
||||
```
|
||||
|
||||
* ****Multiple services benchmark (YAML config)****
|
||||
|
||||
```
|
||||
ros2 run orbbec_camera service_benchmark_node.py --yaml_file /path/to/default_service.yaml
|
||||
```
|
||||
|
||||
|
||||
|
||||
### **Example YAML configuration**
|
||||
|
||||
We provide an example YAML configuration, located in the `scripts` directory as `service_default.yaml`.
|
||||
|
||||
```yaml
|
||||
default_count: 50
|
||||
|
||||
services:
|
||||
- name: /camera/get_auto_white_balance
|
||||
type: orbbec_camera_msgs/srv/GetInt32
|
||||
- name: /camera/get_color_exposure
|
||||
type: orbbec_camera_msgs/srv/GetInt32
|
||||
- name: /camera/get_color_gain
|
||||
type: orbbec_camera_msgs/srv/GetInt32
|
||||
- name: /camera/get_depth_exposure
|
||||
type: orbbec_camera_msgs/srv/GetInt32
|
||||
- name: /camera/get_depth_gain
|
||||
type: orbbec_camera_msgs/srv/GetInt32
|
||||
- name: /camera/get_device_info
|
||||
type: orbbec_camera_msgs/srv/GetDeviceInfo
|
||||
- name: /camera/send_software_trigger
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_auto_white_balance
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_color_ae_roi
|
||||
type: orbbec_camera_msgs/srv/SetArrays
|
||||
request: {data_param: [0,1279,0,719]}
|
||||
- name: /camera/set_color_auto_exposure
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_color_exposure
|
||||
type: orbbec_camera_msgs/srv/SetInt32
|
||||
request: {data: 30}
|
||||
- name: /camera/set_color_flip
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_color_gain
|
||||
type: orbbec_camera_msgs/srv/SetInt32
|
||||
request: {data: 20}
|
||||
- name: /camera/set_color_mirror
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_color_rotation
|
||||
type: orbbec_camera_msgs/srv/SetInt32
|
||||
request: {data: 90}
|
||||
- name: /camera/set_depth_ae_roi
|
||||
type: orbbec_camera_msgs/srv/SetArrays
|
||||
request: {data_param: [0,1279,0,719]}
|
||||
- name: /camera/set_depth_auto_exposure
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_depth_exposure
|
||||
type: orbbec_camera_msgs/srv/SetInt32
|
||||
request: {data: 3000}
|
||||
- name: /camera/set_depth_flip
|
||||
type: std_srvs/srv/SetBool
|
||||
request: {data: false}
|
||||
- name: /camera/set_depth_gain
|
||||
type: orbbec_camera_msgs/srv/SetInt32
|
||||
request: {data: 200}
|
||||
```
|
||||
@@ -0,0 +1,45 @@
|
||||
# Introduction
|
||||
|
||||
This section introduces the benchmark tool, explaining its purpose, features, and what it can help you measure.
|
||||
|
||||
## common benchmark node
|
||||
|
||||
`common_benchmark_node.py` is a tool for monitoring the performance of Orbbec cameras running in a ROS environment. It collects and records key camera metrics such as frame rate, latency, system resource usage, and packet loss rate in real time, helping users evaluate the stability and performance of camera nodes (updated once per second).
|
||||
|
||||
**Features**
|
||||
|
||||
- Measure published image frame rate and latency (current, min, max, average)
|
||||
|
||||
- Monitor the camera node's CPU/ARM usage (current, min, max, average)
|
||||
|
||||
- Track frame drop rate (publisher) and packet loss rate (subscriber)
|
||||
|
||||
- Print real-time statistics (1 Hz) to the terminal and save results to a CSV file
|
||||
|
||||
- Support configurable runtime duration and CSV output path
|
||||
|
||||
**Example**
|
||||
|
||||
In ROS1, both frame drop rate and packet loss rate can be measured, while in ROS2, the header lacks the `seq` field, so only the publisher-side frame drop rate is calculated.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## service benchmark node
|
||||
|
||||
The `service_benchmark_node` tool is used to monitor the performance of service calls. It can measure the success rate of service calls and the time required to execute service.
|
||||
|
||||
**Features**
|
||||
|
||||
- Benchmark a single service call, measuring latency and success rate
|
||||
|
||||
- Benchmark multiple services as defined in a YAML configuration file
|
||||
|
||||
- Optionally save benchmark results to a CSV file
|
||||
|
||||
**Example**
|
||||
|
||||
|
||||
|
||||
When you need to collect data for multiple services, it is recommended to use a CSV file for analysis.
|
||||
@@ -0,0 +1,334 @@
|
||||
# Performance & Optimization
|
||||
|
||||
## Ob_benchmark tool
|
||||
|
||||
> The goal of this tool is to benchmark the performance of various OrbbecSDK_ROS2 camera configurations. The benchmark results depend on the camera and settings used.(Currently only works with ROS2 Humble)
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
### Tool Configuration ([start_benchmark_params.json](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/config/tools/startbenchmark/start_benchmark_params.json))
|
||||
|
||||
```json
|
||||
{
|
||||
"start_benchmark_params": {
|
||||
"camera_name": [
|
||||
"camera_01",
|
||||
"camera_02",
|
||||
"camera_03",
|
||||
"camera_04"
|
||||
],
|
||||
"process_name": "component_conta",
|
||||
"switch_cycle": 300,
|
||||
"test_cycle": 1,
|
||||
"skip_number": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `camera_name`: Names of the cameras to be configured. Example: `"camera_01"`, `"camera_02"`, etc.
|
||||
- `process_name`: The name of the process to be monitored. For example, `"component_conta"` will monitor the data of the container process.
|
||||
- `switch_cycle`: The cycle time for switching configurations, in seconds. For example, setting it to `300` means the configuration will switch every 300 seconds.
|
||||
- `test_cycle`: The testing cycle, in seconds. For example, setting it to `1` means the tool will collect data for the monitored process every 1 second.
|
||||
- `skip_number`: The number of data points to skip. For example, setting it to `30` means that the first 30 data points will be ignored.
|
||||
|
||||
### Camera configuration (launch files)
|
||||
|
||||
In the launch folder, there are multiple.launch.py files (`ob_benchmark_0.launch.py`, `ob_benchmark_1.launch.py`, ..., `ob_benchmark_19.launch.py`). Each file corresponds to a different camera configuration.
|
||||
|
||||
### Running the ob_benchmark tool
|
||||
|
||||
To run the tool, use the following commands:
|
||||
|
||||
```bash
|
||||
source install/setup.bash
|
||||
ros2 run orbbec_camera ob_benchmark_node
|
||||
```
|
||||
|
||||
### Output Data Files
|
||||
|
||||
The output data files will be stored in the ob_benchmark folder with filenames like `0.csv`, `1.csv`, ..., 19.csv. For example:
|
||||
|
||||
- `0.csv` contains data from the `ob_benchmark_0.launch.py` configuration.
|
||||
- `1.csv` contains data from the `ob_benchmark_1.launch.py` configuration.
|
||||
|
||||
## Reducing CPU Usage with Orbbec ROS Package
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
This document outlines strategies for minimizing CPU usage in the **OrbbecSDK_ROS2 v2** environment when using **Gemini 330 series cameras**. The firmware version must be **no lower than 1.4.10**, and `device` should be set to **Default**.
|
||||
|
||||
### Recommended Settings for Lower CPU Usage
|
||||
|
||||
To achieve the lowest possible CPU usage in OrbbecSDK_ROS2, it is recommended to configure the following parameters.
|
||||
|
||||
| Parameter | Recommendation | Note |
|
||||
| ---------------- | -------------------------------------- | ---------------------------------------------- |
|
||||
| `uvc_backend` | `v4l2` | Lower CPU usage compared to `libuvc` |
|
||||
| `color_format` | `RGB` | Lower CPU usage than `MJPG` |
|
||||
| `filter` | Only `hardware_noise_removal_filter` | Other filters significantly increase CPU usage |
|
||||
|
||||
### Launch Files Used for Testing
|
||||
|
||||
- `gemini_330_series_lower_cpu_usage.launch.py`
|
||||
- `multi_camera_lower_cpu_usage.launch.py`
|
||||
|
||||
### Test environment
|
||||
|
||||
**Hardware Configuration**
|
||||
|
||||
- **CPU**: Intel i7-8700 @ 3.20GHz
|
||||
- **Memory**: 24 GB
|
||||
- **Storage**: Micron 2200S NVMe 256GB
|
||||
- **GPU**: NVIDIA GeForce GTX 1660Ti
|
||||
- **OS**: Ubuntu22.04
|
||||
|
||||
**ROS Configuration**
|
||||
|
||||
- **ROS Version**: ROS2 Humble
|
||||
- **SDK Version**: OrbbecSDK_ROS2 v2.2.1
|
||||
|
||||
**Camera Setup**
|
||||
|
||||
- Devices: 2x Gemini 335, 1x Gemini 336, 1x Gemini 336L
|
||||
- Firmware Version: 1.4.10
|
||||
|
||||
### Test Setup
|
||||
|
||||
**Stream Settings:**
|
||||
|
||||
- Depth / IR Left / IR Right: 848×480 @ 30fps
|
||||
- Color: 848×480 @ 30fps
|
||||
|
||||
Note: The following CPU usage data focuses on `uvc_backend`, `color_format` and various filter combinations.
|
||||
|
||||
### Test Results
|
||||
|
||||
**`uvc_backend` Comparison (RGB format)**
|
||||
|
||||
| libuvc CPU Usage | v4l2 CPU Usage | Absolute Change |
|
||||
| ---------------- | -------------- | --------------- |
|
||||
| 182.8% | 118.8% | -64.0% |
|
||||
|
||||
The CPU usage can be significantly reduced with v4l2 backend. In our implementation, v4l2 works without requiring any patches to the Linux kernel, allowing users to easily switch between v4l2 and libuvc and maintaining full compatibility with standard Linux distributions.
|
||||
|
||||
**`color_format` Comparison (MJPG vs RGB)**
|
||||
|
||||
| Backend | MJPG CPU Usage | RGB CPU Usage | Absolute Change |
|
||||
| ------- | -------------- | ------------- | --------------- |
|
||||
| libuvc | 347.7% | 182.8% | -164.9% |
|
||||
| v4l2 | 170.0% | 118.8% | -51.2% |
|
||||
|
||||
The CPU usage can be reduced if the RGB format is selected instead of MJPG, since the decoding of MJPG image will consume the host CPU resource.
|
||||
|
||||
**Filter Configuration Impact**
|
||||
|
||||
| Filters Applied | libuvc CPU Usage | CPU Usage Increase | v4l2 CPU Usage | CPU Usage Increase |
|
||||
| ----------------------------------------------------- | ---------------- | ------------------ | -------------- | ------------------ |
|
||||
| No Filter (benchmark) | 182.8% | 0.0%(benchmark) | 118.8% | 0.0%(benchmark) |
|
||||
| `(software)noise_removal_filter` | 218.0% | +35.2% | 128.5% | +9.7% |
|
||||
| `(software)noise_removal_filter + spatial_filter` | 469.6% | +286.8% | 336.7% | +217.9% |
|
||||
| `hardware_noise_removal_filter` | 186.3% | +3.5% | 115.4% | -3.4% |
|
||||
| `hardware_noise_removal_filter + spatial_filter` | 251.3% | +68.5% | 152.5% | +33.7% |
|
||||
|
||||
Based on the test results, using only the `hardware_noise_removal_filter` results in a negligible change in CPU usage for both `libuvc` (+3.5%) and `v4l2` (-3.4%) compared to the no-filter benchmark, as this filter runs internally on the camera hardware. In contrast, other filters execute on the host system. Adding the `spatial_filter` to the hardware filter leads to a moderate increase in CPU usage, while applying the software-based `noise_removal_filter` —either alone or combined with `spatial_filter` —significantly increases CPU load. To maintain low CPU usage, it is recommended to avoid software-based filters and rely solely on the `hardware_noise_removal_filter`.
|
||||
|
||||
### Further Optimizationa
|
||||
|
||||
| Parameter | Recommendation | Note |
|
||||
| ------------------------------ | ------------------------------------------------ | ----------------------------------------------- |
|
||||
| `depth_registration` | `false` or `true` with `align_mode=HW` | Software alignment consumes more CPU |
|
||||
| `enable_point_cloud` | `false` | Disabling point cloud reduces CPU usage |
|
||||
| `enable_colored_point_cloud` | `false` | Disabling colored point cloud reduces CPU usage |
|
||||
|
||||
## Efficient intra-process communication
|
||||
|
||||
### Introduction
|
||||
|
||||
Our ROS2 Wrapper node supports zero-copy communications if loaded in the same process as a subscriber node. This can reduce copy times on image/pointcloud topics, especially with big frame resolutions and high FPS.
|
||||
|
||||
You will need to launch a component container and launch our node as a component together with other component nodes. Further details on "Composing multiple nodes in a single process" can be found [here](https://docs.ros.org/en/rolling/Tutorials/Composition.html).
|
||||
|
||||
Further details on efficient intra-process communication can be found [here](https://docs.ros.org/en/humble/Tutorials/Intra-Process-Communication.html#efficient-intra-process-communication).
|
||||
|
||||
### Example
|
||||
|
||||
**Manually loading multiple components into the same process**
|
||||
|
||||
- Start the component:
|
||||
|
||||
```bash
|
||||
ros2 run rclcpp_components component_container
|
||||
```
|
||||
- Add the wrapper:
|
||||
|
||||
```bash
|
||||
ros2 component load /ComponentManager orbbec_camera orbbec_camera::OBCameraNodeDriver -e use_intra_process_comms:=true
|
||||
```
|
||||
|
||||
Load other component nodes (consumers of the wrapper topics) in the same way.
|
||||
|
||||
**Using a launch file**
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_intra_process_demo_launch.py
|
||||
```
|
||||
|
||||
**Limitations**
|
||||
|
||||
- Node components are currently not supported on RCLPY
|
||||
- Compressed images using `image_transport` will be disabled as this isn't supported with intra-process communication
|
||||
|
||||
## Fast DDS Optimization for Orbbec Camera with ROS2
|
||||
|
||||
When operating with the default configuration, Fast DDS exhibits suboptimal transmission efficiency, resulting in
|
||||
significant image transmission delays when used with the Orbbec camera in ROS2. This document provides guidance on
|
||||
optimizing Fast DDS to enhance image transfer efficiency.
|
||||
|
||||
### Adjusting System Parameters
|
||||
|
||||
**IP Fragmentation Time**
|
||||
|
||||
- **Path**: `/proc/sys/net/ipv4/ipfrag_time` (default: 30 seconds)
|
||||
- **Purpose**: Defines the duration that IP fragments are kept in memory.
|
||||
- **Adjustment**: Decrease this value to reduce the time window where no fragments are received, which can help reduce
|
||||
delays. Consider the specific needs of your environment as this setting affects all incoming fragments.
|
||||
|
||||
**Example**: Set to 3 seconds.
|
||||
|
||||
```bash
|
||||
sudo sysctl net.ipv4.ipfrag_time=3
|
||||
```
|
||||
|
||||
**IP Fragmentation Memory Threshold**
|
||||
|
||||
- **Path**: `/proc/sys/net/ipv4/ipfrag_high_thresh` (default: 262144 bytes)
|
||||
- **Purpose**: Sets the maximum memory used to reassemble IP fragments.
|
||||
- **Adjustment**: Increase this value to allow more memory for fragment reassembly, which can improve handling of larger
|
||||
data packets.
|
||||
|
||||
**Example**: Increase to 128 MB.
|
||||
|
||||
```bash
|
||||
sudo sysctl net.ipv4.ipfrag_high_thresh=134217728
|
||||
```
|
||||
|
||||
**Maximum Buffer Sizes**
|
||||
|
||||
- **Purpose**: Configures the maximum buffer sizes for receiving and sending data, which is critical for high-throughput
|
||||
data transmission.
|
||||
- **Adjustment**: Set the maximum buffer sizes for both receiving and sending operations.
|
||||
|
||||
**Commands**:
|
||||
|
||||
```bash
|
||||
sudo sysctl -w net.core.rmem_max=2147483647
|
||||
sudo sysctl -w net.core.rmem_default=2147483647
|
||||
sudo sysctl -w net.core.wmem_max=2147483647
|
||||
sudo sysctl -w net.core.wmem_default=2147483647
|
||||
```
|
||||
|
||||
Alternatively, make these settings permanent by adding them to the `/etc/sysctl.d/10-fastrtps-max.conf` file.
|
||||
|
||||
```bash
|
||||
sudo gedit /etc/sysctl.d/10-fastrtps-max.conf
|
||||
```
|
||||
|
||||
add blow lines to the file:
|
||||
|
||||
```bash
|
||||
net.core.rmem_max=2147483647
|
||||
net.core.rmem_default=2147483647
|
||||
net.core.wmem_max=2147483647
|
||||
net.core.wmem_default=2147483647
|
||||
```
|
||||
|
||||
then save and exit the file. run `sudo sysctl -p` to apply the changes.
|
||||
|
||||
For detailed guidance, refer
|
||||
to [ROS 2 DDS Tuning Documentation](https://docs.ros.org/en/foxy/How-To-Guides/DDS-tuning.html).
|
||||
|
||||
### Fast DDS Configuration
|
||||
|
||||
Below is an example of a Fast DDS configuration file optimized for ROS2 usage with the Orbbec camera. This configuration
|
||||
enhances the overall data transmission by adjusting buffer sizes and transport settings.
|
||||
|
||||
**Configuration File:** `shm_fastdds.xml`
|
||||
|
||||
Place this file in the `$HOME` directory.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<profiles xmlns="http://www.eprosima.com/XMLSchemas/fastRTPS_Profiles">
|
||||
<transport_descriptors>
|
||||
<transport_descriptor>
|
||||
<transport_id>UDP_transport</transport_id>
|
||||
<type>UDPv4</type>
|
||||
<maxInitialPeersRange>10</maxInitialPeersRange>
|
||||
<maxMessageSize>65000</maxMessageSize>
|
||||
<sendBufferSize>1048576</sendBufferSize>
|
||||
<receiveBufferSize>1048576</receiveBufferSize>
|
||||
</transport_descriptor>
|
||||
</transport_descriptors>
|
||||
<participant profile_name="participant_profile_ros2" is_default_profile="true">
|
||||
<rtps>
|
||||
<name>profile_for_ros2_context</name>
|
||||
<userTransports>
|
||||
<transport_id>UDP_transport</transport_id>
|
||||
</userTransports>
|
||||
<useBuiltinTransports>false</useBuiltinTransports>
|
||||
<sendSocketBufferSize>1048576</sendSocketBufferSize>
|
||||
<listenSocketBufferSize>1048576</listenSocketBufferSize>
|
||||
<builtin>
|
||||
<initialPeersList>
|
||||
<locator>
|
||||
<udpv4>
|
||||
<address>127.0.0.1</address>
|
||||
</udpv4>
|
||||
</locator>
|
||||
</initialPeersList>
|
||||
</builtin>
|
||||
</rtps>
|
||||
</participant>
|
||||
<data_writer profile_name="default publisher profile" is_default_profile="true">
|
||||
<qos>
|
||||
<publishMode>
|
||||
<kind>ASYNCHRONOUS</kind>
|
||||
</publishMode>
|
||||
<latencyBudget>
|
||||
<duration>
|
||||
<sec>0</sec>
|
||||
<nanosec>1000000</nanosec>
|
||||
</duration>
|
||||
</latencyBudget>
|
||||
</qos>
|
||||
<historyMemoryPolicy>PREALLOCATED_WITH_REALLOC</historyMemoryPolicy>
|
||||
</data_writer>
|
||||
<data_reader profile_name="default subscription profile" is_default_profile="true">
|
||||
<qos>
|
||||
<data_sharing>
|
||||
<kind>AUTOMATIC</kind>
|
||||
</data_sharing>
|
||||
<latencyBudget>
|
||||
<duration>
|
||||
<sec>0</sec>
|
||||
<nanosec>1000000</nanosec>
|
||||
</duration>
|
||||
</latencyBudget>
|
||||
</qos>
|
||||
<historyMemoryPolicy>PREALLOCATED_WITH_REALLOC</historyMemoryPolicy>
|
||||
</data_reader>
|
||||
</profiles>
|
||||
```
|
||||
|
||||
**Environment Variables**
|
||||
|
||||
Set the following environment variables to use the custom Fast DDS profile:
|
||||
|
||||
```bash
|
||||
export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
|
||||
export FASTRTPS_DEFAULT_PROFILES_FILE=$HOME/shm_fastdds.xml
|
||||
export RMW_FASTRTPS_USE_QOS_FROM_XML=1
|
||||
```
|
||||
|
||||
This configuration aims to optimize the data flow and reduce transmission delays, improving the responsiveness and
|
||||
reliability of the Orbbec camera system in a ROS2 environment.
|
||||
+2
@@ -2,6 +2,8 @@
|
||||
|
||||
> The goal of this tool is to benchmark the performance of various OrbbecSDK_ROS2 camera configurations. The benchmark results depend on the camera and settings used.(Currently only works with ROS2 Humble)
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
### Tool Configuration ([start_benchmark_params.json](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/config/tools/startbenchmark/start_benchmark_params.json))
|
||||
|
||||
```json
|
||||
+2
@@ -1,5 +1,7 @@
|
||||
## Reducing CPU Usage with Orbbec ROS Package
|
||||
|
||||
You can find example usage code in the [example](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples).
|
||||
|
||||
This document outlines strategies for minimizing CPU usage in the **OrbbecSDK_ROS2 v2** environment when using **Gemini 330 series cameras**. The firmware version must be **no lower than 1.4.10**, and `device` should be set to **Default**.
|
||||
|
||||
### Recommended Settings for Lower CPU Usage
|
||||
Reference in New Issue
Block a user