mirror of
https://github.com/orbbec/OrbbecSDK_ROS2.git
synced 2026-10-08 22:07:46 +08:00
Merge branch 'docs/2.10.1-minimal' into Document
This commit is contained in:
ob-yalian
@@ -1,6 +1,6 @@
|
||||
# Introduction
|
||||
|
||||
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, and Jazzy distributions.
|
||||
OrbbecSDK ROS2 Wrapper provides seamless integration of Orbbec cameras with ROS 2 environment. It supports ROS2 Foxy, Humble, Jazzy, and Lyrical distributions, with experimental support for Rolling.
|
||||
|
||||
By default, we recommend using the **v2-main** branch. For older OpenNI devices not supported by v2-main, please use the **main** branch. Device models that are only supported by the main branch are listed in the table below.
|
||||
|
||||
|
||||
@@ -65,6 +65,8 @@ The following are the launch parameters available:
|
||||
* For lower CPU usage, see the `color_format` recommendations in [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md).
|
||||
* **`enable_[color|depth|left_ir|right_ir|ir]`**
|
||||
* Enable or disable the corresponding image stream.
|
||||
* **`color_frame_queue_max_frames`**, **`left_color_frame_queue_max_frames`**, **`right_color_frame_queue_max_frames`**
|
||||
* Set the maximum number of color frames buffered by the corresponding color-frame worker. The default is `10`; when the queue is full, the oldest frame is discarded and the overflow counter is incremented. The current queue size and overflow counters can be queried with `/camera/get_color_queue_stats`.
|
||||
* **`[color|depth|left_ir|right_ir|ir]_rotation`**
|
||||
* Set stream image rotation.
|
||||
* The possible values are `0`, `90`, `180`, `270`.
|
||||
@@ -82,6 +84,9 @@ The following are the launch parameters available:
|
||||
* Enable filtering of invalid point clouds.
|
||||
* **`point_cloud_qos`, `[stream]_qos`, `[stream]_camera_info_qos`**
|
||||
* 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.
|
||||
* **`[stream]_qos_history`, `[stream]_qos_depth`**
|
||||
* Override the image publisher History and Depth. Common parameters include `color_qos_history`, `color_qos_depth`, `depth_qos_history`, and `depth_qos_depth`; depending on the selected launch file, `stream` can also be `left_color`, `right_color`, `ir`, `left_ir`, or `right_ir`.
|
||||
* `qos_history` accepts `DEFAULT`, `KEEP_LAST`, or `KEEP_ALL` (case-insensitive). The default is `default`, which keeps the history policy from `[stream]_qos`. `qos_depth` defaults to `-1`, which keeps the base QoS depth; a positive value overrides it.
|
||||
* **`color.image_raw.enable_pub_plugins`**
|
||||
* Enable Color image transport plugins. The enabled list is determined by the device launch file. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
|
||||
* **`depth.image_raw.enable_pub_plugins`**
|
||||
@@ -239,12 +244,11 @@ The following are the launch parameters available:
|
||||
* `DEPTH`: Align color to depth.
|
||||
* This parameter is case-insensitive. Hardware D2C only supports `COLOR` as the target stream; use `align_mode:=SW` if you need to align to `DEPTH`. See [Aligning Depth to Color](../5_advanced_guide/configuration/align_depth_color.md) for startup and viewing examples.
|
||||
- **`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 empty, the node leaves the device's current setting unchanged.
|
||||
- Sets the reference point for intra-camera synchronization on supported Gemini 330/335 series devices. **Options:** `Start`, `Middle`, `End`. When empty, the node leaves the device's current setting unchanged.
|
||||
|
||||
## Device-Specific Parameters
|
||||
* **`enable_gmsl_trigger`** / **`gmsl_trigger_fps`**
|
||||
* Enable the gmsl trigger out signal / set gmsl trigger fps.
|
||||
> Only supports [gmsl camera](../5_advanced_guide/multi_camera/gmsl_camera.md).
|
||||
* Enable the GMSL trigger output signal / set the GMSL trigger frame rate. Supported modules are Gemini 335Lg, 338Lg, 345Lg, and 305g; see [GMSL camera](../5_advanced_guide/multi_camera/gmsl_camera.md).
|
||||
>
|
||||
* **`enable_ptp_config`**
|
||||
* Enable PTP time synchronization. Requires `enable_sync_host_time` to be `false`.
|
||||
@@ -280,7 +284,7 @@ The following are the launch parameters available:
|
||||
> **Supported Modules**: Gemini 330 series
|
||||
* **`enable_fps_boost`**
|
||||
* Enable device FPS Boost. The default is `false`; this parameter only takes effect when the device supports the `FPS Boost` property.
|
||||
> **Supported Modules**: Gemini 330 series
|
||||
> **Supported Modules:** Gemini 305 / Gemini 330 series
|
||||
* **`enable_edge_noise_removal_filter`**
|
||||
* Enable EdgeNoiseRemovalFilter to reduce edge noise in depth frames.
|
||||
> **Supported Modules**: DaBai Max Pro
|
||||
@@ -346,6 +350,8 @@ The following are the launch parameters available:
|
||||
* Diagnostic period in seconds.
|
||||
* **`enable_heartbeat`**
|
||||
* Enable the heartbeat function. Default is `false`. If `true`, the camera node will send heartbeat signals to the firmware.
|
||||
* **`monitor_poll_interval_sec`**
|
||||
* Set the SDK polling interval for the device heartbeat and firmware log, in seconds. The default is `-1`, which leaves the SDK polling interval unchanged. Valid values are `1–10`; values outside this range are clamped to the nearest boundary. This parameter controls the polling interval and does not enable heartbeat or firmware-log capture by itself.
|
||||
|
||||
### Miscellaneous
|
||||
* **`config_file_path`**
|
||||
@@ -361,6 +367,9 @@ The following are the launch parameters available:
|
||||
* This parameter is case-insensitive. Use one of the valid values listed above.
|
||||
* **`enable_d2c_viewer`**
|
||||
* Publishes the D2C overlay image (for testing only). See [Aligning Depth to Color](../5_advanced_guide/configuration/align_depth_color.md) for examples.
|
||||
* **`depth_colorizer_mode`**
|
||||
* Colorizes the depth image published on `/camera/depth/image_raw`. Supported values are `none`, `jet`, `jet_inv`, and `gray`. `none` keeps the raw depth image, `gray` publishes `mono8`, and `jet` / `jet_inv` publish `rgb8`.
|
||||
* When a colorizer mode other than `none` is selected together with `enable_d2c_viewer:=true`, the node logs a warning and automatically disables `enable_d2c_viewer`, because the viewer requires a raw `16UC1` depth image.
|
||||
|
||||
## IMU
|
||||
|
||||
@@ -386,11 +395,11 @@ The following are the launch parameters available:
|
||||
* **`enable_sequence_id_filter`**
|
||||
* Enable the Depth sequence id filter. Set with `sequence_id_filter_id`.
|
||||
* **`enable_threshold_filter`**
|
||||
* Enable the Depth threshold filter. Set with `threshold_filter_max`, `threshold_filter_min`.
|
||||
* Enable the Depth threshold filter. Set with `threshold_filter_max` and `threshold_filter_min`.
|
||||
* **`enable_hardware_noise_removal_filter`**
|
||||
* Enable the Depth hardware noise removal filter. See [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md) for low-CPU configuration recommendations.
|
||||
* Enable the Depth hardware noise removal filter. For Gemini 330 series devices, an empty value uses the SDK default. See [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md) for low-CPU configuration recommendations.
|
||||
* **`enable_noise_removal_filter`**
|
||||
* Enable the Depth software noise removal filter. Set with `noise_removal_filter_min_diff`, etc. See [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md) for low-CPU configuration recommendations.
|
||||
* Enable the Depth software noise removal filter. For Gemini 330 series devices, an empty value uses the SDK default. Set `noise_removal_filter_min_diff`, etc. See [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md) for low-CPU configuration recommendations.
|
||||
* **`enable_spatial_filter`**
|
||||
* Enable the Depth spatial filter. Set with `spatial_filter_alpha`, etc. See [Lower CPU Usage](../5_advanced_guide/performance/lower_cpu_usage.md) for low-CPU configuration recommendations.
|
||||
* **`enable_temporal_filter`**
|
||||
|
||||
@@ -108,6 +108,22 @@
|
||||
ros2 service call /camera/set_streams_enable std_srvs/srv/SetBool '{data: false}'
|
||||
```
|
||||
|
||||
### Color Queue Diagnostics
|
||||
|
||||
* `/camera/get_color_queue_stats`
|
||||
|
||||
This service uses `std_srvs/srv/SetBool`. Pass `false` to query the current statistics, or `true` to query and reset the accumulated statistics.
|
||||
|
||||
```bash
|
||||
ros2 service call /camera/get_color_queue_stats std_srvs/srv/SetBool '{data: false}'
|
||||
```
|
||||
|
||||
The JSON response in `message` contains the total `overflow_count` and a `queues` object. Each enabled queue reports `capacity_frames`, `queue_size`, `max_queue_size`, `overflow_count`, `oldest_queue_wait_ms`, and `max_queue_wait_ms`. The service also reports the node `namespace` and whether the statistics were reset in `statistics_reset`.
|
||||
|
||||
```bash
|
||||
ros2 service call /camera/get_color_queue_stats std_srvs/srv/SetBool '{data: true}'
|
||||
```
|
||||
|
||||
### Runtime Stream Configuration
|
||||
|
||||
* `/camera/set_stream_profile`
|
||||
@@ -138,6 +154,35 @@
|
||||
ros2 service call /camera/set_white_balance orbbec_camera_msgs/srv/SetInt32 '{data: 2800}'
|
||||
ros2 service call /camera/get_white_balance orbbec_camera_msgs/srv/GetInt32 '{}'
|
||||
```
|
||||
|
||||
#### Gemini 330 AE/AWB Debugging
|
||||
|
||||
On Gemini 330 series devices with firmware `1.8.21` or later, the following services are advertised when the corresponding SDK properties are supported:
|
||||
|
||||
* `/camera/get_color_ae_awb_status`
|
||||
|
||||
Returns the device AE/AWB status value.
|
||||
|
||||
```bash
|
||||
ros2 service call /camera/get_color_ae_awb_status orbbec_camera_msgs/srv/GetInt32 '{}'
|
||||
```
|
||||
|
||||
* `/camera/get_color_awb_gain`
|
||||
|
||||
Returns the raw Q8.8 `r_gain`, `b_gain`, and `g_gain` values.
|
||||
|
||||
```bash
|
||||
ros2 service call /camera/get_color_awb_gain orbbec_camera_msgs/srv/GetAwbGain '{}'
|
||||
```
|
||||
|
||||
* `/camera/set_color_awb_gain`
|
||||
|
||||
Sets raw Q8.8 RGB channel gains. Color auto white balance must be disabled before setting the gains.
|
||||
|
||||
```bash
|
||||
ros2 service call /camera/set_color_awb_gain orbbec_camera_msgs/srv/SetAwbGain "{r_gain: 512, b_gain: 512, g_gain: 512}"
|
||||
```
|
||||
|
||||
* `/camera/set_laser_enable`
|
||||
```bash
|
||||
ros2 service call /camera/set_laser_enable std_srvs/srv/SetBool '{data: true}'
|
||||
@@ -302,6 +347,7 @@
|
||||
```bash
|
||||
ros2 service call /camera/save_images std_srvs/srv/Empty '{}'
|
||||
```
|
||||
The service saves frames from each enabled image stream, up to the configured `max_save_images_count` (default `10`). For every frame, the node writes matching `.raw`, `.png`, and metadata `.json` files under the `image` directory in the current working directory. File names include the stream, resolution, frame rate, local timestamp with microsecond precision, and frame index.
|
||||
* `/camera/save_point_cloud`
|
||||
```bash
|
||||
ros2 service call /camera/save_point_cloud std_srvs/srv/Empty '{}'
|
||||
|
||||
@@ -19,6 +19,7 @@ These topics provide the raw image data and corresponding calibration informatio
|
||||
|
||||
* `/camera/depth/image_raw`
|
||||
* Raw image data from the depth stream.
|
||||
* When `depth_colorizer_mode` is `none`, the topic keeps the raw depth encoding. `gray` changes the published encoding to `mono8`; `jet` and `jet_inv` change it to `rgb8`.
|
||||
* `/camera/depth/camera_info`
|
||||
* Camera calibration data and metadata for the depth stream.
|
||||
* `/camera/depth/metadata`
|
||||
|
||||
@@ -6,7 +6,7 @@ You can find example usage code in the [example](https://github.com/orbbec/Orbbe
|
||||
|
||||
## Single GMSL camera
|
||||
|
||||
The usage of GMSL camera in OrbbecSDK_ROS2 is the same as that of Gemini 330 series camera via USB.
|
||||
The usage of GMSL camera in OrbbecSDK_ROS2 is the same as that of Gemini 330 series camera via USB. ROS2 v2.10.1 supports Gemini 335Lg, Gemini 338Lg, Gemini 345Lg, and Gemini 305g.
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_gmsl.launch.py
|
||||
@@ -30,6 +30,8 @@ ros2 launch orbbec_camera multi_gmsl_camera.launch.py
|
||||
|
||||
> Note: By default, multi_gmsl_camera.launch.py only starts color and depth. If you want to start other sensors, please go to [camera_secondary_params.yaml](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/config/camera_secondary_params.yaml) to modify them.
|
||||
|
||||
Use `gemini_330_gmsl.launch.py` for Gemini 335Lg / 338Lg, `gemini_301_series.launch.py` for Gemini 305g, and `gemini345_lg.launch.py` for Gemini 345Lg when composing a multi-camera launch.
|
||||
|
||||
## Multi GMSL camera synced
|
||||
|
||||
First, please see how to use [multi_camera_synced](./multi_camera_synced.md).
|
||||
|
||||
@@ -4,7 +4,7 @@ This section describes frame continuity, timestamp, topic statistics, end-to-end
|
||||
|
||||
## Frame Drop Log and Timestamp CSV Recording
|
||||
|
||||
After `enable_frame_drop_log` is enabled, the camera node prints color and depth frame drop statistics in the log. This helps locate frame drops at the SDK receive stage and ROS publish stage. When `frame_timestamp_csv_file` is set, the camera node also records color and depth frame timestamp data to a CSV file for analyzing frame continuity, publish latency, and timestamp anomalies.
|
||||
After `enable_frame_drop_log` is enabled, the camera node prints color and depth frame drop statistics in the log. This helps locate frame drops at the SDK receive stage and ROS publish stage. When `frame_timestamp_csv_file` is set, the camera node records timestamp data for color, depth, and enabled IMU streams to CSV files for analyzing frame continuity, publish latency, and timestamp anomalies. When frame synchronization (`enable_frame_sync:=true`) is enabled, color and depth timestamps are combined into one CSV file; otherwise, they are written to separate `<stem>_color.csv` and `<stem>_depth.csv` files. Synchronized accelerometer and gyroscope data are written to `<stem>_imu.csv`, while standalone accelerometer and gyroscope data are written to `<stem>_accel.csv` and `<stem>_gyro.csv`. All CSV files follow the same rotation rule.
|
||||
|
||||
```bash
|
||||
ros2 launch orbbec_camera gemini_330_series.launch.py \
|
||||
@@ -14,6 +14,10 @@ frame_timestamp_csv_file:=/tmp/frame_timestamp.csv
|
||||
|
||||
The CSV contains SDK frame index, hardware frame number, sensor timestamp, device/global/system timestamp, steady arrival/publish delta, ROS publish duration, and SDK delay fields.
|
||||
|
||||
### CSV Rotation
|
||||
|
||||
Each CSV file contains at most `1,024,575` frame rows plus the header. When the limit is reached, the logger automatically starts the next indexed file, for example `frame_timestamp_1.csv` and `frame_timestamp_2.csv`.
|
||||
|
||||
### Field Description
|
||||
|
||||
The current CSV contains two groups of fields with the same structure, prefixed by `color_` and `depth_`, for example `color_sdk_frame_index` and `depth_sdk_frame_index`. The two groups have identical definitions and differ only in data source.
|
||||
|
||||
Reference in New Issue
Block a user