docs: update camera feature documentation

docs/zh/source/camera_devices/4_application_guide/launch_parameters.md

@@ -40,19 +40,14 @@
     *   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`。
 * **`color.image_raw.enable_pub_plugins`**
   * 启用彩色图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 * **`depth.image_raw.enable_pub_plugins`**
   * 启用深度图像传输插件。默认值：`["image_transport/compressedDepth", "image_transport/raw"]`。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 * **`left_ir.image_raw.enable_pub_plugins`**
   * 启用左红外图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 * **`right_ir.image_raw.enable_pub_plugins`**
   * 启用右红外图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 * **`point_cloud_decimation_filter_factor`**
   * 点云下采样因子。范围：`1–8`，`1`表示不下采样，数值越大下采样倍数越大。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 
 ### 传感器控制
 
@@ -71,18 +66,22 @@
     *   设置彩色白平衡。
 *   **`color_ae_max_exposure`**
     *   设置彩色自动曝光的最大曝光值。
+*   **`color_ae_max_gain`**
+    *   设置彩色自动曝光的最大增益。Gemini 2 固件 `1.5.04` 及以上、Gemini 2L 固件 `1.5.09` 及以上支持。范围通常为 `16–112`，具体范围以设备属性为准。
 *   **`color_brightness`**、**`color_sharpness`**、**`color_gamma`**、**`color_saturation`**、**`color_contrast`**、**`color_hue`**
     *   设置彩色亮度、锐度、伽马、饱和度、对比度和色调。
 *   **`color_backlight_compensation`**
     *   启用彩色相机的背光补偿功能。**范围**：`0–6`，**默认值**：`3`。
 *   **`color_powerline_freq`**
     *   设置电源线频率。可能的值为 `disable`、`50hz`、`60hz`、`auto`。
+*   **`color_anti_flicker`**
+    *   启用彩色防闪烁功能。Gemini 330 系列固件 `1.7.13` 及以上支持；Gemini 305 系列固件 `1.0.54` 及以上支持。
 *   **`enable_color_decimation_filter`** / **`color_decimation_filter_scale`**
     *   启用彩色抽取滤波器并设置其比例。
 *   **`color_ae_roi_[left|right|top|bottom]`**
     *   设置彩色自动曝光ROI。
 *   **`color_denoising_level`**
-    *   启用Gemini 330系列设备的ISP降噪功能。**范围：** `0–8`，**默认值：** `0`（自动）。
+    *   启用ISP彩色降噪功能。**范围：** `0–8`，`0`表示自动。支持 Gemini 330 系列、Gemini 2 固件 `1.5.04` 及以上、Gemini 2L 固件 `1.5.09` 及以上；该功能需要开启彩色自动曝光并依赖新固件支持。
 
 
 #### 深度流
@@ -143,19 +142,14 @@
   * 设置网络设备的IP地址和端口（通常为 `8090`）。
 * **`force_ip_enable`**
   * 启用强制IP功能。**默认值：** `false`
-  > **支持版本**： wrapper version 2.5.4 及以上。
 * **`force_ip_mac`**
   * 连接多个相机时的目标设备MAC地址（例如，`"54:14:FD:06:07:DA"`）。您可以使用 `list_devices_node` 查找每个设备的MAC。**默认值：** `""`
-  > **支持版本**： wrapper version 2.5.4 及以上。
 * **`force_ip_address`**
   * 要分配的静态IP地址。**默认值：** `192.168.1.10`
-  > **支持版本**： wrapper version 2.5.4 及以上。
 * **`force_ip_subnet_mask`**
   * 静态IP的子网掩码。**默认值：** `255.255.255.0`
-  > **支持版本**： wrapper version 2.5.4 及以上。
 * **`force_ip_gateway`**
   * 静态IP的网关地址。**默认值：** `192.168.1.1`
-  > **支持版本**： wrapper version 2.5.4 及以上。
 
 > 用于 [网络相机](../5_advanced_guide/configuration/net_camera.md)。
 
@@ -165,27 +159,23 @@
 * **`enable_ptp_config`**
   * 启用PTP时间同步。仅适用于Gemini 335Le。需要 `enable_sync_host_time` 设置为 `false`。
   > **支持模组**：Gemini 335Le。
-  > **支持版本**： wrapper version 2.3.4 及以上。
 * **`preset_resolution_config`**
   * 摄像头设备的预设分辨率配置。格式: "width,height,ir_decimation_factor,depth_decimation_factor". Example: "1280,720,4,4". 留空禁用。
   > **支持模组**：Gemini 435Le。
-  > **支持版本**： wrapper version 2.6.3 及以上。
-* **`ae_mode`**
-  * `colorbased`：自动曝光基于彩色流。`depthbased`：自动曝光基于深度流。**默认值：** `depthbased`
-  > **支持模组**：Gemini 305。
-  > **支持版本**： wrapper version 2.7.2 及以上。
-* **`enalbe_sports_mode`**
-  * 是否开启运动模式。**默认值：** `false`
-  > **支持模组**：Gemini 305。
-  > **支持版本**： wrapper version 2.7.2 及以上。
+* **`ae_reference_stream`**
+  * 设置自动曝光参考流。可选值：`depth`、`color`，默认值为 `depth`。
+  > **支持模组**：Gemini 305 系列。
+  > **兼容说明**：该参数替代旧参数 `ae_mode`，旧值 `depthbased/colorbased` 对应新值 `depth/color`。
+* **`ae_strategy`**
+  * 设置自动曝光策略。可选值：`default`、`motion`，默认值为 `motion`。
+  > **支持模组**：Gemini 305 系列。
+  > **兼容说明**：该参数替代旧参数 `enable_sports_mode`。
 * **`depth_downscale`** / **`left_ir_downscale`** /**`right_ir_downscale`**
   * 设置下采样倍数。可用`ros2 run orbbec_camera list_camera_profile_mode_node`查看可设置分辨率。**默认值：** `1`
   > **支持模组**：Gemini 305。
-  > **支持版本**： wrapper version 2.7.2 及以上。
 * **`enable_false_positive_filter`**
   * 启用鬼影滤波。可减少重影噪声。
   > **支持模组**： DaBaiA/DaBaiAL/Gemini345/Gemini345Lg.
-  > **支持版本**： wrapper version 2.7.6 及以上；firmware version 1.9.03 及以上。
 
 #### 视差
 *   **`disparity_to_depth_mode`**
@@ -215,13 +205,12 @@
   *   `DEPTH`：将彩色对齐到深度。
 - **`intra_camera_sync_reference`**
   - 设置相机内同步的参考点。适用于Gemini 330系列设备，当 `sync_mode` 设置为**软件**或**硬件触发**模式时。**选项：** `Start`、`Middle`、`End`。设置为空时，长基线设备默认End，短基线设备默认Middle。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 
 ### 基础与通用参数
 
 #### 固件与后端
 *   **`upgrade_firmware`**
-    *   输入参数为固件路径。
+    *   输入参数为固件路径。新版本建议使用独立工具 `firmware_update_tool` 进行固件升级。
 *   **`preset_firmware_path`**
     *   输入参数为预设固件路径。如果输入多个路径，每个路径需要用 `,` 分隔，最多可输入3个固件路径。
 *   **`uvc_backend`**
@@ -249,16 +238,21 @@
 * **`time_sync_period`**
   * 相机时间与主机系统同步的间隔（秒）。
   > **注意**：仅当 **`enable_sync_host_time = true`** 且 **`time_domain = device`** 时需要设置此参数。
-  > **支持版本**： wrapper version 2.6.3 及以上。
 *   **`enable_frame_sync`**
     *   启用帧同步。
+*   **`enable_frame_timestamp_csv`**
+    *   启用帧时间戳CSV记录。主要用于分析彩色/深度帧时间戳、发布延迟和同步问题。
+*   **`frame_timestamp_csv_file`**
+    *   帧时间戳CSV文件路径。为空时使用默认路径；建议在排查时指定到可写目录。
 
 #### 日志与诊断
 *   **`log_level`**
-    *   SDK日志级别。默认为 `info`。可选值：`debug`、`info`、`warn`、`error`、`fatal`。
+    *   SDK和ROS节点日志级别。默认只输出设备当前状态；需要更多调试信息时可设置为 `debug`。可选值：`none`、`debug`、`info`、`warn`、`error`、`fatal`。
+    *   SDK日志和崩溃文件默认保存在 `~/.ros/Log`，ROS日志仍保存在 `~/.ros/log`。
 * **`log_file_name`**
   * 保存的SDK日志文件名。当`log_level`为`debug`时生效。
-  > **支持版本**： wrapper version 2.6.3 及以上。
+*   **`enable_firmware_log`**
+    *   启用固件日志。该开关与 `enable_heartbeat` 解耦，适合在需要抓取固件日志时单独开启。
 *   **`diagnostic_period`**
     *   诊断周期（秒）。
 *   **`enable_heartbeat`**
@@ -311,6 +305,10 @@
     *   启用深度空间快速滤波器。使用 `spatial_fast_filter_radius` 设置。
 *   **`enable_spatial_moderate_filter`**
     *   启用深度空间中等滤波器。使用 `spatial_moderate_filter_diff_threshold` 等设置。
+*   **`enable_mgc_noise_removal_filter`**
+    *   启用 MGC 降噪滤波器，主要用于支持该滤波能力的 OpenNI 设备。
+*   **`enable_lut_noise_removal_filter`**
+    *   启用 LUT 降噪滤波器，主要用于支持该滤波能力的 OpenNI 设备。
 
 ---
 

docs/zh/source/camera_devices/4_application_guide/services.md

@@ -128,7 +128,6 @@
     ```bash
     ros2 service call /camera/get_laser_status orbbec_camera_msgs/srv/GetBool '{}'
     ```
-    > **支持版本**： wrapper version 2.6.3 及以上。
 *   `/camera/set_ldp_enable` & `/camera/get_ldp_status`
     ```bash
     ros2 service call /camera/set_ldp_enable std_srvs/srv/SetBool '{data: true}'
@@ -217,6 +216,26 @@
 
     # 设置 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]}'
+
+    # 设置 FalsePositiveFilter: []
+    ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter '{filter_name: FalsePositiveFilter, filter_enable: true, filter_param: []}'
+
+    # 设置 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: []}'
+    ```
+
+    滤波状态会在服务调用后同步更新到 `/camera/depth_filter_status` 和 `/camera/depth_filters/status`。其中 `/camera/depth_filters/status` 使用结构化消息 `orbbec_camera_msgs/msg/DepthFiltersStatus`，包含每个滤波器的使能状态和参数。
+
+### 视差配置
+
+*   `/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}'
     ```
 
 ### 数据捕获与校准管理
@@ -238,7 +257,6 @@
     ros2 service call /camera/read_customer_data orbbec_camera_msgs/srv/GetString '{}'
     ```
     > **支持模组**：Gemini 435Le。
-    > **支持版本**： wrapper version 2.5.4 及以上。
 *   `/camera/set_user_calib_params` & `/camera/get_user_calib_params`
     ```bash
     ros2 service call /camera/set_user_calib_params orbbec_camera_msgs/srv/SetUserCalibParams \
@@ -260,28 +278,27 @@
     ros2 service call /camera/get_user_calib_params orbbec_camera_msgs/srv/GetUserCalibParams '{}'
     ```
     > **支持模组**：Gemini 435Le。
-    > **支持版本**： wrapper version 2.5.4 及以上。
-*   `/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}"
     ```
-    > **支持模组**：Gemini 305。
-    > **支持版本**： wrapper version 2.7.2 及以上。
-*   `/camera/set_sports_mode`
+    > **支持模组**：Gemini 305 系列。
+    > **兼容说明**：替代旧服务 `/camera/set_ae_mode`，旧值 `depthbased/colorbased` 对应新值 `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}"
     ```
-    > **支持模组**：Gemini 305。
-    > **支持版本**： wrapper version 2.7.2 及以上。
+    > **支持模组**：Gemini 305 系列。
+    > **兼容说明**：替代旧服务 `/camera/set_sports_mode`。
+
 ### 点云下采样
 *   `/camera/set_point_cloud_decimation`
     ```bash
     ros2 service call /camera/set_point_cloud_decimation orbbec_camera_msgs/srv/SetInt32 '{data: 8}'
     ```
-    > **支持版本**： wrapper version 2.6.3 及以上。
 *   `/camera/get_point_cloud_decimation`
     ```bash
     ros2 service call /camera/get_point_cloud_decimation orbbec_camera_msgs/srv/GetInt32 '{}'
     ```
-    > **支持版本**： wrapper version 2.6.3 及以上。

docs/zh/source/camera_devices/4_application_guide/topics.md

@@ -21,7 +21,6 @@
     *   深度流的相机校准数据和元数据。
 *   `/camera/depth/metadata`
     *   来自深度流固件的底层元数据。
-
 *   `/camera/ir/image_raw`
     *   红外（IR）流的原始图像数据。
 *   `/camera/ir/camera_info`
@@ -61,7 +60,11 @@
     *   报告相机设备的当前状态。
 
 *   `/camera/depth_filter_status`
-    *   报告深度传感器后处理滤波器的状态。
+    *   报告深度传感器后处理滤波器的状态，类型为 `std_msgs/msg/String`，内容为 JSON 字符串。
+
+*   `/camera/depth_filters/status`
+    *   报告深度传感器后处理滤波器的结构化状态，类型为 `orbbec_camera_msgs/msg/DepthFiltersStatus`。
+    *   消息中包含 `DepthFilterState[] filters`，每个滤波器状态包含 `filter_name`、`enabled` 和 `DepthFilterParam[] params`。
 
 *   `/diagnostics`
     *   发布相机节点的诊断信息。目前包括设备温度。