reorganize documentation tree and supplement with additional guides

2026-10-07 21:37:46 +08:00 · 2025-09-16 16:39:38 +08:00
parent 2460077f7c
commit 87898ee11d
34 changed files with 169 additions and 78 deletions
@@ -1,26 +1,42 @@
 Advanced Guide
 ======================================================

-This chapter covers advanced features of the SDK, including multi-camera synchronization, depth-color alignment, performance tuning, and more.
+This chapter covers advanced features of the SDK, including multi-camera usage, performance tuning, and special configuration modes.
+
+Performance & Optimization
+------------------------------------------------------

 .. toctree::
    :maxdepth: 2

-    align_depth_color.md
-    benchmark.md
-    building_a_Debian_Package.md
-    configuration_of_depth_NFOV_and_WFOV_modes.md
-    depth_work_mode_switch.md
-    disparity_search_offset.md
-    efficient_intra_process_communication.md
-    fastdds_tuning.md
-    gmsl_camera.md
-    interleave_ae_mode.md
-    lower_cpu_usage.md
-    multi_camera.md
-    multi_camera_synced.md
-    multi_camera_synced_verification_tool.md
-    net_camera.md
-    point_cloud.md
-    predefined_presets.md
+    performance/benchmark.md
+    performance/lower_cpu_usage.md
+    performance/efficient_intra_process_communication.md
+    performance/fastdds_tuning.md

+
+Multi-Camera
+------------------------------------------------------
+
+.. toctree::
+    :maxdepth: 2
+
+    multi_camera/multi_camera.md
+    multi_camera/multi_camera_synced.md
+    multi_camera/multi_camera_synced_verification_tool.md
+    multi_camera/gmsl_camera.md
+
+
+Configuration & Modes
+------------------------------------------------------
+
+.. toctree::
+    :maxdepth: 2
+
+    configuration/align_depth_color.md
+    configuration/configuration_of_depth_NFOV_and_WFOV_modes.md
+    configuration/depth_work_mode_switch.md
+    configuration/disparity_search_offset.md
+    configuration/interleave_ae_mode.md
+    configuration/predefined_presets.md
+    configuration/net_camera.md
@@ -1,45 +0,0 @@
-# Building a Debian Package
-
-## Preparing the Environment
-
-Before starting, install the required tools:
-
-```bash
-sudo apt install debhelper fakeroot python3-bloom
-```
-
-## Configuring ROS Dependencies
-
-Add the following YAML file to your system at `/etc/ros/rosdep/sources.list.d/00-orbbec.yaml`. Make sure to
-replace `focal` with the codename of your Ubuntu version and `humble` with your ROS2 distribution name:
-
-```yaml
-orbbec_camera_msgs:
-  ubuntu:
-    focal: [ ros-humble-orbbec-camera-msgs ]
-```
-
-Next, create a new file `/etc/ros/rosdep/sources.list.d/50-orbbec.list` and add this line to specify the path to the
-YAML file:
-
-```bash
-yaml file:///etc/ros/rosdep/sources.list.d/00-orbbec.yaml
-```
-
-Update the rosdep database to reflect these changes:
-
-```bash
-rosdep update
-```
-
-## Building the Package
-
-Navigate to your workspace and build the project:
-
-```bash
-cd ~/ros2_ws/
-colcon build --event-handlers console_direct+ --cmake-args -DCMAKE_BUILD_TYPE=Release
-. install/setup.bash
-cd src/OrbbecSDK_ROS2/
-bash .make_deb.sh
-```
@@ -30,10 +30,10 @@ To visualize the aligned images in RViz2:
 1. Launch RViz2 after running one of the above commands.
 2. Select the topic for the depth to color overlay image. An example topic selection is shown here:

-   ![Topic Selection for Depth to Color Overlay](../image/align_depth_color/image3.png)
+   ![Topic Selection for Depth to Color Overlay](../../image/align_depth_color/image3.png)

 ### Example of Depth to Color Overlay

 After selecting the appropriate topic in RViz2, you will be able to see the depth to color overlay image. Here's what it might look like:

-![Depth to Color Overlay Image](../image/align_depth_color/image4.jpg)
+![Depth to Color Overlay Image](../../image/align_depth_color/image4.jpg)
@@ -6,7 +6,7 @@

 The definition of disparity search range: For any pixel *(u_l, v)* in the left image, by default, the corresponding disparity search range in the right image is *[ (u_l - 255, v)*, *(u_l, v) ]*, where the disparity search length is 256 and the maximum integer disparity is 255. If the starting point of the search is adjusted to *[ (u_l - 255 - offset, v)*, *(u_l - offset, v) ]*, the offset is defined as the disparity shift. Therefore, our disparity search range configuration includes both the disparity search length and the search position offset (which can also be referred to as the disparity shift).

-![Depth Point Cloud Visualization](../image/disparity_search_offset/search_offset0.png)
+![Depth Point Cloud Visualization](../../image/disparity_search_offset/search_offset0.png)

 ## Parameter Introduction

@@ -14,7 +14,7 @@ The interleave_ae related parameters are set in [gemini_330_series.launch.py](ht

 * `interleave_skip_index` : Set 0 for skip pattern ir, set 1 for skip flood ir.

-### interleave hdr
+**interleave hdr**

 When the `interleave_ae_mode` parameter is set to `hdr` and `interleave_frame_enable `is set to `true`, interleave hdr will be enabled

@@ -38,7 +38,7 @@ When the `interleave_ae_mode` parameter is set to `hdr` and `interleave_frame_en

 * `hdr_index0_ir_ae_max_exposure` : Frame 0 ir maximum exposure value setting in AE (auto exposure).

-### interleave laser
+**interleave laser**

 When the `interleave_ae_mode` parameter is set to `laser` and `interleave_frame_enable `is set to `true`, interleave laser will be enabled

@@ -70,11 +70,11 @@ Setting the interleave_ae parameter,`colcon build` again and run launch
 ros2 launch orbbec_camera gemini_330_series.launch.py
 ```

-#### Example Visualization
+**Example Visualization**

-![Depth Point Cloud Visualization](../image/interleave_ae_mode/interleave_ae0.jpeg)
+![Depth Point Cloud Visualization](../../image/interleave_ae_mode/interleave_ae0.jpeg)

-![Depth Point Cloud Visualization](../image/interleave_ae_mode/interleave_ae1.jpeg)
+![Depth Point Cloud Visualization](../../image/interleave_ae_mode/interleave_ae1.jpeg)

 ## Multi_camera_synced + Interleave_ae

@@ -4,7 +4,7 @@

 ## Femto Mega & Gemini 435Le

-### Parameter Introduction
+**Parameter Introduction**

 Network device settings: `enumerate_net_device` is set to true, which will automatically enumerate network devices.

@@ -14,7 +14,7 @@ If you do not want to automatically enumerate network devices,you can set `enume
 * `net_device_ip` : Setting net device's IP address.
 * `net_device_port` : Setting net device's port.Usually, you can set it to 8090.

-### Single Net camera
+**Single Net camera**

 > If you need to run Gemini 435Le, you only need to replace [femto_mega.launch.py ](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/launch/femto_mega.launch.py)in the run command with [gemini435_le.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/launch/gemini435_le.launch.py)

@@ -42,7 +42,7 @@ Network device settings: `enumerate_net_device` must be set to true, set `net_de
 * `net_device_ip` : Setting net device's IP address.
 * `net_device_port` : Setting net device's port.Usually, you can set it to 8090.

-### Single Net camera
+**Single Net camera**

 For [gemini_330_series.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/launch/gemini_330_series.launch.py) as an example:

@@ -34,12 +34,12 @@ First, please see how to use [multi_camera_synced](./multi_camera_synced.md).

 In addition, GMSL multi-camera synced does not require Multi-Camera Sync Hub Pro, so there is no need to set the `primary` mode. Each GMSL camera is `secondary`.

-### Additional Parameter Settings
+**Additional Parameter Settings**

 * `gmsl_trigger_fps` : set hardware soc trigger source frame rate.
 * `enable_gmsl_trigger` : enable hardware soc trigger.

-### Run the launch
+**Run the launch**

 Please refer to the configuration in [multi_gmsl_camera_synced.launch.py.](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/examples/gmsl_camera/multi_gmsl_camera_synced.launch.py)

@@ -88,4 +88,4 @@ ros2 launch orbbec_camera multi_camera.launch.py

 ## Image topic frame rate too low from Multiple Cameras

-Refer to the [Fast DDS Configuration](./fastdds_tuning.md) file.
+Refer to the [Fast DDS Configuration](../performance/fastdds_tuning.md) file.
@@ -2,12 +2,12 @@

 > The purpose of this document is to explain how to use multi-camera synced with OrbbecSDK_ROS2

-## Setup instructions
+### Setup instructions

 * Please read the Multi-Camera Synchronization Setup Guide:[Multi-Camera Synchronization Setup](https://www.orbbec.com/docs/set-up-cameras-for-external-synchronization_v1-2/)
 * Make sure the camera is correctly connected to the multi-camera synchronizer.

-![Depth Point Cloud Visualization](../image/multi_camera_synced/multi_camera_synced1.png)
+![Depth Point Cloud Visualization](../../image/multi_camera_synced/multi_camera_synced1.png)

 ### Checking camera port with OrbbecSDK_ROS2

@@ -19,7 +19,7 @@ ros2 run orbbec_camera list_devices_node

 Open multi_camera_synced.launch.py, and configure the camera settings as shown below:

-![Depth Point Cloud Visualization](../image/multi_camera_synced/multi_camera_synced2.png)
+![Depth Point Cloud Visualization](../../image/multi_camera_synced/multi_camera_synced2.png)

 1. `gemini_330_series.launch.py` is the launch file for starting the camera.

@@ -19,12 +19,12 @@
 ├── multi_camera_synced_verify.launch.py
 ```

-### multicamera_sync
+**multicamera_sync**

 * `gemini_330_series_synced_verify.launch.py` : Single camera runs launch, which provides the camera running node for multi_camera_synced_verify.launch.py.
 * `multi_camera_synced_verify.launch.py` : Multi camer synced + launch of save_rgbir tool.

-#### output
+**output**

 > The `ouput` folder is the folder where the camera pictures are output

@@ -36,13 +36,13 @@ In the output example provided
 * `DevicesInfo.txt` : Camera equipment basic information (need to be modified).
 * `StreamProfileInfo.txt` : Camera video stream information (no need to modify).

-#### Python
+**Python**

 * `Config.ini` : Configuration file for Python analysis script (need to be modified).

 ## Preparation for operation

-### save_rgbir node
+**save_rgbir node**

 Edit multi_camera_synced_verify.launch.py and fill in the activated camera device,we can find that save_rgbir is started at the end.

@@ -88,7 +88,7 @@ save_rgbir is a tool for saving images. The configuration file of this tool is i
 * `usb_ports` : "primary", "secondary 1", "secondary 2", "secondary 3", fill in as many usb_ports as there are cameras
 * `camera_name` : The name of the camera setting, for example: camera_01

-### DevicesInfo.txt
+**DevicesInfo.txt**

 Edit DevicesInfo.txt. Only the `primarySerialNumber`, `index` and `serialNumber` parameters need to be changed. Other parameters do not need to be changed.Refer to the example of [20250218102900](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool/multicamera_sync/output/20250218102900).

@@ -96,13 +96,13 @@ Edit DevicesInfo.txt. Only the `primarySerialNumber`, `index` and `serialNumber`
 * `index` : Camera index
 * `serialNumber` : The SN serial number of the camera

-### Config.ini
+**Config.ini**

 Edit Config.ini.Modify `frameRate` and `tspRangeThreshold`.

 ## Run this example

-### Run launch and save camera pictures
+**Run launch and save camera pictures**

 * First terminal

@@ -118,7 +118,7 @@ ros2 service call /save_rgbir/start_capture orbbec_camera_msgs/srv/SetInt32 '{da

 When the terminal displays "over", the image is saved.A new multicamera_sync folder will be generated under the workspace.

-### Camera pictures naming format
+**Camera pictures naming format**

 Take [color_SNCP1E5420006D_Index0_g1739874543227_f0_s1739874543327_e50_d16_.jpg](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool/multicamera_sync/output/20250218102900/TotalModeFrames/SNCP1E5420006D_Index0/color_SNCP1E5420006D_Index0_g1739874543227_f0_s1739874543327_e50_d16_.jpg) as an example

@@ -131,7 +131,7 @@ Take [color_SNCP1E5420006D_Index0_g1739874543227_f0_s1739874543327_e50_d16_.jpg]
 * `e50` : The exposure of this frame is 50.
 * `d16` : The gain of this frame is 16.

-### Analyzing camera image data
+**Analyzing camera image data**

 You need to copy the modified [Python folder](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool//multicamera_sync/Python) to the new multi_camera_synced subdirectory, and copy the modified [DevicesInfo.txt ](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool/multicamera_sync/output/20250218102900/DevicesInfo.txt)and [StreamProfileInfo.txt](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool//multicamera_sync/output/20250218102900/StreamProfileInfo.txt) to the same level directory as the TotalModeFrames folder.

@@ -146,13 +146,13 @@ After the operation is successful, you can view the synchronization effect in th

 ## Files that need to be changed

-### Analysis tools
+**Analysis tools**

 * [multi_save_rgbir_params.json](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/config/tools/multisavergbir/multi_save_rgbir_params.json)
 * [DevicesInfo.txt ](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool//multicamera_sync/output/20250218102900/DevicesInfo.txt)
 * [Config.ini](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/examples/multi_camera_synced_verification_tool//multicamera_sync/Python/Config.ini)

-### Camera Configuration
+**Camera Configuration**

 [camera_params.yaml](https://github.com/orbbec/OrbbecSDK_ROS2/tree/v2-main/orbbec_camera/config/camera_params.yaml)(Camera startup parameter settings)

@@ -2,8 +2,6 @@

 > 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)

-## Usage Instructions
-
 ### 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
@@ -1,20 +1,23 @@
 # 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
+### Example

-### Manually loading multiple components into the same process
+**Manually loading multiple components into the same process**

 * Start the component:

  ```bash
  ros2 run rclcpp_components component_container
  ```
+
 * Add the wrapper:

  ```bash
@@ -23,13 +26,14 @@ Further details on efficient intra-process communication can be found [here](htt

  Load other component nodes (consumers of the wrapper topics) in the same way.

-### Using a launch file
+**Using a launch file**

 ```bash
 ros2 launch orbbec_camera gemini_intra_process_demo_launch.py
 ```

-### Limitations
+**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
@@ -6,7 +6,7 @@ optimizing Fast DDS to enhance image transfer efficiency.

 ## Adjusting System Parameters

-### IP Fragmentation Time
+**IP Fragmentation Time**

 - **Path**: `/proc/sys/net/ipv4/ipfrag_time` (default: 30 seconds)
 - **Purpose**: Defines the duration that IP fragments are kept in memory.
@@ -19,7 +19,7 @@ optimizing Fast DDS to enhance image transfer efficiency.
  sudo sysctl net.ipv4.ipfrag_time=3
  ```

-### IP Fragmentation Memory Threshold
+**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.
@@ -32,7 +32,7 @@ optimizing Fast DDS to enhance image transfer efficiency.
  sudo sysctl net.ipv4.ipfrag_high_thresh=134217728
  ```

-### Maximum Buffer Sizes
+**Maximum Buffer Sizes**

 - **Purpose**: Configures the maximum buffer sizes for receiving and sending data, which is critical for high-throughput
  data transmission.
@@ -72,7 +72,7 @@ to [ROS 2 DDS Tuning Documentation](https://docs.ros.org/en/foxy/How-To-Guides/D
 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`
+**Configuration File:** `shm_fastdds.xml`

 Place this file in the `$HOME` directory.

@@ -140,7 +140,7 @@ Place this file in the `$HOME` directory.
 </profiles>
 ```

-### Environment Variables
+**Environment Variables**

 Set the following environment variables to use the custom Fast DDS profile:

@@ -19,35 +19,43 @@ To achieve the lowest possible CPU usage in OrbbecSDK_ROS2, it is recommended to

 ### Test environment

-#### Hardware Configuration
+**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 Configuration**

 * **ROS Version**: ROS2 Humble
+
 * **SDK Version**: OrbbecSDK_ROS2 v2.2.1

-#### Camera Setup
+**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
+**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)
+**`uvc_backend` Comparison (RGB format)**

 | libuvc CPU Usage | v4l2 CPU Usage | Absolute Change |
 | :--------------: | :------------: | :-------------: |
@@ -55,7 +63,7 @@ Note: The following CPU usage data focuses on `uvc_backend`, `color_format` and

 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)
+**`color_format` Comparison (MJPG vs RGB)**

 | Backend | MJPG CPU Usage | RGB CPU Usage | Absolute Change |
 | :-----: | :------------: | :-----------: | :-------------: |
@@ -64,7 +72,7 @@ The CPU usage can be significantly reduced with v4l2 backend. In our implementat

 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
+**Filter Configuration Impact**

 | Filters Applied                                       | libuvc CPU Usage | CPU Usage Increase | v4l2 CPU Usage | CPU Usage Increase |
 | ----------------------------------------------------- | ---------------- | ------------------ | -------------- | ------------------ |
@@ -1,53 +0,0 @@
-## Enabling and Visualizing Point Cloud in ROS 2
-
-This section demonstrates how to enable point cloud data output from the camera node and visualize it using RViz2.
-
-### Enabling Depth Point Cloud
-
-#### Command to Enable Depth Point Cloud
-
-To activate the point cloud data stream for depth information, use the following command:
-
-```bash
-ros2 launch orbbec_camera gemini_330_series.launch.py enable_point_cloud:=true
-```
-
-#### Visualizing Depth Point Cloud in RViz2
-
-After running the above command, perform the following steps to visualize the depth point cloud:
-
-1. Open RViz2.
-2. Add a `PointCloud2` display.
-3. Select the `/camera/depth/points` topic for visualization.
-4. Set the fixed frame to `camera_link` to properly align the data.
-
- **Example Visualization**
-
-Here is what the depth point cloud might look like in RViz2:
-
-![Depth Point Cloud Visualization](../image/point_cloud/image5.jpg)
-
-### Enabling Colored Point Cloud
-
-#### Command to Enable Colored Point Cloud
-
-To enable the colored point cloud feature, enter the following command:
-
-```bash
-ros2 launch orbbec_camera gemini_330_series.launch.py enable_colored_point_cloud:=true
-```
-
-#### Visualizing Colored Point Cloud in RViz2
-
-To visualize the colored point cloud data:
-
-1. Launch RViz2 following the command execution.
-2. Add a `PointCloud2` display panel.
-3. Choose the `/camera/depth_registered/points` topic from the list.
-4. Ensure the fixed frame is set to `camera_link`.
-
- **Example Visualization**
-
-The result of the colored point cloud in RViz2 should look similar to this:
-
-![Colored Point Cloud Visualization](../image/point_cloud/image6.jpg)