wehub/roboflow--supervision

Fork 0

Files

T

wehub-resource-sync 9194ef5abd

Docs/Test Workflow / Test docs build (push) Failing after 0s

Details

Check links & references / links-check (push) Failing after 1s

Details

Pytest/Test Workflow / Import Test and Pytest Run (ubuntu-latest, 3.10) (push) Failing after 0s

Details

Pytest/Test Workflow / Import Test and Pytest Run (ubuntu-latest, 3.11) (push) Failing after 0s

Details

PR Conflict Labeler / main (push) Failing after 2s

Details

Pytest/Test Workflow / Import Test and Pytest Run (ubuntu-latest, 3.12) (push) Failing after 2s

Details

Pytest/Test Workflow / Import Test and Pytest Run (ubuntu-latest, 3.13) (push) Failing after 0s

Details

Pytest/Test Workflow / Build this Package (push) Failing after 5s

Details

Pytest/Test Workflow / Import Test and Pytest Run (macos-latest, 3.10) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (macos-latest, 3.11) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (macos-latest, 3.12) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (macos-latest, 3.13) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (windows-latest, 3.10) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (windows-latest, 3.11) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (windows-latest, 3.12) (push) Has been cancelled

Details

Pytest/Test Workflow / Import Test and Pytest Run (windows-latest, 3.13) (push) Has been cancelled

Details

Pytest/Test Workflow / testing-guardian (push) Has been cancelled

Details

chore: import upstream snapshot with attribution

2026-07-13 12:06:10 +08:00

19 KiB

Raw Permalink Blame History

comments, description

comments	description
true	API reference for supervision's annotator classes — draw bounding boxes, masks, labels, tracks, and heatmaps on images with one method call.

Annotators

Annotators accept detections and apply box or mask visualizations to the detections. Annotators have many available styles.

=== "Outlines"

=== "Box"

    ```python
    import supervision as sv

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

    box_annotator = sv.BoxAnnotator()
    annotated_frame = box_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![bounding-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/bounding-box-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "RoundBox"

    ```python
    import supervision as sv

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

    round_box_annotator = sv.RoundBoxAnnotator()
    annotated_frame = round_box_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![round-box-annotator-example](https://media.roboflow.com/supervision-annotator-examples/round-box-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "BoxCorner"

    ```python
    import supervision as sv

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

    corner_annotator = sv.BoxCornerAnnotator()
    annotated_frame = corner_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![box-corner-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-corner-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Circle"

    ```python
    import supervision as sv

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

    circle_annotator = sv.CircleAnnotator()
    annotated_frame = circle_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![circle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/circle-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Ellipse"

    ```python
    import supervision as sv

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

    ellipse_annotator = sv.EllipseAnnotator()
    annotated_frame = ellipse_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![ellipse-annotator-example](https://media.roboflow.com/supervision-annotator-examples/ellipse-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Polygon"

    ```python
    import supervision as sv

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

    polygon_annotator = sv.PolygonAnnotator()
    annotated_frame = polygon_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![polygon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/polygon-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Shading"

=== "Color"

    ```python
    import supervision as sv

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

    color_annotator = sv.ColorAnnotator()
    annotated_frame = color_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![box-mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/box-mask-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Halo"

    ```python
    import supervision as sv

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

    halo_annotator = sv.HaloAnnotator()
    annotated_frame = halo_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![halo-annotator-example](https://media.roboflow.com/supervision-annotator-examples/halo-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Mask"

    ```python
    import supervision as sv

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

    mask_annotator = sv.MaskAnnotator()
    annotated_frame = mask_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    !!! note

        `MaskAnnotator` expects `detections.mask` to contain instance segmentation masks aligned to the image passed to `annotate`. For dense masks, provide a boolean array of shape `(N, H, W)` where `(H, W)` matches the image height and width (it also accepts `sv.CompactMask`). If your model returns framework-specific results, convert them to `sv.Detections` first, for example with `sv.Detections.from_ultralytics(...)` or `sv.Detections.from_inference(...)`.

    <div class="result" markdown>

    ![mask-annotator-example](https://media.roboflow.com/supervision-annotator-examples/mask-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Markers"

=== "Dot"

    ```python
    import supervision as sv

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

    dot_annotator = sv.DotAnnotator()
    annotated_frame = dot_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![dot-annotator-example](https://media.roboflow.com/supervision-annotator-examples/dot-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Triangle"

    ```python
    import supervision as sv

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

    triangle_annotator = sv.TriangleAnnotator()
    annotated_frame = triangle_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![triangle-annotator-example](https://media.roboflow.com/supervision-annotator-examples/triangle-annotator-example.png){ align=center width="800" }

    </div>

=== "Labels"

=== "Label"

    ```python
    import supervision as sv

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

    labels = [
        f"{class_name} {confidence:.2f}"
        for class_name, confidence in zip(
            detections["class_name"],
            detections.confidence,
        )
    ]

    label_annotator = sv.LabelAnnotator(text_position=sv.Position.CENTER)
    annotated_frame = label_annotator.annotate(
        scene=image.copy(), detections=detections, labels=labels
    )
    ```

    <div class="result" markdown>

    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "RichLabel"

    ```python
    import supervision as sv

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

    labels = [
        f"{class_name} {confidence:.2f}"
        for class_name, confidence in zip(
            detections["class_name"],
            detections.confidence,
        )
    ]

    rich_label_annotator = sv.RichLabelAnnotator(
        font_path="TTF_FONT_PATH",
        text_position=sv.Position.CENTER,
    )
    annotated_frame = rich_label_annotator.annotate(
        scene=image.copy(),
        detections=detections,
        labels=labels,
    )
    ```

    <div class="result" markdown>

    ![label-annotator-example](https://media.roboflow.com/supervision-annotator-examples/label-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Transformative"

=== "Blur"

    ```python
    import supervision as sv

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

    blur_annotator = sv.BlurAnnotator()
    annotated_frame = blur_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![blur-annotator-example](https://media.roboflow.com/supervision-annotator-examples/blur-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Pixelate"

    ```python
    import supervision as sv

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

    pixelate_annotator = sv.PixelateAnnotator()
    annotated_frame = pixelate_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![pixelate-annotator-example](https://media.roboflow.com/supervision-annotator-examples/pixelate-annotator-example-10.png){ align=center width="800" }

    </div>

    <!-- === "Crop"

    ```python
    import supervision as sv

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

    crop_annotator = sv.CropAnnotator()
    annotated_frame = crop_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![crop-annotator-example](https://media.roboflow.com/supervision-annotator-examples/crop-annotator-example.png){ align=center width="800" }

    </div>

    -->

=== "Tracking & Aggregation"

=== "Trace"

    ```python
    import supervision as sv
    from ultralytics import YOLO

    model = YOLO("yolov8x.pt")

    trace_annotator = sv.TraceAnnotator()

    video_info = sv.VideoInfo.from_video_path(video_path="...")
    frames_generator = sv.get_video_frames_generator(source_path="...")
    tracker = sv.ByteTrack()

    with sv.VideoSink(target_path="...", video_info=video_info) as sink:
        for frame in frames_generator:
            result = model(frame)[0]
            detections = sv.Detections.from_ultralytics(result)
            detections = tracker.update_with_detections(detections)
            annotated_frame = trace_annotator.annotate(
                scene=frame.copy(),
                detections=detections,
            )
            sink.write_frame(frame=annotated_frame)
    ```

    <div class="result" markdown>

    ![trace-annotator-example](https://media.roboflow.com/supervision-annotator-examples/trace-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "HeatMap"

    ```python
    import supervision as sv
    from ultralytics import YOLO

    model = YOLO("yolov8x.pt")

    heat_map_annotator = sv.HeatMapAnnotator()

    video_info = sv.VideoInfo.from_video_path(video_path="...")
    frames_generator = sv.get_video_frames_generator(source_path="...")

    with sv.VideoSink(target_path="...", video_info=video_info) as sink:
        for frame in frames_generator:
            result = model(frame)[0]
            detections = sv.Detections.from_ultralytics(result)
            annotated_frame = heat_map_annotator.annotate(
                scene=frame.copy(),
                detections=detections,
            )
            sink.write_frame(frame=annotated_frame)
    ```

    <div class="result" markdown>

    ![heat-map-annotator-example](https://media.roboflow.com/supervision-annotator-examples/heat-map-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Others"

=== "PercentageBar"

    ```python
    import supervision as sv

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

    percentage_bar_annotator = sv.PercentageBarAnnotator()
    annotated_frame = percentage_bar_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![percentage-bar-annotator-example](https://media.roboflow.com/supervision-annotator-examples/percentage-bar-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Icon"

    ```python
    import supervision as sv

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

    icon_paths = ["<ICON_PATH>" for _ in detections]

    icon_annotator = sv.IconAnnotator()
    annotated_frame = icon_annotator.annotate(
        scene=image.copy(),
        detections=detections,
        icon_path=icon_paths,
    )
    ```

    <div class="result" markdown>

    ![icon-annotator-example](https://media.roboflow.com/supervision-annotator-examples/icon-annotator-example.png){ align=center width="800" }

    </div>

=== "Background Color"

    ```python
    import supervision as sv

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

    background_overlay_annotator = sv.BackgroundOverlayAnnotator()
    annotated_frame = background_overlay_annotator.annotate(
        scene=image.copy(),
        detections=detections,
    )
    ```

    <div class="result" markdown>

    ![background-overlay-annotator-example](https://media.roboflow.com/supervision-annotator-examples/background-color-annotator-example-purple.png){ align=center width="800" }

    </div>

=== "Comparison"

    ```python
    import supervision as sv

    image = ...
    detections_1 = sv.Detections(...)
    detections_2 = sv.Detections(...)

    comparison_annotator = sv.ComparisonAnnotator()
    annotated_frame = comparison_annotator.annotate(
        scene=image.copy(),
        detections_1=detections_1,
        detections_2=detections_2,
    )
    ```

    <div class="result" markdown>

    ![comparison-annotator-example](https://media.roboflow.com/supervision-annotator-examples/comparison-annotator-example.png){ align=center width="800" }

    </div>