リポジトリ解析: roboflow/supervision

基本情報

• リポジトリ名: roboflow/supervision
• 主要言語: Python
• スター数: 32,139
• フォーク数: 2,562
• 最終更新: 2025年7月（活発に開発中）
• ライセンス: MIT License
• トピックス: コンピュータビジョン、物体検出、画像アノテーション、ビデオ処理、物体追跡、データセット管理

概要

一言で言うと

コンピュータビジョンプロジェクトで再利用可能なツールを提供するPythonライブラリ。物体検出モデルの出力を標準化し、アノテーション、追跡、ゾーン分析などの実用的な機能を簡単に実装できる。

詳細説明

supervisionは、Roboflowが開発したオープンソースのコンピュータビジョンツールキットです。「We write your reusable computer vision tools」というキャッチフレーズのとおり、CVエンジニアが頻繁に必要とする機能を再利用可能な形で提供します。様々なモデル（YOLO、Transformers、SAMなど）の出力を統一的に扱え、物体検出、セグメンテーション、分類タスクに対応。豊富なアノテーター、物体追跡、ゾーンベースの分析、データセット管理など、実践的な機能を網羅しています。

主な特徴

• モデル非依存の統一API（YOLO、Transformers、MMDetection等に対応）
• 20種類以上の豊富なアノテーター（ボックス、マスク、ラベル、ヒートマップ等）
• 物体追跡機能（ByteTrack実装）
• ゾーンベース分析（ポリゴン/ライン通過検知、カウント）
• データセット管理（YOLO、COCO、Pascal VOC形式の相互変換）
• ビデオ処理ユーティリティ
• 高解像度画像のスライス推論（InferenceSlicer）
• メトリクス計算（mAP、F1スコア、精度、再現率）
• 型ヒント完備
• 最小限の依存関係

使用方法

インストール

前提条件

• Python 3.9以上
• NumPy
• OpenCV-Python
• Matplotlib
• Pillow

インストール手順

# 方法1: pip（推奨）
pip install supervision

# 方法2: conda
conda install -c conda-forge supervision

# 方法3: poetry
poetry add supervision

# 方法4: uv
uv add supervision

# 開発版をインストール
pip install git+https://github.com/roboflow/supervision.git

基本的な使い方

Hello World相当の例

import cv2
import supervision as sv
from ultralytics import YOLO

# モデルと画像の読み込み
model = YOLO("yolov8s.pt")
image = cv2.imread("image.jpg")

# 推論実行
results = model(image)[0]
detections = sv.Detections.from_ultralytics(results)

# アノテーション
box_annotator = sv.BoxAnnotator()
annotated_image = box_annotator.annotate(image.copy(), detections=detections)

# 結果表示
cv2.imshow("Detection", annotated_image)
cv2.waitKey(0)

実践的な使用例

import supervision as sv
from ultralytics import YOLO

# モデルロード
model = YOLO("yolov8m.pt")

# ビデオ処理
video_info = sv.VideoInfo.from_video_path("input.mp4")
tracker = sv.ByteTrack()

# アノテーター準備
box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

# ビデオ処理
with sv.VideoSink("output.mp4", video_info) as sink:
    for frame in sv.get_video_frames_generator("input.mp4"):
        # 検出と追跡
        results = model(frame)[0]
        detections = sv.Detections.from_ultralytics(results)
        detections = tracker.update_with_detections(detections)
        
        # ラベル作成
        labels = [
            f"#{tracker_id} {model.model.names[class_id]} {confidence:.2f}"
            for tracker_id, class_id, confidence 
            in zip(detections.tracker_id, detections.class_id, detections.confidence)
        ]
        
        # アノテーション
        annotated_frame = box_annotator.annotate(frame, detections)
        annotated_frame = label_annotator.annotate(annotated_frame, detections, labels)
        
        sink.write_frame(annotated_frame)

高度な使い方

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

# ゾーンベースカウンティング
polygon = np.array([[100, 100], [500, 100], [500, 400], [100, 400]])
zone = sv.PolygonZone(polygon=polygon)
zone_annotator = sv.PolygonZoneAnnotator(zone=zone, color=sv.Color.RED)

# 高解像度画像のスライス推論
model = YOLO("yolov8x.pt")

def callback(image_slice: np.ndarray) -> sv.Detections:
    result = model(image_slice)[0]
    return sv.Detections.from_ultralytics(result)

slicer = sv.InferenceSlicer(
    callback=callback,
    slice_wh=(640, 640),
    overlap_ratio_wh=(0.2, 0.2)
)

# 4K画像でも効率的に処理
large_image = cv2.imread("4k_image.jpg")
detections = slicer(large_image)

# 複雑なフィルタリング
filtered_detections = detections[
    (detections.class_id == 0) &  # 人物のみ
    (detections.confidence > 0.7) &  # 高信頼度
    (zone.trigger(detections))  # ゾーン内
]

ドキュメント・リソース

公式ドキュメント

• README.md: プロジェクト概要、基本的な使い方
• docs/: MkDocsベースの詳細ドキュメント
• CONTRIBUTING.md: 貢献ガイドライン
• 公式サイト: https://supervision.roboflow.com/

サンプル・デモ

• demo.ipynb: Jupyter Notebookでの使用例
• examples/: 実用的なサンプルコード
• Cookbooks: 特定のユースケース向けチュートリアル
  • トラフィック分析
  • 速度推定
  • 滞在時間分析
  • 人数カウント

チュートリアル・ガイド

• 公式ドキュメントのHow-toガイド
• YouTube動画チュートリアル
• Roboflowブログの技術記事
• コミュニティフォーラム

技術的詳細

アーキテクチャ

全体構造

モジュラーアーキテクチャを採用し、各機能が独立したモジュールとして実装。コアとなるDetectionsクラスを中心に、様々なツールが連携して動作。モデル固有の実装を抽象化し、統一的なAPIを提供。

ディレクトリ構成

supervision/
├── annotators/         # 視覚化ツール（20種類以上）
│   ├── core.py         # ベースクラス
│   ├── box.py          # ボックスアノテーター
│   ├── mask.py         # マスクアノテーター
│   └── ...             # その他多数
├── detection/          # 検出コア機能
│   ├── core.py         # Detectionsクラス
│   ├── tools/          # ゾーン、スライサー等
│   └── utils/          # NMS、IoU等のユーティリティ
├── dataset/            # データセット管理
│   └── formats/        # COCO、YOLO、Pascal VOC
├── tracker/            # 物体追跡
│   └── byte_tracker/   # ByteTrack実装
├── metrics/            # 評価メトリクス
│   ├── detection.py    # mAP、精度、再現率
│   └── classification.py # 分類メトリクス
└── utils/              # 汎用ユーティリティ

主要コンポーネント

• Detectionsクラス: 検出結果の統一表現

  • 場所: supervision/detection/core.py
  • 依存: NumPy配列ベース
  • インターフェース: from_ultralytics、from_transformers等

• ByteTracker: 多物体追跡アルゴリズム

  • 場所: supervision/tracker/byte_tracker/
  • 依存: カルマンフィルター、IoU計算
  • インターフェース: update_with_detections

• InferenceSlicer: 高解像度画像処理

  • 場所: supervision/detection/tools/inference_slicer.py
  • 依存: Detectionsクラス、コールバック関数
  • インターフェース: __call__メソッド

技術スタック

コア技術

• 言語: Python 3.9+（型ヒント完備）
• フレームワーク: フレームワーク非依存（標準ライブラリ中心）
• 主要ライブラリ:
  • numpy: 配列操作とベクトル演算
  • opencv-python: 画像・動画処理
  • matplotlib: 可視化
  • pillow: 画像フォーマット処理

開発・運用ツール

• ビルドツール: Poetry、setuptools
• テスト: pytest、tox
• CI/CD: GitHub Actions
• ドキュメント: MkDocs Material

設計パターン・手法

• ビルダーパターン: アノテーターのチェーン
• ストラテジーパターン: 交換可能な追跡アルゴリズム
• ファクトリーパターン: モデル固有の変換器
• イテレーターパターン: データセット・動画フレーム生成
• コンテキストマネージャー: VideoSinkでのリソース管理

データフロー・処理フロー

1. モデルから検出結果を取得
2. Detectionsオブジェクトに統一変換
3. オプション: 追跡、フィルタリング、ゾーン分析
4. アノテーターで視覚化
5. 結果の出力（画像、動画、メトリクス）

API・インターフェース

公開API

Detectionsクラス

• 目的: 検出結果の統一表現と操作
• 使用例:

# フィルタリング
high_conf = detections[detections.confidence > 0.5]

# スライシング
first_10 = detections[:10]

# 結合
combined = sv.Detections.merge([detections1, detections2])

# カスタムデータ追加
detections.data["custom_field"] = custom_values

設定・カスタマイズ

アノテーター設定

# カスタマイズ例
box_annotator = sv.BoxAnnotator(
    color=sv.ColorPalette.default(),
    thickness=2,
    text_thickness=1,
    text_scale=0.5
)

# カスタムカラー
custom_colors = sv.ColorPalette.from_hex(["#FF0000", "#00FF00", "#0000FF"])

拡張・プラグイン開発

• カスタムアノテーターの作成
• 新しいトラッカーの実装
• モデル固有の変換器追加

パフォーマンス・スケーラビリティ

パフォーマンス特性

• ベクトル化された演算によ高速処理
• メモリ効率的なジェネレーターベースの動画処理
• InferenceSlicerによる超高解像度画像対応（4K以上）
• 最適化されたNMS実装

スケーラビリティ

• バッチ処理対応
• 並列処理可能な設計
• 大規模データセット対応（遅延読み込み）
• ストリーミング処理サポート

制限事項

• リアルタイムの上限はモデルとハードウェアに依存
• メモリは同時処理する検出数に比例
• 追跡精度は動画のフレームレートに影響される

評価・所感

技術的評価

強み

• モデル非依存の統一API設計
• 豊富な実用的機能（20種類以上のアノテーター）
• プロダクション対応の品質
• 優れたドキュメントとコミュニティサポート
• 型安全性と開発体験の良さ
• 最小限の依存関係

改善の余地

• 3D物体検出のサポート
• より高度な追跡アルゴリズムの追加
• WebAssembly対応でブラウザ実行
• GPUアクセラレーション対応

向いている用途

• 物体検出・追跡アプリケーション開発
• 監視カメラシステム
• トラフィック分析・人流解析
• 品質検査システム
• リテール分析（来店者数、滞在時間）
• スポーツ分析

向いていない用途

• 3D点群処理
• 医療画像の専門的解析
• エッジデバイス向け最適化が必要な用途
• リアルタイム要求が極めて厳しいシステム

総評

supervisionは、コンピュータビジョンの実装における「車輪の再発明」を防ぎ、開発者が本質的な問題解決に集中できるようにする優れたライブラリです。モデル非依存の設計により、異なるフレームワーク間の移行も容易で、プロトタイピングから本番環境まで幅広く活用できます。特に物体検出後の処理（アノテーション、追跡、分析）において、これ以上ないほど充実した機能を提供しており、CVプロジェクトの必須ツールと言えるでしょう。