# roboflow/supervision architecture

> Architecture diagram of the GitHub repository roboflow/supervision, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/roboflow/supervision
- Repository: https://github.com/roboflow/supervision

## Overview

Supervision is a model-agnostic computer-vision toolkit. Its principal workflow accepts model results as standardized detections, then supports visualization; dataset loading and format conversion are a parallel workflow. The package also provides detection processing, depth and keypoint representations, classification, and evaluation. The graph follows documented workflows and relationships shown in the source index; unsampled subsystems are included where the tree and README identify capabilities, but their internal call paths are not inferred.

Main entry points: [`src/supervision/detection/core.py`](https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/core.py) (Detections), [`src/supervision/dataset/core.py`](https://github.com/roboflow/supervision/blob/develop/src/supervision/dataset/core.py) (Detection Dataset), [`src/supervision/annotators/core.py`](https://github.com/roboflow/supervision/blob/develop/src/supervision/annotators/core.py) (Annotators), [`src/supervision/metrics/core.py`](https://github.com/roboflow/supervision/blob/develop/src/supervision/metrics/core.py) (Evaluation Metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection Data"]
  node_detections["Detections<br/>[core.py]"]
  node_compact_masks["Compact Masks<br/>[compact_mask.py]"]
  node_detection_ops["Detection Geometry<br/>[iou_and_nms.py]"]
  node_detection_tools["Detection Tools"]
  node_format_converters["Detection Converters<br/>[converters.py]"]
end

subgraph group_visualization["Visualization"]
  node_annotators["Annotators<br/>[core.py]"]
  node_colors["Color System<br/>[color.py]"]
  node_cv_backend["OpenCV Compatibility"]
end

subgraph group_datasets["Dataset Workflows"]
  node_detection_dataset["Detection Dataset<br/>[core.py]"]
  node_dataset_formats["Dataset Formats"]
end

subgraph group_analysis["Vision Analysis"]
  node_classification["Classification Data<br/>[core.py]"]
  node_depth["Depth Processing<br/>[core.py]"]
  node_keypoints["Keypoints<br/>[core.py]"]
  node_metrics["Evaluation Metrics<br/>[core.py]"]
  node_geometry["Geometry Primitives<br/>[core.py]"]
  node_config["Shared Data Fields<br/>[config.py]"]
end

subgraph group_utilities["Image Utilities"]
  node_image_utils["Image Utilities<br/>[image.py]"]
  node_video_utils["Video Utilities<br/>[video.py]"]
  node_array_utils["Array Conversion<br/>[conversion.py]"]
end

node_user(("Toolkit User"))
node_model(("Vision Model"))

node_model -->|"yields results"| node_detections
node_user -->|"annotates with"| node_annotators
node_detections -->|"visualizes"| node_annotators
node_user -->|"loads or saves"| node_detection_dataset
node_detection_dataset -->|"reads and writes"| node_dataset_formats
node_detections -->|"uses"| node_compact_masks
node_detections -->|"uses overlap ops"| node_detection_ops
node_detections -->|"converts geometry"| node_format_converters
node_detections -->|"supports processing"| node_detection_tools
node_annotators -->|"draws through"| node_cv_backend
node_annotators -->|"uses colors"| node_colors
node_detection_dataset -->|"stores annotations"| node_detections
node_detection_dataset -->|"supports classification data"| node_classification
node_depth -->|"uses detections"| node_detections
node_keypoints -->|"uses detection utilities"| node_detections
node_metrics -->|"evaluates detections"| node_detections
node_metrics -->|"evaluates keypoints"| node_keypoints
node_detections -->|"uses geometry"| node_geometry
node_detections -->|"uses shared fields"| node_config
node_detection_dataset -->|"uses shared fields"| node_config
node_image_utils -->|"converts images"| node_array_utils
node_video_utils -->|"uses video backend"| node_cv_backend

click node_detections "https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/core.py"
click node_compact_masks "https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/compact_mask.py"
click node_detection_ops "https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/utils/iou_and_nms.py"
click node_detection_tools "https://github.com/roboflow/supervision/tree/develop/src/supervision/detection/tools"
click node_format_converters "https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/utils/converters.py"
click node_annotators "https://github.com/roboflow/supervision/blob/develop/src/supervision/annotators/core.py"
click node_colors "https://github.com/roboflow/supervision/blob/develop/src/supervision/draw/color.py"
click node_cv_backend "https://github.com/roboflow/supervision/tree/develop/src/supervision/_cv2"
click node_detection_dataset "https://github.com/roboflow/supervision/blob/develop/src/supervision/dataset/core.py"
click node_dataset_formats "https://github.com/roboflow/supervision/tree/develop/src/supervision/dataset/formats"
click node_classification "https://github.com/roboflow/supervision/blob/develop/src/supervision/classification/core.py"
click node_depth "https://github.com/roboflow/supervision/blob/develop/src/supervision/depth/core.py"
click node_keypoints "https://github.com/roboflow/supervision/blob/develop/src/supervision/key_points/core.py"
click node_metrics "https://github.com/roboflow/supervision/blob/develop/src/supervision/metrics/core.py"
click node_geometry "https://github.com/roboflow/supervision/blob/develop/src/supervision/geometry/core.py"
click node_config "https://github.com/roboflow/supervision/blob/develop/src/supervision/config.py"
click node_image_utils "https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/image.py"
click node_video_utils "https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/video.py"
click node_array_utils "https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/conversion.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_detections,node_compact_masks,node_detection_ops,node_detection_tools,node_format_converters,node_user toneBlue
class node_annotators,node_colors,node_cv_backend toneAmber
class node_detection_dataset,node_dataset_formats toneMint
class node_classification,node_depth,node_keypoints,node_metrics,node_geometry,node_config toneRose
class node_image_utils,node_video_utils,node_array_utils,node_model toneIndigo
```

## Components

### Detection Data

- [Detections](https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/core.py): `src/supervision/detection/core.py`
- [Compact Masks](https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/compact_mask.py): `src/supervision/detection/compact_mask.py`
- [Detection Geometry](https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/utils/iou_and_nms.py): `src/supervision/detection/utils/iou_and_nms.py`
- [Detection Tools](https://github.com/roboflow/supervision/tree/develop/src/supervision/detection/tools): `src/supervision/detection/tools`
- [Detection Converters](https://github.com/roboflow/supervision/blob/develop/src/supervision/detection/utils/converters.py): `src/supervision/detection/utils/converters.py`

### Visualization

- [Annotators](https://github.com/roboflow/supervision/blob/develop/src/supervision/annotators/core.py): `src/supervision/annotators/core.py`
- [Color System](https://github.com/roboflow/supervision/blob/develop/src/supervision/draw/color.py): `src/supervision/draw/color.py`
- [OpenCV Compatibility](https://github.com/roboflow/supervision/tree/develop/src/supervision/_cv2): `src/supervision/_cv2`

### Dataset Workflows

- [Detection Dataset](https://github.com/roboflow/supervision/blob/develop/src/supervision/dataset/core.py): `src/supervision/dataset/core.py`
- [Dataset Formats](https://github.com/roboflow/supervision/tree/develop/src/supervision/dataset/formats): `src/supervision/dataset/formats`

### Vision Analysis

- [Classification Data](https://github.com/roboflow/supervision/blob/develop/src/supervision/classification/core.py): `src/supervision/classification/core.py`
- [Depth Processing](https://github.com/roboflow/supervision/blob/develop/src/supervision/depth/core.py): `src/supervision/depth/core.py`
- [Keypoints](https://github.com/roboflow/supervision/blob/develop/src/supervision/key_points/core.py): `src/supervision/key_points/core.py`
- [Evaluation Metrics](https://github.com/roboflow/supervision/blob/develop/src/supervision/metrics/core.py): `src/supervision/metrics/core.py`
- [Geometry Primitives](https://github.com/roboflow/supervision/blob/develop/src/supervision/geometry/core.py): `src/supervision/geometry/core.py`
- [Shared Data Fields](https://github.com/roboflow/supervision/blob/develop/src/supervision/config.py): `src/supervision/config.py`

### Image Utilities

- [Image Utilities](https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/image.py): `src/supervision/utils/image.py`
- [Video Utilities](https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/video.py): `src/supervision/utils/video.py`
- [Array Conversion](https://github.com/roboflow/supervision/blob/develop/src/supervision/utils/conversion.py): `src/supervision/utils/conversion.py`

### Other components

- **Toolkit User**
- **Vision Model**

## Connections

- Vision Model → Detections: yields results (evidence: `README.md`)
- Toolkit User → Annotators: annotates with (evidence: `README.md`)
- Detections → Annotators: visualizes (evidence: `README.md`)
- Toolkit User → Detection Dataset: loads or saves (evidence: `README.md`)
- Detection Dataset → Dataset Formats: reads and writes (evidence: `src/supervision/dataset/core.py`)
- Detections → Compact Masks: uses (evidence: `src/supervision/detection/core.py`)
- Detections → Detection Geometry: uses overlap ops (evidence: `src/supervision/detection/core.py`)
- Detections → Detection Converters: converts geometry (evidence: `src/supervision/detection/core.py`)
- Detections → Detection Tools: supports processing (evidence: `src/supervision/detection/core.py`)
- Annotators → OpenCV Compatibility: draws through (evidence: `src/supervision/annotators/core.py`)
- Annotators → Color System: uses colors (evidence: `src/supervision/annotators/core.py`)
- Detection Dataset → Detections: stores annotations (evidence: `src/supervision/dataset/core.py`)
- Detection Dataset → Classification Data: supports classification data (evidence: `src/supervision/dataset/core.py`)
- Depth Processing → Detections: uses detections (evidence: `src/supervision/depth/core.py`)
- Keypoints → Detections: uses detection utilities (evidence: `src/supervision/key_points/core.py`)
- Evaluation Metrics → Detections: evaluates detections (evidence: `src/supervision/metrics/mean_average_precision.py`)
- Evaluation Metrics → Keypoints: evaluates keypoints (evidence: `src/supervision/metrics/keypoint_mean_average_precision.py`)
- Detections → Geometry Primitives: uses geometry (evidence: `src/supervision/detection/core.py`)
- Detections → Shared Data Fields: uses shared fields (evidence: `src/supervision/detection/core.py`)
- Detection Dataset → Shared Data Fields: uses shared fields (evidence: `src/supervision/dataset/core.py`)
- Image Utilities → Array Conversion: converts images (evidence: `src/supervision/utils/image.py`)
- Video Utilities → OpenCV Compatibility: uses video backend (evidence: `src/supervision/utils/video.py`)
