コンテンツにスキップ
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 ソフトウェアアップデートまたはシェルソフトウェアアップデートドキュメントを参照してアップデートしてください。バージョンごとの変更事項はファームウェアリリースノートで確認できます。

  • REST API 認証情報: すべての REST エンドポイントは HTTP Basic 認証が必要です。BATCAM FX には、デフォルトで admin、user の 2 つのアカウントがあらかじめ設定されており、出荷時の初期パスワードは必ず変更したうえでご使用ください。

  • ROS 2 環境（ROS 2 で設定する場合）: 装置の ROS 2 インターフェース構成については ROS Integration ドキュメントを、ROS Domain ID の設定については ROS Domain ID ドキュメントを参照してください。

設定インターフェース

オーバーレイパラメータは、REST API または ROS 2 Action の 2 つの方法で設定できます。

インターフェース方式名称 / パス備考
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 メッセージのフィールド名に共通で使用されます。

フィールド名タイプ範囲Step備考
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
  }
}

リクエスト/レスポンススキーマの全体仕様については、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 設定（ベータ）ドキュメントを参照してください。

適用結果の確認

  • 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 の場合、これら 3 つの値は適用されません。ソース検出モードをオフにした状態で再度確認してください。

  • ソース検出モードが動作しない場合: ソース検出モードは、オーバーレイがオンになっている必要があります。enable_overlay が true であるかを確認してください。

  • PATCH リクエストが 400（error: 1）で失敗する場合: 部分更新はサポートされていません。6 つのフィールド全体を form-data で送信したか、各値が許容範囲内であるかを確認してください。

  • 401 が返される場合: HTTP Basic 認証の資格情報が欠落しているか、正しくありません。アカウント情報を確認してください。

関連ドキュメント