Function blend_images

monai/visualize/utils.py:164–230

Blend an image and a label. Both should have the shape CHW[D]. The image may have C==1 or 3 channels (greyscale or RGB). The label is expected to have C==1. Args: image: the input image to blend with label data. label: the input label to blend with image data.

(
    image: NdarrayOrTensor,
    label: NdarrayOrTensor,
    alpha: float | NdarrayOrTensor = 0.5,
    cmap: str = "hsv",
    rescale_arrays: bool = True,
    transparent_background: bool = True,
)

def blend_images(
    image: NdarrayOrTensor,
    label: NdarrayOrTensor,
    alpha: float | NdarrayOrTensor = 0.5,
    cmap: str = "hsv",
    rescale_arrays: bool = True,
    transparent_background: bool = True,
) -> NdarrayOrTensor:
    """
    Blend an image and a label. Both should have the shape CHW[D].
    The image may have C==1 or 3 channels (greyscale or RGB).
    The label is expected to have C==1.

    Args:
        image: the input image to blend with label data.
        label: the input label to blend with image data.
        alpha: this specifies the weighting given to the label, where 0 is completely
            transparent and 1 is completely opaque. This can be given as either a
            single value or an array/tensor that is the same size as the input image.
        cmap: specify colormap in the matplotlib, default to `hsv`, for more details, please refer to:
            https://matplotlib.org/2.0.2/users/colormaps.html.
        rescale_arrays: whether to rescale the array to [0, 1] first, default to `True`.
        transparent_background: if true, any zeros in the label field will not be colored.

    .. image:: ../../docs/images/blend_images.png

    """

    if label.shape[0] != 1:
        raise ValueError("Label should have 1 channel.")
    if image.shape[0] not in (1, 3):
        raise ValueError("Image should have 1 or 3 channels.")
    if image.shape[1:] != label.shape[1:]:
        raise ValueError("image and label should have matching spatial sizes.")
    if isinstance(alpha, (np.ndarray, torch.Tensor)):
        if image.shape[1:] != alpha.shape[1:]:  # pytype: disable=attribute-error,invalid-directive
            raise ValueError("if alpha is image, size should match input image and label.")

    # rescale arrays to [0, 1] if desired
    if rescale_arrays:
        image = rescale_array(image)
        label = rescale_array(label)
    # convert image to rgb (if necessary) and then rgba
    if image.shape[0] == 1:
        image = repeat(image, 3, axis=0)

    def get_label_rgb(cmap: str, label: NdarrayOrTensor) -> NdarrayOrTensor:
        _cmap = plt.colormaps.get_cmap(cmap)
        label_np, *_ = convert_data_type(label, np.ndarray)
        label_rgb_np = _cmap(label_np[0])
        label_rgb_np = np.moveaxis(label_rgb_np, -1, 0)[:3]
        label_rgb, *_ = convert_to_dst_type(label_rgb_np, label)
        return label_rgb

    label_rgb = get_label_rgb(cmap, label)
    if isinstance(alpha, (torch.Tensor, np.ndarray)):
        w_label = alpha
    elif isinstance(label, torch.Tensor):