빔포밍 파라미터

개요

BATCAM FX에서는 마이크에서 전달되는 신호의 주파수 필터, 증폭, Listening Point(LPoint) 설정 등을 지정할 수 있습니다. 이 문서에서는 각 빔포밍 파라미터의 의미와 범위, 그리고 REST API와 ROS 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 두 개의 계정이 미리 설정되어 있으며, 출고 기본 비밀번호는 반드시 변경 후 사용하세요.
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: 주파수 범위 상에서 표시할 최대 주파수입니다. 해당 주파수 위의 소리는 필터에 걸러지게 됩니다.

두 값은 항상 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)를 하나의 문자열로 전송합니다. 예) 20,510,579

반드시 3개의 인덱스를 모두 지정해야 하며, REST GET 응답에서는 정수 배열(예: [20, 510, 579])로 반환됩니다.

⚠️ BF Map 인덱스는 우하단이 0, 좌상단이 1199인 좌표계를 사용합니다. 40×30 ↔ 40×15 압축/복원 공식과 언어별 예제 코드는 Listening Point 좌표 문서를 참조하시기 바랍니다.

REST와 ROS 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 필드 하나로 구성됩니다. 상세 명세는 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)를 모두 지정해야 하며, 두 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 두 개의 계정이 미리 설정되어 있습니다.
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이 반환됩니다.