superiorvision 0.30.0.dev4

Supervision, except the numbers have finally been informed that GPUs exist.

SuperiorVision is Roboflow's tensor-native, inference-focused fork of Supervision. It preserves the import supervision as sv API used by Roboflow Inference, while keeping rectangular numeric state in torch.Tensor objects throughout the supported code paths.

If detections begin as tensors, converting them to NumPy so the next operation can turn them back into tensors is not "compatibility." It is cardio. SuperiorVision declines the workout.

Same API. Fewer NumPy vacations.

For the external multi-object trackers used by Inference, pair SuperiorVision with the Tracktors package. The dependency points one way—Tracktors consumes tensor-native sv.Detections—so SuperiorVision keeps its existing sv.ByteTrack compatibility API without a circular package dependency.

📑 Table of Contents

• 👋 Hello
• 💻 Install
• 🔥 Quickstart
  • Models
  • Annotators
  • Datasets
• 🎬 Tutorials
• 💜 Built with the API
• 📚 Documentation
• 🏆 Contribution

👋 Hello

The familiar computer-vision toolkit, now with fewer surprise trips to the CPU. From tensor-native detections to real-time zone counting, SuperiorVision keeps the compatible building blocks used by Inference while letting GPUs do the job they were purchased to do. 🤝

💻 Install

Install the SuperiorVision distribution in a Python>=3.10 environment. The published version is currently a development release, so pin it explicitly:

pip install superiorvision==0.30.0.dev3

For an editable checkout:

git clone git@github.com:roboflow/superiorvision.git
cd superiorvision
pip install -e .

Both imports are supported:

import supervision as sv       # existing Inference code
import superiorvision as sv    # cheekier spelling, same API

The PyPI distribution is named superiorvision, but it intentionally provides the supervision import namespace for drop-in compatibility. Install it as a replacement for upstream Supervision, not beside it. Two distributions cannot both own the same trench coat and pretend everything is fine.

The upstream documentation below remains useful for the compatible API surface.

🔥 Quickstart

Models

SuperiorVision preserves Supervision's model-agnostic API. Just plug in any classification, detection, or segmentation model. The compatible connectors cover popular libraries such as Ultralytics, Transformers, MMDetection, and Inference. Other integrations, including rfdetr, already return sv.Detections directly.

Install the optional dependencies for this example with pip install pillow rfdetr.

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

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

len(detections)
# 5

👉 more model connectors

• inference

  Running with Inference requires a Roboflow API KEY.

  import supervision as sv
  from PIL import Image
  from inference import get_model
  
  image = Image.open("path/to/image.jpg")
  model = get_model(model_id="rfdetr-small", api_key="ROBOFLOW_API_KEY")
  result = model.infer(image)[0]
  detections = sv.Detections.from_inference(result)
  
  len(detections)
  # 5
  

Annotators

SuperiorVision retains the wide range of customizable annotators from its upstream API, allowing you to compose the visualization your use case needs.

import cv2
import supervision as sv

image = cv2.imread("path/to/image.jpg")
# Assuming detections are obtained from a model
detections = sv.Detections(...)

box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(scene=image.copy(), detections=detections)

https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce

Datasets

SuperiorVision retains the compatible dataset utilities for loading, splitting, merging, and saving supported formats. Dataset and image I/O remain deliberate CPU boundaries; tensor-native runtime paths do not need to cosplay as JPEG encoders.

import supervision as sv
from roboflow import Roboflow

project = Roboflow().workspace("WORKSPACE_ID").project("PROJECT_ID")
dataset = project.version("PROJECT_VERSION").download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
)

path, image, annotation = ds[0]
# loads image on demand

for path, image, annotation in ds:
    # loads image on demand
    pass

👉 more dataset utils

• load

  dataset = sv.DetectionDataset.from_yolo(
      images_directory_path=...,
      annotations_directory_path=...,
      data_yaml_path=...,
  )
  
  dataset = sv.DetectionDataset.from_pascal_voc(
      images_directory_path=...,
      annotations_directory_path=...,
  )
  
  dataset = sv.DetectionDataset.from_coco(
      images_directory_path=...,
      annotations_path=...,
  )
  

• split

  train_dataset, test_dataset = dataset.split(split_ratio=0.7)
  test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)
  
  len(train_dataset), len(test_dataset), len(valid_dataset)
  # (700, 150, 150)
  

• merge

  ds_1 = sv.DetectionDataset(...)
  len(ds_1)
  # 100
  ds_1.classes
  # ['dog', 'person']
  
  ds_2 = sv.DetectionDataset(...)
  len(ds_2)
  # 200
  ds_2.classes
  # ['cat']
  
  ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
  len(ds_merged)
  # 300
  ds_merged.classes
  # ['cat', 'dog', 'person']
  

• save

  dataset.as_yolo(
      images_directory_path=...,
      annotations_directory_path=...,
      data_yaml_path=...,
  )
  
  dataset.as_pascal_voc(
      images_directory_path=...,
      annotations_directory_path=...,
  )
  
  dataset.as_coco(
      images_directory_path=...,
      annotations_path=...,
  )
  

• convert

  sv.DetectionDataset.from_yolo(
      images_directory_path=...,
      annotations_directory_path=...,
      data_yaml_path=...,
  ).as_pascal_voc(
      images_directory_path=...,
      annotations_directory_path=...,
  )
  

🎬 Tutorials

Want to learn the compatible API? Explore the upstream how-to guides, end-to-end examples, cheatsheet, and cookbooks!

Dwell Time Analysis with Computer Vision | Real-Time Stream Processing

Learn how to use computer vision to analyze wait times and optimize processes. This tutorial covers object detection, tracking, and calculating time spent in designated zones. Use these techniques to improve customer experience in retail, traffic management, or other scenarios.

Speed Estimation & Vehicle Tracking | Computer Vision | Open Source

Learn how to track and estimate the speed of vehicles using YOLO, ByteTrack, and Roboflow Inference. This comprehensive tutorial covers object detection, multi-object tracking, filtering detections, perspective transformation, speed estimation, visualization improvements, and more.

💜 Built with the API

Did you build something cool using the compatible supervision API? Tell us in the SuperiorVision repository.

https://user-images.githubusercontent.com/26109316/207858600-ee862b22-0353-440b-ad85-caa0c4777904.mp4

https://github.com/roboflow/supervision/assets/26109316/c9436828-9fbf-4c25-ae8c-60e9c81b3900

https://github.com/roboflow/supervision/assets/26109316/3ac6982f-4943-4108-9b7f-51787ef1a69f

📚 Documentation

The upstream Supervision documentation describes the compatible API. Fork-specific tensor coverage and Inference compatibility are tracked in this repository and the Inference API surface audit.

🏆 Contribution

We love your input! Please see our contributing guide to get started. The fork lives at roboflow/superiorvision; upstream-compatible changes may still belong in Supervision. Thank you 🙏 to all our contributors!