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

docs: update camera feature documentation

Browse Source
This commit is contained in:
slz
2026-04-27 16:41:07 +08:00
parent af9b03e7db
commit 627af59d4f
17 changed files with 358 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/source/camera_devices/1_overview/introduction.md
+1
View File
@@ -181,6 +181,7 @@ To learn how to obtain and upgrade the latest firmware, [please click here](../3
| **Products List** | **Recommended FW Version** | Launch File |
| ----------------------- | -------------------------------------------------------------------------------------------- | --------------------------- |
| Gemini 305 | [1.0.30](https://doc.orbbec.com/documentation/Gemini%20305%20Series%20Documentation/Firmware%20Release%20of%20Gemini%20305) | gemini305.launch.py |
| Gemini 305G | [1.0.54](https://doc.orbbec.com/documentation/Gemini%20305%20Series%20Documentation/Firmware%20Release%20of%20Gemini%20305) | gemini305_g.launch.py |
| 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.6](https://github.com/orbbec/OrbbecFirmware/releases/tag/Gemin435Le-Firmware) | gemini435_le.launch.py |
docs/en/source/camera_devices/4_application_guide/launch_parameters.md
+26 -28
View File
@@ -40,19 +40,14 @@ The following are the launch parameters available:
* ROS 2 Message Quality of Service (QoS) settings. The possible values are `SYSTEM_DEFAULT`, `DEFAULT`, `PARAMETER_EVENTS`, `SERVICES_DEFAULT`, `PARAMETERS`, `SENSOR_DATA` and are case-insensitive. These correspond to `rmw_qos_profile_system_default`, `rmw_qos_profile_default`, `rmw_qos_profile_parameter_events`, `rmw_qos_profile_services_default`, `rmw_qos_profile_parameters`, and `SENSOR_DATA`, respectively.
* **`color.image_raw.enable_pub_plugins`**
* Enable Color image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`depth.image_raw.enable_pub_plugins`**
* Enable Depth image transport plugins. Default: `["image_transport/compressedDepth", "image_transport/raw"]`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`left_ir.image_raw.enable_pub_plugins`**
* Enable Left IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`right_ir.image_raw.enable_pub_plugins`**
* Enable Right IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`point_cloud_decimation_filter_factor`**
* Point cloud downsampling factor. Range: `1–8`. `1` means no downsampling.
> **Supported Versions**: Wrapper version 2.6.3 and above.
### Sensor Controls
@@ -71,18 +66,22 @@ The following are the launch parameters available:
* Set the Color white balance.
* **`color_ae_max_exposure`**
* Set the maximum exposure value for Color auto exposure.
* **`color_ae_max_gain`**
* Set the maximum gain for Color auto exposure. Supported by Gemini 2 firmware `1.5.04` and above, and Gemini 2L firmware `1.5.09` and above.
* **`color_brightness`**, **`color_sharpness`**, **`color_gamma`**, **`color_saturation`**, **`color_contrast`**, **`color_hue`**
* Set the Color brightness, sharpness, gamma, saturation, contrast, and hue.
* **`color_backlight_compensation`**
* Enables the color camera’s backlight compensation feature. **Range**: `0–6`, **Default**: `3`.
* **`color_powerline_freq`**
* Set the power line freq. The possible values are `disable`, `50hz`, `60hz`, `auto`.
* **`color_anti_flicker`**
* Enable Color anti-flicker. Supported by Gemini 330 series firmware `1.7.13` and above, and Gemini 305 series firmware `1.0.54` and above.
* **`enable_color_decimation_filter`** / **`color_decimation_filter_scale`**
* Enable the Color decimation filter and set its scale.
* **`color_ae_roi_[left|right|top|bottom]`**
* Set Color auto exposure ROI.
* **`color_denoising_level`**
* Enables the ISP denoising feature for Gemini 330 series devices. **Range:** `0–8`, **Default:** `0` (auto).
* Enable ISP Color denoising. **Range:** `0–8`; `0` means auto. Supported by Gemini 330 series, Gemini 2 firmware `1.5.04` and above, and Gemini 2L firmware `1.5.09` and above. This feature requires Color auto exposure and new firmware support.
#### Depth Stream
@@ -142,19 +141,14 @@ The following are the launch parameters available:
* Set net device's IP address and port (Usually `8090`).
* **`force_ip_enable`**
* Enable the Force IP function. **Default:** `false`
> **Supported Versions**: Wrapper version 2.5.4 and above.
* **`force_ip_mac`**
* Target device MAC address when multiple cameras are connected (e.g., `"54:14:FD:06:07:DA"`). You can use the `list_devices_node` to find the MAC of each device. **Default:** `""`
> **Supported Versions**: Wrapper version 2.5.4 and above.
* **`force_ip_address`**
* Static IP address to assign. **Default:** `192.168.1.10`
> **Supported Versions**: Wrapper version 2.5.4 and above.
* **`force_ip_subnet_mask`**
* Subnet mask for the static IP. **Default:** `255.255.255.0`
> **Supported Versions**: Wrapper version 2.5.4 and above.
* **`force_ip_gateway`**
* Gateway address for the static IP. **Default:** `192.168.1.1`
> **Supported Versions**: Wrapper version 2.5.4 and above.
> Used for [net camera](../5_advanced_guide/configuration/net_camera.md).
#### Device-Specific
@@ -165,27 +159,23 @@ The following are the launch parameters available:
* **`enable_ptp_config`**
* Enable PTP time synchronization. Requires `enable_sync_host_time` to be `false`.
> **Supported Modules**: Gemini 335Le
> **Supported Versions**: Wrapper version 2.3.4 and above.
* **`preset_resolution_config`**
* Preset resolution configuration for the camera device. Format: "width,height,ir_decimation_factor,depth_decimation_factor". Example: "1280,720,4,4". Leave empty to disable.
> **Supported Modules**: Gemini 435Le
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`ae_mode`**
* `colorbased`: Automatic exposure based on color flow. `depthbased`: Automatic exposure based on depth flow. **Default:** `depthbased`
> **Supported Modules**: Gemini 305
> **Supported Versions**: Wrapper version 2.7.2 and above.
* **`enalbe_sports_mode`**
* Whether to enable sports mode. **Default:** `false`
> **Supported Modules**: Gemini 305
> **Supported Versions**: Wrapper version 2.7.2 and above.
* **`ae_reference_stream`**
* Set the auto-exposure reference stream. Options: `depth`, `color`. Default: `depth`.
> **Supported Modules**: Gemini 305 series.
> **Compatibility**: This replaces the old `ae_mode` parameter. The old values `depthbased/colorbased` map to `depth/color`.
* **`ae_strategy`**
* Set the auto-exposure strategy. Options: `default`, `motion`. Default: `motion`.
> **Supported Modules**: Gemini 305 series.
> **Compatibility**: This replaces the old `enable_sports_mode` parameter.
* **`depth_downscale`** / **`left_ir_downscale`** /**`right_ir_downscale`**
* Set the downsampling multiple. You can use `ros2 run orbbec_camera list_camera_profile_mode_node` to view the settable resolution. **Default value:** `1`
> **Supported Modules**: Gemini 305
> **Supported Versions**: Wrapper version 2.7.2 and above.
* **`enable_false_positive_filter`**
* Enable this option to reduce ghosting noise.
> **Supported Modules**: DaBaiA / DaBaiAL / Gemini345 / Gemini345Lg
> **Supported Versions**: Wrapper version 2.7.6 and above; Firmware version 1.9.03 and above.
#### Disparity
* **`disparity_to_depth_mode`**
* `HW`: use hardware disparity to depth conversion. `SW`: use software disparity to depth conversion.
@@ -214,13 +204,12 @@ The following are the launch parameters available:
* `DEPTH`: Align color to depth.
- **`intra_camera_sync_reference`**
- Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. When set to empty, the long baseline device defaults to End, and the short baseline device defaults to Middle.
> **Supported Versions**: Wrapper version 2.6.3 and above.
### Basic & General Parameters
#### Firmware & Backend
* **`upgrade_firmware`**
* The input parameter is the firmware path.
* The input parameter is the firmware path. For new versions, use the standalone `firmware_update_tool` for firmware updates.
* **`preset_firmware_path`**
* The input parameter is the preset firmware path. If multiple paths are input, each path needs to be separated by `,` and a maximum of 3 firmware paths can be input.
* **`uvc_backend`**
@@ -248,17 +237,22 @@ The following are the launch parameters available:
* **`time_sync_period`**
* Interval (in seconds) for synchronizing the camera time with the host system.
> **Note**: This parameter only needs to be set when `enable_sync_host_time = true` and `time_domain = device`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`enable_frame_sync`**
* Enable the frame synchronization.
* **`enable_frame_timestamp_csv`**
* Enable frame timestamp CSV logging. This is mainly used to analyze Color/Depth frame timestamps, publish latency, and synchronization issues.
* **`frame_timestamp_csv_file`**
* Path of the frame timestamp CSV file. If empty, the default path is used; specify a writable path when debugging.
#### Logging & Diagnostics
* **`log_level`**
* SDK log level. Default is `info`. Optional values: `debug`, `info`, `warn`, `error`, `fatal`.
* Shared SDK and ROS node log level. By default, only current device status is printed; set it to `debug` for more debug logs. Optional values: `none`, `debug`, `info`, `warn`, `error`, `fatal`.
* SDK logs and crash files are saved to `~/.ros/Log` by default. ROS logs remain in `~/.ros/log`.
* **`log_file_name`**
* Saved SDK log file name. Effective when `log_level` is `debug`.
> **Supported Versions**: Wrapper version 2.6.3 and above.
* **`enable_firmware_log`**
* Enable firmware logging. This switch is independent from `enable_heartbeat` and can be enabled only when firmware logs are needed.
* **`diagnostic_period`**
* Diagnostic period in seconds.
* **`enable_heartbeat`**
@@ -311,6 +305,10 @@ The following are the launch parameters available:
* Enable the Depth spatial fast filter. Set with `spatial_fast_filter_radius`.
* **`enable_spatial_moderate_filter`**
* Enable the Depth spatial moderate filter. Set with `spatial_moderate_filter_diff_threshold`, etc.
* **`enable_mgc_noise_removal_filter`**
* Enable the MGC noise removal filter, mainly for OpenNI devices that support this filter.
* **`enable_lut_noise_removal_filter`**
* Enable the LUT noise removal filter, mainly for OpenNI devices that support this filter.
---
docs/en/source/camera_devices/4_application_guide/services.md
+31 -14
View File
@@ -128,7 +128,6 @@
```bash
ros2 service call /camera/get_laser_status orbbec_camera_msgs/srv/GetBool '{}'
```
> **Supported Versions**: Wrapper version 2.6.3 and above.
* `/camera/set_ldp_enable` & `/camera/get_ldp_status`
```bash
ros2 service call /camera/set_ldp_enable std_srvs/srv/SetBool '{data: true}'
@@ -216,6 +215,26 @@
# Set SpatialModerateFilter: [disp_diff, magnitude, radius]
ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: SpatialModerateFilter, filter_enable: true, filter_param: [160,1,3]}'
# Set FalsePositiveFilter: []
ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: FalsePositiveFilter, filter_enable: true, filter_param: []}'
# Set MgcNoiseRemovalFilter / LutNoiseRemovalFilter: []
ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: MgcNoiseRemovalFilter, filter_enable: true, filter_param: []}'
ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: LutNoiseRemovalFilter, filter_enable: true, filter_param: []}'
```
Filter status is updated after service calls on `/camera/depth_filter_status` and `/camera/depth_filters/status`. `/camera/depth_filters/status` uses the structured `orbbec_camera_msgs/msg/DepthFiltersStatus` message and includes each filter's enabled state and parameters.
### Disparity Configuration
* `/camera/set_disparity_range_mode`
```bash
ros2 service call /camera/set_disparity_range_mode orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
```
* `/camera/set_disparity_search_offset`
```bash
ros2 service call /camera/set_disparity_search_offset orbbec_camera_msgs/srv/SetInt32 '{data: 0}'
```
### Data Capture
@@ -237,7 +256,6 @@
ros2 service call /camera/read_customer_data orbbec_camera_msgs/srv/GetString '{}'
```
> **Supported Modules**: Gemini 435Le
> **Supported Versions**: Wrapper version 2.5.4 and above.
* `/camera/set_user_calib_params` & `/camera/get_user_calib_params`
```bash
ros2 service call /camera/set_user_calib_params orbbec_camera_msgs/srv/SetUserCalibParams \
@@ -259,29 +277,28 @@
ros2 service call /camera/get_user_calib_params orbbec_camera_msgs/srv/GetUserCalibParams '{}'
```
> **Supported Modules**: Gemini 435Le
> **Supported Versions**: Wrapper version 2.5.4 and above.
* `/camera/set_ae_mode`
* `/camera/set_ae_reference_stream`
```bash
# depthbased or colorbased
ros2 service call /camera/set_ae_mode orbbec_camera_msgs/srv/SetString "data: depthbased"
# depth or color
ros2 service call /camera/set_ae_reference_stream orbbec_camera_msgs/srv/SetString "{data: depth}"
```
> **Supported Modules**: Gemini 305
> **Supported Versions**: Wrapper version 2.7.2 and above.
* `/camera/set_sports_mode`
> **Supported Modules**: Gemini 305 series.
> **Compatibility**: Replaces the old `/camera/set_ae_mode` service. The old values `depthbased/colorbased` map to `depth/color`.
* `/camera/set_ae_strategy`
```bash
ros2 service call /camera/set_sports_mode std_srvs/srv/SetBool "data: true"
# default or motion
ros2 service call /camera/set_ae_strategy orbbec_camera_msgs/srv/SetString "{data: motion}"
```
> **Supported Modules**: Gemini 305
> **Supported Versions**: Wrapper version 2.7.2 and above.
> **Supported Modules**: Gemini 305 series.
> **Compatibility**: Replaces the old `/camera/set_sports_mode` service.
### Point cloud decimation
* `/camera/set_point_cloud_decimation`
```bash
ros2 service call /camera/set_point_cloud_decimation orbbec_camera_msgs/srv/SetInt32 '{data: 8}'
```
> **Supported Versions**: Wrapper version 2.6.3 and above.
* `/camera/get_point_cloud_decimation`
```bash
ros2 service call /camera/get_point_cloud_decimation orbbec_camera_msgs/srv/GetInt32 '{}'
```
> **Supported Versions**: Wrapper version 2.6.3 and above.
docs/en/source/camera_devices/4_application_guide/topics.md
+5 -1
View File
@@ -61,7 +61,11 @@ The Inertial Measurement Unit (IMU) topics provide accelerometer and gyroscope d
* Reports the current status of the camera device.
* `/camera/depth_filter_status`
* Reports the status of the depth sensor's post-processing filters.
* Reports the status of the depth sensor's post-processing filters. The type is `std_msgs/msg/String`, and the content is a JSON string.
* `/camera/depth_filters/status`
* Reports the structured status of the depth sensor's post-processing filters. The type is `orbbec_camera_msgs/msg/DepthFiltersStatus`.
* The message contains `DepthFilterState[] filters`; each filter state contains `filter_name`, `enabled`, and `DepthFilterParam[] params`.
* `/diagnostics`
* Publishes diagnostic information about the camera node. Currently, this includes the device temperature.
docs/en/source/camera_devices/5_advanced_guide/configuration/net_camera.md
+56 -14
View File
@@ -44,38 +44,80 @@ For [multi_net_camera.launch.py](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v
ros2 launch orbbec_camera multi_net_camera.launch.py
```
## set_device_ip Utility
Use `list_devices_node` to inspect connected devices. Since v2.8.x, this tool also prints firmware version, local network interface name for Ethernet devices, and IP source type (`NONE`, `LLA`, `DHCP`, `PERSISTENT`).
The **`set_device_ip`** executable allows you to configure the IP settings of a network camera directly from ROS 2, including switching between DHCP and static IP, and setting subnet mask and gateway. This is useful for quickly assigning or updating IP addresses without modifying launch files.
## ip_config_tool Utility
> **Note:** The IP settings applied with `set_device_ip` are **permanent** and **will not be reset** if the device is powered off or restarted.
> **Supported Versions**: Wrapper version 2.6.3 and above.
The **`ip_config_tool`** executable allows you to configure network camera IP settings directly from ROS 2, including DHCP, static IP, Force IP, and DHCP address assignment timeout. This is useful for quickly assigning or updating IP addresses without modifying launch files.
> **Note:** Configuration applied with `dhcp` or `set_ip` is written to the device. `force_ip` is temporary and must be applied again after the device is powered off or restarted.
> **Compatibility**: `set_device_ip` is still kept as a legacy alias and calls `ip_config_tool`. The old `old_ip` argument has been renamed to `current_ip`.
**Example Usage**
Show help:
```bash
ros2 run orbbec_camera set_device_ip --ros-args \
-p old_ip:=192.168.1.10 \
-p dhcp:=false \
-p new_ip:=192.168.1.11 \
-p mask:=255.255.255.0 \
-p gateway:=192.168.1.1
ros2 run orbbec_camera ip_config_tool -- --help
```
Enable DHCP:
```bash
ros2 run orbbec_camera ip_config_tool -- \
dhcp \
--current_ip 192.168.1.10 \
--enable_dhcp true
```
Disable DHCP and set a static IP:
```bash
ros2 run orbbec_camera ip_config_tool -- \
set_ip \
--current_ip 192.168.1.10 \
--new_ip 192.168.1.11 \
--mask 255.255.255.0 \
--gateway 192.168.1.1
```
Force IP by MAC address:
```bash
ros2 run orbbec_camera ip_config_tool -- \
force_ip \
--force_ip_mac 54:14:FD:06:07:DA \
--new_ip 192.168.1.50 \
--mask 255.255.255.0 \
--gateway 192.168.1.1
```
Set DHCP address assignment timeout:
```bash
ros2 run orbbec_camera ip_config_tool -- \
set_dhcp_timeout \
--current_ip 192.168.1.10 \
--timeout 10
```
**Parameters**
- **`old_ip`** – Current IP address of the device.
- **`dhcp`** – Set to `true` to use DHCP or `false` for static IP.
- **`new_ip`** – Static IP address to assign when DHCP is disabled.
- **`current_ip`** – Current IP address of the device.
- **`enable_dhcp`** – Enable or disable DHCP for the `dhcp` or `force_ip` subcommand.
- **`new_ip`** – Static IP address to assign.
- **`mask`** – Subnet mask for the new IP.
- **`gateway`** – Gateway address for the new IP.
- **`force_ip_mac`** – Target MAC address for Force IP.
- **`timeout`** / **`dhcp_assign_ip_timeout`** – DHCP address assignment timeout in seconds.
> **Version notes**: `ip_config_tool` was integrated in wrapper version 2.8.0. The `LLA` switch was removed from this tool after wrapper version 2.8.1. `set_dhcp_timeout` is supported from wrapper version 2.8.5.
## Force IP Function
The **Force IP** feature allows you to assign a **static IP address** to a network camera, overriding DHCP settings. This is useful when multiple network cameras are connected, and you need each device to have a fixed IP for reliable communication.
> **Note:** The Force IP configuration **will be reset if the device is powered off or restarted**. You need to reapply the settings after reboot.
> **Supported Versions**: Wrapper version 2.6.3 and above.
**Parameters**
docs/en/source/camera_devices/5_advanced_guide/configuration/predefined_presets.md
+10
View File
@@ -38,6 +38,16 @@ This document lists available presets, features, and recommended scenarios by pr
| Binned Sparse Default | Small dead zone, low power consumption, high frame rate |
| Unbinned Sparse Default | Balance quality and power consumption, improve low-reflection and semi-outdoor effects |
### Gemini 2L Dual IR Mode
Gemini 2L can switch to Dual IR mode with a YAML configuration:
```bash
ros2 launch orbbec_camera gemini2L.launch.py config_file_path:=gemini2L_dual_ir.yaml
```
The configuration file is located at `orbbec_camera/config/gemini2L_dual_ir.yaml`. It sets `depth_work_mode` to `In-scene Calibration`, disables the normal `ir` stream, and enables `left_ir` and `right_ir`.
## Gemini 305
| Defaults | Features |
docs/en/source/camera_devices/5_advanced_guide/multi_camera/multi_camera_synced_verification_tool.md
-1
View File
@@ -4,7 +4,6 @@
This example node is designed for **synchronized capture and timestamp verification** across **four Orbbec cameras**.
It can be used to validate frame alignment accuracy under the multi-camera **Primary / Secondary Synced** mode.
> **Supported Versions**: Wrapper version 2.6.3 and above.
---
docs/en/source/camera_devices/6_benchmark/othertools.md
+48 -1
View File
@@ -1,5 +1,52 @@
# Other Tools
## firmware_update_tool
`firmware_update_tool` upgrades device firmware or writes preset files from the ROS 2 command line. Before upgrading, make sure the device connection is stable. When multiple devices are connected, specify the serial number to avoid updating the wrong device.
Show help:
```bash
ros2 run orbbec_camera firmware_update_tool -- --help
```
Upgrade firmware for one device:
```bash
ros2 run orbbec_camera firmware_update_tool -- \
--serial_number <SN> \
--firmware_path /path/to/firmware.bin
```
Write a preset file:
```bash
ros2 run orbbec_camera firmware_update_tool -- \
--serial_number <SN> \
--preset_path /path/to/preset.bin
```
For batch updates, `--serial_number` accepts comma-separated values. Add `--continue_on_error` if later devices should still be processed after one device fails.
```bash
ros2 run orbbec_camera firmware_update_tool -- \
--serial_number SN1,SN2 \
--firmware_path /path/to/firmware.bin \
--continue_on_error
```
## Frame Timestamp CSV Logging
When `enable_frame_timestamp_csv` is enabled, the camera node records Color and Depth frame timestamp data to a CSV file. This is useful for frame synchronization, publish latency, and timestamp debugging.
```bash
ros2 launch orbbec_camera gemini_330_series.launch.py \
enable_frame_timestamp_csv:=true \
frame_timestamp_csv_file:=/tmp/frame_timestamp.csv
```
The CSV includes SDK frame index, hardware frame number, sensor timestamp, device/global/system timestamp, arrival timestamp, publish timestamp, inter-frame delta values, and SDK delay fields.
## 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)
@@ -49,4 +96,4 @@ ros2 run orbbec_camera ob_benchmark_node
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.
- `1.csv` contains data from the `ob_benchmark_1.launch.py` configuration.