docs: update the documentation to version 2.8.8

2026-10-04 03:57:46 +08:00 · 2026-06-06 15:00:20 +08:00
parent 14e481abfe
commit 64bd2e9145
16 changed files with 212 additions and 73 deletions
@@ -15,7 +15,7 @@
 *   **`device_num`**
    *   设备数量。如果需要多个相机，必须填写此参数。
 *   **`device_preset`**
-    *   默认值为 `Default`。可以使用下面命令查看可设置模式
+    *   默认值由启动文件决定。可以使用下面命令查看可设置模式；该工具会同时打印 preset 列表和 preset 版本信息。
    ```bash
    ros2 run orbbec_camera list_camera_profile_mode_node
    ```
@@ -177,11 +177,12 @@
  > **支持模组**：Gemini 305。
 * **`enable_false_positive_filter`**
  * 启用鬼影滤波。可减少重影噪声。
-  > **支持模组**： DaBaiA/DaBaiAL/Gemini345/Gemini345Lg.
+  > **支持模组**：DaBaiA / DaBaiAL / Gemini 330 系列 / Gemini345 / Gemini345Lg。

 #### 视差
 *   **`disparity_to_depth_mode`**
-    *   `HW`：使用硬件视差到深度转换。`SW`：使用软件视差到深度转换。
+    *   `HW`：使用硬件视差到深度转换。`SW`：使用软件视差到深度转换。也可以设置为 `disable` 关闭。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
 *   **`disparity_range_mode`**、**`disparity_search_offset`**、**`disparity_offset_config`**
    *   视差搜索偏移参数。用于 [视差搜索偏移](../5_advanced_guide/configuration/disparity_search_offset.md)。

@@ -200,11 +201,13 @@
  *   启用深度帧与彩色帧的对齐。当 `enable_colored_point_cloud` 设置为 `true` 时需要此字段。
 - **`align_mode`**
  *   要使用的对齐模式。选项为 `HW`（硬件对齐）和 `SW`（软件对齐）。
+  *   该参数大小写不敏感；非法值会报错并回退默认值。
 - **`align_target_stream`**
  *   设置对齐目标流模式。
  *   可能的值为 `COLOR`、`DEPTH`。
  *   `COLOR`：将深度对齐到彩色。
  *   `DEPTH`：将彩色对齐到深度。
+  *   该参数大小写不敏感。硬件 D2C 仅支持 `COLOR` 作为对齐目标；如需对齐到 `DEPTH`，请使用 `align_mode:=SW`。
 - **`intra_camera_sync_reference`**
  - 设置相机内同步的参考点。适用于Gemini 330系列设备，当 `sync_mode` 设置为**软件**或**硬件触发**模式时。**选项：** `Start`、`Middle`、`End`。设置为空时，长基线设备默认End，短基线设备默认Middle。

@@ -229,23 +232,26 @@
    *   启用外参发布。
 *   **`ir_info_url`** / **`color_info_url`**
    *   设置IR/彩色相机信息的URL。
-*   **`enable_color_undistortion`**
-    *   启用彩色去畸变。
+*   **`enable_[color|depth|ir|left_ir|right_ir]_undistortion`**
+    *   启用对应图像流的 SDK 去畸变滤波器。双 IR 设备使用 `enable_left_ir_undistortion` / `enable_right_ir_undistortion`，单 IR 设备使用 `enable_ir_undistortion`。

 #### 时间同步
 *   **`enable_sync_host_time`**
    *   启用主机时间与相机时间的同步。默认值为 `true`。如果使用全局时间，设置为 `false`。
 *   **`time_domain`**
    *   选择时间戳类型：`device`、`global` 和 `system`。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
+*   **`timestamp_clock_type`**
+    *   设置 SDK 时间戳时钟类型。可选值：`realtime`、`monotonic`。默认使用 `realtime`。
 * **`time_sync_period`**
  * 相机时间与主机系统同步的间隔（秒）。
  > **注意**：仅当 **`enable_sync_host_time = true`** 且 **`time_domain = device`** 时需要设置此参数。
 *   **`enable_frame_sync`**
    *   启用帧同步。
-*   **`enable_frame_timestamp_csv`**
-    *   启用帧时间戳CSV记录。主要用于分析彩色/深度帧时间戳、发布延迟和同步问题。
+*   **`enable_frame_drop_log`**
+    *   启用帧丢失日志。日志会分别统计 SDK 接收阶段和 ROS 发布阶段检测到的丢帧。
 *   **`frame_timestamp_csv_file`**
-    *   帧时间戳CSV文件路径。为空时使用默认路径；建议在排查时指定到可写目录。
+    *   帧时间戳 CSV 输出路径。为空时不写 CSV；如需保存 CSV，请指定文件路径，例如 `/tmp/frame_timestamp.csv`。

 #### 日志与诊断
 *   **`log_level`**
@@ -263,8 +269,13 @@
 #### 其他
 *   **`config_file_path`**
    *   YAML配置文件的路径。默认为 `""`。如果未指定，将使用启动文件中的默认参数。
+*   **`load_config_json_file_path`**
+    *   SDK JSON 配置导入路径。设置后节点会在初始化时调用 SDK 导入 JSON 配置。Gemini 330 系列可使用 `gemini_330_series_sdk_json.launch.py` 作为专用启动文件。
+*   **`export_config_json_file_path`**
+    *   SDK JSON 配置导出路径。设置后节点会在初始化完成后将当前设备配置导出为 JSON。也可以通过 `/camera/export_config_json` 服务运行时导出。
 *   **`frame_aggregate_mode`**
    *   设置帧聚合输出模式。可选值：`full_frame`、`color_frame`、`ANY`、`disable`。
+    *   该参数大小写不敏感；非法值会报错并回退默认值。
 *   **`enable_d2c_viewer`**
    *   发布D2C叠加图像（仅用于测试）。

@@ -161,6 +161,10 @@
    ```bash
    ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
    ```
+*   `/camera/export_config_json`
+    ```bash
+    ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
+    ```
 *   `/camera/reboot_device`
    ```bash
    ros2 service call /camera/reboot_device std_srvs/srv/Empty '{}'
@@ -191,7 +195,9 @@

 *   `/camera/set_filter`
    ```bash
-    # filter_name 为滤波器名称，filter_enable 表示是否开启滤波器开关，filter_param 表示滤波参数
+    # filter_name 为滤波器名称，filter_enable 表示是否开启滤波器开关。
+    # filter_param 为旧的按位置传参方式；filter_config 为新的命名参数方式。
+    # filter_param 和 filter_config 不能同时使用。

    # 设置 DecimationFilter: [scale]
    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: DecimationFilter, filter_enable: false, filter_param: [5]}'
@@ -223,6 +229,11 @@
    # 设置 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_config 按参数名调参
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: NoiseRemovalFilter, filter_enable: true, filter_config: [{name: min_diff, value: '256'}, {name: max_size, value: '80'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: HardwareNoiseRemovalFilter, filter_enable: true, filter_config: [{name: threshold, value: '0.2'}]}"
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: SpatialAdvancedFilter, filter_enable: true, filter_config: [{name: alpha, value: '0.5'}, {name: disp_diff, value: '160'}, {name: magnitude, value: '1'}, {name: radius, value: '8'}]}"
    ```

    滤波状态会在服务调用后同步更新到 `/camera/depth_filter_status` 和 `/camera/depth_filters/status`。其中 `/camera/depth_filters/status` 使用结构化消息 `orbbec_camera_msgs/msg/DepthFiltersStatus`，包含每个滤波器的使能状态和参数。
@@ -9,7 +9,9 @@
 这些话题提供每个启用的相机数据流的原始图像数据和相应的校准信息。对于 `color`、`depth`、`ir`、`left_ir` 和 `right_ir` 数据流，模式是一致的。

 *   `/camera/color/image_raw`
-    *   彩色流的原始图像数据。
+    *   彩色流的原始图像数据。彩色格式为 RGB/YUYV 等非 MJPG 时，通常订阅该话题。
+*   `/camera/color/image_raw/compressed`
+    *   来自 MJPG 彩色流的压缩图像数据。使用 `color_format:=MJPG` 时建议订阅该话题，以避免 ROS wrapper 侧额外解码并降低 CPU 占用。
 *   `/camera/color/camera_info`
    *   彩色流的相机校准数据和元数据。
 *   `/camera/color/metadata`