Annotate

BoxAnnotator

A class for drawing bounding boxes on an image using detections provided.

Attributes:

Name	Type	Description
color	Union[Color, ColorPalette]	The color to draw the bounding box, can be a single color or a color palette
thickness	int	The thickness of the bounding box lines, default is 2
text_color	Color	The color of the text on the bounding box, default is white
text_scale	float	The scale of the text on the bounding box, default is 0.5
text_thickness	int	The thickness of the text on the bounding box, default is 1
text_padding	int	The padding around the text on the bounding box, default is 5

Source code in supervision/detection/annotate.py

class BoxAnnotator:
    """
    A class for drawing bounding boxes on an image using detections provided.

    Attributes:
        color (Union[Color, ColorPalette]): The color to draw the bounding box,
            can be a single color or a color palette
        thickness (int): The thickness of the bounding box lines, default is 2
        text_color (Color): The color of the text on the bounding box, default is white
        text_scale (float): The scale of the text on the bounding box, default is 0.5
        text_thickness (int): The thickness of the text on the bounding box,
            default is 1
        text_padding (int): The padding around the text on the bounding box,
            default is 5

    """

    def __init__(
        self,
        color: Union[Color, ColorPalette] = ColorPalette.default(),
        thickness: int = 2,
        text_color: Color = Color.black(),
        text_scale: float = 0.5,
        text_thickness: int = 1,
        text_padding: int = 10,
    ):
        self.color: Union[Color, ColorPalette] = color
        self.thickness: int = thickness
        self.text_color: Color = text_color
        self.text_scale: float = text_scale
        self.text_thickness: int = text_thickness
        self.text_padding: int = text_padding

    def annotate(
        self,
        scene: np.ndarray,
        detections: Detections,
        labels: Optional[List[str]] = None,
        skip_label: bool = False,
    ) -> np.ndarray:
        """
        Draws bounding boxes on the frame using the detections provided.

        Args:
            scene (np.ndarray): The image on which the bounding boxes will be drawn
            detections (Detections): The detections for which the
                bounding boxes will be drawn
            labels (Optional[List[str]]): An optional list of labels
                corresponding to each detection. If `labels` are not provided,
                corresponding `class_id` will be used as label.
            skip_label (bool): Is set to `True`, skips bounding box label annotation.
        Returns:
            np.ndarray: The image with the bounding boxes drawn on it

        Example:
            ```python
            >>> import supervision as sv

            >>> classes = ['person', ...]
            >>> image = ...
            >>> detections = sv.Detections(...)

            >>> box_annotator = sv.BoxAnnotator()
            >>> labels = [
            ...     f"{classes[class_id]} {confidence:0.2f}"
            ...     for _, _, confidence, class_id, _
            ...     in detections
            ... ]
            >>> annotated_frame = box_annotator.annotate(
            ...     scene=image.copy(),
            ...     detections=detections,
            ...     labels=labels
            ... )
            ```
        """
        font = cv2.FONT_HERSHEY_SIMPLEX
        for i in range(len(detections)):
            x1, y1, x2, y2 = detections.xyxy[i].astype(int)
            class_id = (
                detections.class_id[i] if detections.class_id is not None else None
            )
            idx = class_id if class_id is not None else i
            color = (
                self.color.by_idx(idx)
                if isinstance(self.color, ColorPalette)
                else self.color
            )
            cv2.rectangle(
                img=scene,
                pt1=(x1, y1),
                pt2=(x2, y2),
                color=color.as_bgr(),
                thickness=self.thickness,
            )
            if skip_label:
                continue

            text = (
                f"{class_id}"
                if (labels is None or len(detections) != len(labels))
                else labels[i]
            )

            text_width, text_height = cv2.getTextSize(
                text=text,
                fontFace=font,
                fontScale=self.text_scale,
                thickness=self.text_thickness,
            )[0]

            text_x = x1 + self.text_padding
            text_y = y1 - self.text_padding

            text_background_x1 = x1
            text_background_y1 = y1 - 2 * self.text_padding - text_height

            text_background_x2 = x1 + 2 * self.text_padding + text_width
            text_background_y2 = y1

            cv2.rectangle(
                img=scene,
                pt1=(text_background_x1, text_background_y1),
                pt2=(text_background_x2, text_background_y2),
                color=color.as_bgr(),
                thickness=cv2.FILLED,
            )
            cv2.putText(
                img=scene,
                text=text,
                org=(text_x, text_y),
                fontFace=font,
                fontScale=self.text_scale,
                color=self.text_color.as_rgb(),
                thickness=self.text_thickness,
                lineType=cv2.LINE_AA,
            )
        return scene

annotate(scene, detections, labels=None, skip_label=False)

Draws bounding boxes on the frame using the detections provided.

Parameters:

Name	Type	Description	Default
scene	ndarray	The image on which the bounding boxes will be drawn	required
detections	Detections	The detections for which the bounding boxes will be drawn	required
labels	Optional[List[str]]	An optional list of labels corresponding to each detection. If labels are not provided, corresponding class_id will be used as label.	None
skip_label	bool	Is set to True, skips bounding box label annotation.	False

Returns: np.ndarray: The image with the bounding boxes drawn on it

Example

>>> import supervision as sv

>>> classes = ['person', ...]
>>> image = ...
>>> detections = sv.Detections(...)

>>> box_annotator = sv.BoxAnnotator()
>>> labels = [
...     f"{classes[class_id]} {confidence:0.2f}"
...     for _, _, confidence, class_id, _
...     in detections
... ]
>>> annotated_frame = box_annotator.annotate(
...     scene=image.copy(),
...     detections=detections,
...     labels=labels
... )

Source code in supervision/detection/annotate.py

def annotate(
    self,
    scene: np.ndarray,
    detections: Detections,
    labels: Optional[List[str]] = None,
    skip_label: bool = False,
) -> np.ndarray:
    """
    Draws bounding boxes on the frame using the detections provided.

    Args:
        scene (np.ndarray): The image on which the bounding boxes will be drawn
        detections (Detections): The detections for which the
            bounding boxes will be drawn
        labels (Optional[List[str]]): An optional list of labels
            corresponding to each detection. If `labels` are not provided,
            corresponding `class_id` will be used as label.
        skip_label (bool): Is set to `True`, skips bounding box label annotation.
    Returns:
        np.ndarray: The image with the bounding boxes drawn on it

    Example:
        ```python
        >>> import supervision as sv

        >>> classes = ['person', ...]
        >>> image = ...
        >>> detections = sv.Detections(...)

        >>> box_annotator = sv.BoxAnnotator()
        >>> labels = [
        ...     f"{classes[class_id]} {confidence:0.2f}"
        ...     for _, _, confidence, class_id, _
        ...     in detections
        ... ]
        >>> annotated_frame = box_annotator.annotate(
        ...     scene=image.copy(),
        ...     detections=detections,
        ...     labels=labels
        ... )
        ```
    """
    font = cv2.FONT_HERSHEY_SIMPLEX
    for i in range(len(detections)):
        x1, y1, x2, y2 = detections.xyxy[i].astype(int)
        class_id = (
            detections.class_id[i] if detections.class_id is not None else None
        )
        idx = class_id if class_id is not None else i
        color = (
            self.color.by_idx(idx)
            if isinstance(self.color, ColorPalette)
            else self.color
        )
        cv2.rectangle(
            img=scene,
            pt1=(x1, y1),
            pt2=(x2, y2),
            color=color.as_bgr(),
            thickness=self.thickness,
        )
        if skip_label:
            continue

        text = (
            f"{class_id}"
            if (labels is None or len(detections) != len(labels))
            else labels[i]
        )

        text_width, text_height = cv2.getTextSize(
            text=text,
            fontFace=font,
            fontScale=self.text_scale,
            thickness=self.text_thickness,
        )[0]

        text_x = x1 + self.text_padding
        text_y = y1 - self.text_padding

        text_background_x1 = x1
        text_background_y1 = y1 - 2 * self.text_padding - text_height

        text_background_x2 = x1 + 2 * self.text_padding + text_width
        text_background_y2 = y1

        cv2.rectangle(
            img=scene,
            pt1=(text_background_x1, text_background_y1),
            pt2=(text_background_x2, text_background_y2),
            color=color.as_bgr(),
            thickness=cv2.FILLED,
        )
        cv2.putText(
            img=scene,
            text=text,
            org=(text_x, text_y),
            fontFace=font,
            fontScale=self.text_scale,
            color=self.text_color.as_rgb(),
            thickness=self.text_thickness,
            lineType=cv2.LINE_AA,
        )
    return scene

MaskAnnotator

A class for overlaying masks on an image using detections provided.

Attributes:

Name	Type	Description
color	Union[Color, ColorPalette]	The color to fill the mask, can be a single color or a color palette

Source code in supervision/detection/annotate.py

class MaskAnnotator:
    """
    A class for overlaying masks on an image using detections provided.

    Attributes:
        color (Union[Color, ColorPalette]): The color to fill the mask,
            can be a single color or a color palette
    """

    def __init__(
        self,
        color: Union[Color, ColorPalette] = ColorPalette.default(),
    ):
        self.color: Union[Color, ColorPalette] = color

    def annotate(
        self, scene: np.ndarray, detections: Detections, opacity: float = 0.5
    ) -> np.ndarray:
        """
        Overlays the masks on the given image based on the provided detections,
            with a specified opacity.

        Args:
            scene (np.ndarray): The image on which the masks will be overlaid
            detections (Detections): The detections for which the
                masks will be overlaid
            opacity (float): The opacity of the masks, between 0 and 1, default is 0.5

        Returns:
            np.ndarray: The image with the masks overlaid
        """
        if detections.mask is None:
            return scene

        for i in np.flip(np.argsort(detections.area)):
            class_id = (
                detections.class_id[i] if detections.class_id is not None else None
            )
            idx = class_id if class_id is not None else i
            color = (
                self.color.by_idx(idx)
                if isinstance(self.color, ColorPalette)
                else self.color
            )

            mask = detections.mask[i]
            colored_mask = np.zeros_like(scene, dtype=np.uint8)
            colored_mask[:] = color.as_bgr()

            scene = np.where(
                np.expand_dims(mask, axis=-1),
                np.uint8(opacity * colored_mask + (1 - opacity) * scene),
                scene,
            )

        return scene

annotate(scene, detections, opacity=0.5)

Overlays the masks on the given image based on the provided detections, with a specified opacity.

Parameters:

Name	Type	Description	Default
scene	ndarray	The image on which the masks will be overlaid	required
detections	Detections	The detections for which the masks will be overlaid	required
opacity	float	The opacity of the masks, between 0 and 1, default is 0.5	0.5

Returns:

Type	Description
ndarray	np.ndarray: The image with the masks overlaid

Source code in supervision/detection/annotate.py

def annotate(
    self, scene: np.ndarray, detections: Detections, opacity: float = 0.5
) -> np.ndarray:
    """
    Overlays the masks on the given image based on the provided detections,
        with a specified opacity.

    Args:
        scene (np.ndarray): The image on which the masks will be overlaid
        detections (Detections): The detections for which the
            masks will be overlaid
        opacity (float): The opacity of the masks, between 0 and 1, default is 0.5

    Returns:
        np.ndarray: The image with the masks overlaid
    """
    if detections.mask is None:
        return scene

    for i in np.flip(np.argsort(detections.area)):
        class_id = (
            detections.class_id[i] if detections.class_id is not None else None
        )
        idx = class_id if class_id is not None else i
        color = (
            self.color.by_idx(idx)
            if isinstance(self.color, ColorPalette)
            else self.color
        )

        mask = detections.mask[i]
        colored_mask = np.zeros_like(scene, dtype=np.uint8)
        colored_mask[:] = color.as_bgr()

        scene = np.where(
            np.expand_dims(mask, axis=-1),
            np.uint8(opacity * colored_mask + (1 - opacity) * scene),
            scene,
        )

    return scene

TraceAnnotator

A class for drawing trace paths on an image based on detection coordinates.

Attributes:

Name	Type	Description
color	Union[Color, ColorPalette]	The color to draw the trace, can be a single color or a color palette.
position	Optional[Position]	The position of the trace. Defaults to CENTER.
trace_length	int	The maximum length of the trace in terms of historical points. Defaults to 30.
thickness	int	The thickness of the trace lines. Defaults to 2.

Source code in supervision/detection/annotate.py

class TraceAnnotator:
    """
    A class for drawing trace paths on an image based on detection coordinates.

    Attributes:
        color (Union[Color, ColorPalette]): The color to draw the trace, can be
            a single color or a color palette.
        position (Optional[Position]): The position of the trace. Defaults to `CENTER`.
        trace_length (int): The maximum length of the trace in terms of historical
            points. Defaults to `30`.
        thickness (int): The thickness of the trace lines. Defaults to `2`.

    """

    def __init__(
        self,
        color: Union[Color, ColorPalette] = ColorPalette.default(),
        position: Optional[Position] = Position.CENTER,
        trace_length: int = 30,
        thickness: int = 2,
    ):
        self.color: Union[Color, ColorPalette] = color
        self.position = position
        self.trace = Trace(max_size=trace_length)
        self.thickness = thickness

    def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
        """
        Draws trace paths on the frame based on the detection coordinates provided.

        Args:
            scene (np.ndarray): The image on which the traces will be drawn.
            detections (Detections): The detections which include coordinates for
                which the traces will be drawn.

        Returns:
            np.ndarray: The image with the trace paths drawn on it.

        Example:
            ```python
            >>> import supervision as sv

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

            >>> trace_annotator = sv.TraceAnnotator()
            >>> annotated_frame = trace_annotator.annotate(
            ...     scene=image.copy(),
            ...     detections=detections
            ... )
            ```
        """
        self.trace.put(detections)

        for i, (xyxy, mask, confidence, class_id, tracker_id) in enumerate(detections):
            class_id = detections.class_id[i] if class_id is not None else None
            idx = class_id if class_id is not None else i
            color = (
                self.color.by_idx(idx)
                if isinstance(self.color, ColorPalette)
                else self.color
            )

            xy = self.trace.get(tracker_id=tracker_id)
            if len(xy) > 1:
                scene = cv2.polylines(
                    scene,
                    [xy.astype(np.int32)],
                    False,
                    color=color.as_bgr(),
                    thickness=self.thickness,
                )
        return scene

annotate(scene, detections)

Draws trace paths on the frame based on the detection coordinates provided.

Parameters:

Name	Type	Description	Default
scene	ndarray	The image on which the traces will be drawn.	required
detections	Detections	The detections which include coordinates for which the traces will be drawn.	required

Returns:

Type	Description
ndarray	np.ndarray: The image with the trace paths drawn on it.

Example

>>> import supervision as sv

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

>>> trace_annotator = sv.TraceAnnotator()
>>> annotated_frame = trace_annotator.annotate(
...     scene=image.copy(),
...     detections=detections
... )

Source code in supervision/detection/annotate.py

def annotate(self, scene: np.ndarray, detections: Detections) -> np.ndarray:
    """
    Draws trace paths on the frame based on the detection coordinates provided.

    Args:
        scene (np.ndarray): The image on which the traces will be drawn.
        detections (Detections): The detections which include coordinates for
            which the traces will be drawn.

    Returns:
        np.ndarray: The image with the trace paths drawn on it.

    Example:
        ```python
        >>> import supervision as sv

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

        >>> trace_annotator = sv.TraceAnnotator()
        >>> annotated_frame = trace_annotator.annotate(
        ...     scene=image.copy(),
        ...     detections=detections
        ... )
        ```
    """
    self.trace.put(detections)

    for i, (xyxy, mask, confidence, class_id, tracker_id) in enumerate(detections):
        class_id = detections.class_id[i] if class_id is not None else None
        idx = class_id if class_id is not None else i
        color = (
            self.color.by_idx(idx)
            if isinstance(self.color, ColorPalette)
            else self.color
        )

        xy = self.trace.get(tracker_id=tracker_id)
        if len(xy) > 1:
            scene = cv2.polylines(
                scene,
                [xy.astype(np.int32)],
                False,
                color=color.as_bgr(),
                thickness=self.thickness,
            )
    return scene