API Reference

def image_to_pil(image: CudaImage) -> Image:
    """
    Converts a CudaImage to a PIL.Image in RGBA format.

    The image is copied from GPU memory to host memory and returned
    as a Pillow image object.

    Args:
        image (CudaImage): The image in GPU memory.

    Returns:
        PIL.Image: A new PIL Image with RGBA channels.

    Example:
        >>> pil_img = image_to_pil(cuda_img)
        >>> pil_img.show()
    """

    img_data = bytearray(image.width * image.height * 4)
    data_ptr = ffi.from_buffer(img_data)
    copy_to_host(ffi.cast("uchar4*", data_ptr), image.buffer, image.width,
                 image.height)
    return Image.frombytes("RGBA", (image.width, image.height),
                           bytes(img_data))

def load_image(filename: str, container: CudaImage | None = None) -> CudaImage:
    """
    Loads an image from disk and transfers it to a CudaImage.

    The image is loaded using Pillow and converted to RGBA format. It is then copied
    to GPU memory. Optionally, a pre-allocated CudaImage container can be used to avoid allocation.

    Args:
        filename (str): Path to the image file to load.
        container (CudaImage, optional): Pre-allocated image buffer. Must be large enough to hold the image.

    Returns:
        CudaImage: A new or reused image object with the loaded data.

    Raises:
        ValueError: If the input image is larger than the provided container.

    Example:
        >>> cuda_img = load_image("texture.png")
    """

    img = Image.open(filename).convert("RGBA")
    width, height = img.size

    if container is None:
        container = CudaImage(width, height)
    if width > container.width or height > container.height:
        raise ValueError("Image dimensions exceed container dimensions")

    host_buf = bytearray(img.tobytes())

    src_ptr = ffi.cast("uchar4*", ffi.from_buffer(host_buf))
    copy_to_device(container.buffer, src_ptr, width, height)

    container.width = width
    container.height = height
    return container

def save_image(image: CudaImage, filename: str) -> None:
    """
    Saves a CudaImage to disk as a standard image file.

    This function converts the image from GPU memory to a Pillow image and saves it
    using the given filename. The format is inferred from the file extension.

    Args:
        image (CudaImage): The image to save.
        filename (str): Destination path, including extension (e.g., 'output.png').

    Returns:
        None

    Example:
        >>> save_image(cuda_img, "output.png")
    """

    img = image_to_pil(image)
    img.save(filename)
    img.close()

def blend(background: CudaImage, over: CudaImage, x: int, y: int) -> None:
    """
    Blends an image (`over`) on top of another (`background`) at a specified position.

    The blending respects the alpha channel of the overlaid image. No clipping is performed
    if the `over` image exceeds the bounds of the `background`; behavior in such cases depends on the underlying CUDA implementation.

    Args:
        background (CudaImage): The base image to draw onto.
        over (CudaImage): The image to blend on top.
        x (int): Horizontal position in the background where the top-left corner of `over` is placed.
        y (int): Vertical position in the background where the top-left corner of `over` is placed.

    Returns:
        None

    Example:
        >>> blend(bg_img, icon_img, x=100, y=50)
    """
    _lib.blend_buffers(background.buffer,
                       over.buffer,
                       background.width,
                       background.height,
                       over.width,
                       over.height,
                       x,
                       y,
                       )

def fill_color(image: CudaImage, color: RGBA) -> None:
    """
    Fills the entire image with a solid color.

    This operation overwrites all pixels in the image with the specified RGBA color.

    Args:
        image (CudaImage): The image to fill.
        color (RGBA): The fill color to apply.

    Returns:
        None

    Example:
        >>> fill_color(img, RGBA(255, 255, 255, 255))  # Fill with solid white
    """

    _lib.fill_color(image.buffer,
                    image.width,
                    image.height,
                    color.r,
                    color.g,
                    color.b,
                    color.a)

def fill_gradient(image: CudaImage,
                  color1: RGBA,
                  color2: RGBA,
                  direction: int = 0,
                  seamless: bool = False) -> None:
    """
    Fills the image with a linear gradient between two colors.

    The gradient direction and style (seamless or linear) can be customized.

    Args:
        image (CudaImage): The target image to fill.
        color1 (RGBA): The starting color of the gradient.
        color2 (RGBA): The ending color of the gradient.
        direction (int, optional): Gradient direction:
            - 0 = vertical (top to bottom)
            - 1 = horizontal (left to right)
            - 2 = diagonal (top-left to bottom-right)
            - 3 = diagonal (bottom-left to top-right)
            Defaults to 0.
        seamless (bool, optional): Whether the gradient should repeat seamlessly. Defaults to False.

    Returns:
        None

    Raises:
        ValueError: If an invalid direction value is provided.

    Example:
        >>> fill_gradient(img, RGBA(0, 0, 0, 255), RGBA(255, 255, 255, 255), direction=1)
    """
    if direction not in (0, 1, 2, 3):
        raise ValueError(f"Invalid gradient direction: {direction}. Must be 0, 1, 2 or 3.")

    _lib.fill_gradient(image.buffer,
                       image.width,
                       image.height,
                       color1.r,
                       color1.g,
                       color1.b,
                       color1.a,
                       color2.r,
                       color2.g,
                       color2.b,
                       color2.a,
                       direction,
                       seamless,
                       )

def apply_chroma_key(image: CudaImage,
                     key_image: CudaImage,
                     channel: str = "A",
                     threshold: int = 128,
                     invert: bool = False,
                     zero_all_channels: bool = False) -> None:
    """
    Applies a chroma key mask based on a channel of another image.

    Args:
        image (CudaImage): The target image to apply transparency.
        key_image (CudaImage): Image whose channel values are used as a mask.
        channel (str, optional): Channel to use from the key image ('R', 'G', 'B', 'A'). Defaults to 'A'.
        threshold (int, optional): Threshold (0–255) to apply masking. Defaults to 128.
        invert (bool, optional): Invert the mask logic. Defaults to False.
        zero_all_channels (bool, optional): If True, sets RGB to zero where mask applies. Defaults to False.

    Raises:
        ValueError: If the provided channel is invalid.

    Returns:
        None
    """

    channel_upper = (channel.upper() if isinstance(channel, str) else str(channel).upper())

    if channel_upper == "R":
        channel_idx = 0
    elif channel_upper == "G":
        channel_idx = 1
    elif channel_upper == "B":
        channel_idx = 2
    elif channel_upper == "A":
        channel_idx = 3
    else:
        raise ValueError(f"Invalid channel: {channel}, must be one of 'R', 'G', 'B', 'A'")

    _lib.apply_chroma_key(image.buffer,
                          key_image.buffer,
                          image.width,
                          image.height,
                          key_image.width,
                          key_image.height,
                          channel_idx,
                          threshold,
                          invert,
                          zero_all_channels,
                          )

def apply_corner_radius(image: CudaImage, size: int) -> None:
    """
    Applies a rounded corner mask to an image in-place.

    Args:
        image (CudaImage): Image to be modified.
        size (int): Radius of the corner in pixels.

    Returns:
        None
    """

    _lib.apply_corner_radius(image.buffer, image.width, image.height, size)

def apply_flip(image: CudaImage,
               flip_horizontal: bool = False,
               flip_vertical: bool = False) -> None:
    """
    Flips an image horizontally or vertically in-place.

    Args:
        image (CudaImage): Image to flip.
        flip_horizontal (bool, optional): Flip the image horizontally. Defaults to False.
        flip_vertical (bool, optional): Flip the image vertically. Defaults to False.

    Raises:
        ValueError: If both `flip_horizontal` and `flip_vertical` are True.

    Returns:
        None
    """

    if flip_horizontal and flip_vertical:
        raise ValueError("Cannot flip both horizontal and vertical at the same time")

    _lib.apply_flip(image.buffer, image.width, image.height, flip_horizontal, flip_vertical)

def apply_gaussian_blur(image: CudaImage,
                        radius: float,
                        image_copy_cache: CudaImage = None) -> None:
    """
    Applies a Gaussian blur effect to an image in-place.

    Args:
        image (CudaImage): Image to blur.
        radius (float): Radius of the blur in pixels.
        image_copy_cache (CudaImage, optional): Optional buffer. Must match image size.

    Raises:
        ValueError: If the cache does not match the image dimensions.

    Returns:
        None
    """

    need_free = False
    if image_copy_cache is None:
        image_copy_cache = CudaImage(image.width, image.height)
        copy_buffers_same_size(image_copy_cache.buffer, image.buffer, image.width, image.height)
        need_free = True
    else:
        if (image_copy_cache.width != image.width or image_copy_cache.height != image.height):
            raise ValueError(f"El buffer auxiliar debe coincidir con las dimensiones de la imagen original: {image.width}x{image.height}, recibido {image_copy_cache.width}x{image_copy_cache.height}")

    _lib.apply_gaussian_blur(image.buffer, image_copy_cache.buffer, image.width, image.height, radius)

    if need_free:
        image_copy_cache.free()

def apply_grayscale(image: CudaImage) -> None:
    """
    Converts an image to grayscale in-place using luminosity method.

    Args:
        image (CudaImage): Image to convert.

    Returns:
        None
    """

    _lib.apply_grayscale(image.buffer, image.width, image.height)

def apply_opacity(image: CudaImage, opacity: float) -> None:
    """
    Modifies the alpha channel of an image to apply global opacity.

    Args:
        image (CudaImage): Image to modify.
        opacity (float): Opacity value between 0.0 (transparent) and 1.0 (opaque).

    Returns:
        None
    """

    _lib.apply_opacity(image.buffer, image.width, image.height, opacity)

def apply_shadow(image: CudaImage,
                 radius: float,
                 intensity: float,
                 shadow_color: RGBA,
                 image_copy_cache: CudaImage = None,
                 inner: bool = False) -> None:
    """
    Applies a shadow effect around the opaque regions of an image.

    Args:
        image (CudaImage): Image to apply the shadow to.
        radius (float): Blur radius of the shadow.
        intensity (float): Intensity multiplier of the shadow.
        shadow_color (RGBA): Color of the shadow.
        image_copy_cache (CudaImage, optional): Optional image copy buffer. Must match original image size.
        inner (bool, optional): Whether to draw the shadow inside the shape. Defaults to False.

    Raises:
        ValueError: If the cache does not match the image dimensions.

    Returns:
        None
    """

    need_free = False
    if image_copy_cache is None:
        image_copy_cache = CudaImage(image.width, image.height)
        copy_buffers_same_size(image_copy_cache.buffer, image.buffer, image.width, image.height)
        need_free = True
    else:
        if (image_copy_cache.width != image.width or image_copy_cache.height != image.height):
            raise ValueError(f"Destination image dimensions must match original image dimensions: {image.width}x{image.height}, got {image_copy_cache.width}x{image_copy_cache.height}")

    _lib.apply_shadow(image.buffer,
                      image_copy_cache.buffer,
                      image.width,
                      image.height,
                      radius,
                      intensity,
                      shadow_color.r,
                      shadow_color.g,
                      shadow_color.b,
                      shadow_color.a,
                      int(inner),
                      )

    if need_free:
        image_copy_cache.free()

def apply_stroke(image: CudaImage,
                 stroke_width: int,
                 stroke_color: RGBA,
                 image_copy_cache: CudaImage = None,
                 inner: bool = True) -> None:
    """
    Draws a stroke (outline) around the non-transparent areas of an image.

    Args:
        image (CudaImage): Image to which the stroke will be applied.
        stroke_width (int): Width of the stroke in pixels.
        stroke_color (RGBA): Color of the stroke.
        image_copy_cache (CudaImage, optional): Optional cache of the original image. Must match dimensions.
        inner (bool, optional): If True, stroke is drawn inside the shape; otherwise outside. Defaults to True.

    Raises:
        ValueError: If the provided cache does not match image dimensions.

    Returns:
        None
    """

    need_free = False
    if image_copy_cache is None:
        image_copy_cache = CudaImage(image.width, image.height)
        copy_buffers_same_size(image_copy_cache.buffer, image.buffer, image.width, image.height)
        need_free = True
    else:
        if (image_copy_cache.width != image.width or image_copy_cache.height != image.height):
            raise ValueError(f"Destination image dimensions must match original image dimensions: {image.width}x{image.height}, got {image_copy_cache.width}x{image_copy_cache.height}")

    _lib.apply_stroke(image.buffer,
                      image_copy_cache.buffer,
                      image.width,
                      image.height,
                      stroke_width,
                      stroke_color.r,
                      stroke_color.g,
                      stroke_color.b,
                      stroke_color.a,
                      int(inner),
                      )

    if need_free:
        image_copy_cache.free()

def crop_margins(image: CudaImage,
                 left: int = 0,
                 top: int = 0,
                 right: int = 0,
                 bottom: int = 0,
                 crop_image_cache: CudaImage = None,
                 ) -> CudaImage:
    """
    Crops margins from the edges of a CudaImage.

    Margins are specified in pixels. The resulting image will be smaller and positioned
    relative to the top-left corner of the cropped area.

    Args:
        image (CudaImage): The input image to crop.
        left (int, optional): Pixels to remove from the left edge. Defaults to 0.
        top (int, optional): Pixels to remove from the top edge. Defaults to 0.
        right (int, optional): Pixels to remove from the right edge. Defaults to 0.
        bottom (int, optional): Pixels to remove from the bottom edge. Defaults to 0.
        crop_image_cache (CudaImage, optional): Pre-allocated buffer for the cropped image.
            Must match the expected result dimensions.

    Returns:
        CudaImage: The cropped image.

    Raises:
        ValueError: If any margin is negative.
        ValueError: If margins exceed the image's size.
        ValueError: If the cache image does not match the result size.

    Example:
        >>> cropped = crop_margins(img, left=10, top=10, right=10, bottom=10)
    """

    if left < 0 or top < 0 or right < 0 or bottom < 0:
        raise ValueError("Margins cannot be negative")

    if left + right >= image.width or top + bottom >= image.height:
        raise ValueError("Total margins exceed image dimensions")

    new_width = image.width - left - right
    new_height = image.height - top - bottom

    if crop_image_cache is None:
        result = CudaImage(new_width, new_height)
    else:
        if crop_image_cache.width != new_width or crop_image_cache.height != new_height:
            raise ValueError(f"Destination image cache dimensions must match crop result: {new_width}x{new_height}")
        result = crop_image_cache

    _lib.crop_image(result.buffer,
                    image.buffer,
                    image.width,
                    image.height,
                    new_width,
                    new_height,
                    left,
                    top,
                    )

    return result

def resize(image: CudaImage,
           width: int,
           height: int,
           method: ResizeMethod = ResizeMethod.BICUBIC,
           resize_image_cache: CudaImage = None,
           ) -> CudaImage:
    """
    Resizes a CudaImage to the specified dimensions using the chosen interpolation method.

    Supports bilinear, nearest-neighbor, and bicubic resampling. A cache image can be reused
    for performance to avoid memory allocation.

    Args:
        image (CudaImage): The input image to resize.
        width (int): Target width.
        height (int): Target height.
        method (ResizeMethod, optional): Resampling method. Defaults to BICUBIC.
        resize_image_cache (CudaImage, optional): Pre-allocated image for the resized result.
            Must match target dimensions if provided.

    Returns:
        CudaImage: A new (or reused) image resized to the given dimensions.

    Raises:
        ValueError: If the cache image dimensions do not match the target size.
        ValueError: If the interpolation method is not supported.

    Example:
        >>> resized = resize(img, 256, 256, method=ResizeMethod.BILINEAR)
    """

    if resize_image_cache is None:
        result = CudaImage(width, height)
    else:
        if resize_image_cache.width != width or resize_image_cache.height != height:
            raise ValueError(f"Destination image dimensions must match resize dimensions: {width}x{height}, got {resize_image_cache.width}x{resize_image_cache.height}")
        result = resize_image_cache

    if method == ResizeMethod.BILINEAR:
        _lib.resize_bilinear(result.buffer, image.buffer, width, height, image.width, image.height)
    elif method == ResizeMethod.NEAREST:
        _lib.resize_nearest(result.buffer, image.buffer, width, height, image.width, image.height)
    elif method == ResizeMethod.BICUBIC:
        _lib.resize_bicubic(result.buffer, image.buffer, width, height, image.width, image.height)
    else:
        raise ValueError(f"Unsupported resize method: {method}")

    return result

def render_text(text: str,
                font_path: str,
                font_size: int = 24,
                color: RGBA = RGBA(0, 0, 0, 255)
                ) -> CudaImage:
    """
    Renders a string of text into a CudaImage using a specified TrueType font.

    The function uses Pillow (PIL) to rasterize the text and transfers the resulting
    RGBA image into GPU memory as a `CudaImage`. Font metrics are computed to fit
    the rendered text exactly, avoiding unnecessary padding.

    Args:
        text (str): The string to render.
        font_path (str): Path to a TrueType (.ttf) or OpenType (.otf) font file.
        font_size (int, optional): Font size in points. Defaults to 24.
        color (RGBA, optional): Text color. Defaults to opaque black (0, 0, 0, 255).

    Returns:
        CudaImage: GPU image containing the rendered text.

    Raises:
        ValueError: If the font file cannot be loaded.

    Example:
        >>> img = render_text("Hello GPU!", "/fonts/Roboto-Regular.ttf", 32, RGBA(255, 255, 255, 255))
    """

    try:
        font = ImageFont.truetype(font_path, font_size)
    except Exception as e:
        raise ValueError(f"Error loading font '{font_path}': {e}")

    tmp_img = Image.new("RGBA", (1, 1))
    tmp_draw = ImageDraw.Draw(tmp_img)
    try:
        left, top, right, bottom = font.getbbox(text)
    except AttributeError:
        left, top, right, bottom = tmp_draw.textbbox((0, 0), text, font=font)

    width, height = right - left, bottom - top

    pil_img = Image.new("RGBA", (width, height), (0, 0, 0, 0))
    draw = ImageDraw.Draw(pil_img)
    draw.text((-left, -top), text, fill=(color.r, color.g, color.b, color.a), font=font)

    cuda_img = CudaImage(width, height)

    host_buf = bytearray(pil_img.tobytes())
    src_ptr = ffi.cast("uchar4*", ffi.from_buffer(host_buf))
    copy_to_device(cuda_img.buffer, src_ptr, width, height)

    return cuda_img

def blend_aligned(background: CudaImage,
                  image: CudaImage,
                  align: str = "center",
                  offset_x: int = 0,
                  offset_y: int = 0,
                  ) -> None:
    """
    Blends an image onto a background at a specified alignment and optional offset.

    The image is positioned relative to the background based on the `align` parameter,
    which supports standard alignment strings (e.g., "center", "top-left", etc.).
    Offsets can be applied to adjust the final position.

    Args:
        background (CudaImage): The background image where the input image will be blended.
        image (CudaImage): The image to blend.
        align (str, optional): Alignment method. Supported values:
            - "center" / "middle"
            - "top", "bottom", "left", "right"
            - "top-left", "top-right", "bottom-left", "bottom-right"
            Defaults to "center".
        offset_x (int, optional): Horizontal pixel offset to apply after alignment. Defaults to 0.
        offset_y (int, optional): Vertical pixel offset to apply after alignment. Defaults to 0.

    Returns:
        None

    Example:
        >>> blend_aligned(bg, img, align="bottom-right", offset_x=-10, offset_y=-10)
    """

    if align == "center" or align == "middle":
        x = (background.width - image.width) // 2
        y = (background.height - image.height) // 2

    elif align == "top":
        x = (background.width - image.width) // 2
        y = 0

    elif align == "bottom":
        x = (background.width - image.width) // 2
        y = background.height - image.height

    elif align == "left":
        x = 0
        y = (background.height - image.height) // 2

    elif align == "right":
        x = background.width - image.width
        y = (background.height - image.height) // 2

    elif align == "top-left":
        x = 0
        y = 0

    elif align == "top-right":
        x = background.width - image.width
        y = 0

    elif align == "bottom-left":
        x = 0
        y = background.height - image.height

    elif align == "bottom-right":
        x = background.width - image.width
        y = background.height - image.height

    else:
        x = (background.width - image.width) // 2
        y = (background.height - image.height) // 2

    x += offset_x
    y += offset_y

    blend(background, image, x, y)