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 값으로 현재 펌웨어 버전을 확인할 수 있습니다. 버전이 낮은 경우 웹 소프트웨어 업데이트 또는 셸 소프트웨어 업데이트 문서를 참조하여 업데이트하세요. 버전별 변경 사항은 펌웨어 릴리즈 노트에서 확인할 수 있습니다.
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 API	`GET` / `PATCH`	`/beamforming/overlay`	HTTP Basic 인증 · `PATCH` 요청 본문은 `multipart/form-data` · 상세 명세는 FX API 레퍼런스 참조
ROS 2	Action	`/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_overlay`	Boolean	`true` / `false`	—	오버레이 출력 여부 · 나머지 설정의 전제 조건
`enable_source_mode`	Boolean	`true` / `false`	—	오버레이가 켜져 있어야 동작
`number_of_sources`	Integer	1 ~ 5	1	단위: 소스 개수 · 최대 3개 권장 · 소스 탐지 모드에서 사용
`average`	Integer	0 ~ 10	1	단위: 빔포밍(BF) 맵 개수 · 소스 탐지 모드 활성 시 미적용
`threshold`	Float	0 ~ 120	1	BF 시각화 기준값 · 소스 탐지 모드 활성 시 미적용
`range`	Float	0 ~ 10	0.1	BF 시각화 범위 · 소스 탐지 모드 활성 시 미적용

파라메터 간 의존 관계

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)와 계정 정보는 사용 환경에 맞게 변경하세요.

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로 전송합니다.

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 액션으로 동일한 설정을 전송할 수 있습니다.

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이면 이 세 값은 적용되지 않습니다. 소스 탐지 모드를 끈 상태에서 다시 확인하세요.
소스 탐지 모드가 동작하지 않는 경우: 소스 탐지 모드는 오버레이가 켜져 있어야 동작합니다. enable_overlay가 true인지 확인하세요.
PATCH 요청이 400(error: 1)으로 실패하는 경우: 부분 업데이트는 지원되지 않습니다. 6개 필드 전체를 form-data로 전송했는지, 각 값이 허용 범위 내인지 확인하세요.
401이 반환되는 경우: HTTP Basic 인증 자격 증명이 누락되었거나 올바르지 않습니다. 계정 정보를 확인하세요.

Overlay 파라메터 목록 및 설정 설명

개요

전제조건

설정 인터페이스

파라메터 레퍼런스

파라메터 간 의존 관계

파라메터 상세

Enable Overlay (필드 명: enable_overlay)

Enable Source find mode (필드 명: enable_source_mode)

Number of sources (필드 명: number_of_sources)

Beamforming Averaging (필드 명: average)

Beamforming Threshold (필드 명: threshold)

Beamforming Image Range (필드 명: range)

설정 예제

REST API (curl)

ROS 2 (CLI)

적용 결과 확인

문제 해결 (Troubleshooting)

관련 문서

Enable Overlay (필드 명: `enable_overlay`)

Enable Source find mode (필드 명: `enable_source_mode`)

Number of sources (필드 명: `number_of_sources`)

Beamforming Averaging (필드 명: `average`)

Beamforming Threshold (필드 명: `threshold`)

Beamforming Image Range (필드 명: `range`)