Merge branch 'docs/2.10.1-minimal' into Document

2026-10-08 22:07:46 +08:00 · 2026-08-26 17:04:48 +08:00
parent 9e0418b813 072aec04c3
commit 34fd989a24
12 changed files with 144 additions and 19 deletions
@@ -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 分支支持的设备型号列在下表中。

@@ -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`**
@@ -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 '{}'
@@ -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`
@@ -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)。
@@ -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 文件中；未启用时分别写入 `<stem>_color.csv` 和 `<stem>_depth.csv`。同步加速度计和陀螺仪数据写入 `<stem>_imu.csv`，独立加速度计和陀螺仪数据分别写入 `<stem>_accel.csv` 和 `<stem>_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`。两组字段定义完全一致，仅数据来源不同。