Draw 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, defaults to Color.ROBOFLOW	ROBOFLOW
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

def draw_line(
    scene: np.ndarray,
    start: Point,
    end: Point,
    color: Color = Color.ROBOFLOW,
    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, defaults to Color.ROBOFLOW
        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	ROBOFLOW
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

def draw_rectangle(
    scene: np.ndarray, rect: Rect, color: Color = Color.ROBOFLOW, 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	ROBOFLOW
opacity	float	The opacity of rectangle when drawn on the scene.	1

Returns:

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

Source code in supervision/draw/utils.py

def draw_filled_rectangle(
    scene: np.ndarray, rect: Rect, color: Color = Color.ROBOFLOW, opacity: float = 1
) -> 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
        opacity (float): The opacity of rectangle when drawn on the scene.

    Returns:
        np.ndarray: The scene with the rectangle drawn on it
    """
    if opacity == 1:
        cv2.rectangle(
            scene,
            rect.top_left.as_xy_int_tuple(),
            rect.bottom_right.as_xy_int_tuple(),
            color.as_bgr(),
            -1,
        )
    else:
        scene_with_annotations = scene.copy()
        cv2.rectangle(
            scene_with_annotations,
            rect.top_left.as_xy_int_tuple(),
            rect.bottom_right.as_xy_int_tuple(),
            color.as_bgr(),
            -1,
        )
        cv2.addWeighted(
            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
        )

    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. Defaults to Color.ROBOFLOW.	ROBOFLOW
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

def draw_polygon(
    scene: np.ndarray,
    polygon: np.ndarray,
    color: Color = Color.ROBOFLOW,
    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. Defaults to Color.ROBOFLOW.
        thickness (int): 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_filled_polygon

Draw a filled 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. Defaults to Color.ROBOFLOW.	ROBOFLOW
opacity	float	The opacity of polygon when drawn on the scene.	1

Returns:

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

Source code in supervision/draw/utils.py

def draw_filled_polygon(
    scene: np.ndarray,
    polygon: np.ndarray,
    color: Color = Color.ROBOFLOW,
    opacity: float = 1,
) -> np.ndarray:
    """Draw a filled 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. Defaults to Color.ROBOFLOW.
        opacity (float): The opacity of polygon when drawn on the scene.

    Returns:
        np.ndarray: The scene with the polygon drawn on it.
    """
    if opacity == 1:
        cv2.fillPoly(scene, [polygon], color=color.as_bgr())
    else:
        scene_with_annotations = scene.copy()
        cv2.fillPoly(scene_with_annotations, [polygon], color=color.as_bgr())
        cv2.addWeighted(
            scene_with_annotations, opacity, scene, 1 - opacity, gamma=0, dst=scene
        )

    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	Optional[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:

import numpy as np

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

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): The color of the text. Defaults to black.
        text_scale (float): The scale of the text. Defaults to 0.5.
        text_thickness (int): The thickness of the text. Defaults to 1.
        text_padding (int): The amount of padding to add around the text
            when drawing a rectangle in the background. Defaults to 10.
        text_font (int): The font to use for the text.
            Defaults to cv2.FONT_HERSHEY_SIMPLEX.
        background_color (Optional[Color]): 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
        import numpy as np

        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_anchor_x, text_anchor_y = text_anchor.as_xy_int_tuple()

    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

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_optimal_text_scale

Calculate 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

def calculate_optimal_text_scale(resolution_wh: Tuple[int, int]) -> float:
    """
    Calculate 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_optimal_line_thickness

Calculate 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

def calculate_optimal_line_thickness(resolution_wh: Tuple[int, int]) -> int:
    """
    Calculate 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.
    """
    if min(resolution_wh) < 1080:
        return 2
    return 4

Color

Represents a color in RGB format.

This class provides methods to work with colors, including creating colors from hex codes, converting colors to hex strings, RGB tuples, and BGR tuples.

Attributes:

Name	Type	Description
r	int	Red channel value (0-255).
g	int	Green channel value (0-255).
b	int	Blue channel value (0-255).

Example

import supervision as sv

sv.Color.WHITE
# Color(r=255, g=255, b=255)

Constant	Hex Code	RGB
WHITE	#FFFFFF	(255, 255, 255)
BLACK	#000000	(0, 0, 0)
RED	#FF0000	(255, 0, 0)
GREEN	#00FF00	(0, 255, 0)
BLUE	#0000FF	(0, 0, 255)
YELLOW	#FFFF00	(255, 255, 0)
ROBOFLOW	#A351FB	(163, 81, 251)

Source code in supervision/draw/color.py

@dataclass
class Color:
    """
    Represents a color in RGB format.

    This class provides methods to work with colors, including creating colors from hex
    codes, converting colors to hex strings, RGB tuples, and BGR tuples.

    Attributes:
        r (int): Red channel value (0-255).
        g (int): Green channel value (0-255).
        b (int): Blue channel value (0-255).

    Example:
        ```python
        import supervision as sv

        sv.Color.WHITE
        # Color(r=255, g=255, b=255)
        ```

    | Constant   | Hex Code   | RGB              |
    |------------|------------|------------------|
    | `WHITE`    | `#FFFFFF`  | `(255, 255, 255)`|
    | `BLACK`    | `#000000`  | `(0, 0, 0)`      |
    | `RED`      | `#FF0000`  | `(255, 0, 0)`    |
    | `GREEN`    | `#00FF00`  | `(0, 255, 0)`    |
    | `BLUE`     | `#0000FF`  | `(0, 0, 255)`    |
    | `YELLOW`   | `#FFFF00`  | `(255, 255, 0)`  |
    | `ROBOFLOW` | `#A351FB`  | `(163, 81, 251)` |
    """

    r: int
    g: int
    b: int

    @classmethod
    def from_hex(cls, color_hex: str) -> Color:
        """
        Create a Color instance from a hex string.

        Args:
            color_hex (str): The hex string representing the color. This string can
                start with '#' followed by either 3 or 6 hexadecimal characters. In
                case of 3 characters, each character is repeated to form the full
                6-character hex code.

        Returns:
            Color: An instance representing the color.

        Example:
            ```python
            import supervision as sv

            sv.Color.from_hex('#ff00ff')
            # Color(r=255, g=0, b=255)

            sv.Color.from_hex('#f0f')
            # Color(r=255, g=0, b=255)
            ```
        """
        _validate_color_hex(color_hex)
        color_hex = color_hex.lstrip("#")
        if len(color_hex) == 3:
            color_hex = "".join(c * 2 for c in color_hex)
        r, g, b = (int(color_hex[i : i + 2], 16) for i in range(0, 6, 2))
        return cls(r, g, b)

    @classmethod
    def from_rgb_tuple(cls, color_tuple: Tuple[int, int, int]) -> Color:
        """
        Create a Color instance from an RGB tuple.

        Args:
            color_tuple (Tuple[int, int, int]): A tuple representing the color in RGB
                format, where each element is an integer in the range 0-255.

        Returns:
            Color: An instance representing the color.

        Example:
            ```python
            import supervision as sv

            sv.Color.from_rgb_tuple((255, 255, 0))
            # Color(r=255, g=255, b=0)
            ```
        """
        r, g, b = color_tuple
        return cls(r=r, g=g, b=b)

    @classmethod
    def from_bgr_tuple(cls, color_tuple: Tuple[int, int, int]) -> Color:
        """
        Create a Color instance from a BGR tuple.

        Args:
            color_tuple (Tuple[int, int, int]): A tuple representing the color in BGR
                format, where each element is an integer in the range 0-255.

        Returns:
            Color: An instance representing the color.

        Example:
            ```python
            import supervision as sv

            sv.Color.from_bgr_tuple((0, 255, 255))
            # Color(r=255, g=255, b=0)
            ```
        """
        b, g, r = color_tuple
        return cls(r=r, g=g, b=b)

    def as_hex(self) -> str:
        """
        Converts the Color instance to a hex string.

        Returns:
            str: The hexadecimal color string.

        Example:
            ```python
            import supervision as sv

            sv.Color(r=255, g=255, b=0).as_hex()
            # '#ffff00'
            ```
        """
        return f"#{self.r:02x}{self.g:02x}{self.b:02x}"

    def as_rgb(self) -> Tuple[int, int, int]:
        """
        Returns the color as an RGB tuple.

        Returns:
            Tuple[int, int, int]: RGB tuple.

        Example:
            ```python
            import supervision as sv

            sv.Color(r=255, g=255, b=0).as_rgb()
            # (255, 255, 0)
            ```
        """
        return self.r, self.g, self.b

    def as_bgr(self) -> Tuple[int, int, int]:
        """
        Returns the color as a BGR tuple.

        Returns:
            Tuple[int, int, int]: BGR tuple.

        Example:
            ```python
            import supervision as sv

            sv.Color(r=255, g=255, b=0).as_bgr()
            # (0, 255, 255)
            ```
        """
        return self.b, self.g, self.r

    @classproperty
    def WHITE(cls) -> Color:
        return Color.from_hex("#FFFFFF")

    @classproperty
    def BLACK(cls) -> Color:
        return Color.from_hex("#000000")

    @classproperty
    def RED(cls) -> Color:
        return Color.from_hex("#FF0000")

    @classproperty
    def GREEN(cls) -> Color:
        return Color.from_hex("#00FF00")

    @classproperty
    def BLUE(cls) -> Color:
        return Color.from_hex("#0000FF")

    @classproperty
    def YELLOW(cls) -> Color:
        return Color.from_hex("#FFFF00")

    @classproperty
    def ROBOFLOW(cls) -> Color:
        return Color.from_hex("#A351FB")

    def __hash__(self):
        return hash((self.r, self.g, self.b))

    def __eq__(self, other):
        return (
            isinstance(other, Color)
            and self.r == other.r
            and self.g == other.g
            and self.b == other.b
        )

Functions

as_bgr()

Returns the color as a BGR tuple.

Returns:

Type	Description
Tuple[int, int, int]	Tuple[int, int, int]: BGR tuple.

Example

import supervision as sv

sv.Color(r=255, g=255, b=0).as_bgr()
# (0, 255, 255)

Source code in supervision/draw/color.py

def as_bgr(self) -> Tuple[int, int, int]:
    """
    Returns the color as a BGR tuple.

    Returns:
        Tuple[int, int, int]: BGR tuple.

    Example:
        ```python
        import supervision as sv

        sv.Color(r=255, g=255, b=0).as_bgr()
        # (0, 255, 255)
        ```
    """
    return self.b, self.g, self.r

as_hex()

Converts the Color instance to a hex string.

Returns:

Name	Type	Description
str	str	The hexadecimal color string.

Example

import supervision as sv

sv.Color(r=255, g=255, b=0).as_hex()
# '#ffff00'

Source code in supervision/draw/color.py

def as_hex(self) -> str:
    """
    Converts the Color instance to a hex string.

    Returns:
        str: The hexadecimal color string.

    Example:
        ```python
        import supervision as sv

        sv.Color(r=255, g=255, b=0).as_hex()
        # '#ffff00'
        ```
    """
    return f"#{self.r:02x}{self.g:02x}{self.b:02x}"

as_rgb()

Returns the color as an RGB tuple.

Returns:

Type	Description
Tuple[int, int, int]	Tuple[int, int, int]: RGB tuple.

Example

import supervision as sv

sv.Color(r=255, g=255, b=0).as_rgb()
# (255, 255, 0)

Source code in supervision/draw/color.py

def as_rgb(self) -> Tuple[int, int, int]:
    """
    Returns the color as an RGB tuple.

    Returns:
        Tuple[int, int, int]: RGB tuple.

    Example:
        ```python
        import supervision as sv

        sv.Color(r=255, g=255, b=0).as_rgb()
        # (255, 255, 0)
        ```
    """
    return self.r, self.g, self.b

from_bgr_tuple(color_tuple) classmethod

Create a Color instance from a BGR tuple.

Parameters:

Name	Type	Description	Default
color_tuple	Tuple[int, int, int]	A tuple representing the color in BGR format, where each element is an integer in the range 0-255.	required

Returns:

Name	Type	Description
Color	Color	An instance representing the color.

Example

import supervision as sv

sv.Color.from_bgr_tuple((0, 255, 255))
# Color(r=255, g=255, b=0)

Source code in supervision/draw/color.py

@classmethod
def from_bgr_tuple(cls, color_tuple: Tuple[int, int, int]) -> Color:
    """
    Create a Color instance from a BGR tuple.

    Args:
        color_tuple (Tuple[int, int, int]): A tuple representing the color in BGR
            format, where each element is an integer in the range 0-255.

    Returns:
        Color: An instance representing the color.

    Example:
        ```python
        import supervision as sv

        sv.Color.from_bgr_tuple((0, 255, 255))
        # Color(r=255, g=255, b=0)
        ```
    """
    b, g, r = color_tuple
    return cls(r=r, g=g, b=b)

from_hex(color_hex) classmethod

Create a Color instance from a hex string.

Parameters:

Name	Type	Description	Default
color_hex	str	The hex string representing the color. This string can start with '#' followed by either 3 or 6 hexadecimal characters. In case of 3 characters, each character is repeated to form the full 6-character hex code.	required

Returns:

Name	Type	Description
Color	Color	An instance representing the color.

Example

import supervision as sv

sv.Color.from_hex('#ff00ff')
# Color(r=255, g=0, b=255)

sv.Color.from_hex('#f0f')
# Color(r=255, g=0, b=255)

Source code in supervision/draw/color.py

@classmethod
def from_hex(cls, color_hex: str) -> Color:
    """
    Create a Color instance from a hex string.

    Args:
        color_hex (str): The hex string representing the color. This string can
            start with '#' followed by either 3 or 6 hexadecimal characters. In
            case of 3 characters, each character is repeated to form the full
            6-character hex code.

    Returns:
        Color: An instance representing the color.

    Example:
        ```python
        import supervision as sv

        sv.Color.from_hex('#ff00ff')
        # Color(r=255, g=0, b=255)

        sv.Color.from_hex('#f0f')
        # Color(r=255, g=0, b=255)
        ```
    """
    _validate_color_hex(color_hex)
    color_hex = color_hex.lstrip("#")
    if len(color_hex) == 3:
        color_hex = "".join(c * 2 for c in color_hex)
    r, g, b = (int(color_hex[i : i + 2], 16) for i in range(0, 6, 2))
    return cls(r, g, b)

from_rgb_tuple(color_tuple) classmethod

Create a Color instance from an RGB tuple.

Parameters:

Name	Type	Description	Default
color_tuple	Tuple[int, int, int]	A tuple representing the color in RGB format, where each element is an integer in the range 0-255.	required

Returns:

Name	Type	Description
Color	Color	An instance representing the color.

Example

import supervision as sv

sv.Color.from_rgb_tuple((255, 255, 0))
# Color(r=255, g=255, b=0)

Source code in supervision/draw/color.py

@classmethod
def from_rgb_tuple(cls, color_tuple: Tuple[int, int, int]) -> Color:
    """
    Create a Color instance from an RGB tuple.

    Args:
        color_tuple (Tuple[int, int, int]): A tuple representing the color in RGB
            format, where each element is an integer in the range 0-255.

    Returns:
        Color: An instance representing the color.

    Example:
        ```python
        import supervision as sv

        sv.Color.from_rgb_tuple((255, 255, 0))
        # Color(r=255, g=255, b=0)
        ```
    """
    r, g, b = color_tuple
    return cls(r=r, g=g, b=b)

ColorPalette

Source code in supervision/draw/color.py

@dataclass
class ColorPalette:
    colors: List[Color]

    @classproperty
    def DEFAULT(cls) -> ColorPalette:
        """
        Returns a default color palette.

        Returns:
            ColorPalette: A ColorPalette instance with default colors.

        Example:
            ```python
            import supervision as sv

            sv.ColorPalette.DEFAULT
            # ColorPalette(colors=[Color(r=255, g=64, b=64), Color(r=255, g=161, b=160), ...])
            ```

        ![default-color-palette](https://media.roboflow.com/
        supervision-annotator-examples/default-color-palette.png)
        """  # noqa: E501 // docs
        return ColorPalette.from_hex(color_hex_list=DEFAULT_COLOR_PALETTE)

    @classproperty
    def ROBOFLOW(cls) -> ColorPalette:
        """
        Returns a Roboflow color palette.

        Returns:
            ColorPalette: A ColorPalette instance with Roboflow colors.

        Example:
            ```python
            import supervision as sv

            sv.ColorPalette.ROBOFLOW
            # ColorPalette(colors=[Color(r=194, g=141, b=252), Color(r=163, g=81, b=251), ...])
            ```

        ![roboflow-color-palette](https://media.roboflow.com/
        supervision-annotator-examples/roboflow-color-palette.png)
        """  # noqa: E501 // docs
        return ColorPalette.from_hex(color_hex_list=ROBOFLOW_COLOR_PALETTE)

    @classproperty
    def LEGACY(cls) -> ColorPalette:
        return ColorPalette.from_hex(color_hex_list=LEGACY_COLOR_PALETTE)

    @classmethod
    def from_hex(cls, color_hex_list: List[str]) -> ColorPalette:
        """
        Create a ColorPalette instance from a list of hex strings.

        Args:
            color_hex_list (List[str]): List of color hex strings.

        Returns:
            ColorPalette: A ColorPalette instance.

        Example:
            ```python
            import supervision as sv

            sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
            # ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
            ```
        """
        colors = [Color.from_hex(color_hex) for color_hex in color_hex_list]
        return cls(colors)

    @classmethod
    def from_matplotlib(cls, palette_name: str, color_count: int) -> ColorPalette:
        """
        Create a ColorPalette instance from a Matplotlib color palette.

        Args:
            palette_name (str): Name of the Matplotlib palette.
            color_count (int): Number of colors to sample from the palette.

        Returns:
            ColorPalette: A ColorPalette instance.

        Example:
            ```python
            import supervision as sv

            sv.ColorPalette.from_matplotlib('viridis', 5)
            # ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])
            ```

        ![visualized_color_palette](https://media.roboflow.com/
        supervision-annotator-examples/visualized_color_palette.png)
        """  # noqa: E501 // docs
        mpl_palette = plt.get_cmap(palette_name, color_count)

        if hasattr(mpl_palette, "colors"):
            colors = mpl_palette.colors
        else:
            colors = [mpl_palette(i / (color_count - 1)) for i in range(color_count)]

        return cls(
            [Color(int(r * 255), int(g * 255), int(b * 255)) for r, g, b, _ in colors]
        )

    def by_idx(self, idx: int) -> Color:
        """
        Return the color at a given index in the palette.

        Args:
            idx (int): Index of the color in the palette.

        Returns:
            Color: Color at the given index.

        Example:
            ```python
            import supervision as sv

            color_palette = sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
            color_palette.by_idx(1)
            # Color(r=0, g=255, b=0)
            ```
        """
        if idx < 0:
            raise ValueError("idx argument should not be negative")
        idx = idx % len(self.colors)
        return self.colors[idx]

    def __len__(self) -> int:
        """
        Returns the number of colors in the palette.

        Returns:
            int: The number of colors.
        """
        return len(self.colors)

Functions

DEFAULT()

Returns a default color palette.

Returns:

Name	Type	Description
ColorPalette	ColorPalette	A ColorPalette instance with default colors.

Example

import supervision as sv

sv.ColorPalette.DEFAULT
# ColorPalette(colors=[Color(r=255, g=64, b=64), Color(r=255, g=161, b=160), ...])

Source code in supervision/draw/color.py

@classproperty
def DEFAULT(cls) -> ColorPalette:
    """
    Returns a default color palette.

    Returns:
        ColorPalette: A ColorPalette instance with default colors.

    Example:
        ```python
        import supervision as sv

        sv.ColorPalette.DEFAULT
        # ColorPalette(colors=[Color(r=255, g=64, b=64), Color(r=255, g=161, b=160), ...])
        ```

    ![default-color-palette](https://media.roboflow.com/
    supervision-annotator-examples/default-color-palette.png)
    """  # noqa: E501 // docs
    return ColorPalette.from_hex(color_hex_list=DEFAULT_COLOR_PALETTE)

ROBOFLOW()

Returns a Roboflow color palette.

Returns:

Name	Type	Description
ColorPalette	ColorPalette	A ColorPalette instance with Roboflow colors.

Example

import supervision as sv

sv.ColorPalette.ROBOFLOW
# ColorPalette(colors=[Color(r=194, g=141, b=252), Color(r=163, g=81, b=251), ...])

Source code in supervision/draw/color.py

@classproperty
def ROBOFLOW(cls) -> ColorPalette:
    """
    Returns a Roboflow color palette.

    Returns:
        ColorPalette: A ColorPalette instance with Roboflow colors.

    Example:
        ```python
        import supervision as sv

        sv.ColorPalette.ROBOFLOW
        # ColorPalette(colors=[Color(r=194, g=141, b=252), Color(r=163, g=81, b=251), ...])
        ```

    ![roboflow-color-palette](https://media.roboflow.com/
    supervision-annotator-examples/roboflow-color-palette.png)
    """  # noqa: E501 // docs
    return ColorPalette.from_hex(color_hex_list=ROBOFLOW_COLOR_PALETTE)

__len__()

Returns the number of colors in the palette.

Returns:

Name	Type	Description
int	int	The number of colors.

Source code in supervision/draw/color.py

def __len__(self) -> int:
    """
    Returns the number of colors in the palette.

    Returns:
        int: The number of colors.
    """
    return len(self.colors)

by_idx(idx)

Return the color at a given index in the palette.

Parameters:

Name	Type	Description	Default
idx	int	Index of the color in the palette.	required

Returns:

Name	Type	Description
Color	Color	Color at the given index.

Example

import supervision as sv

color_palette = sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
color_palette.by_idx(1)
# Color(r=0, g=255, b=0)

Source code in supervision/draw/color.py

def by_idx(self, idx: int) -> Color:
    """
    Return the color at a given index in the palette.

    Args:
        idx (int): Index of the color in the palette.

    Returns:
        Color: Color at the given index.

    Example:
        ```python
        import supervision as sv

        color_palette = sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
        color_palette.by_idx(1)
        # Color(r=0, g=255, b=0)
        ```
    """
    if idx < 0:
        raise ValueError("idx argument should not be negative")
    idx = idx % len(self.colors)
    return self.colors[idx]

from_hex(color_hex_list) classmethod

Create a ColorPalette instance from a list of hex strings.

Parameters:

Name	Type	Description	Default
color_hex_list	List[str]	List of color hex strings.	required

Returns:

Name	Type	Description
ColorPalette	ColorPalette	A ColorPalette instance.

Example

import supervision as sv

sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
# ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])

Source code in supervision/draw/color.py

@classmethod
def from_hex(cls, color_hex_list: List[str]) -> ColorPalette:
    """
    Create a ColorPalette instance from a list of hex strings.

    Args:
        color_hex_list (List[str]): List of color hex strings.

    Returns:
        ColorPalette: A ColorPalette instance.

    Example:
        ```python
        import supervision as sv

        sv.ColorPalette.from_hex(['#ff0000', '#00ff00', '#0000ff'])
        # ColorPalette(colors=[Color(r=255, g=0, b=0), Color(r=0, g=255, b=0), ...])
        ```
    """
    colors = [Color.from_hex(color_hex) for color_hex in color_hex_list]
    return cls(colors)

from_matplotlib(palette_name, color_count) classmethod

Create a ColorPalette instance from a Matplotlib color palette.

Parameters:

Name	Type	Description	Default
palette_name	str	Name of the Matplotlib palette.	required
color_count	int	Number of colors to sample from the palette.	required

Returns:

Name	Type	Description
ColorPalette	ColorPalette	A ColorPalette instance.

Example

import supervision as sv

sv.ColorPalette.from_matplotlib('viridis', 5)
# ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])

Source code in supervision/draw/color.py

@classmethod
def from_matplotlib(cls, palette_name: str, color_count: int) -> ColorPalette:
    """
    Create a ColorPalette instance from a Matplotlib color palette.

    Args:
        palette_name (str): Name of the Matplotlib palette.
        color_count (int): Number of colors to sample from the palette.

    Returns:
        ColorPalette: A ColorPalette instance.

    Example:
        ```python
        import supervision as sv

        sv.ColorPalette.from_matplotlib('viridis', 5)
        # ColorPalette(colors=[Color(r=68, g=1, b=84), Color(r=59, g=82, b=139), ...])
        ```

    ![visualized_color_palette](https://media.roboflow.com/
    supervision-annotator-examples/visualized_color_palette.png)
    """  # noqa: E501 // docs
    mpl_palette = plt.get_cmap(palette_name, color_count)

    if hasattr(mpl_palette, "colors"):
        colors = mpl_palette.colors
    else:
        colors = [mpl_palette(i / (color_count - 1)) for i in range(color_count)]

    return cls(
        [Color(int(r * 255), int(g * 255), int(b * 255)) for r, g, b, _ in colors]
    )

Comments