def overlay_images(
    base: Image.Image,
    overlays: Image.Image | list[Image.Image],
    alpha: float | list[float] = 0.5,
) -> Image.Image:
    """Overlay multiple images on top of a base image with specified transparency.

    This function overlays one or more images on top of a base image with specified
    alpha/transparency values. If an overlay is a mask (L mode), it will be drawn
    as a semi-transparent overlay.

    Args:
        base (:class:`PIL.Image.Image`): The base image to overlay on top of.
        overlays (:class:`PIL.Image.Image` | list[:class:`PIL.Image.Image`]): One
            or more images to overlay on the base image.
        alpha (float | list[float], optional): Alpha/transparency value(s) between
            0.0 (fully transparent) and 1.0 (fully opaque). Can be a single float
            applied to all overlays, or a list of values. Defaults to ``0.5``.

    Returns:
        :class:`PIL.Image.Image`: A new image with all overlays composited on top
        of the base image using the specified alpha values.

    Examples:
        Overlay a single mask:

        >>> from PIL import Image, ImageDraw
        >>> # Create base image with yellow triangle on green background
        >>> image = Image.new('RGB', (200, 200), color='green')
        >>> draw = ImageDraw.Draw(image)
        >>> draw.polygon([(50, 50), (150, 50), (100, 150)], fill='yellow')
        >>> # Create mask with white rectangle
        >>> mask = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask)
        >>> draw.rectangle([75, 75, 125, 125], fill=255)
        >>> # Apply overlay
        >>> result = overlay_images(image, mask)

        Overlay multiple masks with different alphas:

        >>> # Create second mask with white ellipse
        >>> mask2 = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask2)
        >>> draw.ellipse([50, 50, 150, 100], fill=255)
        >>> # Apply overlays with different alpha values
        >>> result = overlay_images(image, [mask, mask2], alpha=[0.3, 0.7])

    Note:
        - All images are converted to RGBA mode internally
        - Overlays are automatically resized to match the base image size
        - Uses PIL's alpha compositing for high-quality blending
        - The output preserves the RGBA mode of the composite result
    """
    if not isinstance(overlays, list):
        overlays = [overlays]

    alphas = [alpha] * len(overlays) if not isinstance(alpha, list) else alpha
    for overlay, overlay_alpha in zip(overlays, alphas, strict=False):
        base = overlay_image(base, overlay, alpha=overlay_alpha)

    return base
Overlay multiple images on top of a base image with specified transparency.

    This function overlays one or more images on top of a base image with specified
    alpha/transparency values. If an overlay is a mask (L mode), it will be drawn
    as a semi-transparent overlay.

    Args:
        base (:class:`PIL.Image.Image`): The base image to overlay on top of.
        overlays (:class:`PIL.Image.Image` | list[:class:`PIL.Image.Image`]): One
            or more images to overlay on the base image.
        alpha (float | list[float], optional): Alpha/transparency value(s) between
            0.0 (fully transparent) and 1.0 (fully opaque). Can be a single float
            applied to all overlays, or a list of values. Defaults to ``0.5``.

    Returns:
        :class:`PIL.Image.Image`: A new image with all overlays composited on top
        of the base image using the specified alpha values.

    Examples:
        Overlay a single mask:

        >>> from PIL import Image, ImageDraw
        >>> # Create base image with yellow triangle on green background
        >>> image = Image.new('RGB', (200, 200), color='green')
        >>> draw = ImageDraw.Draw(image)
        >>> draw.polygon([(50, 50), (150, 50), (100, 150)], fill='yellow')
        >>> # Create mask with white rectangle
        >>> mask = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask)
        >>> draw.rectangle([75, 75, 125, 125], fill=255)
        >>> # Apply overlay
        >>> result = overlay_images(image, mask)

        Overlay multiple masks with different alphas:

        >>> # Create second mask with white ellipse
        >>> mask2 = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask2)
        >>> draw.ellipse([50, 50, 150, 100], fill=255)
        >>> # Apply overlays with different alpha values
        >>> result = overlay_images(image, [mask, mask2], alpha=[0.3, 0.7])

    Note:
        - All images are converted to RGBA mode internally
        - Overlays are automatically resized to match the base image size
        - Uses PIL's alpha compositing for high-quality blending
        - The output preserves the RGBA mode of the composite result
    
src/anomalib/visualization/image/functional.py