pyimagecuda 0.1.0__cp311-cp311-win_amd64.whl

pyimagecuda/fill.py

@@ -0,0 +1,263 @@
+from typing import Literal
+from .image import Image
+from .pyimagecuda_internal import (fill_color_f32, #type: ignore
+                                   fill_gradient_f32,
+                                   fill_circle_f32,
+                                   fill_checkerboard_f32,
+                                   fill_grid_f32,
+                                   fill_stripes_f32,
+                                   fill_dots_f32,
+                                   fill_noise_f32,
+                                   fill_perlin_f32,
+                                   fill_ngon_f32
+                                   )
+
+
+class Fill:
+    
+    @staticmethod
+    def color(image: Image, rgba: tuple[float, float, float, float]) -> None:
+        """
+        Fills the image with a solid color (in-place).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#solid-colors
+        """
+        fill_color_f32(image._buffer._handle, rgba, image.width, image.height)
+    
+    @staticmethod
+    def gradient(image: Image, 
+                 rgba1: tuple[float, float, float, float],
+                 rgba2: tuple[float, float, float, float],
+                 direction: Literal['horizontal', 'vertical', 'diagonal', 'radial'] = 'horizontal',
+                 seamless: bool = False) -> None:
+        """
+        Fills the image with a gradient (in-place).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#gradients
+        """
+        direction_map = {
+            'horizontal': 0,
+            'vertical': 1,
+            'diagonal': 2,
+            'radial': 3
+        }
+        
+        dir_int = direction_map.get(direction)
+        if dir_int is None:
+            raise ValueError(f"Invalid direction: {direction}. Must be one of {list(direction_map.keys())}")
+        
+        fill_gradient_f32(
+            image._buffer._handle, 
+            rgba1, 
+            rgba2, 
+            image.width, 
+            image.height, 
+            dir_int,
+            seamless
+        )
+
+    @staticmethod
+    def checkerboard(
+        image: Image,
+        size: int = 20,
+        color1: tuple[float, float, float, float] = (0.8, 0.8, 0.8, 1.0),
+        color2: tuple[float, float, float, float] = (0.5, 0.5, 0.5, 1.0),
+        offset_x: int = 0,
+        offset_y: int = 0
+    ) -> None:
+        """
+        Fills buffer with a checkerboard pattern.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#checkerboard
+        """
+        if size <= 0:
+            raise ValueError("Checkerboard size must be positive")
+        
+        fill_checkerboard_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            int(size),
+            int(offset_x), int(offset_y),
+            color1, color2
+        )
+
+    @staticmethod
+    def grid(
+        image: Image,
+        spacing: int = 50,
+        line_width: int = 1,
+        color: tuple[float, float, float, float] = (0.5, 0.5, 0.5, 1.0),
+        bg_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        offset_x: int = 0,
+        offset_y: int = 0
+    ) -> None:
+        """
+        Fills buffer with a grid pattern.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#grid
+        """
+        if spacing <= 0:
+            raise ValueError("Grid spacing must be positive")
+        if line_width <= 0:
+            raise ValueError("Line width must be positive")
+        
+        fill_grid_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            int(spacing), int(line_width),
+            int(offset_x), int(offset_y),
+            color, bg_color
+        )
+
+    @staticmethod
+    def stripes(
+        image: Image,
+        angle: float = 45.0,
+        spacing: int = 40,
+        width: int = 20,
+        color1: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
+        color2: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        offset: int = 0
+    ) -> None:
+        """
+        Fills buffer with alternating stripes with Anti-Aliasing.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#stripes
+        """
+        if spacing <= 0:
+            raise ValueError("Stripes spacing must be positive")
+        
+        fill_stripes_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            float(angle), int(spacing), int(width), int(offset),
+            color1, color2
+        )
+
+    @staticmethod
+    def dots(
+        image: Image,
+        spacing: int = 40,
+        radius: float = 10.0,
+        color: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
+        bg_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        offset_x: int = 0,
+        offset_y: int = 0,
+        softness: float = 0.0
+    ) -> None:
+        """
+        Fills buffer with a Polka Dot pattern.
+        - softness: 0.0 = Hard edge, 1.0 = Soft glow.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#dots
+        """
+        if spacing <= 0:
+            raise ValueError("Spacing must be positive")
+
+        fill_dots_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            int(spacing), float(radius), 
+            int(offset_x), int(offset_y), float(softness),
+            color, bg_color
+        )
+
+    @staticmethod
+    def circle(
+        image: Image,
+        color: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
+        bg_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        softness: float = 0.0
+    ) -> None:
+        """
+        Fills the buffer with a centered circle fitted to the image size.
+        - softness: Edge softness. 0.0 = Hard edge (with AA), >0.0 = Soft gradient.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#circle
+        """
+
+        fill_circle_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            float(softness),
+            color, bg_color
+        )
+
+    @staticmethod
+    def noise(
+        image: Image,
+        seed: float = 0.0,
+        monochrome: bool = True
+    ) -> None:
+        """
+        Fills the buffer with random White Noise.
+        - seed: Random seed. Change this to animate the noise.
+        - monochrome: True for grayscale noise, False for RGB noise.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#noise
+        """
+        
+        fill_noise_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            float(seed),
+            int(monochrome)
+        )
+
+    @staticmethod
+    def perlin(
+        image: Image,
+        scale: float = 50.0,
+        seed: float = 0.0,
+        octaves: int = 1,
+        persistence: float = 0.5,
+        lacunarity: float = 2.0,
+        offset_x: float = 0.0,
+        offset_y: float = 0.0,
+        color1: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0),
+        color2: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0)
+    ) -> None:
+        """
+        Fills buffer with Perlin Noise (Gradient Noise).
+        - scale: "Zoom" level. Higher values = bigger features (zoomed in).
+        - octaves: Detail layers. 1 = smooth, 6 = rocky/detailed.
+        - persistence: How much each octave contributes (0.0 to 1.0).
+        - lacunarity: Detail frequency multiplier (usually 2.0).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#perlin-noise
+        """
+        if scale <= 0: scale = 0.001
+        
+        fill_perlin_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            float(scale), float(seed),
+            int(octaves), float(persistence), float(lacunarity),
+            float(offset_x), float(offset_y),
+            color1, color2
+        )
+
+    @staticmethod
+    def ngon(
+        image: Image,
+        sides: int = 3,
+        color: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 1.0),
+        bg_color: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+        rotation: float = 0.0,
+        softness: float = 0.0
+    ) -> None:
+        """
+        Fills buffer with a Regular Polygon (Triangle, Pentagon, Hexagon...).
+        - softness: Edge softness (0.0 = Hard AA, >0.0 = Glow).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/fill/#ngon
+        """
+        if sides < 3:
+            raise ValueError("Polygon must have at least 3 sides")
+
+        fill_ngon_f32(
+            image._buffer._handle,
+            image.width, image.height,
+            int(sides), float(rotation), float(softness),
+            color, bg_color
+        )

pyimagecuda/filter.py

@@ -0,0 +1,199 @@
+from .image import Image
+from .io import copy
+from .pyimagecuda_internal import ( #type: ignore
+    gaussian_blur_separable_f32,
+    sharpen_f32,
+    sepia_f32,
+    invert_f32,
+    threshold_f32,
+    solarize_f32,
+    filter_sobel_f32,
+    filter_emboss_f32
+)
+
+
+class Filter:
+
+    @staticmethod
+    def gaussian_blur(
+        src: Image,
+        radius: int = 3,
+        sigma: float | None = None,
+        dst_buffer: Image | None = None,
+        temp_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Applies a Gaussian blur to the image (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#gaussian-blur
+        """
+
+        if radius == 0 or (sigma is not None and sigma <= 0.001):
+            if dst_buffer is None:
+                dst_buffer = Image(src.width, src.height)
+                copy(dst_buffer, src)
+                return dst_buffer
+            else:
+                copy(dst_buffer, src)
+                return None
+
+        if sigma is None:
+            sigma = radius / 3.0
+        
+        if dst_buffer is None:
+            dst_buffer = Image(src.width, src.height)
+            return_dst = True
+        else:
+            dst_buffer.resize(src.width, src.height)
+            return_dst = False
+
+        if temp_buffer is None:
+            temp_buffer = Image(src.width, src.height)
+            owns_temp = True
+        else:
+            temp_buffer.resize(src.width, src.height)
+            owns_temp = False
+
+        gaussian_blur_separable_f32(
+            src._buffer._handle,
+            temp_buffer._buffer._handle,
+            dst_buffer._buffer._handle,
+            src.width,
+            src.height,
+            radius,
+            float(sigma)
+        )
+
+        if owns_temp:
+            temp_buffer.free()
+        
+        return dst_buffer if return_dst else None
+
+    @staticmethod
+    def sharpen(
+        src: Image,
+        strength: float = 1.0,
+        dst_buffer: Image | None = None
+    ) -> Image | None:
+        """
+        Sharpens the image (returns new image or writes to buffer).
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#sharpen
+        """
+
+        if abs(strength) < 1e-6:
+            if dst_buffer is None:
+                dst_buffer = Image(src.width, src.height)
+                copy(dst_buffer, src)
+                return dst_buffer
+            else:
+                copy(dst_buffer, src)
+                return None
+
+        if dst_buffer is None:
+            dst_buffer = Image(src.width, src.height)
+            return_buffer = True
+        else:
+            dst_buffer.resize(src.width, src.height)
+            return_buffer = False
+        
+        sharpen_f32(
+            src._buffer._handle,
+            dst_buffer._buffer._handle,
+            src.width,
+            src.height,
+            float(strength)
+        )
+        
+        return dst_buffer if return_buffer else None
+
+    @staticmethod
+    def sepia(image: Image, intensity: float = 1.0) -> None:
+        """
+        Applies Sepia tone (in-place).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#sepia
+        """
+        if abs(intensity) < 1e-6:
+            return
+        
+        sepia_f32(image._buffer._handle, image.width, image.height, float(intensity))
+
+    @staticmethod
+    def invert(image: Image) -> None:
+        """
+        Inverts colors (Negative effect) in-place.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#invert
+        """
+        invert_f32(image._buffer._handle, image.width, image.height)
+
+    @staticmethod
+    def threshold(image: Image, value: float = 0.5) -> None:
+        """
+        Converts to pure Black & White based on luminance threshold.
+        value: 0.0 to 1.0. Pixels brighter than value become white, others black.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#threshold
+        """
+        threshold_f32(image._buffer._handle, image.width, image.height, float(value))
+
+    @staticmethod
+    def solarize(image: Image, threshold: float = 0.5) -> None:
+        """
+        Inverts only pixels brighter than threshold. Creates a psychedelic/retro look.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#solarize
+        """
+        solarize_f32(image._buffer._handle, image.width, image.height, float(threshold))
+
+    @staticmethod
+    def sobel(src: Image, dst_buffer: Image | None = None) -> Image | None:
+        """
+        Detects edges using Sobel operator. Returns a black & white image with edges.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#sobel
+        """
+        if dst_buffer is None:
+            dst_buffer = Image(src.width, src.height)
+            return_buffer = True
+        else:
+            dst_buffer.resize(src.width, src.height)
+            return_buffer = False
+
+        filter_sobel_f32(
+            src._buffer._handle,
+            dst_buffer._buffer._handle,
+            src.width, src.height
+        )
+        return dst_buffer if return_buffer else None
+
+    @staticmethod
+    def emboss(src: Image, strength: float = 1.0, dst_buffer: Image | None = None) -> Image | None:
+        """
+        Applies Emboss (Relief) effect.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/filter/#emboss
+        """
+        if abs(strength) < 1e-6:
+            if dst_buffer is None:
+                dst_buffer = Image(src.width, src.height)
+                copy(dst_buffer, src)
+                return dst_buffer
+            else:
+                copy(dst_buffer, src)
+                return None
+
+        if dst_buffer is None:
+            dst_buffer = Image(src.width, src.height)
+            return_buffer = True
+        else:
+            dst_buffer.resize(src.width, src.height)
+            return_buffer = False
+        
+        filter_emboss_f32(
+            src._buffer._handle,
+            dst_buffer._buffer._handle,
+            src.width, src.height, float(strength)
+        )
+        return dst_buffer if return_buffer else None

pyimagecuda/gl_interop.py

@@ -0,0 +1,84 @@
+from .pyimagecuda_internal import (  # type: ignore
+    register_gl_pbo,
+    unregister_gl_resource,
+    copy_to_gl_pbo
+)
+from .image import ImageU8
+
+
+class GLResource:
+    """
+    CUDA-OpenGL interop resource for direct GPU-to-GPU transfers.
+    
+    Represents a registered OpenGL PBO that can receive ImageU8 data
+    directly without CPU roundtrips.
+    
+    Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+    """
+    
+    def __init__(self, pbo_id: int):
+        """
+        Parameters:
+            pbo_id: Valid OpenGL PBO ID. The PBO must exist and remain 
+                    valid for the lifetime of this GLResource.
+        
+        Raises:
+            ValueError: If pbo_id is invalid
+            RuntimeError: If CUDA registration fails
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if not isinstance(pbo_id, int) or pbo_id <= 0:
+            raise ValueError(f"Invalid PBO ID: {pbo_id}")
+        
+        self._handle = None
+        self.pbo_id = pbo_id
+        self._handle = register_gl_pbo(pbo_id)
+    
+    def copy_from(self, image: ImageU8, sync: bool = True) -> None:
+        """
+        Copies ImageU8 data directly to the registered PBO (GPU→GPU).
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if not isinstance(image, ImageU8):
+            raise TypeError(f"Expected ImageU8, got {type(image).__name__}")
+        
+        if self._handle is None:
+            raise RuntimeError("GLResource has been freed")
+        
+        copy_to_gl_pbo(
+            image._buffer._handle,
+            self._handle,
+            image.width,
+            image.height,
+            sync
+        )
+    
+    def free(self) -> None:
+        """
+        Unregisters the OpenGL resource from CUDA.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/opengl/
+        """
+        if self._handle is not None:
+            unregister_gl_resource(self._handle)
+            self._handle = None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.free()
+        return False
+    
+    def __del__(self):
+        if hasattr(self, '_handle') and self._handle is not None:
+            try:
+                self.free()
+            except Exception:
+                pass
+    
+    def __repr__(self) -> str:
+        status = "active" if getattr(self, '_handle', None) is not None else "freed"
+        return f"GLResource(pbo_id={self.pbo_id}, status={status})"

pyimagecuda/image.py

@@ -0,0 +1,121 @@
+from .pyimagecuda_internal import create_buffer_f32, free_buffer, create_buffer_u8  #type: ignore
+
+class Buffer:
+    
+    def __init__(self, width: int, height: int, is_u8: bool = False):
+        create_func = create_buffer_u8 if is_u8 else create_buffer_f32
+        self._handle = create_func(width, height)
+        self.capacity_pixels = width * height
+    
+    def free(self) -> None:
+        free_buffer(self._handle)
+
+
+class ImageBase:
+
+    def __init__(self, width: int, height: int, is_u8: bool = False):
+        self._buffer = Buffer(width, height, is_u8)
+        self._width = width
+        self._height = height
+    
+    @property
+    def width(self) -> int:
+        return self._width
+    
+    @width.setter
+    def width(self, value: int) -> None:
+        value = int(value)
+        if value <= 0:
+            raise ValueError(f"Width must be positive, got {value}")
+
+        if value * self._height > self._buffer.capacity_pixels:
+            raise ValueError(
+                f"Dimensions {value}×{self._height} exceed buffer capacity "
+                f"({self._buffer.capacity_pixels:,} pixels)"
+            )
+        
+        self._width = value
+    
+    @property
+    def height(self) -> int:
+        return self._height
+    
+    @height.setter
+    def height(self, value: int) -> None:
+        value = int(value)
+        if value <= 0:
+            raise ValueError(f"Height must be positive, got {value}")
+        
+        if self._width * value > self._buffer.capacity_pixels:
+            raise ValueError(
+                f"Dimensions {self._width}×{value} exceed buffer capacity "
+                f"({self._buffer.capacity_pixels:,} pixels)"
+            )
+        
+        self._height = value
+
+    def resize(self, width: int, height: int) -> None:
+        """
+        Sets both width and height atomically with proper validation.
+        
+        Recommended when changing aspect ratio to avoid temporary invalid states.
+        
+        Example:
+            img = Image(1920, 1080)
+            img.resize(3840, 540)  # Changes aspect ratio safely
+        
+        Note: This not change image data, only dimensions.
+        """
+        width = int(width)
+        height = int(height)
+        
+        if width <= 0 or height <= 0:
+            raise ValueError(f"Dimensions must be positive, got {width}×{height}")
+        
+        total_pixels = width * height
+        if total_pixels > self._buffer.capacity_pixels:
+            raise ValueError(
+                f"Dimensions {width}×{height} ({total_pixels:,} pixels) "
+                f"exceed buffer capacity ({self._buffer.capacity_pixels:,} pixels)"
+            )
+        
+        self._width = width
+        self._height = height
+
+    def get_max_capacity(self) -> int:
+        """Returns the total pixel capacity of the buffer."""
+        return self._buffer.capacity_pixels
+
+    def free(self) -> None:
+        self._buffer.free()
+
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.free()
+        return False
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.width}×{self.height})"
+
+class Image(ImageBase):
+    
+    def __init__(self, width: int, height: int):
+        """
+        Creates a floating-point image with the given width and height.
+        
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/image/#image-float32-precision
+        """
+        super().__init__(width, height, is_u8=False)
+
+
+class ImageU8(ImageBase):
+    
+    def __init__(self, width: int, height: int):
+        """
+        Creates an 8-bit unsigned integer image with the given width and height.
+
+        Docs & Examples: https://offerrall.github.io/pyimagecuda/image/#imageu8-8-bit-precision
+        """
+        super().__init__(width, height, is_u8=True)