19 KiB

Raw Blame History

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>