Conversion Utils

cv2_to_pillow

supervision.utils.conversion.cv2_to_pillow(image: npt.NDArray[np.uint8]) -> Image.Image

Converts OpenCV image into Pillow image, handling BGR -> RGB conversion.

Parameters:

Name	Type	Description	Default
image	NDArray[uint8]	OpenCV image (in BGR format).	required

Returns:

Type	Description
Image	Input image converted to Pillow format.

Examples:

>>> import numpy as np
>>> from supervision.utils.conversion import cv2_to_pillow
>>> scene = np.zeros((10, 10, 3), dtype=np.uint8)
>>> scene[:, :, 2] = 255
>>> image = cv2_to_pillow(scene)
>>> image.size
(10, 10)
>>> image.getpixel((0, 0))
(255, 0, 0)

Source code in src/supervision/utils/conversion.py

def cv2_to_pillow(image: npt.NDArray[np.uint8]) -> Image.Image:
    """
    Converts OpenCV image into Pillow image, handling BGR -> RGB
    conversion.

    Args:
        image: OpenCV image (in BGR format).

    Returns:
        Input image converted to Pillow format.

    Examples:
        ```pycon
        >>> import numpy as np
        >>> from supervision.utils.conversion import cv2_to_pillow
        >>> scene = np.zeros((10, 10, 3), dtype=np.uint8)
        >>> scene[:, :, 2] = 255
        >>> image = cv2_to_pillow(scene)
        >>> image.size
        (10, 10)
        >>> image.getpixel((0, 0))
        (255, 0, 0)

        ```
    """
    rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
    return Image.fromarray(rgb_image)

pillow_to_cv2

supervision.utils.conversion.pillow_to_cv2(image: Image.Image) -> npt.NDArray[np.uint8]

Converts Pillow image into OpenCV image, handling RGB -> BGR conversion. Palette images are first expanded to RGB so palette indices are resolved to their actual colors.

Parameters:

Name	Type	Description	Default
image	Image	Pillow image in RGB, grayscale, or palette mode.	required

Returns:

Type	Description
NDArray[uint8]	Input image converted to OpenCV format.

Examples:

>>> from PIL import Image
>>> from supervision.utils.conversion import pillow_to_cv2
>>> image = Image.new("RGB", (10, 10), color=(255, 0, 0))
>>> scene = pillow_to_cv2(image)
>>> scene.shape
(10, 10, 3)
>>> scene[0, 0].tolist()
[0, 0, 255]

Source code in src/supervision/utils/conversion.py

def pillow_to_cv2(image: Image.Image) -> npt.NDArray[np.uint8]:
    """
    Converts Pillow image into OpenCV image, handling RGB -> BGR
    conversion. Palette images are first expanded to RGB so palette indices are
    resolved to their actual colors.

    Args:
        image: Pillow image in RGB, grayscale, or palette mode.

    Returns:
        Input image converted to OpenCV format.

    Examples:
        ```pycon
        >>> from PIL import Image
        >>> from supervision.utils.conversion import pillow_to_cv2
        >>> image = Image.new("RGB", (10, 10), color=(255, 0, 0))
        >>> scene = pillow_to_cv2(image)
        >>> scene.shape
        (10, 10, 3)
        >>> scene[0, 0].tolist()
        [0, 0, 255]

        ```
    """
    if image.mode == "P":
        image = image.convert("RGB")

    scene = np.array(image)
    if scene.ndim == 2:
        return cast(npt.NDArray[np.uint8], scene.astype(np.uint8, copy=False))
    scene = cv2.cvtColor(scene, cv2.COLOR_RGB2BGR)
    # cvtColor already returns uint8 here, so astype is a no-op other than the
    # full-image copy it forces; copy=False keeps the dtype guard without it.
    return cast(npt.NDArray[np.uint8], scene.astype(np.uint8, copy=False))

ensure_cv2_image_for_annotation

supervision.utils.conversion.ensure_cv2_image_for_annotation(annotate_func: F) -> F

Source code in src/supervision/utils/conversion.py

@deprecated(  # type: ignore[untyped-decorator]
    target=ensure_cv2_image_for_class_method,
    deprecated_in="0.27.0",
    remove_in="0.31.0",
)
def ensure_cv2_image_for_annotation(
    annotate_func: F,
) -> F:
    return cast(F, void(annotate_func))

ensure_pil_image_for_annotation

supervision.utils.conversion.ensure_pil_image_for_annotation(annotate_func: F) -> F

Source code in src/supervision/utils/conversion.py

@deprecated(  # type: ignore[untyped-decorator]
    target=ensure_pil_image_for_class_method,
    deprecated_in="0.27.0",
    remove_in="0.31.0",
)
def ensure_pil_image_for_annotation(
    annotate_func: F,
) -> F:
    return cast(F, void(annotate_func))

images_to_cv2

supervision.utils.conversion.images_to_cv2(images: list[npt.NDArray[np.uint8] | Image.Image]) -> list[npt.NDArray[np.uint8]]

Converts images provided either as Pillow images or OpenCV images into OpenCV format.

Parameters:

Name	Type	Description	Default
images	list[NDArray[uint8] | Image]	Images to be converted	required

Returns:

Type	Description
list[NDArray[uint8]]	List of input images in OpenCV format (with order preserved).

Source code in src/supervision/utils/conversion.py

def images_to_cv2(
    images: list[npt.NDArray[np.uint8] | Image.Image],
) -> list[npt.NDArray[np.uint8]]:
    """
    Converts images provided either as Pillow images or OpenCV
    images into OpenCV format.

    Args:
        images: Images to be converted

    Returns:
        List of input images in OpenCV format
            (with order preserved).

    """
    result: list[npt.NDArray[np.uint8]] = []
    for image in images:
        if isinstance(image, Image.Image):
            result.append(pillow_to_cv2(image))
        else:
            result.append(image)
    return result

Comments