Supervision

What it is

Supervision is an open source Python library from Roboflow for building computer vision applications. It does not run a model. You pair it with one. RF-DETR’s predict method already returns Supervision’s Detections object, and for other models Supervision’s converters turn the output into that same object. From there you can draw boxes, masks and labels on images and video, filter detections and count them inside zones. It also loads and converts datasets between YOLO, COCO and Pascal VOC, and scores a model with mAP and confusion matrices. Tracking objects across frames takes a separate package, trackers.

1. A model finds objects in an image or a video frame
2. Supervision turns its output into one Detections object
3. You filter, track, count or draw on those detections
4. You save the picture, the video or a CSV or JSON file

Who it suits

Python developers and machine learning engineers who already have a detection or segmentation model and want the code around it. That means drawing results, counting in zones, converting datasets and scoring. Skip it if you need a model itself, because Supervision holds none.

Where to use it

Inside your own Python code. PyPI lists Linux, macOS and Windows. The maker documents these routes, and the kit has a page for each.

• pip, the route the docs list as recommended, with a choice of OpenCV backend
• Poetry, uv and rye
• conda and mamba, from conda-forge
• A clone of the develop branch, for development
• A model and a tracker: RF-DETR, Roboflow Inference, Ultralytics, Transformers and the trackers package
• Datasets, saved detections and benchmarks
• Where the guides, the cheatsheet and the sample files are

The maker documents no steps for coding agents.

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each route above. The main route is pip, in a Python 3.10 or newer environment.

1. Open a Python 3.10 or newer environment.
2. Install Supervision with OpenCV, and a model package.
3. Run the docs example on one image.

pip install opencv-python supervision
pip install pillow rfdetr

How to use it

Run a model, then hand its output to Supervision. The documentation home gives this example. It finds objects in one image and draws a box and a label on each one.

import cv2
import supervision as sv
from rfdetr import RFDETRMedium

model = RFDETRMedium()
image = cv2.imread("image.jpg")
detections = model.predict(image[:, :, ::-1])

box_annotator = sv.BoxAnnotator()
label_annotator = sv.LabelAnnotator()

annotated_image = box_annotator.annotate(scene=image, detections=detections)
annotated_image = label_annotator.annotate(scene=annotated_image, detections=detections)

A model from another package returns its own kind of result, so you convert it first. Each converter is a class method on Detections, such as from_inference, from_ultralytics and from_transformers.

Example

You run a model on one photo and want only the confident detections. The Filter Detections page keeps them with one line.

detections = detections[detections.confidence > 0.5]

The same page filters by class, area, box size and zone. Draw the filtered result with the two annotators above.

For newcomers and experts

If you are new. A detection model looks at a picture and returns boxes, each with a class and a confidence. Supervision does not find anything itself. It is the code you write around the model: drawing, counting, saving and scoring. Start with one image and the example above. The Track Objects page downloads a sample video when you want to try video.

For experts. Every model connector ends in the same Detections object, so annotators and filters work the same whatever made the boxes. The process_video function runs a callback on every frame and writes a new video. LineZone counts crossings and needs tracker_id, so run a tracker first. For a moving camera, the Count in Zone page passes a coord_transform from the trackers motion estimator to the zone test.

CompactMask stores each mask as a run-length encoding of its box crop, and Detections.from_inference takes compact_masks=True. The page warns that a native COCO RLE mask can lose pixels outside its reported box.

Good to know

It is a library you run in your own Python code. The points below come from the maker’s pages.

• Models: none comes with it. A model comes from another package. The Benchmark a Model page says RF-DETR ships pre-trained detection and segmentation checkpoints in the rfdetr package. The pages do not say whether those weights download, or from where
• Network: download_assets fetches sample videos, and a Roboflow dataset download needs a login. The README says its Inference example needs a Roboflow API key and says nothing about usage data
• Tracking: sv.ByteTrack was removed as of supervision-0.31.0. The cheatsheet still shows it. The current pages use ByteTrackTracker from the trackers package
• OpenCV: it is no longer installed with Supervision. Some text and anti-aliased drawing pixels can differ from OpenCV’s, and the docs give a pin, pip install "supervision<0.30.0", for code that needs the older behavior
• Versions: the repository’s default branch is develop. Mindket’s note: a PyPI release can be behind it, so check that the call you want exists in your version
• Removal: the README gives no uninstall steps. Mindket’s note: use pip’s own uninstall, or delete the environment you made for it
• License: MIT. The LICENSE file reads “Copyright (c) 2022 Roboflow”