Supervision
👋 hello
We write your reusable computer vision tools. 💜
Project Overview
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.
Key Features
- 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.
Goals
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.
Why Supervision?
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.
Expected Outcomes
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.
💻 install
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.
🔐 Environment Variables
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 values🔥 quickstart
models
Supervision 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](https://github.com/roboflow/inference) requires a [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key). ```python import cv2 import supervision as sv from inference import get_model image = cv2.imread(...) model = get_model(model_id="yolov8s-640", api_key=annotators
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)https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce
datasets
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 ```python 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 ```python 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 ```python 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 ```python 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 ```python sv.DetectionDataset.from_yolo( images_directory_path=..., annotations_directory_path=..., data_yaml_path=... ).as_pascal_voc( images_directory_path=..., annotations_directory_path=... ) ```💜 built with supervision
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
Visit our documentation page to learn how supervision can help you build computer vision applications faster and more reliably.
🏆 contribution
We love your input! Please see our contributing guide to get started. Thank you 🙏 to all our contributors!