deckbuilder 1.0.0b1__py3-none-any.whl

placekitten/smart_crop.py

@@ -0,0 +1,314 @@
+"""
+Smart Crop - Intelligent cropping engine with computer vision.
+
+This module implements the intelligent cropping pipeline using OpenCV
+for edge detection, contour analysis, and rule-of-thirds composition.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+class SmartCropEngine:
+    """
+    Intelligent cropping engine using computer vision techniques.
+
+    Implements a multi-step pipeline:
+    1. Original analysis and preprocessing
+    2. Edge detection with Canny algorithm
+    3. Contour identification and analysis
+    4. Rule-of-thirds composition calculation
+    5. Optimal crop area determination
+    """
+
+    def __init__(self):
+        """Initialize the smart crop engine."""
+        self.debug_steps = []
+        self.crop_info = {}
+
+    def smart_crop(
+        self,
+        image: Image.Image,
+        target_width: int,
+        target_height: int,
+        save_steps: bool = False,
+        output_prefix: str = "smart_crop",
+        output_folder: Optional[str] = None,
+        strategy: str = "haar-face",
+    ) -> Tuple[Image.Image, Dict]:
+        """
+        Perform intelligent cropping with computer vision.
+
+        Args:
+            image: PIL Image to crop
+            target_width: Target width in pixels
+            target_height: Target height in pixels
+            save_steps: Save intermediate processing steps
+            output_prefix: Prefix for step visualization files
+            output_folder: Directory to save step files (optional)
+
+        Returns:
+            Tuple of (cropped_image, crop_info)
+        """
+        # Clear previous debug info
+        self.debug_steps = []
+        self.crop_info = {}
+
+        # Convert PIL to OpenCV format
+        cv_image = self._pil_to_cv2(image)
+        original_height, original_width = cv_image.shape[:2]
+
+        # Step 1: Original analysis
+        step1_image = cv_image.copy()
+        self._add_debug_step("1-original", step1_image, save_steps, output_prefix, output_folder)
+
+        # Step 2: Grayscale conversion
+        gray = cv2.cvtColor(cv_image, cv2.COLOR_BGR2GRAY)
+        step2_image = cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)
+        self._add_debug_step("2-grayscale", step2_image, save_steps, output_prefix, output_folder)
+
+        # Step 3: Noise reduction with Gaussian blur
+        blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+        step3_image = cv2.cvtColor(blurred, cv2.COLOR_GRAY2BGR)
+        self._add_debug_step("3-blurred", step3_image, save_steps, output_prefix, output_folder)
+
+        # Step 4: Edge detection with Canny
+        edges = cv2.Canny(blurred, 50, 150)
+        # Highlight edges in red for visualization
+        step4_vis = cv_image.copy()
+        step4_vis[edges > 0] = [0, 0, 255]  # Red edges
+        self._add_debug_step("4-edges", step4_vis, save_steps, output_prefix, output_folder)
+
+        # Strategy-based subject detection
+        subject_bbox = None
+        largest_area = 0
+
+        if strategy == "haar-face":
+            face_cascade = cv2.CascadeClassifier(
+                cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
+            )
+            faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5)
+
+            if len(faces) > 0:
+                subject_bbox = max(faces, key=lambda r: r[2] * r[3])  # Select largest face
+                x, y, w, h = subject_bbox
+                step5_image = cv_image.copy()
+                cv2.rectangle(step5_image, (x, y), (x + w, y + h), (0, 255, 0), 3)
+                largest_area = w * h
+            else:
+                step5_image = cv_image.copy()
+
+            # Fallback to contour-based detection if face detection fails
+            if subject_bbox is None:
+                contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+                largest_contour = None
+                for contour in contours:
+                    area = cv2.contourArea(contour)
+                    if area > largest_area:
+                        largest_area = area
+                        largest_contour = contour
+
+                if largest_contour is not None:
+                    x, y, w, h = cv2.boundingRect(largest_contour)
+                    subject_bbox = (x, y, w, h)
+                    cv2.drawContours(step5_image, [largest_contour], -1, (0, 255, 0), 3)
+
+        else:
+            # Default to contour-based detection
+            contours, _ = cv2.findContours(edges, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+            largest_contour = None
+            for contour in contours:
+                area = cv2.contourArea(contour)
+                if area > largest_area:
+                    largest_area = area
+                    largest_contour = contour
+
+            step5_image = cv_image.copy()
+            if largest_contour is not None:
+                cv2.drawContours(step5_image, [largest_contour], -1, (0, 255, 0), 3)
+                x, y, w, h = cv2.boundingRect(largest_contour)
+                subject_bbox = (x, y, w, h)
+        self._add_debug_step(
+            "5-largest-contour", step5_image, save_steps, output_prefix, output_folder
+        )
+
+        # Step 6: Calculate bounding box of subject (visualization only)
+        if subject_bbox is not None:
+            x, y, w, h = subject_bbox
+            step6_image = cv_image.copy()
+            cv2.rectangle(step6_image, (x, y), (x + w, y + h), (255, 0, 0), 2)
+            # Fill bounding box with semi-transparent blue
+            overlay = step6_image.copy()
+            cv2.rectangle(overlay, (x, y), (x + w, y + h), (255, 0, 0), -1)
+            step6_image = cv2.addWeighted(step6_image, 0.8, overlay, 0.2, 0)
+        else:
+            step6_image = cv_image.copy()
+        self._add_debug_step(
+            "6-bounding-box", step6_image, save_steps, output_prefix, output_folder
+        )
+
+        # Step 7: Rule of thirds grid and composition
+        crop_box = self._calculate_optimal_crop(
+            original_width, original_height, target_width, target_height, subject_bbox
+        )
+
+        # Visualize rule of thirds and crop area
+        step7_image = cv_image.copy()
+        self._draw_rule_of_thirds(step7_image, original_width, original_height)
+        self._add_debug_step(
+            "7-rule-of-thirds", step7_image, save_steps, output_prefix, output_folder
+        )
+
+        # Step 8: Final crop area visualization
+        step8_image = cv_image.copy()
+        x1, y1, x2, y2 = crop_box
+        cv2.rectangle(step8_image, (x1, y1), (x2, y2), (255, 0, 255), 3)  # Magenta border
+        self._add_debug_step("8-crop-area", step8_image, save_steps, output_prefix, output_folder)
+
+        # Step 9: Perform the actual crop
+        cropped_cv = cv_image[y1:y2, x1:x2]
+        cropped_resized = cv2.resize(
+            cropped_cv, (target_width, target_height), interpolation=cv2.INTER_LANCZOS4
+        )
+
+        # Convert back to PIL
+        final_image = self._cv2_to_pil(cropped_resized)
+
+        # Save final result
+        self._add_debug_step("9-final", cropped_resized, save_steps, output_prefix, output_folder)
+
+        # Store crop information
+        self.crop_info = {
+            "original_size": (original_width, original_height),
+            "target_size": (target_width, target_height),
+            "crop_box": crop_box,
+            "subject_bbox": subject_bbox,
+            "contour_area": largest_area,
+            "steps_saved": len(self.debug_steps) if save_steps else 0,
+        }
+
+        return final_image, self.crop_info
+
+    def _calculate_optimal_crop(
+        self,
+        orig_width: int,
+        orig_height: int,
+        target_width: int,
+        target_height: int,
+        subject_bbox: Optional[Tuple[int, int, int, int]],
+    ) -> Tuple[int, int, int, int]:
+        """
+        Calculate optimal crop box using rule of thirds and subject positioning.
+
+        Args:
+            orig_width: Original image width
+            orig_height: Original image height
+            target_width: Target crop width
+            target_height: Target crop height
+            subject_bbox: Bounding box of main subject (x, y, w, h)
+
+        Returns:
+            Crop box as (x1, y1, x2, y2)
+        """
+        target_ratio = target_width / target_height
+
+        # Calculate crop dimensions maintaining target aspect ratio
+        if orig_width / orig_height > target_ratio:
+            # Original is wider - crop width
+            crop_height = orig_height
+            crop_width = int(crop_height * target_ratio)
+        else:
+            # Original is taller - crop height
+            crop_width = orig_width
+            crop_height = int(crop_width / target_ratio)
+
+        # Default to center crop
+        crop_x = (orig_width - crop_width) // 2
+        crop_y = (orig_height - crop_height) // 2
+
+        # Adjust based on subject position if available
+        if subject_bbox is not None:
+            subj_x, subj_y, subj_w, subj_h = subject_bbox
+            subj_center_x = subj_x + subj_w // 2
+            subj_center_y = subj_y + subj_h // 2
+
+            # Try to position subject in lower third (rule of thirds)
+            ideal_subj_x = crop_width // 2
+            ideal_subj_y = int(crop_height * 2 / 3)  # Lower third
+
+            # Calculate desired crop position
+            desired_crop_x = subj_center_x - ideal_subj_x
+            desired_crop_y = subj_center_y - ideal_subj_y
+
+            # Ensure crop stays within image bounds
+            crop_x = max(0, min(desired_crop_x, orig_width - crop_width))
+            crop_y = max(0, min(desired_crop_y, orig_height - crop_height))
+
+        return (crop_x, crop_y, crop_x + crop_width, crop_y + crop_height)
+
+    def _draw_rule_of_thirds(self, image: np.ndarray, width: int, height: int) -> None:
+        """Draw rule of thirds grid on image."""
+        # Vertical lines
+        cv2.line(image, (width // 3, 0), (width // 3, height), (255, 255, 0), 2)
+        cv2.line(image, (2 * width // 3, 0), (2 * width // 3, height), (255, 255, 0), 2)
+
+        # Horizontal lines
+        cv2.line(image, (0, height // 3), (width, height // 3), (255, 255, 0), 2)
+        cv2.line(image, (0, 2 * height // 3), (width, 2 * height // 3), (255, 255, 0), 2)
+
+    def _pil_to_cv2(self, pil_image: Image.Image) -> np.ndarray:
+        """Convert PIL Image to OpenCV format."""
+        # Convert PIL to RGB if not already
+        if pil_image.mode != "RGB":
+            pil_image = pil_image.convert("RGB")
+
+        # Convert to numpy array and change from RGB to BGR
+        cv_image = np.array(pil_image)
+        cv_image = cv2.cvtColor(cv_image, cv2.COLOR_RGB2BGR)
+        return cv_image
+
+    def _cv2_to_pil(self, cv_image: np.ndarray) -> Image.Image:
+        """Convert OpenCV image to PIL format."""
+        # Convert from BGR to RGB
+        rgb_image = cv2.cvtColor(cv_image, cv2.COLOR_BGR2RGB)
+        return Image.fromarray(rgb_image)
+
+    def _add_debug_step(
+        self,
+        step_name: str,
+        image: np.ndarray,
+        save_steps: bool,
+        output_prefix: str,
+        output_folder: Optional[str] = None,
+    ) -> None:
+        """Add debug step and optionally save to file."""
+        if save_steps:
+            step_info = {"name": step_name, "image": image.copy()}
+            self.debug_steps.append(step_info)
+
+            # Save step image with proper folder handling
+            filename = f"{output_prefix}_{step_name}.jpg"
+            if output_folder:
+                # Ensure output folder exists
+                Path(output_folder).mkdir(parents=True, exist_ok=True)
+                filepath = Path(output_folder) / filename
+            else:
+                filepath = Path(filename)
+
+            cv2.imwrite(str(filepath), image)
+
+    def get_debug_steps(self) -> List[Dict]:
+        """Get list of debug steps with images."""
+        return self.debug_steps
+
+    def get_crop_info(self) -> Dict:
+        """Get detailed information about the last crop operation."""
+        return self.crop_info
+
+
+# Global instance for easy access
+smart_crop_engine = SmartCropEngine()

shared/__init__.py

@@ -0,0 +1,9 @@
+"""
+Shared - Common Utilities
+
+Shared utilities and helper functions used across deckbuilder,
+placekitten, and mcp_tools modules.
+"""
+
+__version__ = "1.0.0"
+__all__ = []