Conversion Utils

cv2_to_pillow

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

Converts an OpenCV image into a Pillow image, reordering channels from OpenCV's BGR(A) convention to Pillow's RGB(A).

Parameters:

Name	Type	Description	Default
image	NDArray[uint8]	OpenCV image. Accepted shapes: - (H, W) — grayscale, passed through unchanged. - (H, W, 3) — BGR, converted to RGB. - (H, W, 4) — BGRA, converted to RGBA.	required

Returns:

Type	Description
Image	Input image converted to Pillow format.

Raises:

Type	Description
ValueError	If image is not 2-D or 3-D with 3 or 4 channels.

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 an OpenCV image into a Pillow image, reordering channels from
    OpenCV's BGR(A) convention to Pillow's RGB(A).

    Args:
        image: OpenCV image. Accepted shapes:
            - `(H, W)` — grayscale, passed through unchanged.
            - `(H, W, 3)` — BGR, converted to RGB.
            - `(H, W, 4)` — BGRA, converted to RGBA.

    Returns:
        Input image converted to Pillow format.

    Raises:
        ValueError: If `image` is not 2-D or 3-D with 3 or 4 channels.

    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)

        ```
    """
    if image.ndim == 2:
        return Image.fromarray(np.ascontiguousarray(image))
    if image.ndim == 3 and image.shape[2] == 3:
        rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
        return Image.fromarray(rgb_image)
    if image.ndim == 3 and image.shape[2] == 4:
        return Image.fromarray(np.ascontiguousarray(image[..., [2, 1, 0, 3]]))
    raise ValueError(f"Expected shape (H,W), (H,W,3), or (H,W,4), got {image.shape}.")

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. RGBA images are converted to BGR, matching OpenCV by dropping the alpha channel.

Parameters:

Name	Type	Description	Default
image	Image	Pillow image in RGB, RGBA, 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. RGBA images are converted to BGR, matching
    OpenCV by dropping the alpha channel.

    Args:
        image: Pillow image in RGB, RGBA, 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