跳转到内容
SMI Developer Center

Overlay 参数列表及设置说明

概述

BATCAM FX 从固件 1.0.3 版本起支持由设备自身合成叠加图像并以 RTSP 流提供的功能。启用叠加后，通过 RTSP 及 ROS 2 传输的图像上会显示波束成形叠加层。本文档介绍叠加合成所使用的参数属性及设置方法。

该功能仅可在固件 1.0.3 及以上版本中使用。关于在设备外部（客户端）直接合成 RTSP 原始视频与波束成形数据的方法，请参阅 BATCAM FX 概述 文档。

前提条件

  • 固件 1.0.3 及以上：可通过 GET /setting/status 响应中的 result.firmware_version 值确认当前固件版本。若版本较低，请参阅 Web 软件更新 或 Shell 软件更新 文档进行更新。各版本的变更内容可在 固件发行说明 中确认。

  • REST API 认证信息：所有 REST 端点均需要 HTTP Basic 认证。BATCAM FX 默认预先配置了 admin、user 两个账户，出厂默认密码请务必修改后再使用。

  • ROS 2 环境（通过 ROS 2 进行设置时）：设备的 ROS 2 接口配置请参阅 ROS Integration 文档，ROS Domain ID 的设置请参阅 ROS Domain ID 文档。

设置接口

叠加参数可通过 REST API 或 ROS 2 Action 两种方式进行设置。

接口方式名称 / 路径备注
REST APIGET / PATCH/beamforming/overlayHTTP Basic 认证 · PATCH 请求正文为 multipart/form-data · 详细规范请参阅 FX API 参考
ROS 2Action/fx_{hardware_id}/setting_overlay动作类型为 fx_stream_msgs/action/OverlaySetting — Goal 的 setting 字段即 OverlaySetting 消息

  • PATCH /beamforming/overlay 不支持部分更新。即使只变更部分值，也必须将全部 6 个字段以 form-data 形式发送。

  • ROS 2 消息及动作定义可在 ROS Integration 文档或 SMI OSS - fx-stream-msgs 仓库中确认。

参数参考

以下字段名同时用作 REST API 的 form-data 键和 ROS 2 OverlaySetting 消息的字段名。

字段名类型范围步长备注
enable_overlayBooleantrue / false—是否输出叠加层 · 其余设置的前提条件
enable_source_modeBooleantrue / false—需在叠加已开启的状态下才生效
number_of_sourcesInteger1 ~ 51单位：声源个数 · 建议最多 3 个 · 在声源探测模式下使用
averageInteger0 ~ 101单位：波束成形（BF）图数量 · 启用声源探测模式时不适用
thresholdFloat0 ~ 1201BF 可视化基准值 · 启用声源探测模式时不适用
rangeFloat0 ~ 100.1BF 可视化范围 · 启用声源探测模式时不适用

参数间的依赖关系

  • enable_overlay 是所有叠加操作的前提。若叠加处于关闭状态（false），则不会输出叠加图像，声源探测模式也不会运行。

  • 开启 enable_source_mode（声源探测模式）后，将根据 number_of_sources 的值以单声源或多声源模式运行，此时 average、threshold、range 的值不会被应用。

  • 若 enable_source_mode 处于关闭状态，则 average、threshold、range 的值将应用于叠加图像的生成。

参数详细说明

Enable Overlay（字段名：enable_overlay）

控制是否输出叠加图像。 设置为 true 时，通过 RTSP 及 ROS 2 传输的图像上会显示叠加层。

Enable Source find mode（字段名：enable_source_mode）

控制声源探测模式。声源探测模式必须在叠加已开启（enable_overlay=true）的情况下才能运行。 设置为 true 时，将根据 number_of_sources 的值启用单声源或多声源模式。 关于可设置的声源数量，请参阅下方 Number of sources 项。

Number of sources（字段名：number_of_sources）

指定同时追踪的声源个数。在声源探测模式（enable_source_mode=true）下使用。 声源最多可指定 5 个，但本公司建议最多使用 3 个。

Beamforming Averaging（字段名：average）

指定进行平均值处理的波束成形（BF）图数量。 用于设置为降低叠加图像噪声而施加的平均处理强度。 值越高，结果越平滑。

启用声源探测模式（enable_source_mode）时，该设置不适用。

Beamforming Threshold（字段名：threshold）

指定在叠加图像中判定为声源的最小强度值。 值越高，则仅显示强度更高的声源。

启用声源探测模式（enable_source_mode）时，该设置不适用。

Beamforming Image Range（字段名：range）

指定叠加图像中声源所对应图像的大小。 值越高，声源所对应叠加层的尺寸越大。

启用声源探测模式（enable_source_mode）时，该设置不适用。

设置示例

REST API (curl)

查询当前的叠加设置。请根据实际使用环境修改设备 IP（192.168.0.30）和账户信息。

Terminal window
curl -u 'admin:<password>' http://192.168.0.30/beamforming/overlay

预期响应 — 所有响应均采用统一的信封结构，error 为 0 即表示成功。

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 1,
    "threshold": 15.0,
    "range": 5.0
  }
}

变更设置。由于不支持部分更新，需以上述查询结果为基准，将全部 6 个字段以 form-data 形式发送。

Terminal window
curl -u 'admin:<password>' -X PATCH http://192.168.0.30/beamforming/overlay \
  -F 'enable_overlay=true' \
  -F 'enable_source_mode=true' \
  -F 'number_of_sources=3' \
  -F 'average=3' \
  -F 'threshold=30' \
  -F 'range=5'

预期响应 — 返回已应用的全部设置。

{
  "error": 0,
  "result": {
    "enable_overlay": true,
    "enable_source_mode": true,
    "number_of_sources": 3,
    "average": 3,
    "threshold": 30.0,
    "range": 5.0
  }
}

关于请求/响应 Schema 的完整规范，请参阅 FX API 参考 中的 /beamforming/overlay 项。

ROS 2 (CLI)

在 ROS 2 环境中，可通过 /fx_{hardware_id}/setting_overlay 动作发送相同的设置。

Terminal window
ros2 action send_goal /fx_276730383020104/setting_overlay fx_stream_msgs/action/OverlaySetting \
"{
  setting: {
    enable_overlay: true,
    enable_source_mode: true,
    number_of_sources: 3,
    range: 5.0,
    threshold: 15.0,
    average: 1
  }
}"

fx_276730383020104 为示例硬件 ID。实际的硬件 ID 可通过 GET /setting/status 响应中的 result.hardware_id 值确认。关于使用 ROS 2 Action 进行设置的详细内容，请参阅 ROS 固件 BF/Overlay 设置（Beta） 文档。

确认应用结果

  • RTSP：使用正在使用的 RTSP 客户端打开设备视频流，确认叠加层是否显示。

  • ROS 2：可在通过 /fx_{hardware_id}/image 话题（sensor_msgs/msg/CompressedImage）发布的图像中确认叠加层。

  • 设置值：通过 GET /beamforming/overlay 重新查询当前已应用的值，确认变更内容。

问题排查 (Troubleshooting)

  • 叠加层未显示在流中时：

    • 通过 GET /beamforming/overlay 确认 enable_overlay 是否为 true。

    • 若固件低于 1.0.3，则不提供该功能。请通过 GET /setting/status 的 result.firmware_version 确认版本，必要时请更新固件。

  • average / threshold / range 的变更未生效时： 若 enable_source_mode 为 true，则这三个值不会被应用。请在关闭声源探测模式的状态下重新确认。

  • 声源探测模式无法运行时： 声源探测模式需在叠加已开启的情况下才能运行。请确认 enable_overlay 是否为 true。

  • PATCH 请求以 400（error: 1）失败时： 不支持部分更新。请确认是否已将全部 6 个字段以 form-data 形式发送，以及各值是否在允许范围内。

  • 返回 401 时： HTTP Basic 认证凭据缺失或不正确。请确认账户信息。

相关文档