docs: clarify default values for launch parameters in application guide

2026-09-12 19:20:20 +08:00 · 2026-07-20 16:23:43 +08:00
parent 45b3e1a5f0
commit a0820c27c3
2 changed files with 36 additions and 32 deletions
@@ -42,6 +42,8 @@ Launch parameters can be modified in two ways:

 The following are the launch parameters available:

+> **About defaults:** Device launch files may assign different defaults to the same parameter. A default is listed below only when it can be confirmed consistently. An empty value or `-1` usually means that the node does not actively change the device's current value.
+
 ## Core & Stream Configuration

 *   **`camera_name`**
@@ -81,13 +83,13 @@ The following are the launch parameters available:
 *   **`point_cloud_qos`, `[stream]_qos`, `[stream]_camera_info_qos`**
    *   ROS 2 Message Quality of Service (QoS) settings. The possible values are `SYSTEM_DEFAULT`, `DEFAULT`, `PARAMETER_EVENTS`, `SERVICES_DEFAULT`, `PARAMETERS`, `SENSOR_DATA` and are case-insensitive. These correspond to `rmw_qos_profile_system_default`, `rmw_qos_profile_default`, `rmw_qos_profile_parameter_events`, `rmw_qos_profile_services_default`, `rmw_qos_profile_parameters`, and `SENSOR_DATA`, respectively.
 * **`color.image_raw.enable_pub_plugins`**
-  * Enable Color image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
+  * Enable Color image transport plugins. The enabled list is determined by the device launch file. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
 * **`depth.image_raw.enable_pub_plugins`**
-  * Enable Depth image transport plugins. Default: `["image_transport/compressedDepth", "image_transport/raw"]`. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
+  * Enable Depth image transport plugins. The enabled list is determined by the device launch file. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
 * **`left_ir.image_raw.enable_pub_plugins`**
-  * Enable Left IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
+  * Enable Left IR image transport plugins. The enabled list is determined by the device launch file. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
 * **`right_ir.image_raw.enable_pub_plugins`**
-  * Enable Right IR image transport plugins. Default: `["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
+  * Enable Right IR image transport plugins. The enabled list is determined by the device launch file. See [Compressed Image](compressed_image.md) for subscribing to compressed images.
 * **`point_cloud_decimation_filter_factor`**
  * Point cloud downsampling factor. Range: `1–8`. `1` means no downsampling.
 * **`bag_record_filename`**
@@ -119,7 +121,7 @@ The following are the launch parameters available:
 *   **`color_brightness`**, **`color_sharpness`**, **`color_gamma`**, **`color_saturation`**, **`color_contrast`**, **`color_hue`**
    *   Set the Color brightness, sharpness, gamma, saturation, contrast, and hue.
 *   **`color_backlight_compensation`**
-    *    Enables the color camera’s backlight compensation feature. **Range**: `0–6`, **Default**: `3`.
+    *   Set the Color camera's backlight compensation level. Valid values are `0–6`; the launch default is `-1`, which leaves the current device value unchanged.
 *   **`color_powerline_freq`**
    *   Set the power line freq. The possible values are `disable`, `50hz`, `60hz`, `auto`.
 *   **`color_preset`**
@@ -143,7 +145,7 @@ The following are the launch parameters available:
 *   **`enable_depth_scale`**
    *   Whether to enable depth scaling after setting D2C. `true` means enabled, the default is `true`.
 *   **`depth_precision`**
-    *   The depth precision should be in the format `1mm`. The default value is `1mm`.
+    *   Set the depth precision, using a value such as `1mm`. When the launch argument is empty, the node does not actively change the device's current depth precision.
 *   **`depth_work_mode`**
    *   Set the depth work mode. See [Depth Work Mode Switch](../5_advanced_guide/configuration/depth_work_mode_switch.md) for supported devices, mode query commands, and launch examples.
 *   **`depth_ae_roi_[left|right|top|bottom]`**
@@ -174,7 +176,7 @@ The following are the launch parameters available:

 ### Multi-Camera Synchronization
 *   **`sync_mode`**
-    *   Set sync mode. The default value is `standalone`. See [multi camera synced](../5_advanced_guide/multi_camera/multi_camera_synced.md) for multi-camera connection, synchronization modes, and trigger configuration.
+    *   Set sync mode. The default is determined by the selected launch file. See [multi camera synced](../5_advanced_guide/multi_camera/multi_camera_synced.md) for multi-camera connection, synchronization modes, and trigger configuration.
 *   **`depth_delay_us`** / **`color_delay_us`**
    *   The delay time (microseconds) of the depth/color image capture after receiving the capture command or trigger signal.
 *   **`trigger2image_delay_us`**
@@ -210,7 +212,7 @@ The following are the launch parameters available:
 ### Disparity
 *   **`disparity_to_depth_mode`**
    *   `HW`: use hardware disparity to depth conversion. `SW`: use software disparity to depth conversion. Use `disable` to turn it off.
-    *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
+    *   This parameter is case-insensitive. Use one of the valid values listed above.
 *   **`disparity_range_mode`**, **`disparity_search_offset`**, **`disparity_offset_config`**
    *   Parameters for disparity search offset. Used for [disparity search offset](../5_advanced_guide/configuration/disparity_search_offset.md).

@@ -229,7 +231,7 @@ The following are the launch parameters available:
  *   Enable alignment of the depth frame to the color frame. This field is required when the `enable_colored_point_cloud` is set to `true`. See [Aligning Depth to Color](../5_advanced_guide/configuration/align_depth_color.md) for startup and viewing examples.
 - **`align_mode`**
  *   The alignment mode to be used. Options are `HW` for hardware alignment and `SW` for software alignment.
-  *   This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
+  *   This parameter is case-insensitive. Use one of the valid values listed above.
 - **`align_target_stream`**
  *   Set align target stream mode.
  *   The possible values are `COLOR`, `DEPTH`.
@@ -237,7 +239,7 @@ The following are the launch parameters available:
  *   `DEPTH`: Align color to depth.
  *   This parameter is case-insensitive. Hardware D2C only supports `COLOR` as the target stream; use `align_mode:=SW` if you need to align to `DEPTH`. See [Aligning Depth to Color](../5_advanced_guide/configuration/align_depth_color.md) for startup and viewing examples.
 - **`intra_camera_sync_reference`**
-  - Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. When set to empty, the long baseline device defaults to End, and the short baseline device defaults to Middle.
+  - Sets the reference point for intra-camera synchronization. Applicable for Gemini 330 series devices when `sync_mode` is set to **software** or **hardware trigger** mode. **Options:** `Start`, `Middle`, `End`. When empty, the node leaves the device's current setting unchanged.

 ## Device-Specific Parameters
 * **`enable_gmsl_trigger`** / **`gmsl_trigger_fps`**
@@ -315,15 +317,15 @@ The following are the launch parameters available:

 ### Time Synchronization
 * **`enable_sync_host_time`**
-  * Enable synchronization of the host time with the camera time. The default value is `true`. If using global time, set to `false`.
+  * Enable synchronization of the host time with the camera time. The default is determined by the device launch file; Gemini 330 series launch files, including Gemini 336L, default to `false`. Set it to `false` when using global time.
 * **`time_domain`**
  * Select timestamp type: `device`, `global`, and `system`.
-  * This parameter is case-insensitive. Invalid values are reported and replaced with the default value.
+  * This parameter is case-insensitive. Use one of the valid values listed above.
 * **`timestamp_clock_type`**
-  * Set the SDK timestamp clock type. Optional values: `realtime`, `monotonic`. The default is `realtime`.
+  * Set the SDK timestamp clock type. Optional values: `realtime`, `monotonic`. When the launch argument is empty, the node does not explicitly set the SDK clock type.
 * **`time_sync_period`**
  * Interval (in seconds) for synchronizing the camera time with the host system.
-  > **Note**: This parameter only needs to be set when `enable_sync_host_time = true` and `time_domain = device`.
+  > **Note**: This parameter takes effect only when `enable_sync_host_time = true` and `time_domain` is not `global`.

 * **`enable_frame_sync`**
  * Enable the frame synchronization.
@@ -334,7 +336,7 @@ The following are the launch parameters available:

 ### Logging & Diagnostics
 * **`log_level`**
-  * Shared SDK and ROS node log level. By default, only current device status is printed; set it to `debug` for more debug logs. Optional values: `none`, `debug`, `info`, `warn`, `error`, `fatal`.
+  * Shared SDK and ROS node log level. The launch default is `info`; set it to `debug` for more debug logs. Optional values: `none`, `debug`, `info`, `warn`, `error`, `fatal`.
  * SDK logs and crash files are saved to `~/.ros/Log` by default. ROS logs remain in `~/.ros/log`.
 * **`log_file_name`**
  * SDK log file name. When empty, the log file is named after the node startup time in the format `OrbbecSDK_<YYYYMMDD_HHMMSS>.log`. When specified, the resulting path is `~/.ros/Log/<camera_name>/<log_file_name>`.
@@ -356,7 +358,7 @@ The following are the launch parameters available:
    *   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.
+    *   This parameter is case-insensitive. Use one of the valid values listed above.
 *   **`enable_d2c_viewer`**
    *   Publishes the D2C overlay image (for testing only). See [Aligning Depth to Color](../5_advanced_guide/configuration/align_depth_color.md) for examples.

@@ -42,6 +42,8 @@

 以下是可用的启动参数：

+> **默认值说明：** 不同设备的 launch 文件可能为同一参数设置不同的默认值。下文仅在默认值能够统一确认时列出；参数默认值为空或为 `-1` 时，通常表示节点不主动修改设备当前值。
+
 ## 核心与数据流配置

 *   **`camera_name`**
@@ -81,13 +83,13 @@
 *   **`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`。
 * **`color.image_raw.enable_pub_plugins`**
-  * 启用彩色图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
+  * 启用彩色图像传输插件。具体启用列表由设备 launch 文件决定。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
 * **`depth.image_raw.enable_pub_plugins`**
-  * 启用深度图像传输插件。默认值：`["image_transport/compressedDepth", "image_transport/raw"]`。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
+  * 启用深度图像传输插件。具体启用列表由设备 launch 文件决定。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
 * **`left_ir.image_raw.enable_pub_plugins`**
-  * 启用左红外图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
+  * 启用左红外图像传输插件。具体启用列表由设备 launch 文件决定。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
 * **`right_ir.image_raw.enable_pub_plugins`**
-  * 启用右红外图像传输插件。默认值：`["image_transport/compressed", "image_transport/raw", "image_transport/theora"]`。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
+  * 启用右红外图像传输插件。具体启用列表由设备 launch 文件决定。压缩图像订阅方法参考 [压缩图像](compressed_image.md)。
 * **`point_cloud_decimation_filter_factor`**
  * 点云下采样因子。范围：`1–8`，`1`表示不下采样，数值越大下采样倍数越大。
 * **`bag_record_filename`**
@@ -119,7 +121,7 @@
 *   **`color_brightness`**、**`color_sharpness`**、**`color_gamma`**、**`color_saturation`**、**`color_contrast`**、**`color_hue`**
    *   设置彩色亮度、锐度、伽马、饱和度、对比度和色调。
 *   **`color_backlight_compensation`**
-    *   启用彩色相机的背光补偿功能。**范围**：`0–6`，**默认值**：`3`。
+    *   设置彩色相机的背光补偿等级。可设置范围为 `0–6`；launch 默认值为 `-1`，表示不修改设备当前值。
 *   **`color_powerline_freq`**
    *   设置电源线频率。可能的值为 `disable`、`50hz`、`60hz`、`auto`。
 *   **`color_preset`**
@@ -143,7 +145,7 @@
 *   **`enable_depth_scale`**
    *   设置D2C后是否启用深度缩放。`true`表示启用，默认为`true`。
 *   **`depth_precision`**
-    *   深度精度应为 `1mm` 格式。默认值为 `1mm`。
+    *   设置深度精度，格式示例为 `1mm`。launch 参数为空时不主动修改设备当前深度精度。
 *   **`depth_work_mode`**
    *   设置深度工作模式。支持的设备、模式列表查看命令和启动示例参考 [深度工作模式切换](../5_advanced_guide/configuration/depth_work_mode_switch.md)。
 *   **`depth_ae_roi_[left|right|top|bottom]`**
@@ -175,7 +177,7 @@

 ### 多相机同步
 *   **`sync_mode`**
-    *   设置同步模式。默认值为 `standalone`。多相机连接、同步模式和触发配置参考 [多相机同步](../5_advanced_guide/multi_camera/multi_camera_synced.md)。
+    *   设置同步模式。具体默认值由所使用的 launch 文件决定。多相机连接、同步模式和触发配置参考 [多相机同步](../5_advanced_guide/multi_camera/multi_camera_synced.md)。
 *   **`depth_delay_us`** / **`color_delay_us`**
    *   接收捕获命令或触发信号后深度/彩色图像捕获的延迟时间（微秒）。
 *   **`trigger2image_delay_us`**
@@ -211,7 +213,7 @@
 ### 视差
 *   **`disparity_to_depth_mode`**
    *   `HW`：使用硬件视差到深度转换。`SW`：使用软件视差到深度转换。也可以设置为 `disable` 关闭。
-    *   该参数大小写不敏感；非法值会报错并回退默认值。
+    *   该参数大小写不敏感；请使用上述有效值。
 *   **`disparity_range_mode`**、**`disparity_search_offset`**、**`disparity_offset_config`**
    *   视差搜索偏移参数。用于 [视差搜索偏移](../5_advanced_guide/configuration/disparity_search_offset.md)。

@@ -230,7 +232,7 @@
  *   启用深度帧与彩色帧的对齐。当 `enable_colored_point_cloud` 设置为 `true` 时需要此字段。启动和查看方法参考 [对齐深度到彩色](../5_advanced_guide/configuration/align_depth_color.md)。
 - **`align_mode`**
  *   要使用的对齐模式。选项为 `HW`（硬件对齐）和 `SW`（软件对齐）。
-  *   该参数大小写不敏感；非法值会报错并回退默认值。
+  *   该参数大小写不敏感；请使用上述有效值。
 - **`align_target_stream`**
  *   设置对齐目标流模式。
  *   可能的值为 `COLOR`、`DEPTH`。
@@ -238,7 +240,7 @@
  *   `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`。设置为空时，长基线设备默认End，短基线设备默认Middle。
+  - 设置相机内同步的参考点。适用于Gemini 330系列设备，当 `sync_mode` 设置为**软件**或**硬件触发**模式时。**选项：** `Start`、`Middle`、`End`。参数为空时，节点不修改设备当前设置。

 ## 设备特定参数
 *   **`enable_gmsl_trigger`** / **`gmsl_trigger_fps`**
@@ -314,15 +316,15 @@

 ### 时间同步
 *   **`enable_sync_host_time`**
-    *   启用主机时间与相机时间的同步。默认值为 `true`。如果使用全局时间，设置为 `false`。
+    *   启用主机时间与相机时间的同步。默认值由设备 launch 文件决定；Gemini 330 系列（包括 Gemini 336L）的 launch 默认关闭。使用全局时间时应设置为 `false`。
 *   **`time_domain`**
    *   选择时间戳类型：`device`、`global` 和 `system`。
-    *   该参数大小写不敏感；非法值会报错并回退默认值。
+    *   该参数大小写不敏感；请使用上述有效值。
 *   **`timestamp_clock_type`**
-    *   设置 SDK 时间戳时钟类型。可选值：`realtime`、`monotonic`。默认使用 `realtime`。
+    *   设置 SDK 时间戳时钟类型。可选值：`realtime`、`monotonic`。launch 参数为空时不显式设置 SDK 时钟类型。
 * **`time_sync_period`**
  * 相机时间与主机系统同步的间隔（秒）。
-  > **注意**：仅当 **`enable_sync_host_time = true`** 且 **`time_domain = device`** 时需要设置此参数。
+  > **注意**：仅当 **`enable_sync_host_time = true`** 且 **`time_domain` 不是 `global`** 时生效。
 *   **`enable_frame_sync`**
    *   启用帧同步。
 *   **`enable_frame_drop_log`**
@@ -332,7 +334,7 @@

 ### 日志与诊断
 *   **`log_level`**
-    *   SDK和ROS节点日志级别。默认只输出设备当前状态；需要更多调试信息时可设置为 `debug`。可选值：`none`、`debug`、`info`、`warn`、`error`、`fatal`。
+    *   SDK和ROS节点日志级别。launch 默认值为 `info`；需要更多调试信息时可设置为 `debug`。可选值：`none`、`debug`、`info`、`warn`、`error`、`fatal`。
    *   SDK日志和崩溃文件默认保存在 `~/.ros/Log`，ROS日志仍保存在 `~/.ros/log`。
 * **`log_file_name`**
  * SDK 日志文件名。为空时，日志默认以节点启动时间命名，格式为 `OrbbecSDK_<YYYYMMDD_HHMMSS>.log`；指定后，实际路径为 `~/.ros/Log/<camera_name>/<log_file_name>`。
@@ -354,7 +356,7 @@
    *   导出前会把当前 ROS2 参数中的传感器流、点云和 HDR 合并配置同步到 SDK `application_config`（设备支持时）。
 *   **`frame_aggregate_mode`**
    *   设置帧聚合输出模式。可选值：`full_frame`、`color_frame`、`ANY`、`disable`。
-    *   该参数大小写不敏感；非法值会报错并回退默认值。
+    *   该参数大小写不敏感；请使用上述有效值。
 *   **`enable_d2c_viewer`**
    *   发布D2C叠加图像（仅用于测试）。使用示例参考 [对齐深度到彩色](../5_advanced_guide/configuration/align_depth_color.md)。