deckbuilder 1.0.0b1__py3-none-any.whl

placekitten/core.py

@@ -0,0 +1,184 @@
+"""
+PlaceKitten Core - Main PlaceKitten class for placeholder image generation.
+
+This module provides the main PlaceKitten class that handles image generation
+from existing kitten images with dimension management and basic functionality.
+"""
+
+import random
+from pathlib import Path
+from typing import List, Optional
+
+from .processor import ImageProcessor
+
+
+class PlaceKitten:
+    """
+    Main PlaceKitten class for generating placeholder images from kitten photos.
+
+    Provides basic image generation with dimension handling, supporting both
+    auto-height 16:9 aspect ratio and custom dimensions.
+    """
+
+    def __init__(self, source_folder: str = "demo"):
+        """
+        Initialize PlaceKitten with source image folder.
+
+        Args:
+            source_folder: Folder name containing source images (relative to assets/images/)
+        """
+        self.source_folder = source_folder
+        self._image_cache = None
+        self._setup_image_paths()
+
+    def _setup_image_paths(self) -> None:
+        """Setup paths to kitten images."""
+        # Get placekitten module directory (this file's parent)
+        placekitten_module = Path(__file__).parent
+
+        if self.source_folder == "demo":
+            # Use the images folder within placekitten module for demo mode
+            self.images_path = placekitten_module / "images"
+        else:
+            # Use custom source folder within placekitten module
+            self.images_path = placekitten_module / "images" / self.source_folder
+
+        if not self.images_path.exists():
+            raise RuntimeError(f"Image source folder not found: {self.images_path}")
+
+    def _get_available_images(self) -> List[Path]:
+        """Get list of available image files."""
+        if self._image_cache is None:
+            # Cache the image list for performance
+            image_extensions = {".png", ".jpg", ".jpeg", ".webp"}
+            self._image_cache = sorted(
+                [
+                    img
+                    for img in self.images_path.iterdir()
+                    if img.is_file() and img.suffix.lower() in image_extensions
+                ]
+            )
+
+        if not self._image_cache:
+            raise RuntimeError(f"No images found in {self.images_path}")
+
+        return self._image_cache
+
+    def _calculate_height(self, width: int) -> int:
+        """Calculate height for 16:9 aspect ratio."""
+        return int(width * 9 / 16)
+
+    def generate(
+        self,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        filter_type: Optional[str] = None,
+        image_id: Optional[int] = None,
+        random_selection: bool = False,
+    ) -> ImageProcessor:
+        """
+        Generate placeholder image with specified dimensions.
+
+        Args:
+            width: Image width in pixels (optional - scales from height if only height given)
+            height: Image height in pixels (optional - scales from width if only width given)
+            filter_type: Filter to apply (e.g., "sepia", "grayscale")
+            image_id: Specific image ID to use (1-based index, uses random if invalid/None)
+            random_selection: Force random image selection (overrides image_id)
+
+        Returns:
+            ImageProcessor instance for further manipulation
+        """
+
+        # Get available images
+        available_images = self._get_available_images()
+
+        # Select image (using 1-based indexing, random for invalid/None)
+        if random_selection:
+            selected_image = random.choice(available_images)  # nosec
+        elif image_id is not None and 1 <= image_id <= len(available_images):
+            selected_image = available_images[image_id - 1]  # Convert to 0-based index
+        else:
+            # Use random for None or out-of-range image_id
+            selected_image = random.choice(available_images)  # nosec
+
+        # Create ImageProcessor with the selected image
+        processor = ImageProcessor(str(selected_image))
+
+        # Handle dimensions - preserve aspect ratio or use original size
+        if width is None and height is None:
+            # Return full size image - no resizing
+            pass
+        elif width is not None and height is not None:
+            # Both specified - resize to exact dimensions
+            processor = processor.resize(width, height)
+        elif width is not None:
+            # Only width specified - calculate height preserving aspect ratio
+            original_width, original_height = processor.get_size()
+            aspect_ratio = original_height / original_width
+            calculated_height = int(width * aspect_ratio)
+            processor = processor.resize(width, calculated_height)
+        elif height is not None:
+            # Only height specified - calculate width preserving aspect ratio
+            original_width, original_height = processor.get_size()
+            aspect_ratio = original_width / original_height
+            calculated_width = int(height * aspect_ratio)
+            processor = processor.resize(calculated_width, height)
+
+        # Apply filter if specified
+        if filter_type:
+            processor = processor.apply_filter(filter_type)
+
+        return processor
+
+    def list_available_images(self) -> List[str]:
+        """
+        Get list of available image filenames.
+
+        Returns:
+            List of image filenames
+        """
+        images = self._get_available_images()
+        return [img.name for img in images]
+
+    def get_image_count(self) -> int:
+        """
+        Get count of available images.
+
+        Returns:
+            Number of available images
+        """
+        return len(self._get_available_images())
+
+    def batch_process(self, configs: List[dict], output_folder: str = "output") -> List[str]:
+        """
+        Process multiple images in batch.
+
+        Args:
+            configs: List of configuration dictionaries with width, height, etc.
+            output_folder: Output folder for generated images
+
+        Returns:
+            List of generated file paths
+        """
+        results = []
+
+        # Ensure output folder exists
+        output_path = Path(output_folder)
+        output_path.mkdir(parents=True, exist_ok=True)
+
+        for i, config in enumerate(configs):
+            # Generate image with config
+            processor = self.generate(**config)
+
+            # Generate filename
+            width = config.get("width", 500)
+            height = config.get("height", self._calculate_height(width))
+            filename = f"placekitten_{width}x{height}_{i + 1}.jpg"
+
+            # Save image
+            output_file = output_path / filename
+            result = processor.save(str(output_file))
+            results.append(result)
+
+        return results

placekitten/filters.py

@@ -0,0 +1,183 @@
+"""
+Filters - Image filter pipeline and effect implementations.
+
+This module provides a comprehensive set of image filters and effects
+for the PlaceKitten library with easy extensibility.
+"""
+
+from typing import Callable, Dict
+
+import PIL.ImageOps
+from PIL import Image, ImageEnhance, ImageFilter
+
+
+class FilterRegistry:
+    """Registry for image filters with extensible architecture."""
+
+    def __init__(self):
+        """Initialize filter registry with built-in filters."""
+        self._filters: Dict[str, Callable] = {}
+        self._register_builtin_filters()
+
+    def _register_builtin_filters(self) -> None:
+        """Register all built-in filters."""
+        # Basic filters
+        self.register("grayscale", self._grayscale)
+        self.register("greyscale", self._grayscale)  # Alternative spelling
+        self.register("blur", self._blur)
+        self.register("sepia", self._sepia)
+        self.register("invert", self._invert)
+
+        # Enhancement filters
+        self.register("brightness", self._brightness)
+        self.register("contrast", self._contrast)
+        self.register("saturation", self._saturation)
+        self.register("sharpness", self._sharpness)
+
+        # Effect filters
+        self.register("pixelate", self._pixelate)
+        self.register("edge_detection", self._edge_detection)
+        self.register("emboss", self._emboss)
+        self.register("smooth", self._smooth)
+
+    def register(self, name: str, filter_func: Callable) -> None:
+        """
+        Register a new filter.
+
+        Args:
+            name: Filter name
+            filter_func: Filter function that takes (image, **kwargs)
+        """
+        self._filters[name] = filter_func
+
+    def apply(self, image: Image.Image, filter_name: str, **kwargs) -> Image.Image:
+        """
+        Apply filter to image.
+
+        Args:
+            image: PIL Image to process
+            filter_name: Name of filter to apply
+            **kwargs: Filter-specific parameters
+
+        Returns:
+            Processed PIL Image
+        """
+        if filter_name not in self._filters:
+            available = ", ".join(self._filters.keys())
+            raise ValueError(f"Unknown filter '{filter_name}'. Available: {available}")
+
+        return self._filters[filter_name](image, **kwargs)
+
+    def list_filters(self) -> list:
+        """Get list of available filter names."""
+        return list(self._filters.keys())
+
+    # Built-in filter implementations
+
+    def _grayscale(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Convert image to grayscale."""
+        return image.convert("L").convert("RGB")
+
+    def _blur(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply Gaussian blur."""
+        strength = kwargs.get("strength", 5)
+        return image.filter(ImageFilter.GaussianBlur(radius=strength))
+
+    def _sepia(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply sepia tone effect."""
+        # Sepia transformation matrix
+        sepia_filter = (0.393, 0.769, 0.189, 0, 0.349, 0.686, 0.168, 0, 0.272, 0.534, 0.131, 0)
+        return image.convert("RGB", sepia_filter)
+
+    def _invert(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Invert image colors."""
+        return PIL.ImageOps.invert(image)
+
+    def _brightness(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Adjust image brightness."""
+        value = kwargs.get("value", 100)  # 100 = no change
+        factor = value / 100.0
+        enhancer = ImageEnhance.Brightness(image)
+        return enhancer.enhance(factor)
+
+    def _contrast(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Adjust image contrast."""
+        value = kwargs.get("value", 100)  # 100 = no change
+        factor = value / 100.0
+        enhancer = ImageEnhance.Contrast(image)
+        return enhancer.enhance(factor)
+
+    def _saturation(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Adjust image saturation."""
+        value = kwargs.get("value", 100)  # 100 = no change
+        factor = value / 100.0
+        enhancer = ImageEnhance.Color(image)
+        return enhancer.enhance(factor)
+
+    def _sharpness(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Adjust image sharpness."""
+        value = kwargs.get("value", 100)  # 100 = no change
+        factor = value / 100.0
+        enhancer = ImageEnhance.Sharpness(image)
+        return enhancer.enhance(factor)
+
+    def _pixelate(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply pixelation effect."""
+        strength = kwargs.get("strength", 5)
+        width, height = image.size
+
+        # Resize down and back up for pixelation
+        small_size = (max(1, width // strength), max(1, height // strength))
+        pixelated = image.resize(small_size, Image.Resampling.NEAREST)
+        return pixelated.resize((width, height), Image.Resampling.NEAREST)
+
+    def _edge_detection(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply edge detection filter."""
+        return image.filter(ImageFilter.FIND_EDGES)
+
+    def _emboss(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply emboss effect."""
+        return image.filter(ImageFilter.EMBOSS)
+
+    def _smooth(self, image: Image.Image, **kwargs) -> Image.Image:
+        """Apply smoothing filter."""
+        strength = kwargs.get("strength", 1)
+        for _ in range(strength):
+            image = image.filter(ImageFilter.SMOOTH)
+        return image
+
+
+# Global filter registry instance
+filter_registry = FilterRegistry()
+
+
+# Convenience functions for direct filter access
+def apply_filter(image: Image.Image, filter_name: str, **kwargs) -> Image.Image:
+    """
+    Apply filter to image using global registry.
+
+    Args:
+        image: PIL Image to process
+        filter_name: Name of filter to apply
+        **kwargs: Filter-specific parameters
+
+    Returns:
+        Processed PIL Image
+    """
+    return filter_registry.apply(image, filter_name, **kwargs)
+
+
+def list_available_filters() -> list:
+    """Get list of all available filters."""
+    return filter_registry.list_filters()
+
+
+def register_custom_filter(name: str, filter_func: Callable) -> None:
+    """
+    Register a custom filter.
+
+    Args:
+        name: Filter name
+        filter_func: Filter function that takes (image, **kwargs)
+    """
+    filter_registry.register(name, filter_func)

placekitten/processor.py

@@ -0,0 +1,262 @@
+"""
+ImageProcessor - Core image manipulation and processing functionality.
+
+This module provides the ImageProcessor class for image loading, resizing,
+filtering, and saving with method chaining support.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+from PIL import Image
+
+from .filters import apply_filter
+from .smart_crop import smart_crop_engine
+
+
+class ImageProcessor:
+    """
+    Image processing class with method chaining support.
+
+    Handles image loading, manipulation, filtering, and saving operations
+    with a fluent interface for complex processing pipelines.
+    """
+
+    def __init__(self, image_path: Optional[str] = None, image_array: Optional[np.ndarray] = None):
+        """
+        Initialize ImageProcessor with image file or numpy array.
+
+        Args:
+            image_path: Path to image file
+            image_array: NumPy array containing image data
+        """
+        if image_path is not None:
+            self.image = Image.open(image_path)
+            self.source_path = image_path
+        elif image_array is not None:
+            self.image = Image.fromarray(image_array)
+            self.source_path = None
+        else:
+            raise ValueError("Must provide either image_path or image_array")
+
+        # Ensure RGB mode for consistent processing
+        if self.image.mode != "RGB":
+            self.image = self.image.convert("RGB")
+
+    def resize(self, width: int, height: Optional[int] = None) -> "ImageProcessor":
+        """
+        Resize image maintaining aspect ratio or to specific dimensions.
+
+        Args:
+            width: Target width in pixels
+            height: Target height in pixels (maintains aspect ratio if None)
+
+        Returns:
+            New ImageProcessor instance with resized image
+        """
+        if height is None:
+            # Maintain aspect ratio when height not specified
+            aspect_ratio = self.image.height / self.image.width
+            height = int(width * aspect_ratio)
+
+        # Use high-quality resampling with both dimensions
+        resized_image = self.image.resize((width, height), Image.Resampling.LANCZOS)
+
+        # Create new processor instance
+        new_processor = ImageProcessor.__new__(ImageProcessor)
+        new_processor.image = resized_image
+        new_processor.source_path = self.source_path
+
+        return new_processor
+
+    def apply_filter(self, filter_name: str, **kwargs) -> "ImageProcessor":
+        """
+        Apply image filter using the filter registry.
+
+        Args:
+            filter_name: Name of filter to apply
+            **kwargs: Filter-specific parameters
+
+        Returns:
+            New ImageProcessor instance with filter applied
+        """
+        # Use the centralized filter registry
+        filtered_image = apply_filter(self.image.copy(), filter_name, **kwargs)
+
+        # Create new processor instance
+        new_processor = ImageProcessor.__new__(ImageProcessor)
+        new_processor.image = filtered_image
+        new_processor.source_path = self.source_path
+
+        return new_processor
+
+    def smart_crop(
+        self,
+        width: int,
+        height: Optional[int] = None,
+        save_steps: bool = False,
+        output_prefix: str = "smart_crop",
+        output_folder: Optional[str] = None,
+        strategy: str = "haar-face",
+    ) -> "ImageProcessor":
+        """
+        Intelligent cropping with computer vision.
+
+        Uses advanced computer vision techniques including:
+        - Edge detection with Canny algorithm
+        - Contour analysis for subject identification
+        - Rule-of-thirds composition optimization
+        - Haar cascade face detection for face-priority cropping
+        - Step-by-step visualization (optional)
+
+        Args:
+            width: Target width
+            height: Target height (16:9 if None)
+            save_steps: Save intermediate processing steps for debugging
+            output_prefix: Prefix for debug step files
+            output_folder: Directory to save step files (optional)
+            strategy: Cropping strategy to use ("haar-face", "contour", etc.)
+
+        Returns:
+            New ImageProcessor instance with intelligently cropped image
+        """
+        if height is None:
+            height = int(width * 9 / 16)
+
+        try:
+            # Use the smart crop engine for intelligent processing
+            cropped_image, crop_info = smart_crop_engine.smart_crop(
+                self.image, width, height, save_steps, output_prefix, output_folder, strategy
+            )
+
+            # Create new processor instance
+            new_processor = ImageProcessor.__new__(ImageProcessor)
+            new_processor.image = cropped_image
+            new_processor.source_path = self.source_path
+            new_processor.crop_info = crop_info  # Store crop metadata
+
+            return new_processor
+
+        except Exception as e:
+            # Fallback to simple center crop if OpenCV fails
+            print(f"⚠️  Smart crop failed ({e}), falling back to center crop")
+            return self._fallback_center_crop(width, height)
+
+    def _fallback_center_crop(self, width: int, height: int) -> "ImageProcessor":
+        """Fallback center crop implementation."""
+        img_width, img_height = self.image.size
+
+        # Calculate scaling to fit target aspect ratio
+        target_ratio = width / height
+        img_ratio = img_width / img_height
+
+        if img_ratio > target_ratio:
+            # Image is wider than target, crop width
+            new_width = int(img_height * target_ratio)
+            left = (img_width - new_width) // 2
+            crop_box = (left, 0, left + new_width, img_height)
+        else:
+            # Image is taller than target, crop height
+            new_height = int(img_width / target_ratio)
+            top = (img_height - new_height) // 2
+            crop_box = (0, top, img_width, top + new_height)
+
+        # Crop and resize
+        cropped_image = self.image.crop(crop_box)
+        final_image = cropped_image.resize((width, height), Image.Resampling.LANCZOS)
+
+        # Create new processor instance
+        new_processor = ImageProcessor.__new__(ImageProcessor)
+        new_processor.image = final_image
+        new_processor.source_path = self.source_path
+
+        return new_processor
+
+    def save(self, output_path: str, quality: str = "high") -> str:
+        """
+        Save processed image.
+
+        Args:
+            output_path: Output file path
+            quality: Quality level ("high", "medium", "low")
+
+        Returns:
+            Path to saved file
+        """
+        # Determine quality settings
+        if quality == "high":
+            jpeg_quality = 95
+        elif quality == "medium":
+            jpeg_quality = 85
+        else:  # low
+            jpeg_quality = 70
+
+        # Ensure output directory exists
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Determine format from extension
+        file_extension = output_path.suffix.lower()
+
+        if file_extension in [".jpg", ".jpeg"]:
+            self.image.save(output_path, "JPEG", quality=jpeg_quality, optimize=True)
+        elif file_extension == ".png":
+            self.image.save(output_path, "PNG", optimize=True)
+        elif file_extension == ".webp":
+            self.image.save(output_path, "WEBP", quality=jpeg_quality, optimize=True)
+        else:
+            # Default to JPEG
+            output_path = output_path.with_suffix(".jpg")
+            self.image.save(output_path, "JPEG", quality=jpeg_quality, optimize=True)
+
+        return str(output_path)
+
+    def get_array(self) -> np.ndarray:
+        """
+        Get image as numpy array.
+
+        Returns:
+            Image as numpy array
+        """
+        return np.array(self.image)
+
+    def get_size(self) -> tuple:
+        """
+        Get image dimensions.
+
+        Returns:
+            Tuple of (width, height)
+        """
+        return self.image.size
+
+    def get_info(self) -> dict:
+        """
+        Get image information.
+
+        Returns:
+            Dictionary with image information
+        """
+        width, height = self.image.size
+        info = {
+            "width": width,
+            "height": height,
+            "mode": self.image.mode,
+            "format": self.image.format,
+            "source_path": self.source_path,
+        }
+
+        # Add crop information if available
+        if hasattr(self, "crop_info"):
+            info["crop_info"] = self.crop_info
+
+        return info
+
+    def get_crop_info(self) -> Optional[dict]:
+        """
+        Get crop information from smart crop operation.
+
+        Returns:
+            Dictionary with crop details or None if no smart crop was performed
+        """
+        return getattr(self, "crop_info", None)