pyimagecuda 0.0.8__cp313-cp313-win_amd64.whl

pyimagecuda/io.py

@@ -0,0 +1,246 @@
+import pyvips
+
+from .pyimagecuda_internal import upload_to_buffer, convert_f32_to_u8, convert_u8_to_f32, download_from_buffer, copy_buffer  #type: ignore
+from .image import Image, ImageU8, ImageBase
+from .utils import ensure_capacity
+
+try:
+    import numpy as np
+except ImportError:
+    np = None
+
+def upload(image: ImageBase, data: bytes | bytearray | memoryview) -> None:
+    """
+    Uploads the image data from a bytes-like object to the GPU.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#direct-uploaddownload
+    """
+    bytes_per_pixel = 4 if isinstance(image, ImageU8) else 16
+    expected = image.width * image.height * bytes_per_pixel
+    actual = data.nbytes if isinstance(data, memoryview) else len(data)
+    
+    if actual != expected:
+        raise ValueError(f"Expected {expected} bytes, got {actual}")
+    
+    upload_to_buffer(image._buffer._handle, data, image.width, image.height)
+
+
+def download(image: ImageBase) -> bytes:
+    """
+    Downloads the image data from the GPU to a bytes object.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#direct-uploaddownload
+    """
+    return download_from_buffer(image._buffer._handle, image.width, image.height)
+
+
+def copy(dst: ImageBase, src: ImageBase) -> None:
+    """
+    Copies image data from the source image to the destination image.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#copy-between-buffers
+    """
+    ensure_capacity(dst, src.width, src.height)
+    copy_buffer(dst._buffer._handle, src._buffer._handle, src.width, src.height)
+
+
+def convert_float_to_u8(dst: ImageU8, src: Image) -> None:
+    """
+    Converts a floating-point image to an 8-bit unsigned integer image.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#manual-conversions
+    """
+    ensure_capacity(dst, src.width, src.height)
+    convert_f32_to_u8(dst._buffer._handle, src._buffer._handle, src.width, src.height)
+
+
+def convert_u8_to_float(dst: Image, src: ImageU8) -> None:
+    """
+    Converts an 8-bit unsigned integer image to a floating-point image.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#manual-conversions
+    """
+    ensure_capacity(dst, src.width, src.height)
+    convert_u8_to_f32(dst._buffer._handle, src._buffer._handle, src.width, src.height)
+
+
+def load(
+    filepath: str, 
+    f32_buffer: Image | None = None, 
+    u8_buffer: ImageU8 | None = None
+) -> Image | None:
+    """
+    Loads an image from a file (returns new image or writes to buffer).
+    
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#loading-images
+    """
+    vips_img = pyvips.Image.new_from_file(filepath, access='sequential')
+
+    if vips_img.bands == 1:
+        vips_img = vips_img.bandjoin([vips_img, vips_img, vips_img])
+        vips_img = vips_img.bandjoin(255)
+    elif vips_img.bands == 3:
+        vips_img = vips_img.bandjoin(255)
+    elif vips_img.bands == 4:
+        pass
+    else:
+        raise ValueError(
+            f"Unsupported image format: {vips_img.bands} channels. "
+            f"Only grayscale (1), RGB (3), and RGBA (4) are supported."
+        )
+    
+    width = vips_img.width
+    height = vips_img.height
+
+    should_return = False
+    
+    if f32_buffer is None:
+        f32_buffer = Image(width, height)
+        should_return = True
+    else:
+        ensure_capacity(f32_buffer, width, height)
+        should_return = False
+
+    if u8_buffer is None:
+        u8_buffer = ImageU8(width, height)
+        owns_u8 = True
+    else:
+        ensure_capacity(u8_buffer, width, height)
+        owns_u8 = False
+
+    vips_img = vips_img.cast('uchar')
+    pixel_data = vips_img.write_to_memory()
+    
+    upload(u8_buffer, pixel_data)
+    
+    convert_u8_to_float(f32_buffer, u8_buffer)
+
+    if owns_u8:
+        u8_buffer.free()
+    
+    return f32_buffer if should_return else None
+
+
+def save(image: Image, filepath: str, u8_buffer: ImageU8 | None = None, quality: int | None = None) -> None:
+    """
+    Saves the floating-point image to a file (using an 8-bit buffer for conversion).
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#saving-images
+    """
+    if u8_buffer is None:
+        u8_buffer = ImageU8(image.width, image.height)
+        owns_buffer = True
+    else:
+        ensure_capacity(u8_buffer, image.width, image.height)
+        owns_buffer = False
+    
+    convert_float_to_u8(u8_buffer, image)
+    pixel_data = download(u8_buffer)
+    
+    vips_img = pyvips.Image.new_from_memory(
+        pixel_data,
+        image.width,
+        image.height,
+        bands=4,
+        format='uchar'
+    )
+    
+    vips_img = vips_img.copy(interpretation='srgb')
+    
+    save_kwargs = {}
+    if quality is not None:
+        if filepath.lower().endswith(('.jpg', '.jpeg')):
+            save_kwargs['Q'] = quality
+        elif filepath.lower().endswith('.webp'):
+            save_kwargs['Q'] = quality
+        elif filepath.lower().endswith(('.heic', '.heif')):
+            save_kwargs['Q'] = quality
+    
+    vips_img.write_to_file(filepath, **save_kwargs)
+    
+    if owns_buffer:
+        u8_buffer.free()
+
+def from_numpy(array, f32_buffer: Image | None = None, u8_buffer: ImageU8 | None = None) -> Image:
+    """
+    Creates a PyImageCUDA Image from a NumPy array (e.g. from OpenCV, Pillow, Matplotlib).
+    
+    - Handles uint8 (0-255) -> float32 (0.0-1.0) conversion automatically on GPU.
+    - Handles Grayscale/RGB -> RGBA expansion automatically.
+    - Optimized: Uploads uint8 data (4x smaller) if possible, then converts on GPU.
+
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#numpy-integration
+    """
+    if np is None:
+        raise ImportError("NumPy is not installed. Run `pip install numpy` to use this feature.")
+
+    if not isinstance(array, np.ndarray):
+        raise TypeError(f"Expected numpy.ndarray, got {type(array)}")
+
+    target_dtype = array.dtype
+
+    if array.ndim == 2:
+        h, w = array.shape
+        alpha_val = 255 if target_dtype == np.uint8 else 1.0
+        alpha_channel = np.full((h, w), alpha_val, dtype=target_dtype)
+        array = np.dstack((array, array, array, alpha_channel))
+
+    elif array.ndim == 3:
+        h, w, c = array.shape
+        if c == 3:
+            alpha_val = 255 if target_dtype == np.uint8 else 1.0
+            alpha_channel = np.full((h, w), alpha_val, dtype=target_dtype)
+            array = np.dstack((array, alpha_channel))
+        elif c != 4:
+            raise ValueError(f"Unsupported channel count: {c}. PyImageCUDA requires 1, 3, or 4 channels.")
+    else:
+        raise ValueError(f"Unsupported array shape: {array.shape}. Expected (H, W), (H, W, 3) or (H, W, 4).")
+
+    if not array.flags['C_CONTIGUOUS']:
+        array = np.ascontiguousarray(array)
+
+    height, width = array.shape[:2]
+
+    should_return = False
+    if f32_buffer is None:
+        f32_buffer = Image(width, height)
+        should_return = True
+    else:
+        ensure_capacity(f32_buffer, width, height)
+
+    if array.dtype == np.uint8:
+        owns_u8 = False
+        if u8_buffer is None:
+            u8_buffer = ImageU8(width, height)
+            owns_u8 = True
+        else:
+            ensure_capacity(u8_buffer, width, height)
+
+        upload(u8_buffer, array.tobytes())
+        convert_u8_to_float(f32_buffer, u8_buffer)
+        
+        if owns_u8:
+            u8_buffer.free()
+
+    elif array.dtype == np.float32:
+        upload(f32_buffer, array.tobytes())
+    else:
+        array = array.astype(np.float32)
+        upload(f32_buffer, array.tobytes())
+
+    return f32_buffer if should_return else None
+
+
+def to_numpy(image: Image) -> 'np.ndarray': # type: ignore
+    """
+    Downloads a PyImageCUDA Image to a NumPy array.
+    
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/io/#numpy-integration
+    """
+    if np is None:
+        raise ImportError("NumPy is not installed. Run `pip install numpy` to use this feature.")
+    
+    raw_bytes = download(image)
+    array = np.frombuffer(raw_bytes, dtype=np.float32)
+    
+    return array.reshape((image.height, image.width, 4))

pyimagecuda/resize.py

@@ -0,0 +1,109 @@
+from .image import Image
+from .utils import ensure_capacity
+from .pyimagecuda_internal import resize_f32  #type: ignore
+from .io import copy
+
+
+def _resize_internal(
+    src: Image,
+    width: int | None,
+    height: int | None,
+    method: int,
+    dst_buffer: Image | None = None
+) -> Image | None:
+    
+    if width is None and height is None:
+        raise ValueError("At least one of width or height must be specified")
+    elif width is None:
+        width = int(src.width * (height / src.height))
+    elif height is None:
+        height = int(src.height * (width / src.width))
+    
+    # No resize needed, just copy
+    if width == src.width and height == src.height:
+        if dst_buffer is None:
+            dst_buffer = Image(width, height)
+            copy(dst_buffer, src)
+            return dst_buffer
+        else:
+            copy(dst_buffer, src)
+            return None
+    
+    # Resize normal
+    if dst_buffer is None:
+        dst_buffer = Image(width, height)
+        return_buffer = True
+    else:
+        ensure_capacity(dst_buffer, width, height)
+        return_buffer = False
+    
+    resize_f32(
+        src._buffer._handle,
+        dst_buffer._buffer._handle,
+        src.width,
+        src.height,
+        width,
+        height,
+        method
+    )
+    
+    return dst_buffer if return_buffer else None
+
+
+class Resize:
+    @staticmethod
+    def nearest(
+        src: Image,
+        width: int | None = None,
+        height: int | None = None,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Resizes the image using nearest neighbor interpolation (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/resize/#nearest
+        """
+        return _resize_internal(src, width, height, 0, dst_buffer)
+
+    @staticmethod
+    def bilinear(
+        src: Image,
+        width: int | None = None,
+        height: int | None = None,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Resizes the image using bilinear interpolation (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/resize/#bilinear
+        """
+
+        return _resize_internal(src, width, height, 1, dst_buffer)
+
+    @staticmethod
+    def bicubic(
+        src: Image,
+        width: int | None = None,
+        height: int | None = None,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Resizes the image using bicubic interpolation (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/resize/#bicubic
+        """
+        return _resize_internal(src, width, height, 2, dst_buffer)
+
+    @staticmethod
+    def lanczos(
+        src: Image,
+        width: int | None = None,
+        height: int | None = None,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Resizes the image using Lanczos interpolation (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/resize/#lanczos
+        """
+        return _resize_internal(src, width, height, 3, dst_buffer)

pyimagecuda/text.py

@@ -0,0 +1,107 @@
+from typing import Literal
+import pyvips
+
+from .image import Image, ImageU8
+from .io import upload, convert_u8_to_float
+from .utils import ensure_capacity
+
+class Text:
+    @staticmethod
+    def create(
+        text: str,
+        font: str = "Sans",
+        size: float = 12.0,
+        color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0),
+        bg_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        align: Literal['left', 'centre', 'right'] = 'left',
+        justify: bool = False,
+        spacing: int = 0,
+        letter_spacing: float = 0.0,
+        dst_buffer: Image | None = None,
+        u8_buffer: ImageU8 | None = None
+    ) -> Image | None:
+        """
+        Renders text into an image with specified font, size, color, alignment, and spacing.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/text/#text-rendering
+        """
+        full_font_string = f"{font} {size}"
+        
+        text_opts = {
+            'font': full_font_string,
+            'dpi': 72,
+            'align': 0 if align == 'left' else (1 if align == 'centre' else 2),
+            'justify': justify,
+            'spacing': spacing
+        }
+        
+        final_text = text
+        if letter_spacing != 0:
+            pango_spacing = int(letter_spacing * 1024)
+            final_text = f'<span letter_spacing="{pango_spacing}">{text}</span>'
+            text_opts['rgba'] = True
+        
+        if '<' in text and '>' in text:
+             text_opts['rgba'] = True
+
+        try:
+            if text_opts.get('rgba'):
+                mask_rgba = pyvips.Image.text(final_text, **text_opts)
+                if mask_rgba.bands == 4:
+                    mask = mask_rgba[3]
+                else:
+                    mask = mask_rgba.colourspace('b-w')[0]
+            else:
+                mask = pyvips.Image.text(final_text, **text_opts)
+                
+        except pyvips.Error as e:
+            raise RuntimeError(f"Failed to render text: {e}")
+
+        fg_r, fg_g, fg_b, fg_a = [int(c * 255) for c in color]
+        bg_r, bg_g, bg_b, bg_a = [int(c * 255) for c in bg_color]
+
+        fg_rgb = mask.new_from_image([fg_r, fg_g, fg_b])
+        
+        if fg_a < 255:
+            fg_alpha = (mask * (fg_a / 255.0)).cast('uchar')
+        else:
+            fg_alpha = mask
+
+        fg_layer = fg_rgb.bandjoin(fg_alpha)
+        fg_layer = fg_layer.copy(interpretation='srgb')
+
+        if bg_a > 0:
+            bg_layer = mask.new_from_image([bg_r, bg_g, bg_b, bg_a])
+            bg_layer = bg_layer.copy(interpretation='srgb')
+            final_vips = bg_layer.composite(fg_layer, 'over')
+        else:
+            final_vips = fg_layer
+
+        final_vips = final_vips.cast('uchar')
+
+        w, h = final_vips.width, final_vips.height
+        raw_bytes = final_vips.write_to_memory()
+
+        if dst_buffer is None:
+            result = Image(w, h)
+            return_result = True
+        else:
+            ensure_capacity(dst_buffer, w, h)
+            result = dst_buffer
+            return_result = False
+
+        if u8_buffer is None:
+            u8_temp = ImageU8(w, h)
+            free_u8 = True
+        else:
+            ensure_capacity(u8_buffer, w, h)
+            u8_temp = u8_buffer
+            free_u8 = False
+        
+        upload(u8_temp, raw_bytes)
+        convert_u8_to_float(result, u8_temp)
+        
+        if free_u8:
+            u8_temp.free()
+
+        return result if return_result else None

pyimagecuda/transform.py

@@ -0,0 +1,196 @@
+import math
+from typing import Literal
+from .image import Image
+from .utils import ensure_capacity
+from .fill import Fill
+from .io import copy
+from .pyimagecuda_internal import ( #type: ignore
+    flip_f32, crop_f32, rotate_fixed_f32, 
+    rotate_arbitrary_f32, copy_buffer 
+)
+
+
+class Transform:
+    
+    @staticmethod
+    def flip(
+        image: Image, 
+        direction: Literal['horizontal', 'vertical', 'both'] = 'horizontal',
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Flips the image across the specified axis (returns new image or writes to buffer).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/transform/#flip
+        """
+        
+        direction_map = {
+            'horizontal': 0,
+            'vertical': 1,
+            'both': 2
+        }
+        
+        mode = direction_map.get(direction)
+        if mode is None:
+            raise ValueError(f"Invalid direction: {direction}. Must be {list(direction_map.keys())}")
+            
+        if dst_buffer is None:
+            dst_buffer = Image(image.width, image.height)
+            return_buffer = True
+        else:
+            ensure_capacity(dst_buffer, image.width, image.height)
+            return_buffer = False
+            
+        flip_f32(
+            image._buffer._handle,
+            dst_buffer._buffer._handle,
+            image.width,
+            image.height,
+            mode
+        )
+        
+        return dst_buffer if return_buffer else None
+
+    @staticmethod
+    def rotate(
+        image: Image,
+        angle: float,
+        expand: bool = True,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Rotates the image by any angle in degrees (Clockwise).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/transform/#rotate
+        """
+        
+        norm_angle = angle % 360
+        if norm_angle < 0: norm_angle += 360
+        
+        is_fixed = False
+        fixed_mode = 0
+        
+        if abs(norm_angle - 0) < 0.01: 
+            if dst_buffer is None:
+                dst_buffer = Image(image.width, image.height)
+                return_buffer = True
+            else:
+                ensure_capacity(dst_buffer, image.width, image.height)
+                return_buffer = False
+            
+            copy_buffer(dst_buffer._buffer._handle, image._buffer._handle, image.width, image.height)
+            return dst_buffer if return_buffer else None
+
+        elif abs(norm_angle - 90) < 0.01: is_fixed = True; fixed_mode = 0
+        elif abs(norm_angle - 180) < 0.01: is_fixed = True; fixed_mode = 1
+        elif abs(norm_angle - 270) < 0.01: is_fixed = True; fixed_mode = 2
+        
+        if is_fixed:
+            if fixed_mode == 1:
+                rot_w, rot_h = image.width, image.height
+            else: 
+                rot_w, rot_h = image.height, image.width
+        else:
+            rads = math.radians(angle)
+            sin_a = abs(math.sin(rads))
+            cos_a = abs(math.cos(rads))
+            rot_w = int(image.width * cos_a + image.height * sin_a)
+            rot_h = int(image.width * sin_a + image.height * cos_a)
+
+        if expand:
+            final_w = rot_w
+            final_h = rot_h
+            offset_x = 0
+            offset_y = 0
+        else:
+            final_w = image.width
+            final_h = image.height
+            offset_x = (final_w - rot_w) // 2
+            offset_y = (final_h - rot_h) // 2
+
+        if dst_buffer is None:
+            dst_buffer = Image(final_w, final_h)
+            return_buffer = True
+        else:
+            ensure_capacity(dst_buffer, final_w, final_h)
+            return_buffer = False
+
+        if is_fixed:
+            rotate_fixed_f32(
+                image._buffer._handle,
+                dst_buffer._buffer._handle,
+                image.width, image.height,
+                final_w, final_h,
+                fixed_mode, offset_x, offset_y
+            )
+        else:
+            rotate_arbitrary_f32(
+                image._buffer._handle,
+                dst_buffer._buffer._handle,
+                image.width, image.height,
+                final_w, final_h,
+                float(angle)
+            )
+        
+        return dst_buffer if return_buffer else None
+
+    @staticmethod
+    def crop(
+        image: Image,
+        x: int,
+        y: int,
+        width: int,
+        height: int,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Crops a rectangular region (returns new image or writes to buffer).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/transform/#crop
+        """
+        if width <= 0 or height <= 0:
+            raise ValueError("Crop dimensions must be positive")
+
+        if x == 0 and y == 0 and width == image.width and height == image.height:
+            if dst_buffer is None:
+                dst_buffer = Image(width, height)
+                copy(dst_buffer, image)
+                return dst_buffer
+            else:
+                copy(dst_buffer, image)
+                return None
+
+        if dst_buffer is None:
+            dst_buffer = Image(width, height)
+            return_buffer = True
+        else:
+            ensure_capacity(dst_buffer, width, height)
+            return_buffer = False
+
+        Fill.color(dst_buffer, (0.0, 0.0, 0.0, 0.0))
+
+        crop_left = x
+        crop_top = y
+        crop_right = x + width
+        crop_bottom = y + height
+        img_right, img_bottom = image.width, image.height
+        
+        intersect_left = max(crop_left, 0)
+        intersect_top = max(crop_top, 0)
+        intersect_right = min(crop_right, img_right)
+        intersect_bottom = min(crop_bottom, img_bottom)
+        
+        copy_w = intersect_right - intersect_left
+        copy_h = intersect_bottom - intersect_top
+        
+        if copy_w > 0 and copy_h > 0:
+            crop_f32(
+                image._buffer._handle,
+                dst_buffer._buffer._handle,
+                image.width, dst_buffer.width,
+                intersect_left, intersect_top,
+                intersect_left - crop_left, intersect_top - crop_top,
+                copy_w, copy_h
+            )
+            
+        return dst_buffer if return_buffer else None

pyimagecuda/utils.py

@@ -0,0 +1,17 @@
+from .image import ImageBase
+
+def ensure_capacity(buffer: ImageBase, required_width: int, required_height: int) -> None:
+    """
+    Checks if the buffer has enough capacity and updates its logical dimensions.
+    Raises ValueError if capacity is insufficient.
+    """
+    max_w, max_h = buffer.get_max_capacity()
+    
+    if required_width > max_w or required_height > max_h:
+        raise ValueError(
+            f"Buffer capacity too small: need {required_width}×{required_height}, "
+            f"got capacity {max_w}×{max_h}"
+        )
+    
+    buffer.width = required_width
+    buffer.height = required_height