diff --git a/docs/en/source/camera_devices/1_overview/introduction.md b/docs/en/source/camera_devices/1_overview/introduction.md index 0b342869..b6946c08 100644 --- a/docs/en/source/camera_devices/1_overview/introduction.md +++ b/docs/en/source/camera_devices/1_overview/introduction.md @@ -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. diff --git a/docs/en/source/camera_devices/4_application_guide/launch_parameters.md b/docs/en/source/camera_devices/4_application_guide/launch_parameters.md index dd6e02a3..3d9bcb0d 100644 --- a/docs/en/source/camera_devices/4_application_guide/launch_parameters.md +++ b/docs/en/source/camera_devices/4_application_guide/launch_parameters.md @@ -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`** diff --git a/docs/en/source/camera_devices/4_application_guide/services.md b/docs/en/source/camera_devices/4_application_guide/services.md index c1b97695..9dc8d129 100644 --- a/docs/en/source/camera_devices/4_application_guide/services.md +++ b/docs/en/source/camera_devices/4_application_guide/services.md @@ -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 '{}' diff --git a/docs/en/source/camera_devices/4_application_guide/topics.md b/docs/en/source/camera_devices/4_application_guide/topics.md index 5f450754..d5c6f26d 100644 --- a/docs/en/source/camera_devices/4_application_guide/topics.md +++ b/docs/en/source/camera_devices/4_application_guide/topics.md @@ -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` diff --git a/docs/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md b/docs/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md index 068edfab..69893f05 100644 --- a/docs/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md +++ b/docs/en/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md @@ -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). diff --git a/docs/en/source/camera_devices/6_benchmark/diagnostic_tools.md b/docs/en/source/camera_devices/6_benchmark/diagnostic_tools.md index 5b8660b7..90683a2e 100644 --- a/docs/en/source/camera_devices/6_benchmark/diagnostic_tools.md +++ b/docs/en/source/camera_devices/6_benchmark/diagnostic_tools.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 `_color.csv` and `_depth.csv` files. Synchronized accelerometer and gyroscope data are written to `_imu.csv`, while standalone accelerometer and gyroscope data are written to `_accel.csv` and `_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. diff --git a/docs/zh/source/camera_devices/1_overview/introduction.md b/docs/zh/source/camera_devices/1_overview/introduction.md index 90c79d10..656fd961 100644 --- a/docs/zh/source/camera_devices/1_overview/introduction.md +++ b/docs/zh/source/camera_devices/1_overview/introduction.md @@ -1,6 +1,6 @@ # 引言 -OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它支持 ROS2 Foxy、Humble 和 Jazzy 发行版。 +OrbbecSDK ROS2 封装为 Orbbec 相机与 ROS 2 环境提供无缝集成。它支持 ROS2 Foxy、Humble、Jazzy 和 Lyrical 发行版,并提供对 Rolling 的实验性支持。 默认推荐使用 **v2-main** 分支。对于 v2-main 尚不支持的旧 OpenNI 设备,请使用 **main** 分支。仅由 main 分支支持的设备型号列在下表中。 diff --git a/docs/zh/source/camera_devices/4_application_guide/launch_parameters.md b/docs/zh/source/camera_devices/4_application_guide/launch_parameters.md index c60b8002..849cfe5c 100644 --- a/docs/zh/source/camera_devices/4_application_guide/launch_parameters.md +++ b/docs/zh/source/camera_devices/4_application_guide/launch_parameters.md @@ -65,6 +65,8 @@ * 如需降低 CPU 使用率,可参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md) 中的 `color_format` 建议。 * **`enable_[color|depth|left_ir|right_ir|ir]`** * 启用或关闭对应图像流。 +* **`color_frame_queue_max_frames`**、**`left_color_frame_queue_max_frames`**、**`right_color_frame_queue_max_frames`** + * 设置对应彩色帧线程缓存的最大帧数,默认值为 `10`。队列满时会丢弃最旧帧,并增加溢出计数;当前队列长度和溢出统计可通过 `/camera/get_color_queue_stats` 查询。 * **`[color|depth|left_ir|right_ir|ir]_rotation`** * 设置流图像旋转。 * 可能的值为 `0`、`90`、`180`、`270`。 @@ -82,6 +84,9 @@ * 启用无效点云过滤。 * **`point_cloud_qos`、`[stream]_qos`、`[stream]_camera_info_qos`** * ROS 2消息服务质量(QoS)设置。可能的值为 `SYSTEM_DEFAULT`、`DEFAULT`、`PARAMETER_EVENTS`、`SERVICES_DEFAULT`、`PARAMETERS`、`SENSOR_DATA`,不区分大小写。这些分别对应 `rmw_qos_profile_system_default`、`rmw_qos_profile_default`、`rmw_qos_profile_parameter_events`、`rmw_qos_profile_services_default`、`rmw_qos_profile_parameters` 和 `SENSOR_DATA`。 +* **`[stream]_qos_history`、`[stream]_qos_depth`** + * 覆盖图像发布器的 History 和 Depth。常用参数包括 `color_qos_history`、`color_qos_depth`、`depth_qos_history` 和 `depth_qos_depth`;根据所使用的 launch 文件,`stream` 还可以是 `left_color`、`right_color`、`ir`、`left_ir` 或 `right_ir`。 + * `qos_history` 支持 `DEFAULT`、`KEEP_LAST` 和 `KEEP_ALL`(大小写不敏感)。默认值为 `default`,表示沿用 `[stream]_qos` 的 History 策略。`qos_depth` 默认为 `-1`,表示沿用基础 QoS 的 Depth;设置为正数时覆盖该值。 * **`color.image_raw.enable_pub_plugins`** * 启用彩色图像传输插件。具体启用列表由设备 launch 文件决定。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。 * **`depth.image_raw.enable_pub_plugins`** @@ -240,11 +245,11 @@ * `DEPTH`:将彩色对齐到深度。 * 该参数大小写不敏感。硬件 D2C 仅支持 `COLOR` 作为对齐目标;如需对齐到 `DEPTH`,请使用 `align_mode:=SW`。启动和查看方法参考 [对齐深度到彩色](../5_advanced_guide/configuration/align_depth_color.md)。 - **`intra_camera_sync_reference`** - - 设置相机内同步的参考点。适用于Gemini 330系列设备,当 `sync_mode` 设置为**软件**或**硬件触发**模式时。**选项:** `Start`、`Middle`、`End`。参数为空时,节点不修改设备当前设置。 + - 设置支持的 Gemini 330/335 系列设备的相机内同步参考点。**选项:** `Start`、`Middle`、`End`。参数为空时,节点不修改设备当前设置。 ## 设备特定参数 * **`enable_gmsl_trigger`** / **`gmsl_trigger_fps`** - * 启用gmsl触发输出信号 / 设置gmsl触发fps。用于 [gmsl相机](../5_advanced_guide/multi_camera/gmsl_camera.md)。 + * 启用 GMSL 触发输出信号 / 设置 GMSL 触发帧率。支持 Gemini 335Lg、338Lg、345Lg 和 305g,具体参考 [GMSL 相机](../5_advanced_guide/multi_camera/gmsl_camera.md)。 * **`enable_ptp_config`** * 启用PTP时间同步。仅适用于Gemini 335Le。需要 `enable_sync_host_time` 设置为 `false`。 > **支持模组**:Gemini 335Le。 @@ -279,7 +284,7 @@ > **支持模组**:Gemini 330 系列。 * **`enable_fps_boost`** * 启用设备 FPS Boost。默认值为 `false`;仅在设备支持 `FPS Boost` 属性时生效。 - > **支持模组**:Gemini 330 系列。 + > **支持模组:** Gemini 305 / Gemini 330 系列。 * **`enable_edge_noise_removal_filter`** * 启用 EdgeNoiseRemovalFilter,用于减少深度图边缘噪声。 > **支持模组**:DaBai Max Pro。 @@ -344,6 +349,8 @@ * 诊断周期(秒)。 * **`enable_heartbeat`** * 启用心跳功能。默认为 `false`。如果为 `true`,相机节点将向固件发送心跳信号。 +* **`monitor_poll_interval_sec`** + * 设置 SDK 设备心跳和固件日志的轮询间隔,单位为秒。默认值为 `-1`,表示不修改 SDK 当前轮询间隔。有效范围为 `1–10`;超出范围的值会被限制到最近的边界。该参数只设置轮询间隔,不会自动启用心跳或固件日志抓取。 ### 其他 * **`config_file_path`** @@ -359,6 +366,9 @@ * 该参数大小写不敏感;请使用上述有效值。 * **`enable_d2c_viewer`** * 发布D2C叠加图像(仅用于测试)。使用示例参考 [对齐深度到彩色](../5_advanced_guide/configuration/align_depth_color.md)。 +* **`depth_colorizer_mode`** + * 对发布到 `/camera/depth/image_raw` 的深度图进行彩色化。支持 `none`、`jet`、`jet_inv` 和 `gray`。`none` 保持原始深度图,`gray` 发布 `mono8`,`jet` 和 `jet_inv` 发布 `rgb8`。 + * 当选择非 `none` 模式且同时设置 `enable_d2c_viewer:=true` 时,节点会输出告警并自动关闭 `enable_d2c_viewer`,因为 D2C Viewer 要求输入原始 `16UC1` 深度图。 ## IMU @@ -384,11 +394,11 @@ * **`enable_sequence_id_filter`** * 启用深度序列id滤波器。使用 `sequence_id_filter_id` 设置。 * **`enable_threshold_filter`** - * 启用深度阈值滤波器。使用 `threshold_filter_max`、`threshold_filter_min` 设置。 + * 启用深度阈值滤波器。使用 `threshold_filter_max` 和 `threshold_filter_min` 设置。 * **`enable_hardware_noise_removal_filter`** - * 启用深度硬件降噪滤波器。低 CPU 配置建议参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。 + * 启用深度硬件降噪滤波器。Gemini 330 系列设备中,参数为空表示使用 SDK 默认值。低 CPU 配置建议参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。 * **`enable_noise_removal_filter`** - * 启用深度软件降噪滤波器。使用 `noise_removal_filter_min_diff` 等设置。低 CPU 配置建议参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。 + * 启用深度软件降噪滤波器。Gemini 330 系列设备中,参数为空表示使用 SDK 默认值。使用 `noise_removal_filter_min_diff` 等参数设置。低 CPU 配置建议参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。 * **`enable_spatial_filter`** * 启用深度空间滤波器。使用 `spatial_filter_alpha` 等设置。低 CPU 配置建议参考 [降低 CPU 使用率](../5_advanced_guide/performance/lower_cpu_usage.md)。 * **`enable_temporal_filter`** diff --git a/docs/zh/source/camera_devices/4_application_guide/services.md b/docs/zh/source/camera_devices/4_application_guide/services.md index 583938b2..e9e4f4ee 100644 --- a/docs/zh/source/camera_devices/4_application_guide/services.md +++ b/docs/zh/source/camera_devices/4_application_guide/services.md @@ -108,6 +108,22 @@ ros2 service call /camera/set_streams_enable std_srvs/srv/SetBool '{data: false}' ``` +### 彩色帧队列诊断 + +* `/camera/get_color_queue_stats` + +该服务使用 `std_srvs/srv/SetBool`。请求值为 `false` 时查询当前统计信息;请求值为 `true` 时查询并重置累计统计信息。 + +```bash +ros2 service call /camera/get_color_queue_stats std_srvs/srv/SetBool '{data: false}' +``` + +响应的 `message` 字段为 JSON,包含总 `overflow_count` 和 `queues` 对象。每个已启用队列会报告 `capacity_frames`、`queue_size`、`max_queue_size`、`overflow_count`、`oldest_queue_wait_ms` 和 `max_queue_wait_ms`。响应同时包含节点 `namespace` 以及是否执行了统计重置的 `statistics_reset` 字段。 + +```bash +ros2 service call /camera/get_color_queue_stats std_srvs/srv/SetBool '{data: true}' +``` + ### 运行时数据流配置 * `/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 调试 + +Gemini 330 系列设备使用固件 `1.8.21` 及以上版本时,如果设备支持对应 SDK 属性,节点会提供以下服务: + +* `/camera/get_color_ae_awb_status` + + 获取设备 AE/AWB 状态值。 + + ```bash + ros2 service call /camera/get_color_ae_awb_status orbbec_camera_msgs/srv/GetInt32 '{}' + ``` + +* `/camera/get_color_awb_gain` + + 获取原始 Q8.8 格式的 `r_gain`、`b_gain` 和 `g_gain`。 + + ```bash + ros2 service call /camera/get_color_awb_gain orbbec_camera_msgs/srv/GetAwbGain '{}' + ``` + +* `/camera/set_color_awb_gain` + + 设置原始 Q8.8 格式的 RGB 通道增益。设置前必须关闭彩色自动白平衡。 + + ```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}' @@ -303,6 +348,7 @@ ```bash ros2 service call /camera/save_images std_srvs/srv/Empty '{}' ``` + 该服务会为每个已启用的图像流保存帧,数量受 `max_save_images_count` 限制(默认值为 `10`)。每帧都会在当前工作目录下的 `image` 目录中生成对应的 `.raw`、`.png` 和元数据 `.json` 文件。文件名包含流名称、分辨率、帧率、带微秒精度的本地时间戳和帧序号。 * `/camera/save_point_cloud` ```bash ros2 service call /camera/save_point_cloud std_srvs/srv/Empty '{}' diff --git a/docs/zh/source/camera_devices/4_application_guide/topics.md b/docs/zh/source/camera_devices/4_application_guide/topics.md index 71b596b3..f27c5845 100644 --- a/docs/zh/source/camera_devices/4_application_guide/topics.md +++ b/docs/zh/source/camera_devices/4_application_guide/topics.md @@ -19,6 +19,7 @@ * `/camera/depth/image_raw` * 深度流的原始图像数据。 + * 当 `depth_colorizer_mode` 为 `none` 时保持原始深度编码;`gray` 会将发布编码改为 `mono8`,`jet` 和 `jet_inv` 会改为 `rgb8`。 * `/camera/depth/camera_info` * 深度流的相机校准数据和元数据。 * `/camera/depth/metadata` diff --git a/docs/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md b/docs/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md index 374c3256..7587e103 100644 --- a/docs/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md +++ b/docs/zh/source/camera_devices/5_advanced_guide/multi_camera/gmsl_camera.md @@ -6,7 +6,7 @@ ## 单个 GMSL 相机 -GMSL 相机在 OrbbecSDK_ROS2 中的使用与通过 USB 的 Gemini 330 系列相机相同。 +GMSL 相机在 OrbbecSDK_ROS2 中的使用与通过 USB 的 Gemini 330 系列相机相同。ROS2 v2.10.1 支持 Gemini 335Lg、Gemini 338Lg、Gemini 345Lg 和 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 > 注意:默认情况下,multi_gmsl_camera.launch.py 仅启动 color 和 depth。如果您想启动其他传感器,请转到 [camera_secondary_params.yaml](https://github.com/orbbec/OrbbecSDK_ROS2/blob/v2-main/orbbec_camera/config/camera_secondary_params.yaml) 进行修改。 +组合多相机启动时,Gemini 335Lg / 338Lg 使用 `gemini_330_gmsl.launch.py`,Gemini 305g 使用 `gemini_301_series.launch.py`,Gemini 345Lg 使用 `gemini345_lg.launch.py`。 + ## 多个 GMSL 相机同步 首先,请查看如何使用 [multi_camera_synced](./multi_camera_synced.md)。 diff --git a/docs/zh/source/camera_devices/6_benchmark/diagnostic_tools.md b/docs/zh/source/camera_devices/6_benchmark/diagnostic_tools.md index 72958fd3..38f98c5b 100644 --- a/docs/zh/source/camera_devices/6_benchmark/diagnostic_tools.md +++ b/docs/zh/source/camera_devices/6_benchmark/diagnostic_tools.md @@ -4,7 +4,7 @@ ## 帧丢失日志与时间戳 CSV 记录 -开启 `enable_frame_drop_log` 后,相机节点会在日志中输出彩色和深度帧丢失统计,用于定位 SDK 接收阶段和 ROS 发布阶段的丢帧。设置 `frame_timestamp_csv_file` 后,相机节点会额外记录彩色和深度帧的时间戳数据到 CSV 文件,用于分析帧连续性、发布延迟和时间戳异常。 +开启 `enable_frame_drop_log` 后,相机节点会在日志中输出彩色和深度帧丢失统计,用于定位 SDK 接收阶段和 ROS 发布阶段的丢帧。设置 `frame_timestamp_csv_file` 后,节点会将彩色、深度以及已启用 IMU 流的时间戳记录到 CSV 文件,用于分析帧连续性、发布延迟和时间戳异常。启用帧同步(`enable_frame_sync:=true`)时,彩色和深度时间戳会汇聚到同一个 CSV 文件中;未启用时分别写入 `_color.csv` 和 `_depth.csv`。同步加速度计和陀螺仪数据写入 `_imu.csv`,独立加速度计和陀螺仪数据分别写入 `_accel.csv` 和 `_gyro.csv`。所有 CSV 文件遵循相同的分片规则。 ```bash ros2 launch orbbec_camera gemini_330_series.launch.py \ @@ -14,6 +14,10 @@ frame_timestamp_csv_file:=/tmp/frame_timestamp.csv CSV 中包含 SDK frame index、hardware frame number、sensor timestamp、device/global/system timestamp、steady arrival/publish delta、ROS 发布耗时以及 SDK delay 等字段。 +### CSV 分片 + +每个 CSV 文件最多保存 `1,024,575` 行帧数据和 1 行表头。达到上限后,日志器会自动写入下一个带序号的文件,例如 `frame_timestamp_1.csv`、`frame_timestamp_2.csv`。 + ### 字段说明 当前 CSV 中包含两组同构字段,分别以 `color_` 和 `depth_` 为前缀,例如 `color_sdk_frame_index` 和 `depth_sdk_frame_index`。两组字段定义完全一致,仅数据来源不同。