Skip to content

Utils

draw_line

Draws a line on a given scene.

Parameters:

Name Type Description Default
scene ndarray

The scene on which the line will be drawn

required
start Point

The starting point of the line

required
end Point

The end point of the line

required
color Color

The color of the line

required
thickness int

The thickness of the line

2

Returns:

Type Description
ndarray

np.ndarray: The scene with the line drawn on it

Source code in supervision/draw/utils.py
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def draw_line(
    scene: np.ndarray, start: Point, end: Point, color: Color, thickness: int = 2
) -> np.ndarray:
    """
    Draws a line on a given scene.

    Parameters:
        scene (np.ndarray): The scene on which the line will be drawn
        start (Point): The starting point of the line
        end (Point): The end point of the line
        color (Color): The color of the line
        thickness (int): The thickness of the line

    Returns:
        np.ndarray: The scene with the line drawn on it
    """
    cv2.line(
        scene,
        start.as_xy_int_tuple(),
        end.as_xy_int_tuple(),
        color.as_bgr(),
        thickness=thickness,
    )
    return scene

draw_rectangle

Draws a rectangle on an image.

Parameters:

Name Type Description Default
scene ndarray

The scene on which the rectangle will be drawn

required
rect Rect

The rectangle to be drawn

required
color Color

The color of the rectangle

required
thickness int

The thickness of the rectangle border

2

Returns:

Type Description
ndarray

np.ndarray: The scene with the rectangle drawn on it

Source code in supervision/draw/utils.py
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def draw_rectangle(
    scene: np.ndarray, rect: Rect, color: Color, thickness: int = 2
) -> np.ndarray:
    """
    Draws a rectangle on an image.

    Parameters:
        scene (np.ndarray): The scene on which the rectangle will be drawn
        rect (Rect): The rectangle to be drawn
        color (Color): The color of the rectangle
        thickness (int): The thickness of the rectangle border

    Returns:
        np.ndarray: The scene with the rectangle drawn on it
    """
    cv2.rectangle(
        scene,
        rect.top_left.as_xy_int_tuple(),
        rect.bottom_right.as_xy_int_tuple(),
        color.as_bgr(),
        thickness=thickness,
    )
    return scene

draw_filled_rectangle

Draws a filled rectangle on an image.

Parameters:

Name Type Description Default
scene ndarray

The scene on which the rectangle will be drawn

required
rect Rect

The rectangle to be drawn

required
color Color

The color of the rectangle

required

Returns:

Type Description
ndarray

np.ndarray: The scene with the rectangle drawn on it

Source code in supervision/draw/utils.py
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def draw_filled_rectangle(scene: np.ndarray, rect: Rect, color: Color) -> np.ndarray:
    """
    Draws a filled rectangle on an image.

    Parameters:
        scene (np.ndarray): The scene on which the rectangle will be drawn
        rect (Rect): The rectangle to be drawn
        color (Color): The color of the rectangle

    Returns:
        np.ndarray: The scene with the rectangle drawn on it
    """
    cv2.rectangle(
        scene,
        rect.top_left.as_xy_int_tuple(),
        rect.bottom_right.as_xy_int_tuple(),
        color.as_bgr(),
        -1,
    )
    return scene

draw_polygon

Draw a polygon on a scene.

Parameters:

Name Type Description Default
scene ndarray

The scene to draw the polygon on.

required
polygon ndarray

The polygon to be drawn, given as a list of vertices.

required
color Color

The color of the polygon.

required
thickness int

The thickness of the polygon lines, by default 2.

2

Returns:

Type Description
ndarray

np.ndarray: The scene with the polygon drawn on it.

Source code in supervision/draw/utils.py
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
def draw_polygon(
    scene: np.ndarray, polygon: np.ndarray, color: Color, thickness: int = 2
) -> np.ndarray:
    """Draw a polygon on a scene.

    Parameters:
        scene (np.ndarray): The scene to draw the polygon on.
        polygon (np.ndarray): The polygon to be drawn, given as a list of vertices.
        color (Color): The color of the polygon.
        thickness (int, optional): The thickness of the polygon lines, by default 2.

    Returns:
        np.ndarray: The scene with the polygon drawn on it.
    """
    cv2.polylines(
        scene, [polygon], isClosed=True, color=color.as_bgr(), thickness=thickness
    )
    return scene

draw_text

Draw text with background on a scene.

Parameters:

Name Type Description Default
scene ndarray

A 2-dimensional numpy ndarray representing an image or scene

required
text str

The text to be drawn.

required
text_anchor Point

The anchor point for the text, represented as a Point object with x and y attributes.

required
text_color Color

The color of the text. Defaults to black.

black()
text_scale float

The scale of the text. Defaults to 0.5.

0.5
text_thickness int

The thickness of the text. Defaults to 1.

1
text_padding int

The amount of padding to add around the text when drawing a rectangle in the background. Defaults to 10.

10
text_font int

The font to use for the text. Defaults to cv2.FONT_HERSHEY_SIMPLEX.

FONT_HERSHEY_SIMPLEX
background_color Color

The color of the background rectangle, if one is to be drawn. Defaults to None.

None

Returns:

Type Description
ndarray

np.ndarray: The input scene with the text drawn on it.

Examples:

>>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
>>> text_anchor = Point(x=50, y=50)
>>> scene = draw_text(scene=scene, text="Hello, world!",text_anchor=text_anchor)
Source code in supervision/draw/utils.py
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def draw_text(
    scene: np.ndarray,
    text: str,
    text_anchor: Point,
    text_color: Color = Color.black(),
    text_scale: float = 0.5,
    text_thickness: int = 1,
    text_padding: int = 10,
    text_font: int = cv2.FONT_HERSHEY_SIMPLEX,
    background_color: Optional[Color] = None,
) -> np.ndarray:
    """
    Draw text with background on a scene.

    Parameters:
        scene (np.ndarray): A 2-dimensional numpy ndarray representing an image or scene
        text (str): The text to be drawn.
        text_anchor (Point): The anchor point for the text, represented as a
            Point object with x and y attributes.
        text_color (Color, optional): The color of the text. Defaults to black.
        text_scale (float, optional): The scale of the text. Defaults to 0.5.
        text_thickness (int, optional): The thickness of the text. Defaults to 1.
        text_padding (int, optional): The amount of padding to add around the text
            when drawing a rectangle in the background. Defaults to 10.
        text_font (int, optional): The font to use for the text.
            Defaults to cv2.FONT_HERSHEY_SIMPLEX.
        background_color (Color, optional): The color of the background rectangle,
            if one is to be drawn. Defaults to None.

    Returns:
        np.ndarray: The input scene with the text drawn on it.

    Examples:
        ```python
        >>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
        >>> text_anchor = Point(x=50, y=50)
        >>> scene = draw_text(scene=scene, text="Hello, world!",text_anchor=text_anchor)
        ```
    """
    text_width, text_height = cv2.getTextSize(
        text=text,
        fontFace=text_font,
        fontScale=text_scale,
        thickness=text_thickness,
    )[0]
    text_rect = Rect(
        x=text_anchor.x - text_width // 2,
        y=text_anchor.y - text_height // 2,
        width=text_width,
        height=text_height,
    ).pad(text_padding)

    if background_color is not None:
        scene = draw_filled_rectangle(
            scene=scene, rect=text_rect, color=background_color
        )

    cv2.putText(
        img=scene,
        text=text,
        org=(text_anchor.x - text_width // 2, text_anchor.y + text_height // 2),
        fontFace=text_font,
        fontScale=text_scale,
        color=text_color.as_bgr(),
        thickness=text_thickness,
        lineType=cv2.LINE_AA,
    )
    return scene

draw_image

Draws an image onto a given scene with specified opacity and dimensions.

Parameters:

Name Type Description Default
scene ndarray

Background image where the new image will be drawn.

required
image Union[str, ndarray]

Image to draw.

required
opacity float

Opacity of the image to be drawn.

required
rect Rect

Rectangle specifying where to draw the image.

required

Returns:

Type Description
ndarray

np.ndarray: The updated scene.

Raises:

Type Description
FileNotFoundError

If the image path does not exist.

ValueError

For invalid opacity or rectangle dimensions.

Source code in supervision/draw/utils.py
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def draw_image(
    scene: np.ndarray, image: Union[str, np.ndarray], opacity: float, rect: Rect
) -> np.ndarray:
    """
    Draws an image onto a given scene with specified opacity and dimensions.

    Args:
        scene (np.ndarray): Background image where the new image will be drawn.
        image (Union[str, np.ndarray]): Image to draw.
        opacity (float): Opacity of the image to be drawn.
        rect (Rect): Rectangle specifying where to draw the image.

    Returns:
        np.ndarray: The updated scene.

    Raises:
        FileNotFoundError: If the image path does not exist.
        ValueError: For invalid opacity or rectangle dimensions.
    """

    # Validate and load image
    if isinstance(image, str):
        if not os.path.exists(image):
            raise FileNotFoundError(f"Image path ('{image}') does not exist.")
        image = cv2.imread(image, cv2.IMREAD_UNCHANGED)

    # Validate opacity
    if not 0.0 <= opacity <= 1.0:
        raise ValueError("Opacity must be between 0.0 and 1.0.")

    # Validate rectangle dimensions
    if (
        rect.x < 0
        or rect.y < 0
        or rect.x + rect.width > scene.shape[1]
        or rect.y + rect.height > scene.shape[0]
    ):
        raise ValueError("Invalid rectangle dimensions.")

    # Resize and isolate alpha channel
    image = cv2.resize(image, (rect.width, rect.height))
    alpha_channel = (
        image[:, :, 3]
        if image.shape[2] == 4
        else np.ones((rect.height, rect.width), dtype=image.dtype) * 255
    )
    alpha_scaled = cv2.convertScaleAbs(alpha_channel * opacity)

    # Perform blending
    scene_roi = scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width]
    alpha_float = alpha_scaled.astype(np.float32) / 255.0
    blended_roi = cv2.convertScaleAbs(
        (1 - alpha_float[..., np.newaxis]) * scene_roi
        + alpha_float[..., np.newaxis] * image[:, :, :3]
    )

    # Update the scene
    scene[rect.y : rect.y + rect.height, rect.x : rect.x + rect.width] = blended_roi

    return scene

calculate_dynamic_font_scale

Calculate a dynamic font scale based on the resolution of an image.

Parameters:

Name Type Description Default
resolution_wh Tuple[int, int]

A tuple representing the width and height of the image.

required

Returns:

Name Type Description
float float

The calculated font scale factor.

Source code in supervision/draw/utils.py
236
237
238
239
240
241
242
243
244
245
246
247
def calculate_dynamic_text_scale(resolution_wh: Tuple[int, int]) -> float:
    """
    Calculate a dynamic font scale based on the resolution of an image.

    Parameters:
         resolution_wh (Tuple[int, int]): A tuple representing the width and height
                 of the image.

    Returns:
         float: The calculated font scale factor.
    """
    return min(resolution_wh) * 1e-3

calculate_dynamic_line_thickness

Calculate a dynamic line thickness based on the resolution of an image.

Parameters:

Name Type Description Default
resolution_wh Tuple[int, int]

A tuple representing the width and height of the image.

required

Returns:

Name Type Description
int int

The calculated line thickness in pixels.

Source code in supervision/draw/utils.py
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
def calculate_dynamic_line_thickness(resolution_wh: Tuple[int, int]) -> int:
    """
    Calculate a dynamic line thickness based on the resolution of an image.

    Parameters:
        resolution_wh (Tuple[int, int]): A tuple representing the width and height
                of the image.

    Returns:
        int: The calculated line thickness in pixels.
    """
    min_dimension = min(resolution_wh)
    if min_dimension < 480:
        return 2
    if min_dimension < 720:
        return 2
    if min_dimension < 1080:
        return 2
    if min_dimension < 2160:
        return 4
    else:
        return 4