Add documentation for False Positive Filter and SDK JSON configuration

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

@@ -258,8 +258,8 @@ The following are the launch parameters available:
   * Set the downsampling multiple. You can use `ros2 run orbbec_camera list_camera_profile_mode_node` to view the settable resolution. **Default value:** `1`
   > **Supported Modules**: Gemini 301 series
 * **`enable_false_positive_filter`**
-  * Enable this option to reduce ghosting noise.
+  * Enable this option to reduce ghosting noise. For usage examples and runtime tuning, see [False Positive Filtering for Gemini 330 Series](../5_advanced_guide/configuration/false_positive_filter.md).
-  > **Supported Modules**: DaBaiA / DaBaiAL / Gemini 330 series / Gemini345 / Gemini345Lg
+  > **Supported Modules**: Gemini 330 series / Gemini 340 series
 * **`enable_edge_noise_removal_filter`**
   * Enable EdgeNoiseRemovalFilter to reduce edge noise in depth frames.
   > **Supported Modules**: DaBai Max Pro
@@ -330,11 +330,11 @@ The following are the launch parameters available:
 *   **`config_file_path`**
     *   The path to the YAML configuration file. Default is `""`. If not specified, default parameters from the launch file will be used. Some presets or special modes are configured through YAML. See [predefined presets](../5_advanced_guide/configuration/predefined_presets.md).
 *   **`load_config_json_file_path`**
-    *   SDK JSON configuration import path. When set, the node imports the JSON configuration during initialization. For Gemini 330 series, use `gemini_330_series_sdk_json.launch.py` as the dedicated SDK JSON launch file.
+    *   SDK JSON configuration import path. When set, the node imports the JSON configuration during initialization. For Gemini 330 series, use `gemini_330_series_sdk_json.launch.py` as the dedicated SDK JSON launch file. See [SDK JSON Import and Export for Gemini 330 Series](../5_advanced_guide/configuration/sdk_json_config.md).
-    *   If the JSON contains `application_config`, the node syncs stream enable states, resolution, frame rate, format, undistortion, point cloud, HDR merge, and device-level decimation from it when those values are not explicitly overridden by launch parameters.
+    *   If the JSON contains `application_config`, the node syncs stream enable states, resolution, frame rate, format, undistortion, point cloud, HDR merge, and device-level decimation from it when the corresponding launch / YAML parameters have not been passed to the node.
 *   **`export_config_json_file_path`**
-    *   SDK JSON configuration export path. When set, the node exports the current device configuration to JSON after initialization. You can also export at runtime with the `/camera/export_config_json` service.
+    *   SDK JSON configuration export path. When set, the node exports the current device configuration to JSON after initialization. You can also export at runtime with the `/camera/export_config_json` service. See [SDK JSON Import and Export for Gemini 330 Series](../5_advanced_guide/configuration/sdk_json_config.md).
-    *   Before export, the node syncs the current ROS sensor stream, point cloud, and HDR merge settings into the SDK `application_config` when the device supports it.
+    *   Before export, the node syncs the current ROS2 sensor stream, point cloud, and HDR merge settings into the SDK `application_config` when the device supports it.
 *   **`frame_aggregate_mode`**
     *   Set frame aggregate output mode. Optional values: `full_frame`, `color_frame`, `ANY`, `disable`.
     *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.

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

@@ -167,6 +167,7 @@
     ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
     ```
 *   `/camera/export_config_json`
+    Export the current device configuration to an SDK JSON file. For the Gemini 330 series JSON import and export workflow, see [SDK JSON Import and Export for Gemini 330 Series](../5_advanced_guide/configuration/sdk_json_config.md).
     ```bash
     ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
     ```
@@ -212,6 +213,7 @@
 ### Depth Filter Configuration
 
 *   `/camera/set_filter`
+    For `FalsePositiveFilter` startup parameters, status checks, and named-parameter tuning examples, see [False Positive Filtering for Gemini 330 Series](../5_advanced_guide/configuration/false_positive_filter.md).
     ```bash
     # filter_name is the filter name, and filter_enable indicates whether the filter is enabled.
     # filter_param is the legacy positional parameter form; filter_config is the new named parameter form.

docs/en/source/camera_devices/5_advanced_guide/advanced_guide.rst

@@ -40,4 +40,6 @@ Configuration & Modes
     configuration/disparity_search_offset.md
     configuration/interleave_ae_mode.md
     configuration/predefined_presets.md
+    configuration/sdk_json_config.md
+    configuration/false_positive_filter.md
     configuration/net_camera.md

docs/en/source/camera_devices/5_advanced_guide/configuration/false_positive_filter.md

@@ -0,0 +1,216 @@
+# False Positive Filtering for Gemini 330 Series
+
+This document describes how to use the `FalsePositiveFilter` in ROS2 for Gemini 330 series cameras, including enabling it at startup, checking its status, enabling or disabling it at runtime, and temporarily tuning its parameters.
+
+The examples below use the default camera name `camera`. If you set a different `camera_name` at startup, replace `/camera/...` in the commands with the actual name.
+
+## Scope
+
+False positive filtering can reduce ghosting noise in depth frames. For the modules supported by the `enable_false_positive_filter` launch parameter, see [Launch Parameters](../../4_application_guide/launch_parameters.md).
+
+This document focuses on Gemini 330 series usage. Before using the filter, confirm that the device firmware, ROS package version, and selected depth preset match the test scenario.
+
+## Optional: Select a Depth Preset
+
+If you need to select an existing depth preset on the device, set `device_preset`:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="<preset_name>"
+```
+
+For example, to use the default preset:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="Default"
+```
+
+If you manage parameters with YAML, set:
+
+```yaml
+device_preset: "<preset_name>"
+```
+
+Notes:
+
+* If no specific preset is required, use the launch default.
+* `<preset_name>` must be a preset name supported by the device. See [Predefined Presets](predefined_presets.md).
+* To flash or upgrade a preset file, see [firmware_update_tool Device Maintenance Tool](../../6_benchmark/firmware_update_tool.md).
+* The startup log `Loaded device preset: <preset_name>` indicates that the preset was loaded successfully.
+
+## Optional: Import an SDK JSON File
+
+If false positive filter parameters are already written in an SDK JSON file, import it with `load_config_json_file_path`. For the Gemini 330 series SDK JSON import and export workflow, parameter priority, and log checks, see [SDK JSON Import and Export for Gemini 330 Series](sdk_json_config.md).
+
+Common cases:
+
+* If the JSON file contains `parameters.sensor_depth.depth_preset`, set `device_preset` to an empty value.
+* If the JSON file contains detailed false positive filter parameters, the parameters from the JSON file take precedence.
+
+If the JSON file configures false positive filtering, continue to check `/camera/depth_filters/status` and confirm that the `enabled` and `params` fields for `FalsePositiveFilter` match expectations.
+
+## Enable False Positive Filtering at Startup
+
+`gemini_330_series.launch.py` provides a startup switch for false positive filtering:
+
+```python
+DeclareLaunchArgument('enable_false_positive_filter', default_value='false')
+```
+
+Set it to `true` at startup:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  enable_false_positive_filter:=true
+```
+
+If you manage parameters with YAML, set:
+
+```yaml
+enable_false_positive_filter: true
+```
+
+Notes:
+
+* `enable_false_positive_filter` only controls whether the filter is enabled.
+* Detailed false positive filter parameters are not configured through launch parameters.
+* To tune detailed parameters at runtime, use `/camera/set_filter` `filter_config`.
+
+## Check the Filter Status
+
+After starting the node, check the depth filter status topic:
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+Find `FalsePositiveFilter` in the output, and check both the enabled state and the detailed parameter state:
+
+```text
+filter_name: "FalsePositiveFilter"
+enabled: true
+params:
+  - name: "fpEdgeBleedFilterEnable"
+    value: "true"
+  - name: "fpebfROIMinXRatio"
+    value: "0.000000"
+```
+
+How to read the result:
+
+* `enabled: true`: false positive filtering is enabled.
+* `enabled: false`: false positive filtering is disabled.
+* `params`: the current detailed parameter state of the filter.
+
+For the publishing behavior of `/camera/depth_filters/status`, see [Topics](../../4_application_guide/topics.md).
+
+## Enable or Disable the Filter at Runtime
+
+While the node is running, use `/camera/set_filter` to temporarily enable or disable the filter.
+
+Enable:
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: []}"
+```
+
+Disable:
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: false, filter_param: [], filter_config: []}"
+```
+
+After calling the service, check the status again:
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+Notes:
+
+* Service calls are temporary runtime operations.
+* To enable the filter automatically after the next startup, set `enable_false_positive_filter:=true` in launch or YAML.
+* For more `/camera/set_filter` usage, see [Services](../../4_application_guide/services.md).
+
+## Tune Filter Parameters at Runtime
+
+The false positive filter has many parameters. When tuning them at runtime, use `filter_config` and set parameters by name.
+
+### Partial Parameter Example
+
+Enable the filter and temporarily tune a few parameters:
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: [
+{name: 'fpEdgeBleedFilterEnable', value: 'true'},
+{name: 'fpebfROIMinXRatio', value: '0.0'},
+{name: 'fpebfROIMaxXRatio', value: '1.0'}
+]}"
+```
+
+Notes:
+
+* `filter_name` must be `FalsePositiveFilter`.
+* `filter_enable` indicates whether the filter is enabled after this call.
+* Keep `filter_param` empty.
+* Use `filter_config` to specify the parameters to tune.
+* Parameters omitted from `filter_config` keep their current values.
+
+### Full Parameter Example
+
+To set the full false positive filter parameter set in one call, use the following example:
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: [
+{name: 'fpEdgeBleedFilterEnable', value: 'true'},
+{name: 'fpebfROIMinXRatio', value: '0.0'},
+{name: 'fpebfROIMaxXRatio', value: '1.0'},
+{name: 'fpebfROIMinYRatio', value: '0.0'},
+{name: 'fpebfROIMaxYRatio', value: '0.6'},
+{name: 'fpebfMinBleedLength', value: '40'},
+{name: 'fpTextureSparsityFilterEnable', value: 'false'},
+{name: 'fptsfROIMinXRatio', value: '0.0'},
+{name: 'fptsfROIMaxXRatio', value: '1.0'},
+{name: 'fptsfROIMinYRatio', value: '0.0'},
+{name: 'fptsfROIMaxYRatio', value: '0.45'},
+{name: 'fptsfMaxNoiseLevel', value: '6000'},
+{name: 'fptsfMaxSpeckleSize', value: '1300'},
+{name: 'fpPatternAmbiguityFilterEnable', value: 'false'},
+{name: 'fppafROIMinXRatio', value: '0.0'},
+{name: 'fppafROIMaxXRatio', value: '0.99'},
+{name: 'fppafROIMinYRatio', value: '0.0'},
+{name: 'fppafROIMaxYRatio', value: '0.9'},
+{name: 'fppafMaxNoiseLevel', value: '6000'},
+{name: 'fppafMaxSpeckleSize', value: '4000'},
+{name: 'fppafMaxWidthRatio', value: '0.3'},
+{name: 'fppafMaxHeightRatio', value: '0.3'},
+{name: 'fppafTolerance', value: '0.15'},
+{name: 'fppafScore', value: '50'}
+]}"
+```
+
+After calling the service, check the status and parameters:
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+## FAQ
+
+### The startup parameter is set, but the status is still false
+
+Check the following:
+
+* Whether the startup command contains `enable_false_positive_filter:=true`.
+* Whether YAML sets `enable_false_positive_filter` to `false`.
+* Whether the node was not restarted after changing parameters.
+* Whether an old parameter file or launch configuration is still being used.
+
+### Are service tuning changes preserved after restart?
+
+`/camera/set_filter` is temporary runtime tuning and only affects the currently running node. After the node restarts, whether false positive filtering is enabled is controlled by the `enable_false_positive_filter` startup parameter. Detailed parameters set through `filter_config` at runtime are not automatically saved through launch or YAML.
+
+### Tuning fails with an unknown parameter error
+
+Check whether each `name` in `filter_config` is a false positive filter parameter supported by the current device and SDK. Parameter names are case-sensitive.

docs/en/source/camera_devices/5_advanced_guide/configuration/sdk_json_config.md

@@ -0,0 +1,162 @@
+# SDK JSON Import and Export for Gemini 330 Series
+
+This document describes how to import and export SDK JSON configuration files for Gemini 330 series cameras in ROS2.
+
+SDK JSON files can be used to restore or migrate camera configuration. The JSON file can come from the SDK, OrbbecViewer, or a configuration exported by ROS. The ROS2 node passes the file path to the SDK, triggers import or export, and reads back the final camera configuration after initialization.
+
+## Scope
+
+This document only covers SDK JSON import and export for the Gemini 330 series. Prefer the dedicated launch file:
+
+```bash
+gemini_330_series_sdk_json.launch.py
+```
+
+This launch file is designed for SDK JSON workflows. It keeps only the parameters required for ROS2 runtime and device management, reducing the chance that default camera parameters from launch override the JSON configuration.
+
+Full launch files such as `gemini_330_series.launch.py` and `gemini_330_series_low_cpu.launch.py` also provide `load_config_json_file_path` and `export_config_json_file_path`, but they contain many camera parameters. When parameters conflict, launch or YAML parameters that have already been passed to the node take precedence over the corresponding configuration in the JSON file.
+
+## Parameter Priority
+
+When SDK JSON and ROS2 launch / YAML parameters configure the same item, use the following rule to understand the final effective value:
+
+```text
+launch / YAML parameters passed to the node > same configuration in SDK JSON
+```
+
+"Passed to the node" includes default parameter values written by the launch file. Therefore, when using full launch files such as `gemini_330_series.launch.py`, some camera parameters may already be passed to the node even if the user did not explicitly set them on the command line, and those values may override the corresponding JSON configuration.
+
+SDK JSON modules such as `application_config`, `parameters.sensor_depth`, and `parameters.sensor_color` can all contain configuration that corresponds to ROS2 parameters. Regardless of which module a field belongs to, if it controls the same configuration item as a launch / YAML parameter, use the priority rule above to determine the final effective value.
+
+For example, if the JSON file sets `color_brightness=10`, but launch or YAML passes `color_brightness=0`, the camera finally uses `0`. The final effective value is reflected by startup logs such as `Config final readback ...`.
+
+Therefore:
+
+* To restore configuration from JSON as much as possible, use `gemini_330_series_sdk_json.launch.py`.
+* If you must use a full launch file, leave parameters that conflict with JSON empty or unset, or set them to the expected values.
+
+For available depth preset names, see [Predefined Presets](predefined_presets.md). To flash or upgrade a preset file, see [firmware_update_tool Device Maintenance Tool](../../6_benchmark/firmware_update_tool.md).
+
+## Import an SDK JSON File
+
+Use `load_config_json_file_path` to specify the SDK JSON file to import:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series_sdk_json.launch.py \
+  load_config_json_file_path:=/path/to/camera_config.json
+```
+
+The file path can be an absolute path, a relative path, or start with `~`. Relative paths are resolved to absolute paths based on the current working directory.
+
+When import succeeds, the log contains:
+
+```text
+Config JSON loaded file=/path/to/camera_config.json
+```
+
+If the file does not exist, the log contains:
+
+```text
+Config JSON load skip file=/path/to/camera_config.json reason=file_not_found
+```
+
+If the SDK fails to load the JSON file, the log contains:
+
+```text
+Config JSON load failed file=/path/to/camera_config.json error="..."
+```
+
+## Confirm the Final Effective Configuration
+
+After importing JSON, the node reads back the final camera configuration during initialization and prints logs similar to:
+
+```text
+Config final readback [depth] device_preset=Default
+Config final readback [color] color_brightness=0
+Config final readback [filter.depth.DecimationFilter] scale=2
+```
+
+These logs show the final effective camera configuration. If imported JSON conflicts with launch / YAML parameters, the readback logs reflect the overridden final values.
+
+For depth filters, you can also check the current enabled state and parameters from the status topic:
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+## Export an SDK JSON File
+
+After the camera node is running, use the `/camera/export_config_json` service to export the current configuration:
+
+```bash
+ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
+```
+
+After a successful call, the specified path contains an SDK JSON configuration file. The file can be imported later with `load_config_json_file_path`.
+
+The export path can be an absolute path, a relative path, or start with `~`. If the parent directory does not exist, the node creates it automatically.
+
+When export succeeds, the service response and log contain:
+
+```text
+Exported config json file path: /tmp/orbbec_camera_config.json
+```
+
+If the path is empty or export fails, the service returns failure information and the log contains the error reason.
+
+## Export Automatically at Startup
+
+In addition to the runtime service, you can set `export_config_json_file_path` at startup. The node exports the current configuration once after initialization:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series_sdk_json.launch.py \
+  export_config_json_file_path:=/tmp/orbbec_camera_config.json
+```
+
+During field debugging, it is usually better to start the node, confirm the camera state, and then export with `/camera/export_config_json`, so the saved file reflects a confirmed configuration.
+
+## Condensed Field Mapping
+
+The table below lists common SDK JSON fields and their related ROS2 parameters. It is intended to help understand conflicts and overrides; it does not mean every field should be configured through launch.
+
+| SDK JSON field | Related ROS2 parameters | Description |
+| --- | --- | --- |
+| `application_config.sensors.Color.profile.*` | `enable_color`, `color_width`, `color_height`, `color_fps`, `color_format`, `enable_color_undistortion` | Color stream enable state, resolution, frame rate, format, and undistortion. |
+| `application_config.sensors.Depth.profile.*` | `enable_depth`, `depth_width`, `depth_height`, `depth_fps`, `depth_format`, `enable_depth_undistortion` | Depth stream enable state, resolution, frame rate, format, and undistortion. |
+| `application_config.sensors.LeftIR.profile.*` | `enable_left_ir`, `left_ir_width`, `left_ir_height`, `left_ir_fps`, `left_ir_format`, `enable_left_ir_undistortion` | Left IR stream configuration. |
+| `application_config.sensors.RightIR.profile.*` | `enable_right_ir`, `right_ir_width`, `right_ir_height`, `right_ir_fps`, `right_ir_format`, `enable_right_ir_undistortion` | Right IR stream configuration. |
+| `application_config.sensors.Accel.profile.*` | `enable_accel`, `accel_rate`, `accel_range` | Accelerometer enable state, sample rate, and range. |
+| `application_config.sensors.Gyro.profile.*` | `enable_gyro`, `gyro_rate`, `gyro_range` | Gyroscope enable state, sample rate, and range. |
+| `application_config.point_cloud.*` | `enable_point_cloud`, `enable_colored_point_cloud`, `point_cloud_decimation_filter_factor`, `depth_registration`, `align_mode`, `align_target_stream`, `enable_frame_sync`, `frame_aggregate_mode` | Point cloud, colored point cloud, alignment, frame sync, and frame aggregation. |
+| `application_config.hdr_merge.*` | `enable_hdr_merge` | HDR merge configuration. |
+| `application_config.device_decimation.*` | `preset_resolution_config` | Device-level decimation configuration. |
+| `parameters.sensor_depth.depth_preset` | `device_preset` | Depth preset. When importing JSON with a full launch file, avoid overriding JSON with `device_preset`. |
+| Exposure, gain, AE ROI, depth unit, laser, disparity, and image orientation fields under `parameters.sensor_depth` | `depth_exposure`, `depth_gain`, `enable_ir_auto_exposure`, `ir_ae_max_exposure`, `depth_ae_roi_*`, `depth_precision`, `enable_laser`, `laser_energy_level`, `disparity_to_depth_mode`, `disparity_range_mode`, `disparity_search_offset`, `depth_rotation`, `depth_flip`, `depth_mirror`, etc. | Depth-related device configuration. |
+| `parameters.sensor_depth.frame_interleave.*` | `interleave_frame_enable`, `interleave_ae_mode`, `interleave_skip_index`, `hdr_index*_*`, `laser_index*_*` | HDR / laser interleave configuration. |
+| `parameters.sensor_depth.post_processing_filter.*` | `enable_*_filter` and related filter parameters | Depth post-processing filter configuration. Detailed `FalsePositiveFilter` parameters are configured through JSON or `/camera/set_filter` `filter_config`. |
+| Exposure, white balance, brightness, sharpness, anti-flicker, AE ROI, and image orientation fields under `parameters.sensor_color` | `enable_color_auto_exposure`, `color_exposure`, `color_gain`, `enable_color_auto_white_balance`, `color_white_balance`, `color_brightness`, `color_sharpness`, `color_powerline_freq`, `color_ae_roi_*`, `color_rotation`, `color_flip`, `color_mirror`, etc. | Color-related device configuration. |
+| `parameters.sensor_color.post_processing_filter.DecimationFilter` | `enable_color_decimation_filter`, `color_decimation_filter_scale` | Color decimation filter configuration. |
+| `parameters.sensor_left_ir` / `parameters.sensor_right_ir` | `left_ir_rotation`, `right_ir_rotation`, `enable_left_ir_sequence_id_filter`, `enable_right_ir_sequence_id_filter`, `left_ir_sequence_id_filter_id`, `right_ir_sequence_id_filter_id`, etc. | Left and right IR image orientation and sequence id filter configuration. |
+
+## FAQ
+
+### JSON import does not take effect
+
+Check the following:
+
+* Whether `load_config_json_file_path` points to an existing file.
+* Whether the log contains `Config JSON loaded file=...`.
+* Whether a full launch file passed the same launch / YAML parameter and overrode the JSON configuration.
+* Whether the current device and firmware support the fields in the JSON file.
+
+### Should I use the dedicated launch file or the full launch file?
+
+If the goal is to restore configuration from JSON as much as possible, use `gemini_330_series_sdk_json.launch.py`.
+
+If you want to keep the larger set of parameter controls from a launch file, you can continue to use full launch files such as `gemini_330_series.launch.py`, but you need to know which parameters will override JSON.
+
+### Does the exported JSON contain the final configuration?
+
+The exported JSON is based on the current final camera state. Before export, the node syncs current ROS2-side sensor, point cloud, and HDR merge configuration to the SDK `application_config`, and then calls the SDK JSON export.
+
+If JSON was imported at startup and some configuration was overridden by launch / YAML, the exported file contains the overridden final configuration.

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

@@ -257,8 +257,8 @@
   * 设置下采样倍数。可用`ros2 run orbbec_camera list_camera_profile_mode_node`查看可设置分辨率。**默认值：** `1`
   > **支持模组**：Gemini 301 系列。
 * **`enable_false_positive_filter`**
-  * 启用鬼影滤波。可减少重影噪声。
+  * 启用鬼影滤波。可减少重影噪声，使用示例和运行时调参方法请参考 [Gemini 330 系列鬼影滤波](../5_advanced_guide/configuration/false_positive_filter.md)。
-  > **支持模组**：DaBaiA / DaBaiAL / Gemini 330 系列 / Gemini345 / Gemini345Lg。
+  > **支持模组**：Gemini 330 系列 / Gemini 340 系列。
 * **`enable_edge_noise_removal_filter`**
   * 启用 EdgeNoiseRemovalFilter，用于减少深度图边缘噪声。
   > **支持模组**：DaBai Max Pro。
@@ -328,11 +328,11 @@
 *   **`config_file_path`**
     *   YAML配置文件的路径。默认为 `""`。如果未指定，将使用启动文件中的默认参数。部分 preset 或特殊模式会通过 YAML 配置，示例参考 [设备预设](../5_advanced_guide/configuration/predefined_presets.md)。
 *   **`load_config_json_file_path`**
-    *   SDK JSON 配置导入路径。设置后节点会在初始化时调用 SDK 导入 JSON 配置。Gemini 330 系列可使用 `gemini_330_series_sdk_json.launch.py` 作为专用启动文件。
+    *   SDK JSON 配置导入路径。设置后节点会在初始化时调用 SDK 导入 JSON 配置。Gemini 330 系列可使用 `gemini_330_series_sdk_json.launch.py` 作为专用启动文件，使用方法参考 [Gemini 330 系列 SDK JSON 配置导入与导出](../5_advanced_guide/configuration/sdk_json_config.md)。
-    *   如果 JSON 中包含 `application_config`，节点会在未被 launch 参数显式覆盖时同步其中的流开关、分辨率、帧率、格式、去畸变、点云、HDR 合并和设备级下采样配置。
+    *   如果 JSON 中包含 `application_config`，节点会在对应 launch / YAML 参数未传入节点时同步其中的流开关、分辨率、帧率、格式、去畸变、点云、HDR 合并和设备级下采样配置。
 *   **`export_config_json_file_path`**
-    *   SDK JSON 配置导出路径。设置后节点会在初始化完成后将当前设备配置导出为 JSON。也可以通过 `/camera/export_config_json` 服务运行时导出。
+    *   SDK JSON 配置导出路径。设置后节点会在初始化完成后将当前设备配置导出为 JSON。也可以通过 `/camera/export_config_json` 服务运行时导出，使用方法参考 [Gemini 330 系列 SDK JSON 配置导入与导出](../5_advanced_guide/configuration/sdk_json_config.md)。
-    *   导出前会把当前 ROS 参数中的传感器流、点云和 HDR 合并配置同步到 SDK `application_config`（设备支持时）。
+    *   导出前会把当前 ROS2 参数中的传感器流、点云和 HDR 合并配置同步到 SDK `application_config`（设备支持时）。
 *   **`frame_aggregate_mode`**
     *   设置帧聚合输出模式。可选值：`full_frame`、`color_frame`、`ANY`、`disable`。
     *   该参数大小写不敏感；非法值会报错并回退默认值。

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

@@ -167,6 +167,7 @@
     ros2 service call /camera/get_sdk_version orbbec_camera_msgs/srv/GetString
     ```
 *   `/camera/export_config_json`
+    导出当前设备配置为 SDK JSON 文件。Gemini 330 系列的 JSON 导入导出流程请参考 [Gemini 330 系列 SDK JSON 配置导入与导出](../5_advanced_guide/configuration/sdk_json_config.md)。
     ```bash
     ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
     ```
@@ -212,6 +213,7 @@
 ### 深度滤波器配置
 
 *   `/camera/set_filter`
+    `FalsePositiveFilter` 的启动参数、状态确认和命名参数调参示例可参考 [Gemini 330 系列鬼影滤波](../5_advanced_guide/configuration/false_positive_filter.md)。
     ```bash
     # filter_name 为滤波器名称，filter_enable 表示是否开启滤波器开关。
     # filter_param 为旧的按位置传参方式；filter_config 为新的命名参数方式。

docs/zh/source/camera_devices/5_advanced_guide/advanced_guide.rst

@@ -40,4 +40,6 @@
     configuration/disparity_search_offset.md
     configuration/interleave_ae_mode.md
     configuration/predefined_presets.md
+    configuration/sdk_json_config.md
+    configuration/false_positive_filter.md
     configuration/net_camera.md

docs/zh/source/camera_devices/5_advanced_guide/configuration/false_positive_filter.md

@@ -0,0 +1,216 @@
+# Gemini 330 系列鬼影滤波
+
+本文档说明如何在 ROS2 中为 Gemini 330 系列相机使用鬼影滤波 `FalsePositiveFilter`，包括启动时开启、状态确认、运行时开关和临时调参。
+
+以下示例默认相机名称为 `camera`。如果启动时修改了 `camera_name`，请将命令中的 `/camera/...` 替换为实际名称。
+
+## 适用范围
+
+鬼影滤波可用于减少深度图中的重影噪声。启动参数 `enable_false_positive_filter` 的支持模组请参考[启动参数](../../4_application_guide/launch_parameters.md)。
+
+本文重点描述 Gemini 330 系列的使用方式。使用前建议确认设备固件、ROS 包版本和所选 depth preset 与当前测试场景匹配。
+
+## 可选：选择 Depth Preset
+
+如果需要指定设备已有的 depth preset，可通过 `device_preset` 设置：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="<preset_name>"
+```
+
+例如使用默认 preset：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="Default"
+```
+
+如果使用 YAML 管理参数，可写为：
+
+```yaml
+device_preset: "<preset_name>"
+```
+
+说明：
+
+* 不需要指定时，可以使用 launch 默认值。
+* `<preset_name>` 必须是设备支持的 preset 名称，可参考[设备预设](predefined_presets.md)。
+* 如果需要烧录或升级 preset 文件，请参考 [firmware_update_tool 设备维护工具](../../6_benchmark/firmware_update_tool.md)。
+* 启动日志中看到 `Loaded device preset: <preset_name>` 表示加载成功。
+
+## 可选：导入 SDK JSON
+
+如果鬼影滤波参数已经写入 SDK JSON，可通过 `load_config_json_file_path` 导入。Gemini 330 系列 SDK JSON 的导入导出流程、参数优先级和日志确认方法，请参考 [Gemini 330 系列 SDK JSON 配置导入与导出](sdk_json_config.md)。
+
+常见情况：
+
+* JSON 中包含 `parameters.sensor_depth.depth_preset` 时，`device_preset` 应置空。
+* JSON 中包含鬼影滤波详细参数时，优先以 JSON 中的参数为准。
+
+如果 JSON 中配置了鬼影滤波，请继续通过 `/camera/depth_filters/status` 确认 `FalsePositiveFilter` 的 `enabled` 和 `params` 是否符合预期。
+
+## 启动时开启鬼影滤波
+
+`gemini_330_series.launch.py` 中提供了鬼影滤波启动开关：
+
+```python
+DeclareLaunchArgument('enable_false_positive_filter', default_value='false')
+```
+
+启动时设置为 `true` 即可开启：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  enable_false_positive_filter:=true
+```
+
+如果使用 YAML 管理参数，可写为：
+
+```yaml
+enable_false_positive_filter: true
+```
+
+说明：
+
+* `enable_false_positive_filter` 只控制鬼影滤波是否开启。
+* 鬼影滤波详细参数不通过 launch 参数配置。
+* 如需运行时调整详细参数，请使用 `/camera/set_filter` 的 `filter_config`。
+
+## 确认鬼影滤波状态
+
+启动节点后，查看深度滤波状态话题：
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+在输出中查找 `FalsePositiveFilter`，同时确认开关状态和详细参数状态：
+
+```text
+filter_name: "FalsePositiveFilter"
+enabled: true
+params:
+  - name: "fpEdgeBleedFilterEnable"
+    value: "true"
+  - name: "fpebfROIMinXRatio"
+    value: "0.000000"
+```
+
+判断标准：
+
+* `enabled: true`：鬼影滤波已开启。
+* `enabled: false`：鬼影滤波未开启。
+* `params`：当前鬼影滤波的详细参数状态。
+
+`/camera/depth_filters/status` 的发布说明可参考[话题](../../4_application_guide/topics.md)。
+
+## 运行时开启或关闭鬼影滤波
+
+节点运行过程中，可通过 `/camera/set_filter` 临时开启或关闭鬼影滤波。
+
+开启：
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: []}"
+```
+
+关闭：
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: false, filter_param: [], filter_config: []}"
+```
+
+调用后再次确认状态：
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+说明：
+
+* service 调用是运行时临时操作。
+* 如果希望下次启动后自动开启，请在 launch 或 YAML 中设置 `enable_false_positive_filter:=true`。
+* `/camera/set_filter` 的更多用法可参考[服务](../../4_application_guide/services.md)。
+
+## 运行时调整鬼影滤波参数
+
+鬼影滤波参数较多，运行时调参时推荐使用 `filter_config`，按参数名称设置。
+
+### 部分参数示例
+
+开启鬼影滤波，并临时调整部分参数：
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: [
+{name: 'fpEdgeBleedFilterEnable', value: 'true'},
+{name: 'fpebfROIMinXRatio', value: '0.0'},
+{name: 'fpebfROIMaxXRatio', value: '1.0'}
+]}"
+```
+
+说明：
+
+* `filter_name` 固定为 `FalsePositiveFilter`。
+* `filter_enable` 表示本次调用后滤波器是否开启。
+* `filter_param` 保持为空。
+* `filter_config` 用于指定需要调整的参数。
+* 未写入 `filter_config` 的参数保持当前值。
+
+### 完整参数示例
+
+如需一次性设置鬼影滤波的完整参数，可参考以下示例：
+
+```bash
+ros2 service call /camera/set_filter orbbec_camera_msgs/srv/SetFilter "{filter_name: 'FalsePositiveFilter', filter_enable: true, filter_param: [], filter_config: [
+{name: 'fpEdgeBleedFilterEnable', value: 'true'},
+{name: 'fpebfROIMinXRatio', value: '0.0'},
+{name: 'fpebfROIMaxXRatio', value: '1.0'},
+{name: 'fpebfROIMinYRatio', value: '0.0'},
+{name: 'fpebfROIMaxYRatio', value: '0.6'},
+{name: 'fpebfMinBleedLength', value: '40'},
+{name: 'fpTextureSparsityFilterEnable', value: 'false'},
+{name: 'fptsfROIMinXRatio', value: '0.0'},
+{name: 'fptsfROIMaxXRatio', value: '1.0'},
+{name: 'fptsfROIMinYRatio', value: '0.0'},
+{name: 'fptsfROIMaxYRatio', value: '0.45'},
+{name: 'fptsfMaxNoiseLevel', value: '6000'},
+{name: 'fptsfMaxSpeckleSize', value: '1300'},
+{name: 'fpPatternAmbiguityFilterEnable', value: 'false'},
+{name: 'fppafROIMinXRatio', value: '0.0'},
+{name: 'fppafROIMaxXRatio', value: '0.99'},
+{name: 'fppafROIMinYRatio', value: '0.0'},
+{name: 'fppafROIMaxYRatio', value: '0.9'},
+{name: 'fppafMaxNoiseLevel', value: '6000'},
+{name: 'fppafMaxSpeckleSize', value: '4000'},
+{name: 'fppafMaxWidthRatio', value: '0.3'},
+{name: 'fppafMaxHeightRatio', value: '0.3'},
+{name: 'fppafTolerance', value: '0.15'},
+{name: 'fppafScore', value: '50'}
+]}"
+```
+
+调用后查看状态和参数：
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+## 常见问题
+
+### 设置了启动参数，但状态仍为 false
+
+请检查：
+
+* 启动命令是否包含 `enable_false_positive_filter:=true`。
+* YAML 中是否将 `enable_false_positive_filter` 设置为 `false`。
+* 是否修改参数后未重启节点。
+* 是否使用了旧的参数文件或启动配置。
+
+### service 调参后重启是否保留
+
+`/camera/set_filter` 是运行时临时调参，只对当前运行的节点生效。节点重启后，鬼影滤波是否开启由 `enable_false_positive_filter` 启动参数决定；运行时通过 `filter_config` 设置的详细参数不会通过 launch 或 YAML 自动保存。
+
+### 调参时报未知参数
+
+请检查 `filter_config` 中的 `name` 是否为当前设备和 SDK 支持的鬼影滤波参数名。参数名大小写需要保持一致。

docs/zh/source/camera_devices/5_advanced_guide/configuration/sdk_json_config.md

@@ -0,0 +1,162 @@
+# Gemini 330 系列 SDK JSON 配置导入与导出
+
+本文档说明如何在 ROS2 中为 Gemini 330 系列相机导入和导出 SDK JSON 配置文件。
+
+SDK JSON 可用于恢复或迁移相机配置。JSON 文件可以来自 SDK、OrbbecViewer 或 ROS 导出的配置。ROS2 节点负责传入文件路径、触发导入导出，并在初始化后回读相机最终配置。
+
+## 适用范围
+
+本文仅描述 Gemini 330 系列的 SDK JSON 导入导出。建议优先使用专用启动文件：
+
+```bash
+gemini_330_series_sdk_json.launch.py
+```
+
+该启动文件面向 SDK JSON 使用场景，只保留 ROS2 运行和设备管理所需参数，尽量避免 launch 默认相机参数覆盖 JSON 中的配置。
+
+`gemini_330_series.launch.py`、`gemini_330_series_low_cpu.launch.py` 等完整启动文件也提供 `load_config_json_file_path` 和 `export_config_json_file_path` 参数，但这些启动文件包含较多相机参数。参数冲突时，launch 或 YAML 中已经传入节点的参数会优先于 JSON 中的对应配置。
+
+## 参数优先级
+
+当 SDK JSON 与 ROS2 launch / YAML 参数同时配置同一项时，可以按下面的规则理解最终生效值：
+
+```text
+已传入节点的 launch / YAML 参数 > SDK JSON 中的同名配置
+```
+
+这里的“已传入节点”包括启动文件中写入节点参数的默认值。因此，使用 `gemini_330_series.launch.py` 等完整启动文件时，即使用户没有在命令行显式设置某些相机参数，启动文件默认值也可能已经传入节点，并覆盖 JSON 中的对应配置。
+
+SDK JSON 中的 `application_config`、`parameters.sensor_depth`、`parameters.sensor_color` 等模块都可能包含与 ROS2 参数对应的配置。无论字段属于哪个模块，只要它和某个 launch / YAML 参数控制同一项配置，就需要按上述优先级判断最终生效值。
+
+例如，JSON 中配置了 `color_brightness=10`，但 launch 或 YAML 中传入了 `color_brightness=0`，最终相机会使用 `0`。最终生效值以启动日志中的 `Config final readback ...` 为准。
+
+因此：
+
+* 如果希望尽量按 JSON 恢复配置，推荐使用 `gemini_330_series_sdk_json.launch.py`。
+* 如果必须使用完整启动文件，请将会与 JSON 冲突的参数置空、不设置，或改为期望值。
+
+可用 depth preset 名称请参考[设备预设](predefined_presets.md)。如果需要烧录或升级 preset 文件，请参考 [firmware_update_tool 设备维护工具](../../6_benchmark/firmware_update_tool.md)。
+
+## 导入 SDK JSON
+
+使用 `load_config_json_file_path` 指定需要导入的 SDK JSON 文件路径：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series_sdk_json.launch.py \
+  load_config_json_file_path:=/path/to/camera_config.json
+```
+
+文件路径支持绝对路径、相对路径和 `~`。相对路径会按当前工作目录解析为绝对路径。
+
+导入成功时，日志中会看到：
+
+```text
+Config JSON loaded file=/path/to/camera_config.json
+```
+
+如果文件不存在，日志中会看到：
+
+```text
+Config JSON load skip file=/path/to/camera_config.json reason=file_not_found
+```
+
+如果 SDK 加载 JSON 失败，日志中会看到：
+
+```text
+Config JSON load failed file=/path/to/camera_config.json error="..."
+```
+
+## 确认最终生效配置
+
+JSON 导入后，节点会在初始化过程中回读相机最终配置，并输出类似日志：
+
+```text
+Config final readback [depth] device_preset=Default
+Config final readback [color] color_brightness=0
+Config final readback [filter.depth.DecimationFilter] scale=2
+```
+
+这些日志表示相机最终生效的配置。若导入的 JSON 与 launch / YAML 参数冲突，回读日志会反映覆盖后的最终值。
+
+对于深度滤波器，也可以通过状态话题确认当前使能状态和参数：
+
+```bash
+ros2 topic echo /camera/depth_filters/status
+```
+
+## 导出 SDK JSON
+
+相机节点运行后，可以通过 `/camera/export_config_json` 服务导出当前配置：
+
+```bash
+ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"
+```
+
+调用成功后，指定路径会生成 SDK JSON 配置文件。该文件可在后续启动时通过 `load_config_json_file_path` 导入。
+
+导出路径支持绝对路径、相对路径和 `~`。如果父目录不存在，节点会自动创建。
+
+导出成功时，服务返回和日志中会包含：
+
+```text
+Exported config json file path: /tmp/orbbec_camera_config.json
+```
+
+如果路径为空或导出失败，服务会返回失败信息，并在日志中输出错误原因。
+
+## 启动时自动导出
+
+除运行时 service 外，也可以在启动时通过 `export_config_json_file_path` 指定导出路径。节点初始化完成后会自动导出一次当前配置：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series_sdk_json.launch.py \
+  export_config_json_file_path:=/tmp/orbbec_camera_config.json
+```
+
+现场调试时更推荐先启动节点并确认相机状态，再使用 `/camera/export_config_json` 导出，避免在配置尚未确认时保存文件。
+
+## 精简字段映射
+
+下表列出常见 SDK JSON 字段与 ROS2 参数的关系。它用于理解冲突和覆盖关系，不表示所有字段都需要通过 launch 配置。
+
+| SDK JSON 字段 | 相关 ROS2 参数 | 说明 |
+| --- | --- | --- |
+| `application_config.sensors.Color.profile.*` | `enable_color`、`color_width`、`color_height`、`color_fps`、`color_format`、`enable_color_undistortion` | 彩色流开关、分辨率、帧率、格式和去畸变。 |
+| `application_config.sensors.Depth.profile.*` | `enable_depth`、`depth_width`、`depth_height`、`depth_fps`、`depth_format`、`enable_depth_undistortion` | 深度流开关、分辨率、帧率、格式和去畸变。 |
+| `application_config.sensors.LeftIR.profile.*` | `enable_left_ir`、`left_ir_width`、`left_ir_height`、`left_ir_fps`、`left_ir_format`、`enable_left_ir_undistortion` | 左 IR 流配置。 |
+| `application_config.sensors.RightIR.profile.*` | `enable_right_ir`、`right_ir_width`、`right_ir_height`、`right_ir_fps`、`right_ir_format`、`enable_right_ir_undistortion` | 右 IR 流配置。 |
+| `application_config.sensors.Accel.profile.*` | `enable_accel`、`accel_rate`、`accel_range` | 加速度计开关、采样率和量程。 |
+| `application_config.sensors.Gyro.profile.*` | `enable_gyro`、`gyro_rate`、`gyro_range` | 陀螺仪开关、采样率和量程。 |
+| `application_config.point_cloud.*` | `enable_point_cloud`、`enable_colored_point_cloud`、`point_cloud_decimation_filter_factor`、`depth_registration`、`align_mode`、`align_target_stream`、`enable_frame_sync`、`frame_aggregate_mode` | 点云、彩色点云、对齐、帧同步和帧聚合配置。 |
+| `application_config.hdr_merge.*` | `enable_hdr_merge` | HDR merge 配置。 |
+| `application_config.device_decimation.*` | `preset_resolution_config` | 设备级下采样配置。 |
+| `parameters.sensor_depth.depth_preset` | `device_preset` | 深度 preset。使用完整启动文件导入 JSON 时，避免用 `device_preset` 覆盖 JSON。 |
+| `parameters.sensor_depth` 中的曝光、增益、AE ROI、深度单位、激光、视差、图像方向等字段 | `depth_exposure`、`depth_gain`、`enable_ir_auto_exposure`、`ir_ae_max_exposure`、`depth_ae_roi_*`、`depth_precision`、`enable_laser`、`laser_energy_level`、`disparity_to_depth_mode`、`disparity_range_mode`、`disparity_search_offset`、`depth_rotation`、`depth_flip`、`depth_mirror` 等 | 深度相关设备配置。 |
+| `parameters.sensor_depth.frame_interleave.*` | `interleave_frame_enable`、`interleave_ae_mode`、`interleave_skip_index`、`hdr_index*_*`、`laser_index*_*` | HDR / laser interleave 配置。 |
+| `parameters.sensor_depth.post_processing_filter.*` | `enable_*_filter` 和对应滤波器参数 | 深度后处理滤波配置。`FalsePositiveFilter` 的详细参数通过 JSON 或 `/camera/set_filter` 的 `filter_config` 配置。 |
+| `parameters.sensor_color` 中的曝光、白平衡、亮度、锐度、防频闪、AE ROI、图像方向等字段 | `enable_color_auto_exposure`、`color_exposure`、`color_gain`、`enable_color_auto_white_balance`、`color_white_balance`、`color_brightness`、`color_sharpness`、`color_powerline_freq`、`color_ae_roi_*`、`color_rotation`、`color_flip`、`color_mirror` 等 | 彩色相关设备配置。 |
+| `parameters.sensor_color.post_processing_filter.DecimationFilter` | `enable_color_decimation_filter`、`color_decimation_filter_scale` | 彩色降采样滤波配置。 |
+| `parameters.sensor_left_ir` / `parameters.sensor_right_ir` | `left_ir_rotation`、`right_ir_rotation`、`enable_left_ir_sequence_id_filter`、`enable_right_ir_sequence_id_filter`、`left_ir_sequence_id_filter_id`、`right_ir_sequence_id_filter_id` 等 | 左右 IR 图像方向和 sequence id filter 配置。 |
+
+## 常见问题
+
+### JSON 导入后没有生效
+
+请检查：
+
+* `load_config_json_file_path` 指向的文件是否存在。
+* 日志中是否出现 `Config JSON loaded file=...`。
+* 是否使用完整启动文件传入了同名 launch / YAML 参数，导致 JSON 配置被覆盖。
+* 当前设备和固件是否支持 JSON 中的配置字段。
+
+### 应该使用专用 launch 还是完整 launch
+
+如果目标是尽量恢复 JSON 中的配置，推荐使用 `gemini_330_series_sdk_json.launch.py`。
+
+如果想保留启动文件中的大量参数控制，可以继续使用 `gemini_330_series.launch.py` 等完整启动文件，但需要明确哪些参数会覆盖 JSON。
+
+### 导出的 JSON 是否包含最终配置
+
+导出的 JSON 基于当前相机最终状态。导出前，节点会把当前 ROS2 侧的 sensor、point cloud 和 HDR merge 配置同步到 SDK `application_config`，再调用 SDK 导出 JSON。
+
+如果启动时导入了 JSON，同时 launch / YAML 覆盖了部分配置，导出的文件会包含覆盖后的最终配置。