We write your reusable computer vision tools. 💜
Supervision is an open-source Python library designed to simplify the development of computer vision applications. It provides a collection of modular, reusable tools that address common tasks in computer vision, such as object detection, tracking, annotation, and dataset management. By leveraging Supervision, developers can accelerate their workflows, reduce complexity, and focus on building innovative solutions.
- Model Agnostic: Supports various computer vision models, including Ultralytics, Transformers, and MMDetection.
- Inference: Easily integrate with Roboflow for model inference.
- Annotators: Provides tools for annotating images and videos with bounding boxes, masks, and more.
- Datasets: Simplifies loading, splitting, merging, and saving datasets in popular formats like COCO, YOLO, and Pascal VOC.
The Supervision project aims to:
- Enhance System Monitoring: Offer real-time insights into the performance of computer vision models, detecting anomalies and ensuring optimal operation.
- Improve Security & Compliance: Ensure the library adheres to security best practices and industry standards, protecting user data and ensuring compliance.
- Optimize Performance: Provide efficient, optimized code that leverages hardware acceleration where possible.
- User-Friendly Interface: Develop an intuitive API with comprehensive documentation and examples to make it accessible to developers of all levels.
- Scalability: Support large-scale datasets and real-time processing requirements, making it suitable for both small projects and enterprise-level applications.
Developing computer vision applications can be complex and time-consuming, requiring expertise in multiple areas such as object detection, tracking, annotation, and dataset management. Supervision addresses this by providing a unified, easy-to-use interface for these common tasks, allowing developers to focus on their specific application logic rather than reinventing the wheel.
By using Supervision, developers can expect to:
- Reduce development time for computer vision projects.
- Improve the reliability and performance of their vision systems.
- Benefit from a community-driven library that is continuously updated and improved.
Pip install the supervision package in a Python>=3.8 environment.
pip install supervisionRead more about conda, mamba, and installing from source in our guide.
Create a .env file to store sensitive configuration:
ROBOFLOW_API_KEY=your_api_key_here
LOG_LEVEL=INFOThen load them in your code:
from dotenv import load_dotenv
load_dotenv() # Load before other imports
# Now use os.getenv() to access valuesSupervision was designed to be model agnostic. Just plug in any classification, detection, or segmentation model. For your convenience, we have created connectors for the most popular libraries like Ultralytics, Transformers, or MMDetection.
import cv2
import supervision as sv
from ultralytics import YOLO
image = cv2.imread(...)
model = YOLO("yolov8s.pt")
result = model(image)[0]
detections = sv.Detections.from_ultralytics(result)
len(detections)
# 5👉 more model connectors
-
inference
Running with Inference requires a Roboflow API KEY.
import cv2 import supervision as sv from inference import get_model image = cv2.imread(...) model = get_model(model_id="yolov8s-640", api_key=<ROBOFLOW API KEY>) result = model.infer(image)[0] detections = sv.Detections.from_inference(result) len(detections) # 5
Supervision offers a wide range of highly customizable annotators, allowing you to compose the perfect visualization for your use case.
import cv2
import supervision as sv
image = cv2.imread(...)
detections = sv.Detections(...)
box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(
scene=image.copy(),
detections=detections)supervision-0.16.0-annotators.mp4
Supervision provides a set of utils that allow you to load, split, merge, and save datasets in one of the supported formats.
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👉 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=... )
football-players-tracking-25.mp4
traffic_analysis_result.mov
vehicles-step-7-new.mp4
Visit our documentation page to learn how supervision can help you build computer vision applications faster and more reliably.
We love your input! Please see our contributing guide to get started. Thank you 🙏 to all our contributors!