Skip to main content

​
supervision 라이브러리

supervision은 Roboflow에서 개발한 CV 시각화 라이브러리로, 다양한 모델의 출력을 통일된 인터페이스로 시각화합니다. YOLO, Detectron2, SAM 등 주요 프레임워크의 결과를 지원합니다.
1
설치
2
pip install supervision
3
바운딩 박스 시각화
4
import cv2
import supervision as sv
from ultralytics import YOLO

model = YOLO('yolo11m.pt')
image = cv2.imread('image.jpg')

results = model(image)[0]
detections = sv.Detections.from_ultralytics(results)

# 바운딩 박스 + 레이블 시각화
box_annotator = sv.BoxAnnotator(thickness=2)
label_annotator = sv.LabelAnnotator(text_scale=0.5, text_thickness=1)

labels = [
    f"{results.names[int(cls)]} {conf:.2f}"
    for cls, conf in zip(detections.class_id, detections.confidence)
]

annotated = box_annotator.annotate(scene=image.copy(), detections=detections)
annotated = label_annotator.annotate(scene=annotated, detections=detections, labels=labels)

cv2.imwrite('boxed.jpg', annotated)
5
마스크 시각화
6
# YOLO-Seg 결과 시각화
seg_model = YOLO('yolo11m-seg.pt')
results = seg_model(image)[0]
detections = sv.Detections.from_ultralytics(results)

mask_annotator = sv.MaskAnnotator(opacity=0.4)
annotated = mask_annotator.annotate(scene=image.copy(), detections=detections)
cv2.imwrite('masked.jpg', annotated)
7
고급 어노테이터
8
# 다양한 어노테이터 조합
corner_annotator = sv.BoxCornerAnnotator(thickness=3)       # 모서리만 표시
circle_annotator = sv.CircleAnnotator()                      # 원형 마커
halo_annotator = sv.HaloAnnotator(opacity=0.3)               # 후광 효과
trace_annotator = sv.TraceAnnotator(thickness=2, trace_length=50)  # 궤적

# 순차 적용
annotated = corner_annotator.annotate(image.copy(), detections)
annotated = label_annotator.annotate(annotated, detections, labels=labels)
9
영상 처리 파이프라인
10
# 영상 처리 + 시각화
model = YOLO('yolo11m.pt')
tracker = sv.ByteTrack()

box_annotator = sv.BoxAnnotator()
trace_annotator = sv.TraceAnnotator(trace_length=50)

def process_frame(frame):
    """프레임 단위 처리 콜백입니다."""
    results = model(frame, verbose=False)[0]
    detections = sv.Detections.from_ultralytics(results)
    detections = tracker.update_with_detections(detections)

    labels = [f"ID:{tid}" for tid in detections.tracker_id]

    annotated = box_annotator.annotate(frame.copy(), detections)
    annotated = trace_annotator.annotate(annotated, detections)
    return annotated

# 영상 처리 실행
sv.process_video(
    source_path='input.mp4',
    target_path='output.mp4',
    callback=process_frame,
)
11
분석 도구
12
# 영역 기반 카운팅
polygon = np.array([[100, 300], [500, 300], [500, 500], [100, 500]])
zone = sv.PolygonZone(polygon=polygon)

zone.trigger(detections=detections)
count = zone.current_count
print(f"영역 내 객체 수: {count}")

# 라인 크로싱 카운팅
line_start = sv.Point(x=0, y=300)
line_end = sv.Point(x=640, y=300)
line_zone = sv.LineZone(start=line_start, end=line_end)

line_zone.trigger(detections=detections)
print(f"IN: {line_zone.in_count}, OUT: {line_zone.out_count}")

​
주요 기능 요약

기능클래스용도
박스 시각화BoxAnnotator바운딩 박스 그리기
마스크 시각화MaskAnnotator세그멘테이션 마스크 오버레이
객체 추적ByteTrack프레임 간 객체 추적
궤적 그리기TraceAnnotator추적 궤적 시각화
영역 카운팅PolygonZone특정 영역 내 객체 수 카운팅
라인 카운팅LineZone라인 통과 카운팅
Ultralytics YOLO, Detectron2, SAM, Transformers, Inference(Roboflow) 등 주요 CV 프레임워크의 출력을 Detections 객체로 변환하는 함수를 제공합니다.
시각화 자체의 오버헤드는 작습니다. 전체 속도는 대부분 모델 추론에 의해 결정됩니다. 경량 모델(YOLO11n)과 조합하면 30FPS 이상의 실시간 처리가 가능합니다.