ビームフォーミングパラメータ

概要

BATCAM FX では、マイクから伝達される信号の周波数フィルタ、増幅、Listening Point（LPoint）設定などを指定できます。本ドキュメントでは、各ビームフォーミングパラメータの意味と範囲、および REST API と ROS 2 という 2 つのインターフェースで値を読み書きする方法を説明します。

本ドキュメントは BATCAM FX を基準としています。BATCAM FX2 のビームフォーミング設定については、Device Manager - Beamforming ドキュメントを参照してください。

インターフェース	方式	パス / インターフェース名	備考
REST API	HTTP `GET` / `PATCH`	`/beamforming/setting`	HTTP Basic 認証が必要です。`PATCH` は `multipart/form-data` 形式です。API プレイグラウンドの beamforming タグから直接実行できます。
ROS 2	Action	`/fx_{hardware_id}/setting_beamforming` ( `fx_stream_msgs/action/BeamformingSetting` )	v1.0.3b 開発ファームウェアからサポートされるベータ機能です。ROS ファームウェア BF/Overlay 設定（ベータ）を参照してください。

前提条件

BATCAM FX 機器が REST API を直接提供します。ベース URL は http://{device_ip} 形式であり、以下の例では機器の IP を 192.168.0.30 と仮定します。
すべての REST エンドポイントは HTTP Basic 認証が必要です。BATCAM FX には既定で admin、user の 2 つのアカウントがあらかじめ設定されており、出荷時の初期パスワードは必ず変更してから使用してください。
ROS 2 Action で設定するには、v1.0.3b 以上の開発ファームウェアと fx-stream-msgs メッセージパッケージが必要です。メッセージ・アクションの定義については、ROS Integration ドキュメントを参照してください。

パラメータリファレンス

REST PATCH リクエストを基準としたフィールド名と範囲です。ステップは値が変化しうる最小単位であり、許容値が定められているパラメータは該当する値のみ使用できます。

パラメータ	REST フィールド	型	単位	最小（Min）	最大（Max）	ステップ / 許容値
LowCut	`low_cut`	integer	Hz	1000	HighCut 未満	ステップ 100
HighCut	`high_cut`	integer	Hz	LowCut 超過	100000	ステップ 100
Gain	`gain`	number	-	1	1000	許容値 `1`、`10`、`100`、`1000` のみ使用可能
Auto Gain	`autogain`	boolean	-	-	-	`true` / `false`
Distance	`distance`	number	-	1	10	ステップ 1
Image Calibration X	`x_cal`	number	-	0	1	ステップ 0.01
Image Calibration Y	`y_cal`	number	-	0	1	ステップ 0.01
Listening Point Index	`index_l`	string	-	0（インデックスごと）	599（インデックスごと）	カンマ区切りの 40×15 圧縮インデックス 3 個が必須

Frequency Range - LowCut / HighCut ( `low_cut`, `high_cut` )

周波数フィルタを設定します。LowCut はハイパスフィルタ、HighCut はローパスフィルタです。

LowCut: 周波数範囲上で表示する最低周波数です。この周波数より下の音はフィルタで除去されます。
HighCut: 周波数範囲上で表示する最大周波数です。この周波数より上の音はフィルタで除去されます。

2 つの値は常に low_cut < high_cut の関係を満たす必要があります。

Gain / Auto Gain ( `gain`, `autogain` )

Gain はマイクの増幅値です。Auto Gain が有効な状態では使用されません。

Auto Gain はマイクの自動増幅を使用するかどうかを示します。音の大きさに応じてカメラが自動的に Gain を決定します。

Gain を直接変更するには、まず autogain を false に設定してから使用する必要があります。Auto Gain が有効な場合、ROS 2 およびストリームメッセージ( WsAudio、LPointAudio、Beamforming )に含まれる gain 値は、最後に設定された値または -1 が返されます。

Distance ( `distance` )

測定する騒音源までの距離を指定します。指定された距離で、もう少し詳細なビームフォーミングを試みます。

Image Calibration ( `x_cal`, `y_cal` )

オーバーレイされるビームフォーミング画像の位置が実際のカメラ映像の位置と一致しない場合、この値を使用して位置を調整できます。

x_cal: カメラ映像と可視化されたオーバーレイ画像の x 座標の誤差を補正します。
y_cal: カメラ映像と可視化されたオーバーレイ画像の y 座標の誤差を補正します。

Listening Point Index ( `index_l` )

カメラに設定する Listening Point（LPoint）のインデックスを設定します。BATCAM FX の BF Map は、カメラ映像（1600x1200）を 40x30 グリッドに分割した構造（1 次元インデックス 0～1199）であり、Listening Point はこのグリッド上の位置をインデックスで指定します。

ただし、API リクエスト時には、縦方向の解像度を半分に縮小した 40×15 形式に変換（圧縮）したインデックスを送信する必要があります。圧縮されたインデックスの範囲は 0～599 です。

値の形式: カンマ区切りの 3 個の圧縮インデックス（各 0～599）を 1 つの文字列として送信します。例）20,510,579

必ず 3 個のインデックスをすべて指定する必要があり、REST GET レスポンスでは整数配列（例: [20, 510, 579]）として返されます。

⚠️ BF Map インデックスは右下が 0、左上が 1199 となる座標系を使用します。40×30 ↔ 40×15 の圧縮/復元の計算式と言語別のサンプルコードについては、Listening Point 座標ドキュメントを参照してください。

REST と ROS 2 のフィールド名の違い

パラメータ自体は 2 つのインターフェースで同一ですが、Listening Point の表現方式が異なります。

パラメータ	REST ( `PATCH /beamforming/setting` )	ROS 2 ( `BeamformingSetting.msg` )
LowCut / HighCut	`low_cut`, `high_cut` (integer)	`low_cut`, `high_cut` (float64)
Gain / Auto Gain	`gain` (number), `autogain` (boolean)	`gain` (float64), `autogain` (bool)
Distance	`distance` (number)	`distance` (float64)
Image Calibration	`x_cal`, `y_cal` (number)	`x_cal`, `y_cal` (float64)
Listening Point	`index_l`（カンマ区切りの文字列 1 個）	`l_point_0`, `l_point_1`, `l_point_2`（int32 3 個）

設定例

現在の設定の照会（REST）

GET /beamforming/setting は、BATCAM FX 内のリアルタイム処理部に保存されたビームフォーミング設定値を返します。

curl -u admin:<password> http://192.168.0.30/beamforming/setting

想定される出力( error が 0 であれば成功 ):

{
  "error": 0,
  "result": {
    "autogain": true,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

設定の変更（REST）

⚠️ 部分的な設定は反映されないため、すべての値を送信する必要があります。 一部の値のみを変更する場合は、まず GET で現在の設定を取得したうえで、修正した全体の値を PATCH で送信してください。

PATCH /beamforming/setting は multipart/form-data 形式ですべてのフィールドを受け取ります。

curl -X PATCH http://192.168.0.30/beamforming/setting \
  -u admin:<password> \
  -F "low_cut=2000" \
  -F "high_cut=45000" \
  -F "gain=100" \
  -F "distance=1" \
  -F "x_cal=0.06" \
  -F "y_cal=0" \
  -F "index_l=20,510,579" \
  -F "autogain=false"

想定される出力( 適用された設定値がそのまま返されます ):

{
  "error": 0,
  "result": {
    "autogain": false,
    "gain": 100,
    "x_cal": 0.06,
    "y_cal": 0,
    "distance": 1,
    "high_cut": 45000,
    "low_cut": 2000,
    "index_l": [20, 510, 579]
  }
}

リクエスト/レスポンススキーマの全体は、API プレイグラウンドの beamforming タグで確認できます。

設定の変更（ROS 2 Action）

ROS 2 では fx_stream_msgs/action/BeamformingSetting Action で同一のパラメータを設定します。基本的に提供される形式は、REST API 上で提供される形式と同じです。

❯ ros2 action send_goal /fx_276730383020104/setting_beamforming fx_stream_msgs/action/BeamformingSetting \
"{
setting: {
autogain: false,
gain: 1,
x_cal: 0.0,
y_cal: 0.0,
distance: 5.0,
high_cut: 60000.0,
low_cut: 25000.0,
l_point_0: 580,
l_point_1: 20,
l_point_2: 290
}
}"

Action の Goal / Result / Progress は、いずれも BeamformingSetting 型の setting フィールド 1 つで構成されます。詳細な仕様については、ROS Integration ドキュメントを参照してください。

制約およびエラーレスポンス

全体値の送信: PATCH /beamforming/setting は部分更新をサポートしていません。すべてのフィールドを常に一緒に送信する必要があります。
周波数範囲: low_cut は high_cut より小さくなければなりません。
Gain の許容値: gain は 1、10、100、1000 のみ使用でき、autogain が false の場合にのみ適用されます。
Listening Point: index_l はカンマ区切りの 3 個の 40×15 圧縮インデックス（各 0～599）をすべて指定する必要があり、2 つの Listening Point の間には横・縦それぞれ最低 ±2 マス以上の間隔が必要です。詳細な制限と変換の計算式については、Listening Point 座標ドキュメントを参照してください。

すべての REST レスポンスは共通のエンベロープ構造を使用します。error が 0 であれば成功、0 以外であればエラーであり、エラー時には result.message に詳細メッセージが含まれる場合があります。

ステータスコード	レスポンス例	原因
400	`{ "error": 1, "result": { "message": "lpoint parameter error" } }`	不正なリクエスト（例: `index_l` パラメータのエラー）
401	-	HTTP Basic 認証の失敗

トラブルシューティング (Troubleshooting)

401 エラーが発生する場合:
- HTTP Basic 認証の資格情報を確認します。BATCAM FX には既定で admin、user の 2 つのアカウントがあらかじめ設定されています。
400 エラー( lpoint parameter error )が発生する場合:
- index_l がカンマ区切りの 3 個のインデックスで構成されているかを確認します。
- 各インデックスが 40×15 圧縮インデックスの範囲（0～599）であるかを確認します。BF Map の元のインデックス（0～1199）を変換せずにそのまま送信してはいけません。変換の計算式については、Listening Point 座標ドキュメントを参照してください。
- Listening Point 間の最小間隔（横・縦 ±2 マス）の制限に違反していないかを確認します。
一部のフィールドのみを送信したが設定が反映されない場合:
- 部分的な設定は反映されません。GET で現在の設定を取得したうえで、すべての値を再送信します。
Gain 設定が反映されない場合:
- autogain が true の状態では gain 値は使用されません。autogain を false に設定してから変更します。
ストリームメッセージの gain 値が -1 と表示される場合:
- 自動増幅（Auto Gain）が有効な場合の正常な動作です。このとき、ストリームメッセージの gain には最後に設定された値または -1 が返されます。