supervision

We write your reusable computer vision tools. 💜

https://github.com/devrhylme-foundation/supervision

Last synced: 10 months ago · JSON representation ·

Export Citation

• BibTeX
• APA Style

Repository

We write your reusable computer vision tools. 💜

README.md

👋 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.

bash pip install supervision

Read more about conda, mamba, and installing from source in our guide.

🔐 Environment Variables

Create a .env file to store sensitive configuration:

bash ROBOFLOW_API_KEY=your_api_key_here LOG_LEVEL=INFO

Then load them in your code: ```python 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.

```python 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=) result = model.infer(image)[0] detections = sv.Detections.from_inference(result) len(detections) # 5 ```

annotators

Supervision offers a wide range of highly customizable annotators, allowing you to compose the perfect visualization for your use case.

```python import cv2 import supervision as sv

image = cv2.imread(...) detections = sv.Detections(...)

boxannotator = sv.BoxAnnotator() annotatedframe = 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.

```python import supervision as sv from roboflow import Roboflow

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

ds = sv.DetectionDataset.fromcoco( imagesdirectorypath=f"{dataset.location}/train", annotationspath=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://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

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!