def overlay_image(base: Image.Image, overlay: Image.Image, alpha: float = 0.5) -> Image.Image:
    """Overlay an image on top of another image with a specified alpha value.

    This function takes a base image and overlays another image on top of it with the
    specified transparency level. Both images are converted to RGBA mode to enable alpha
    compositing. If the overlay image has a different size than the base image, it will
    be resized to match.

    Args:
        base (:class:`PIL.Image.Image`): The base image that will serve as the
            background.
        overlay (:class:`PIL.Image.Image`): The image to overlay on top of the base
            image.
        alpha (float, optional): The alpha/transparency value for blending, between
            0.0 (fully transparent) and 1.0 (fully opaque). Defaults to ``0.5``.

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

    Examples:
        Create a base image with a yellow triangle on a green background:

        >>> from PIL import Image, ImageDraw
        >>> image = Image.new('RGB', (200, 200), color='green')
        >>> draw = ImageDraw.Draw(image)
        >>> draw.polygon([(50, 50), (150, 50), (100, 150)], fill='yellow')

        Create a mask with a white rectangle on black background:

        >>> mask = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask)
        >>> draw.rectangle([75, 75, 125, 125], fill=255)

        Overlay the mask on the image with 30% opacity:

        >>> result = overlay_image(image, mask, alpha=0.3)
        >>> result.show()  # doctest: +SKIP

    Note:
        - Both input images are converted to RGBA mode internally
        - The overlay is automatically resized to match the base image size
        - The function uses PIL's alpha compositing for high-quality blending
        - The output image preserves the RGBA mode of the composite result
    """
    base = base.convert("RGBA")
    overlay = overlay.convert("RGBA")

    # Resize mask to match input image size if necessary
    if base.size != overlay.size:
        overlay = overlay.resize(base.size)

    # Adjust the alpha of the mask
    alpha_mask = overlay.split()[3]
    alpha_mask = ImageEnhance.Brightness(alpha_mask).enhance(alpha)
    overlay.putalpha(alpha_mask)

    # Composite the mask over the input image
    return Image.alpha_composite(base, overlay)
Overlay an image on top of another image with a specified alpha value.

    This function takes a base image and overlays another image on top of it with the
    specified transparency level. Both images are converted to RGBA mode to enable alpha
    compositing. If the overlay image has a different size than the base image, it will
    be resized to match.

    Args:
        base (:class:`PIL.Image.Image`): The base image that will serve as the
            background.
        overlay (:class:`PIL.Image.Image`): The image to overlay on top of the base
            image.
        alpha (float, optional): The alpha/transparency value for blending, between
            0.0 (fully transparent) and 1.0 (fully opaque). Defaults to ``0.5``.

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

    Examples:
        Create a base image with a yellow triangle on a green background:

        >>> from PIL import Image, ImageDraw
        >>> image = Image.new('RGB', (200, 200), color='green')
        >>> draw = ImageDraw.Draw(image)
        >>> draw.polygon([(50, 50), (150, 50), (100, 150)], fill='yellow')

        Create a mask with a white rectangle on black background:

        >>> mask = Image.new('L', (200, 200), color=0)
        >>> draw = ImageDraw.Draw(mask)
        >>> draw.rectangle([75, 75, 125, 125], fill=255)

        Overlay the mask on the image with 30% opacity:

        >>> result = overlay_image(image, mask, alpha=0.3)
        >>> result.show()  # doctest: +SKIP

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