Roboflow Supervision: многоразовый инструментарий для computer vision

«We write your reusable computer vision tools.» — девиз проекта, который честно отражает суть: вам не нужно изобретать велосипед для каждой CV-задачи.

Что это такое и для кого

Supervision — это open-source Python-библиотека (лицензия MIT), разработанная для создания переиспользуемых инструментов компьютерного зрения — от загрузки данных до визуализации и анализа — без привязки к конкретной модели.

Библиотека даёт разработчикам model-agnostic инструментарий для загрузки предсказаний, аннотации изображений и видео, трекинга объектов, подсчёта детекций в зонах, обработки датасетов и оценки качества моделей.

Целевая аудитория:

• ML-инженеры и исследователи, строящие CV-пайплайны
• Разработчики видеоаналитики (ритейл, безопасность, транспорт)
• Команды, которым нужно быстро прототипировать без boilerplate-кода
• Data scientists, работающие с несколькими CV-фреймворками одновременно

Ключевые возможности

1. Унифицированный Detections API

Центральный элемент проекта — единый объект Detections с конвертерами для выходных данных от Ultralytics, Roboflow Inference, Hugging Face Transformers, SAM, Detectron2, MMDetection, YOLO-NAS, PaddleDet, NCNN, Azure AI Vision и VLM-парсеров: Florence-2, PaliGemma, Qwen VL, Gemini, DeepSeek VL 2 и Moondream.

Пример подключения любой модели через один интерфейс:

import supervision as sv
from PIL import Image
from rfdetr import RFDETRSmall

image = Image.open("photo.jpg")
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)

# Используем supervision для аннотации
box_annotator = sv.BoxAnnotator()
annotated = box_annotator.annotate(scene=image, detections=detections)

2. Богатый набор аннотаторов

Supervision предлагает широкий спектр настраиваемых аннотаторов, позволяющих составить идеальную визуализацию для конкретного сценария.

Библиотека позволяет запустить почти любую vision-модель, считать результаты, визуализировать их (15+ аннотаторов), отслеживать объекты между кадрами, считать объекты, пересекающие линии или находящиеся в зонах, сравнивать результаты моделей с метриками.

Доступные аннотаторы включают: BoxAnnotator, LabelAnnotator, MaskAnnotator, DotAnnotator, TriangleAnnotator, TraceAnnotator, RichLabelAnnotator (поддержка Unicode) и многие другие.

3. Трекинг объектов

Supervision поддерживает трекинг объектов с помощью ByteTrack и интегрируется с видеопайплайнами.

Библиотека позволяет настроить трекинг в реальном времени с использованием ByteTracker, добавить сглаживание детекций и определить полигональные зоны для мониторинга конкретных областей в видеопотоке, аннотируя кадры идентификаторами объектов и данными о скорости.

import supervision as sv
from ultralytics import YOLO

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

def callback(frame, _):
    results = model(frame)[0]
    detections = sv.Detections.from_ultralytics(results)
    detections = tracker.update_with_detections(detections)
    return trace_annotator.annotate(frame.copy(), detections)

sv.process_video(
    source_path="input.mp4",
    target_path="output.mp4",
    callback=callback
)

4. Зонная аналитика (LineZone и PolygonZone)

С помощью Supervision можно аннотировать изображения и видео ограничивающими рамками, масками и метками; отслеживать объекты между кадрами с постоянными идентификаторами; считать и фильтровать детекции внутри полигональных зон.

В LineZone решена проблема «дрожащих» детекций: когда объекты пересекают линию с джиттером, они могут быть посчитаны несколько раз. Теперь это контролируется аргументом minimum_crossing_threshold — при значении 2 и выше дополнительные кадры используются для подтверждения пересечения, что значительно повышает точность подсчёта.

5. Работа с датасетами

Пакет включает утилиты для загрузки, разбивки и объединения датасетов в форматах COCO, YOLO и Pascal VOC, что упрощает управление данными для обучения и тестирования.

import supervision as sv

dataset = sv.DetectionDataset.from_yolo(
    images_directory_path="./images",
    annotations_directory_path="./labels",
    data_yaml_path="./data.yaml",
)
train_ds, test_ds = dataset.split(split_ratio=0.7)

6. Метрики качества моделей

В версии 0.25.0 (ноябрь 2024) добавлены новые метрики: Precision, Recall и Mean Average Recall, расширена поддержка LineZone и KeyPoints, обеспечена совместимость с Python 3.13.

Supervision вводит метрики, которые в настоящее время поддерживают ограничивающие рамки (xyxy) и маски. В последующих релизах планируется добавить ещё больше метрик, позволяющих оценивать производительность моделей.

7. Интеграция с VLM и LLM

Метод sv.Detections.from_lmm позволяет преобразовывать текстовые результаты больших мультимодальных моделей (LMM) в объект sv.Detections. Поддерживаются Florence-2, PaliGemma, Qwen VL, Gemini, DeepSeek VL 2 и Moondream.

8. OCR-интеграция

Добавлен метод from_easyocr, позволяющий интегрировать результаты OCR в экосистему supervision. EasyOCR — open-source библиотека оптического распознавания символов, умеющая читать текст с изображений.

Архитектура пайплайна

graph LR
    A[Источник: изображение / видео] --> B[Модель детекции]
    B --> C[sv.Detections — унифицированный объект]
    C --> D{Операции}
    D --> E[Аннотация: BoxAnnotator, MaskAnnotator...]
    D --> F[Трекинг: ByteTrack]
    D --> G[Зоны: PolygonZone / LineZone]
    D --> H[Метрики: mAP, F1, Precision, Recall]
    E --> I[Финальное видео / изображение]
    F --> I
    G --> I
    H --> J[Отчёт о качестве модели]

Тарифы и цены

Единственный платный аспект в экосистеме — Roboflow Inference, если вы хотите запускать модели через облачный API Roboflow (а не локально). Публичный план Roboflow бесплатен для открытых проектов и включает $60/месяц в виде кредитов, двух пользователей, инструменты разметки, обучение моделей и облачный деплой. Платные планы начинаются с Core от $79/месяц при годовой оплате или $99 помесячно.

Но сама библиотека supervision не требует никаких ключей API при использовании с локальными моделями.

Плюсы и минусы

Сравнение с альтернативами

OpenCV — это базовая библиотека компьютерного зрения для обработки изображений, работы с камерами, видео и классического CV. Detectron2 лучше подходит, когда нужна гибкость: если вы хотите экспериментировать с Mask R-CNN, кастомными моделями сегментации, ключевыми точками, паноптической сегментацией или исследовательскими пайплайнами.

Supervision не конкурирует с ними напрямую — на практике многие команды используют несколько библиотек одновременно: OpenCV для одних задач, PyTorch для реализации DL-модели в другой, Transformers для запуска vision-модели — и supervision для обработки детекций модели.

Быстрый старт

pip install supervision

import cv2
import supervision as sv
from ultralytics import YOLO

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

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

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

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

cv2.imwrite("result.jpg", annotated)

Практические применения

С помощью supervision можно анализировать время ожидания и оптимизировать процессы с помощью computer vision, отслеживать объекты и рассчитывать время их пребывания в отведённых зонах — эти техники применимы для улучшения клиентского опыта в ритейле, управления трафиком и других сценариев.

Библиотека позволяет отслеживать и оценивать скорость транспортных средств с помощью YOLO, ByteTrack и Roboflow Inference, охватывая обнаружение объектов, многообъектный трекинг, фильтрацию детекций, перспективное преобразование и оценку скорости.

Вердикт

Если вы работаете в области компьютерного зрения — разрабатываете модели, анализируете видео или создаёте Python-системы — Supervision от Roboflow является мощным, open-source и гибким фреймворком, применимым в широком спектре проектов.

Supervision подойдёт, если вы:

• Строите production CV-пайплайн поверх YOLOv8/v9, RT-DETR, SAM или Transformers
• Нужна быстрая визуализация и аннотация без boilerplate-кода
• Работаете с видеоаналитикой: трекинг, подсчёт объектов, зоны
• Хотите сравнивать модели по mAP, F1 и другим метрикам

Supervision не подойдёт, если вы:

• Ищете инструмент для обучения моделей (нужен PyTorch / Ultralytics)
• Требуется работа на очень низком уровне с пикселями (лучше OpenCV)
• Не пишете код (нужен GUI-инструмент)

Итоговая оценка: 9 / 10

Supervision — это де-факто стандартная «склейка» для современных CV-проектов на Python. Он не заменит вам фреймворк для обучения, зато сэкономит сотни строк boilerplate при визуализации, трекинге и аналитике.