docs: enhance false positive filter and SDK JSON configuration documentation for clarity and usage guidelines

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

@@ -45,8 +45,20 @@ If false positive filter parameters are already written in an SDK JSON file, imp
 
 Common cases:
 
-* If the JSON file contains `parameters.sensor_depth.depth_preset`, set `device_preset` to an empty value.
+* When using a full launch file, if the JSON file contains `parameters.sensor_depth.depth_preset`, set the `device_preset` passed through launch / YAML to an empty value so that it does not override the depth preset in JSON.
-* If the JSON file contains detailed false positive filter parameters, the parameters from the JSON file take precedence.
+* SDK JSON supports partial import. You can remove modules and parameters that are not needed and keep only the depth preset, false positive filter, or other configuration required for the current import.
+* When the JSON file contains detailed false positive filter parameters, those parameters come from the fields retained in JSON. Handle the filter enable state according to the launch-file differences below.
+
+When `gemini_330_series_sdk_json.launch.py` is used, the launch file does not pass `enable_false_positive_filter`, so the filter enable state in JSON can take effect directly. When a full launch file such as `gemini_330_series.launch.py` is used, its default `enable_false_positive_filter=false` overrides the enable state in JSON. If the JSON configuration requires the false positive filter to be enabled, also set:
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="" \
+  enable_false_positive_filter:=true \
+  load_config_json_file_path:=/path/to/camera_config.json
+```
+
+Here, `enable_false_positive_filter` controls only the enable state. It does not replace the detailed false positive filter parameters in JSON.
 
 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.
 

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

@@ -16,6 +16,14 @@ This launch file is designed for SDK JSON workflows. It keeps only the parameter
 
 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`, 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.
 
+## Partial Import
+
+SDK JSON supports partial import. You can remove modules and parameters that are not needed and keep only the content to be imported. Configuration items omitted from the JSON file are not modified by that JSON import; their final values are still determined by launch / YAML parameters, the current device state, or defaults.
+
+It is recommended to minimize the JSON file for the actual use case. This reduces duplicate configuration and override relationships between JSON and launch / YAML parameters. For example, if only a depth preset and one depth post-processing filter are required, other sensor, point cloud, and unrelated filter configuration can be removed.
+
+After removing modules or parameters, the file must remain valid JSON, and the hierarchy and field names that remain must conform to the SDK JSON format supported by the current device and firmware. Re-import the minimized file and verify the final effective configuration as described below.
+
 ## Parameter Priority
 
 When SDK JSON and ROS2 launch / YAML parameters configure the same item, use the following rule to understand the final effective value:
@@ -84,6 +92,19 @@ For depth filters, you can also check the current enabled state and parameters f
 ros2 topic echo /camera/depth_filters/status
 ```
 
+## Recommended On-Site Workflow
+
+Use the following sequence to configure, verify, and persist settings during on-site debugging:
+
+1. Minimize the SDK JSON file so it contains only the modules and parameters that need to be imported.
+2. Start the node with `load_config_json_file_path`. When using a full launch file, check every launch / YAML parameter that overlaps with JSON and set it to the intended value. For example, if the JSON file retains a depth preset or false positive filter configuration, handle `device_preset` and `enable_false_positive_filter` as described above.
+3. Check the `Config JSON loaded ...` and `Config final readback ...` logs. For configuration with a query or status interface, use that interface to verify the final state and parameters. For example, depth filters can be verified through `/camera/depth_filters/status`.
+4. If on-site tuning is required, use the runtime parameters or services provided for that configuration. For example, depth post-processing filters can be adjusted temporarily through `/camera/set_filter`.
+5. After confirming the state, export the current final configuration through `/camera/export_config_json`.
+6. If only part of the exported configuration is needed for delivery, remove unrelated modules and parameters, then re-import the file to verify it.
+
+Runtime parameters and services are intended for verification and tuning while the current node is running. To reuse a confirmed configuration after restarting the node, export the state to SDK JSON and import it again on subsequent startup.
+
 ## Export an SDK JSON File
 
 After the camera node is running, use the `/camera/export_config_json` service to export the current configuration:
@@ -119,7 +140,7 @@ The table below lists common SDK JSON fields and their related ROS2 parameters.
 | `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`. |
+| `parameters.sensor_depth.depth_preset` | `device_preset` | Depth preset. When importing JSON with a full launch file, set the `device_preset` passed through launch / YAML to an empty value so that it does not override JSON. |
 | 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`. |

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

@@ -45,8 +45,20 @@ device_preset: "<preset_name>"
 
 常见情况：
 
-* JSON 中包含 `parameters.sensor_depth.depth_preset` 时，`device_preset` 应置空。
+* 使用完整启动文件且 JSON 中包含 `parameters.sensor_depth.depth_preset` 时，应将 launch / YAML 中传入的 `device_preset` 置空，避免它覆盖 JSON 中的 depth preset。
-* JSON 中包含鬼影滤波详细参数时，优先以 JSON 中的参数为准。
+* SDK JSON 支持部分导入，可以删除不需要的模块和参数，只保留 depth preset、鬼影滤波等本次需要导入的配置。
+* JSON 中包含鬼影滤波详细参数时，详细参数以 JSON 中保留的字段为准；滤波器开关仍需按下面的启动文件差异处理。
+
+使用 `gemini_330_series_sdk_json.launch.py` 时，启动文件不会传入 `enable_false_positive_filter`，JSON 中的鬼影滤波开关可以直接生效。使用 `gemini_330_series.launch.py` 等完整启动文件时，其默认的 `enable_false_positive_filter=false` 会覆盖 JSON 中的开关。如果 JSON 需要开启鬼影滤波，应同时设置：
+
+```bash
+ros2 launch orbbec_camera gemini_330_series.launch.py \
+  device_preset:="" \
+  enable_false_positive_filter:=true \
+  load_config_json_file_path:=/path/to/camera_config.json
+```
+
+其中 `enable_false_positive_filter` 只控制开关，不会替代 JSON 中的鬼影滤波详细参数。
 
 如果 JSON 中配置了鬼影滤波，请继续通过 `/camera/depth_filters/status` 确认 `FalsePositiveFilter` 的 `enabled` 和 `params` 是否符合预期。
 

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

@@ -16,6 +16,14 @@ gemini_330_series_sdk_json.launch.py
 
 `gemini_330_series.launch.py`、`gemini_330_series_low_cpu.launch.py` 等完整启动文件也提供 `load_config_json_file_path` 参数，但这些启动文件包含较多相机参数。参数冲突时，launch 或 YAML 中已经传入节点的参数会优先于 JSON 中的对应配置。
 
+## 部分导入
+
+SDK JSON 支持部分导入。可以从 JSON 中删除不需要配置的模块和参数，只保留本次需要导入的内容。未写入 JSON 的配置项不会由本次 JSON 导入修改，其最终值仍由 launch / YAML 参数、设备当前状态或默认配置决定。
+
+建议根据实际需求精简 JSON，减少它与 launch / YAML 参数之间的重复配置和覆盖关系。例如，只需要配置 depth preset 和某个深度后处理滤波器时，可以删除其他传感器、点云及无关滤波器的配置。
+
+删除模块或参数后，JSON 必须保持合法格式，保留内容的层级和字段名称也必须符合当前设备及固件支持的 SDK JSON 格式。精简后应重新导入，并按下文方法确认最终生效配置。
+
 ## 参数优先级
 
 当 SDK JSON 与 ROS2 launch / YAML 参数同时配置同一项时，可以按下面的规则理解最终生效值：
@@ -84,6 +92,19 @@ Config final readback [filter.depth.DecimationFilter] scale=2
 ros2 topic echo /camera/depth_filters/status
 ```
 
+## 现场推荐闭环
+
+现场调试建议按以下顺序完成配置、验证和固化：
+
+1. 精简 SDK JSON，只保留本次需要导入的模块和参数。
+2. 使用 `load_config_json_file_path` 启动节点。如果使用完整启动文件，应检查所有与 JSON 重复的 launch / YAML 参数并按预期设置。例如，JSON 中保留了 depth preset 或鬼影滤波配置时，可参考上文处理 `device_preset` 和 `enable_false_positive_filter`。
+3. 检查 `Config JSON loaded ...` 和 `Config final readback ...` 日志。对于提供查询或状态接口的配置，再通过相应接口确认最终状态和参数；例如，深度滤波器可以通过 `/camera/depth_filters/status` 确认。
+4. 如需现场微调，使用对应配置提供的运行时参数或 service。例如，深度后处理滤波器可以通过 `/camera/set_filter` 临时调整。
+5. 状态确认后，通过 `/camera/export_config_json` 导出当前最终配置。
+6. 如交付时只需要部分配置，可再次删除导出文件中无关的模块和参数，然后重新导入验证。
+
+运行时参数和 service 适合当前节点运行期间的验证和微调。需要跨节点重启复用配置时，应将确认后的状态导出为 SDK JSON，并在后续启动时重新导入。
+
 ## 导出 SDK JSON
 
 相机节点运行后，可以通过 `/camera/export_config_json` 服务导出当前配置：
@@ -119,7 +140,7 @@ Exported config json file path: /tmp/orbbec_camera_config.json
 | `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.depth_preset` | `device_preset` | 深度 preset。使用完整启动文件导入 JSON 时，应将 launch / YAML 中传入的 `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` 配置。 |