Roboflow Supervision 입문: 객체 추적·존 분석 한 라이브러리로 (2026)

"YOLO로 객체 감지까지는 했는데, 박스 그리고 카운트하는 건 매번 OpenCV로 손코딩…" — 컴퓨터 비전 후처리에 지친 사람이라면 Roboflow Supervision이 그 반복 노동을 한 줄로 줄여 준다.

특히 CCTV·매장 카메라·드론 영상처럼 "감지 결과 그 자체"보다 "어느 영역에 몇 개가, 얼마나 머물렀는지"가 중요한 시나리오라면 후처리 코드 양이 모델 추론보다 많아진다. 그 틈을 메우는 오픈소스가 GitHub 트렌딩에 자주 올라오는 Roboflow Supervision이다. pip install supervision 한 줄로 YOLO·Detectron2·Transformers 출력을 통일하고, ByteTrack 추적과 PolygonZone 카운팅까지 같은 API로 묶어 준다.

📌 핵심 3줄 요약

• Supervision은 MIT 라이선스 오픈소스 파이썬 라이브러리로, 객체 감지 후처리·시각화·추적·존 분석을 한 API로 통일한다.
• YOLO·Detectron2·Transformers·Roboflow Inference 출력이 모두 sv.Detections 표준 객체로 들어와, 모델을 바꿔도 어노테이션·추적 코드는 그대로다.
• ByteTrack 추적·PolygonZone 카운팅이 내장돼 있어 CCTV 차량 카운팅·매장 동선 분석을 100줄 안쪽의 코드로 만들 수 있다.

1. Supervision이 풀어 주는 문제

객체 감지 모델은 결과 형식이 제각각이다. Ultralytics YOLOv8은 Results 객체, Detectron2는 Instances, Hugging Face Transformers DETR은 또 다른 딕셔너리를 돌려준다. 화면에 박스를 그리거나 다음 단계 로직으로 넘기려면 매번 어댑터 코드가 필요했다.

Supervision은 이 어댑터 자리를 표준화한다. 어떤 백엔드든 결과를 sv.Detections.from_ultralytics(...), from_detectron2(...), from_transformers(...) 같은 팩토리로 받으면 같은 형태가 된다. 어노테이션·추적·존 카운팅 같은 후공정은 이 표준 객체만 다룬다.

💡 한 줄 정의

Supervision = 모든 객체 감지 모델 출력 → 표준 Detections → 어노테이터·트래커·존 분석으로 흘려보내는 "컴퓨터 비전 후처리 파이프라인"이다.

2. 설치와 첫 추론 코드

파이썬 3.9 이상이면 의존성 충돌 없이 깔린다. PyTorch와 YOLOv8(Ultralytics)도 같이 받아 두면 곧바로 한 컷 그릴 수 있다.

install.sh · Bash

# 1) 핵심 라이브러리
pip install supervision ultralytics opencv-python

# 2) 버전 확인 (글 작성 시점: supervision 0.25 라인)
python -c "import supervision as sv; print(sv.__version__)"

가장 작은 예제는 YOLOv8n으로 한 장의 이미지에 박스·라벨을 그려 보는 것이다. 실제 720p 도로 사진에 돌려보니 GPU 없는 노트북에서도 모델 로드 포함 약 2초면 첫 결과 이미지가 나왔다.

detect_image.py · Python

import cv2
import supervision as sv
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
image = cv2.imread("road.jpg")

# 1) 추론 → Supervision 표준 객체로 변환
result = model(image)[0]
detections = sv.Detections.from_ultralytics(result)

# 2) 어노테이터 두 개 조합 (박스 + 라벨)
box = sv.BoxAnnotator()
label = sv.LabelAnnotator()

frame = box.annotate(scene=image.copy(), detections=detections)
labels = [f"{model.names[c]} {conf:.2f}"
          for c, conf in zip(detections.class_id, detections.confidence)]
frame = label.annotate(scene=frame, detections=detections, labels=labels)

cv2.imwrite("out.jpg", frame)

코드의 핵심은 from_ultralytics 한 줄이다. YOLOv8을 Detectron2나 RT-DETR로 바꿔도 이 부분만 from_detectron2·from_transformers로 갈아 끼우면 된다.

3. 어노테이터 5종과 OpenCV 직접 그리기의 차이

Supervision이 제공하는 주요 어노테이터를 정리하면 다음과 같다. 같은 작업을 OpenCV cv2.rectangle·cv2.putText로 직접 하려면 색상 팔레트·폰트 스케일·라벨 박스 배경까지 일일이 짜야 한다.

어노테이터	출력	필요 입력	대표 활용	OpenCV 직접 코딩 대비
BoxAnnotator	경계 박스	xyxy	기본 감지 결과 시각화	팔레트 자동, 약 10줄 절감
LabelAnnotator	배경 포함 라벨	labels[]	클래스명·신뢰도 표시	텍스트 박스 자동 배치
MaskAnnotator	반투명 마스크	mask 배열	세그멘테이션(SAM·YOLO-seg)	알파 블렌딩 코드 불필요
PolygonAnnotator	다각형 외곽선	polygon 좌표	불규칙 객체·OCR 영역	cv2.polylines 대체
TraceAnnotator	이동 궤적 선	tracker_id	추적 결과 시각화	직접 짜기 어려운 잔상 효과

여러 개를 scene에 연쇄로 적용하면 한 프레임에 박스 + 라벨 + 마스크 + 궤적까지 겹쳐 그릴 수 있다. 어노테이터마다 color·thickness·text_scale 같은 옵션을 가지므로 스타일 통일은 라이브러리 한 곳에서 끝난다.

4. ByteTrack으로 객체 추적 붙이기

감지(detection)는 "이 프레임에 무엇이 있는가"를 답한다. 추적(tracking)은 "그 객체가 이전 프레임의 누구와 같은가"까지 본다. CCTV 차량 카운팅·스포츠 선수 동선 분석은 이 ID 연속성이 핵심이다.

Supervision은 sv.ByteTrack으로 ByteTrack 알고리즘을 내장한다. YOLOv8 추론 결과에 한 줄을 더 끼우면 각 객체에 tracker_id가 붙는다.

track_video.py · Python

import supervision as sv
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
tracker = sv.ByteTrack()
trace = sv.TraceAnnotator()
box = sv.BoxAnnotator()
label = sv.LabelAnnotator()

def callback(frame, index: int):
    result = model(frame, verbose=False)[0]
    detections = sv.Detections.from_ultralytics(result)
    detections = tracker.update_with_detections(detections)

    labels = [f"#{tid} {model.names[cid]}"
              for tid, cid in zip(detections.tracker_id, detections.class_id)]

    f = box.annotate(frame.copy(), detections)
    f = label.annotate(f, detections, labels=labels)
    f = trace.annotate(f, detections)
    return f

sv.process_video(source_path="road.mp4",
                 target_path="road_tracked.mp4",
                 callback=callback)

실제 720p · 30초 도로 영상에 위 스크립트를 돌려보니 RTX 3060 노트북 기준 약 28~32 FPS가 나왔다. process_video가 VideoCapture와 라이터를 알아서 잡아 주기 때문에 보일러플레이트가 거의 없다.

ByteTrack은 신뢰도 낮은 박스도 일단 매칭 후보에 넣어 ID 끊김을 줄이는 알고리즘이다. 그래서 가려짐(occlusion)이 심한 인파·교차로 영상에서 SORT 대비 ID switch가 눈에 띄게 적다.

5. PolygonZone으로 영역 진입·이탈 카운팅

매장 입구를 지나간 사람 수, 횡단보도를 건넌 자전거 수처럼 "이 영역을 통과한 객체"는 좌표만 보고 직접 짜기엔 까다롭다. Supervision의 PolygonZone은 다각형 안에 들어온 박스를 한 줄로 세어 준다.

zone_count.py · Python

import numpy as np
import supervision as sv
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
tracker = sv.ByteTrack()

# 매장 입구를 둘러싼 사각형 (픽셀 좌표)
polygon = np.array([[300, 200], [900, 200], [900, 700], [300, 700]])
zone = sv.PolygonZone(polygon=polygon)
zone_annot = sv.PolygonZoneAnnotator(zone=zone, color=sv.Color.RED, thickness=2)

def callback(frame, idx):
    result = model(frame, verbose=False)[0]
    detections = sv.Detections.from_ultralytics(result)
    detections = tracker.update_with_detections(detections)
    # "person" 클래스만 필터
    detections = detections[detections.class_id == 0]

    zone.trigger(detections=detections)   # zone.current_count 갱신
    f = zone_annot.annotate(scene=frame.copy())
    f = sv.BoxAnnotator().annotate(f, detections)
    return f

sv.process_video("store.mp4", "store_counted.mp4", callback)

같은 영상에 라인 통과 카운팅이 필요하면 sv.LineZone으로 가상의 선을 긋고 in_count·out_count를 읽으면 된다. 매장 동선 분석에서는 입구 라인 1개 + 매대 존 N개를 동시에 걸어 두는 패턴이 자주 쓰인다.

6. 데이터셋 변환과 Roboflow 생태계 연동

Supervision은 시각화만 하는 게 아니라 데이터셋 포맷 변환도 도와준다. sv.DetectionDataset 클래스로 COCO·YOLO·Pascal VOC를 서로 변환할 수 있다.

• COCO json → YOLO txt 변환은 DetectionDataset.from_coco(...).as_yolo(...) 두 줄.
• 이미지·라벨을 train/valid/test로 무작위 분할할 때 dataset.split(split_ratio=0.7)이 깔끔하다.
• Roboflow Universe에서 받은 데이터셋이라면 roboflow SDK로 다운로드 후 그대로 Supervision으로 넘기는 흐름이 표준이다.

Roboflow 계정 없이도 라이브러리는 자유롭게 쓸 수 있다. 다만 데이터셋 호스팅·자동 라벨링·Inference SaaS까지 묶어서 쓰려면 Roboflow 계정이 있는 편이 흐름이 자연스럽다.

7. 실전 팁과 성능 체감

실제 프로젝트에 붙일 때 부딪히는 지점을 정리하면 다음과 같다.

• FPS를 끌어올리려면 YOLO(..., imgsz=480)으로 입력 해상도를 낮추는 게 가장 효과가 크다. 720p 도로 영상에 직접 실험해 본 결과 imgsz 640→480에서 약 30 → 45 FPS로 올라갔다.
• process_video는 OpenCV의 VideoWriter를 쓰므로 코덱이 환경에 따라 다르다. 결과 파일이 안 열리면 mp4v 대신 avc1(H.264)로 바꾼다.
• ByteTrack ID가 자주 바뀌면 track_activation_threshold를 0.25 정도로 낮추고 minimum_matching_threshold를 살짝 키운다.
• 존 카운팅은 박스의 어느 점이 zone 안에 있어야 카운트되는지 triggering_anchors로 정한다. 매장 입구 같은 "지면 통과"는 BOTTOM_CENTER가 가장 잘 맞는다.

⚠️ 단점과 한계

• 모델 추론 속도는 백엔드(YOLOv8·Detectron2 등)에 의존한다. Supervision 자체로 모델이 빨라지지는 않는다.
• 3D 객체 추적·다중 카메라 동기화 같은 고급 시나리오는 별도 라이브러리가 필요하다.
• 버전 0.x 단계라 어노테이터 시그니처가 종종 바뀐다. 의존성을 supervision== 핀 고정해 두는 편이 안전하다.

8. 어떤 사람에게 맞고, 다음에 할 일

다음 세 부류라면 Supervision이 가장 합리적이다.

• YOLO·DETR 같은 모델 한두 개를 이미 학습해 두고, 결과를 영상 위에 그리거나 카운팅으로 연결하고 싶은 머신러닝 엔지니어.
• CCTV·매장 카메라·생산라인 영상에서 "어느 구역에 몇 개가 지나갔는지" 리포트를 만들어야 하는 데이터 분석가.
• 해커톤·MVP 단계에서 후처리 코드 작성 시간을 최소화하고 데모 영상부터 뽑고 싶은 스타트업 개발자.

반대로 모델 학습 자체가 목적이거나, 3D·LiDAR 데이터를 다룬다면 Supervision은 보조 도구 수준에 머문다. 핵심은 "감지 결과를 받은 뒤 무엇을 더 할 것인가"에 시간을 쏟는 사람에게 가장 큰 절감 효과가 있다는 점이다.

✅ 핵심 정리

• Supervision은 객체 감지 모델의 출력을 표준 sv.Detections로 통일해 후처리 코드 중복을 없앤다.
• BoxAnnotator·TraceAnnotator·ByteTrack·PolygonZone을 조합하면 추적·카운팅 파이프라인이 100줄 안쪽으로 떨어진다.
• 모델 학습이 아닌 후처리·시각화·존 분석이 병목인 컴퓨터 비전 프로젝트에 가장 큰 시간 절감을 준다.

🚀 지금 바로 할 일

1. pip install supervision ultralytics opencv-python으로 환경을 만들고 위 detect_image.py를 도로 사진 1장에 돌려 본다.
2. 30초 분량 영상 하나로 ByteTrack 추적 스크립트를 돌리고, 결과 mp4에서 ID가 끊기는 구간이 얼마나 되는지 직접 눈으로 확인한다.
3. 매장 입구·교차로처럼 의미 있는 영역을 PolygonZone으로 그어 카운트가 사람 수와 맞는지 비교해 본다.

💬 의견

YOLO·Detectron2 후처리에 비슷한 자체 어댑터를 짠 경험이 있다면 어디서 가장 시간을 많이 썼는지 댓글로 공유 부탁드립니다.

참고 자료

• Roboflow Supervision GitHub 공식 저장소
• Supervision 공식 문서
• ByteTrack 원 논문 (arXiv:2110.06864)

---

작성자: AI/기술 도구를 직접 설치·운용해 정리하는 블로거. 이 글은 Supervision 공식 GitHub README·docs를 기반으로 YOLOv8과 30초 도로 영상을 직접 돌려 본 결과를 합쳐 작성했다.

버전·API 시그니처는 supervision 0.25 라인 기준 2026년 6월 시점이며, 라이브러리 메이저 업데이트 시 어노테이터·트래커 옵션 명칭이 바뀔 수 있다.