AddBoundingBoxes

어떤 노드인가요?

AddBoundingBoxes 노드는 좌표 딕셔너리 데이터를 기반으로 이미지 위에 바운딩 박스(경계 상자)를 그려주는 노드입니다. 색상이 지정된 사각형과 선택적 레이블을 이미지에 오버레이하여 객체 탐지(Object Detection) 결과를 시각화하도록 설계되었습니다. YOLO, 얼굴 감지 또는 기타 감지 시스템의 출력 결과를 표시하는 데 적합합니다.

언제 사용하나요?

다음과 같은 상황에서 이 노드를 사용합니다:

YOLO, SSD 또는 기타 탐지 모델의 객체 탐지 결과 시각화
신뢰도 점수(confidence score)와 함께 얼굴 감지 바운딩 박스 표시
좌표 기반 관심 영역(ROI)을 이미지에 주석으로 추가
컴퓨터 비전 워크플로우를 위한 시각적 피드백 생성
탐지 모델의 출력 결과 디버깅 및 검증
단일 이미지 위에 여러 탐지 결과 결합 표시

사용 방법

기본 설정

워크플로우에 AddBoundingBoxes 노드를 추가합니다.
이미지 소스를 "input_image" 입력에 연결합니다.
바운딩 박스 데이터(딕셔너리 또는 딕셔너리 리스트)를 "bounding_boxes" 입력에 연결합니다.
필요에 따라 색상, 레이블, 선 두께를 사용자 정의합니다.
주석이 추가된 이미지가 "output" 파라미터를 통해 출력됩니다.

파라미터 (Parameters)

입력 (Inputs)

input_image: 바운딩 박스를 그릴 대상 이미지 (ImageUrlArtifact 또는 ImageArtifact)
bounding_boxes: 박스 좌표가 포함된 단일 딕셔너리 또는 딕셔너리 리스트
- 각 딕셔너리에는 반드시 x, y, width, height 키가 포함되어야 합니다 (정수 또는 변환 가능한 문자열).
- 레이블 템플릿에 사용할 추가 키(예: confidence, class 등)를 포함할 수 있습니다.
- 예시: {"x": 100, "y": 50, "width": 200, "height": 150, "confidence": 0.95}

스타일링 파라미터

box_color (16진수 색상 코드, 기본값: "#FF0000"): 바운딩 박스 외곽선의 색상
- 손쉬운 색상 선택을 위해 ColorPicker를 사용합니다.
- 16진수(Hex) 형식을 지원합니다 (예: 빨간색의 경우 "#FF0000", 초록색의 경우 "#00FF00").
line_thickness (1-10, 기본값: 2): 픽셀 단위의 바운딩 박스 선 두께
- 값이 낮을수록 얇고 섬세한 주석이 생성됩니다.
- 값이 높을수록 굵고 눈에 띄는 박스가 생성됩니다.

레이블 파라미터

show_labels (불리언, 기본값: True): 레이블 표시 여부 전환
- True로 설정하면 바운딩 박스 위에 레이블을 표시합니다.
- False로 설정하면 레이블을 숨기고 박스만 표시합니다.
label_key (문자열 템플릿): 바운딩 박스 레이블용 템플릿
- 기본값: "{x}, {y}, width: {width}, height: {height}"
- {key} 구문을 사용하여 바운딩 박스 딕셔너리의 값을 삽입합니다.
- 예시: "Class: {class}, Conf: {confidence}"
- 예시: "{x}, {y} - Size: {width}x{height}"
- 딕셔너리에 없는 키는 출력 시 {key} 형태로 그대로 유지됩니다.

출력 (Outputs)

output: 바운딩 박스와 레이블이 그려진 이미지

예시

일반적인 객체 탐지 시각화 워크플로우:

LoadImage를 사용하여 이미지를 불러옵니다.
객체 탐지를 실행합니다 (예: YOLO 또는 커스텀 탐지 모델 사용).

탐지 결과를 딕셔너리 형식으로 구성합니다:

[
  {"x": 100, "y": 50, "width": 200, "height": 150, "class": "person", "confidence": 0.95},
  {"x": 350, "y": 120, "width": 180, "height": 200, "class": "car", "confidence": 0.87}
]

이미지를 AddBoundingBoxes의 "input_image"에 연결합니다.
탐지 결과를 "bounding_boxes"에 연결합니다.
레이블 템플릿을 설정합니다: "Class: {class}, Conf: {confidence}"
박스 색상을 선택합니다: "#00FF00" (초록색)
가시성을 위해 선 두께를 3으로 설정합니다.
"output"을 DisplayImage에 연결하여 주석이 달린 결과를 확인합니다.

중요 참고 사항

좌표계: 바운딩 박스는 (x, y)를 좌측 상단 모서리로 사용하며, 너비(width)와 높이(height)는 각각 오른쪽과 아래쪽으로 확장됩니다.
문자열 변환: 노드는 가능한 경우 문자열 형태의 좌표 값을 자동으로 정수로 변환합니다.
- 예시: {"x": "100", "y": "50"}도 정상적으로 작동합니다.
레이블 위치 지정: 레이블은 지능적인 간격 배치 규칙을 따릅니다:
- 기본: 박스 상단 위에 레이블 높이의 절반에 해당하는 간격을 두고 배치
- 이미지 상단에 가까운 경우: 박스 내부 상단에 배치
레이블 크기: 비율에 맞는 레이블 표시를 위해 글꼴 크기가 이미지 높이의 4%로 자동 조정됩니다.
유효성 검사: 노드는 처리 전 모든 입력을 검증합니다:
- 좌표는 음수가 아니어야 합니다 (x ≥ 0, y ≥ 0).
- 크기는 양수여야 합니다 (width > 0, height > 0).
- 문제가 발생하면 명확한 오류 메시지를 통해 안내합니다.
RGBA 지원: 이 노드는 RGBA 이미지의 투명도를 그대로 유지합니다.

자주 묻는 질문 및 문제 해결

필수 키 누락: 각 바운딩 박스 딕셔너리에 x, y, width, height 키가 있는지 확인하세요.
- 누락된 키가 있으면 오류 메시지에 구체적으로 표시됩니다.
문자열 좌표: 데이터에 문자열 좌표가 포함되어 있으면 노드가 자동으로 변환합니다.
- 변환에 실패하면 명확한 오류 메시지가 출력됩니다.
음수 좌표: 바운딩 박스 좌표는 음수가 아니어야 합니다.
- x ≥ 0 및 y ≥ 0 인지 확인하세요.
0 또는 음수 크기: 너비와 높이는 0보다 커야 합니다.
- width > 0 및 height > 0 인지 확인하세요.
레이블이 표시되지 않음: 다음 사항을 확인하세요:
- show_labels가 True로 설정되어 있는지 확인합니다.
- label_key에 올바른 템플릿이 지정되어 있는지 확인합니다.
- 템플릿에 사용된 키가 바운딩 박스 딕셔너리에 실제로 존재하는지 확인합니다.
잘못된 레이블 텍스트: 템플릿의 {key} 이름이 바운딩 박스 딕셔너리의 키와 정확히 일치하는지 확인하세요.

기술 세부 정보

이 노드는 다음과 같은 작업을 수행합니다:

입력 유효성 검사:
- 바운딩 박스 형식(딕셔너리 또는 리스트) 검증
- 필수 키(x, y, width, height) 확인
- 필요한 경우 문자열 값을 정수로 변환
- 좌표 범위 검증
색상 파싱: 그리기를 위해 16진수 색상 코드를 RGB 튜플로 변환합니다.
글꼴 로드: 이미지 높이의 4% 크기로 글꼴을 동적으로 로드합니다 (LABEL_HEIGHT_PERCENT 상수를 통해 설정 가능).
박스 그리기: 각 바운딩 박스에 대해 다음을 수행합니다:
- x, y, width, height로부터 사각형 모서리 계산
- 지정된 색상 및 두께로 사각형 외곽선 렌더링
레이블 렌더링 (활성화된 경우):
- {key} 패턴을 실제 값으로 치환하여 템플릿 문자열 처리
- 적절한 배치를 위한 텍스트 크기 계산
- 텍스트 가독성을 위한 검은색 배경 사각형 그리기
- 배경 위에 흰색 텍스트 그리기
스마트 위치 지정: 레이블은 박스 상단에 비례 간격을 두고 배치되며, 이미지 상단에 매우 가까운 경우 박스 내부에 배치됩니다.

이 노드는 모든 렌더링 작업에 PIL (Pillow) ImageDraw를 사용하여 표준 이미지 형식과 호환되는 고품질 출력을 보장합니다.