smart-image-cropper 1.0.0__py3-none-any.whl

smart_image_cropper/__init__.py

@@ -0,0 +1,11 @@
+"""Smart Image Cropper - An intelligent image cropping library."""
+
+from .cropper import SmartImageCropper
+from .exceptions import SmartCropperError, APIError, ImageProcessingError
+
+__version__ = "1.0.0"
+__author__ = "Giulio Manuzzi"
+__email__ = "giuliomanuzzi@gmail.com"
+
+__all__ = ["SmartImageCropper", "SmartCropperError",
+           "APIError", "ImageProcessingError"]

smart_image_cropper/cropper.py

@@ -0,0 +1,602 @@
+"""Main Smart Image Cropper implementation."""
+
+import base64
+import logging
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional, Tuple, Union
+
+import cv2
+import numpy as np
+import requests
+from PIL import Image
+
+from .exceptions import APIError, ImageProcessingError
+from .utils import ImageUtils
+
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+class AspectRatio(Enum):
+    """Supported target aspect ratios."""
+
+    PORTRAIT_4_5 = (4, 5)  # 0.8
+    PORTRAIT_3_4 = (3, 4)  # 0.75
+    SQUARE_1_1 = (1, 1)  # 1.0
+    LANDSCAPE_4_3 = (4, 3)  # 1.33
+
+    @property
+    def ratio(self) -> float:
+        return self.value[0] / self.value[1]
+
+
+class CollageDirection(Enum):
+    """Directions for the collage."""
+
+    VERTICAL = "vertical"
+    HORIZONTAL = "horizontal"
+
+
+@dataclass
+class BoundingBox:
+    x1: int
+    y1: int
+    x2: int
+    y2: int
+
+    @property
+    def width(self) -> int:
+        return self.x2 - self.x1
+
+    @property
+    def height(self) -> int:
+        return self.y2 - self.y1
+
+    @property
+    def area(self) -> int:
+        return self.width * self.height
+
+    @property
+    def aspect_ratio(self) -> float:
+        return self.width / self.height
+
+    def get_shape_type(self) -> str:
+        """Determine if the bbox is square, horizontal rectangle, or vertical rectangle."""
+        width_height_diff = abs(self.width - self.height) / \
+            max(self.width, self.height)
+
+        if width_height_diff <= 0.05:
+            return "square"
+        elif self.width > self.height:
+            return "horizontal"
+        else:
+            return "vertical"
+
+
+class AspectRatioCalculator:
+    """Handles aspect ratio calculations."""
+
+    @staticmethod
+    def find_closest_target_ratio(current_ratio: float) -> AspectRatio:
+        """Find the target format closest to the current ratio."""
+        min_diff = float("inf")
+        closest_ratio = AspectRatio.SQUARE_1_1
+
+        for ratio in AspectRatio:
+            diff = abs(current_ratio - ratio.ratio)
+            if diff < min_diff:
+                min_diff = diff
+                closest_ratio = ratio
+
+        logger.info(
+            f"Current ratio: {current_ratio:.2f}, selected target: {closest_ratio.value[0]}:{closest_ratio.value[1]}"
+        )
+        return closest_ratio
+
+    @staticmethod
+    def needs_expansion(
+        current_ratio: float, target_ratio: float, tolerance: float = 0.05
+    ) -> bool:
+        """Check if expansion is needed to reach the target ratio."""
+        return abs(current_ratio - target_ratio) > tolerance
+
+
+class BoundingBoxExpander:
+    """Handles the expansion of bounding boxes."""
+
+    @staticmethod
+    def expand_to_width(
+        img: np.ndarray, bbox: BoundingBox, target_width: int
+    ) -> BoundingBox:
+        """Expand a bbox to reach the target width."""
+        img_height, img_width = img.shape[:2]
+        current_width = bbox.width
+
+        if current_width >= target_width:
+            return bbox
+
+        extra_width = target_width - current_width
+        left_expand = extra_width // 2
+        right_expand = extra_width - left_expand
+
+        new_x1 = max(0, bbox.x1 - left_expand)
+        new_x2 = min(img_width, bbox.x2 + right_expand)
+
+        # Adjust if we couldn't expand enough
+        if new_x2 - new_x1 < target_width:
+            if new_x1 > 0:
+                new_x1 = max(0, new_x2 - target_width)
+            else:
+                new_x2 = min(img_width, new_x1 + target_width)
+
+        return BoundingBox(new_x1, bbox.y1, new_x2, bbox.y2)
+
+    @staticmethod
+    def expand_to_height(
+        img: np.ndarray, bbox: BoundingBox, target_height: int
+    ) -> BoundingBox:
+        """Expand a bbox to reach the target height."""
+        img_height, img_width = img.shape[:2]
+        current_height = bbox.height
+
+        if current_height >= target_height:
+            return bbox
+
+        extra_height = target_height - current_height
+        top_expand = extra_height // 2
+        bottom_expand = extra_height - top_expand
+
+        new_y1 = max(0, bbox.y1 - top_expand)
+        new_y2 = min(img_height, bbox.y2 + bottom_expand)
+
+        # Adjust if we couldn't expand enough
+        if new_y2 - new_y1 < target_height:
+            if new_y1 > 0:
+                new_y1 = max(0, new_y2 - target_height)
+            else:
+                new_y2 = min(img_height, new_y1 + target_height)
+
+        return BoundingBox(bbox.x1, new_y1, bbox.x2, new_y2)
+
+    @staticmethod
+    def expand_to_aspect_ratio(
+        img: np.ndarray, bbox: BoundingBox, target_ratio: AspectRatio
+    ) -> BoundingBox:
+        """Expand a bbox to reach the target format."""
+        current_ratio = bbox.aspect_ratio
+        target_ratio_value = target_ratio.ratio
+
+        logger.info(
+            f"Expanding bbox from {bbox.width}x{bbox.height} (ratio: {current_ratio:.3f}) to target ratio {target_ratio.value[0]}:{target_ratio.value[1]} ({target_ratio_value:.3f})"
+        )
+
+        if not AspectRatioCalculator.needs_expansion(current_ratio, target_ratio_value):
+            logger.info(
+                "Bbox already has correct aspect ratio, no expansion needed")
+            return bbox
+
+        expanded_bbox = bbox
+        img_height, img_width = img.shape[:2]
+
+        if current_ratio < target_ratio_value:
+            # Too tall, expand width
+            ideal_width = int(bbox.height * target_ratio_value)
+            target_width = min(img_width, ideal_width)
+
+            if target_width > bbox.width:
+                expanded_bbox = BoundingBoxExpander.expand_to_width(
+                    img, expanded_bbox, target_width
+                )
+                logger.info(f"Expanded width to {expanded_bbox.width}")
+        else:
+            # Too wide, expand height
+            ideal_height = int(bbox.width / target_ratio_value)
+            target_height = min(img_height, ideal_height)
+
+            if target_height > bbox.height:
+                expanded_bbox = BoundingBoxExpander.expand_to_height(
+                    img, expanded_bbox, target_height
+                )
+                logger.info(f"Expanded height to {expanded_bbox.height}")
+
+        final_ratio = expanded_bbox.aspect_ratio
+        logger.info(
+            f"Final bbox: {expanded_bbox.width}x{expanded_bbox.height}, ratio: {final_ratio:.3f}"
+        )
+
+        if AspectRatioCalculator.needs_expansion(
+            final_ratio, target_ratio_value, tolerance=0.05
+        ):
+            logger.warning(
+                f"Could not reach target ratio {target_ratio_value:.3f}, achieved {final_ratio:.3f}"
+            )
+
+        return expanded_bbox
+
+
+class ImageCropper:
+    """Handles image cropping and manipulation."""
+
+    @staticmethod
+    def crop_image(image_bytes: bytes, bbox: BoundingBox) -> bytes:
+        """Crop image based on bounding box."""
+        try:
+            nparr = np.frombuffer(image_bytes, np.uint8)
+            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+
+            cropped = img[bbox.y1: bbox.y2, bbox.x1: bbox.x2]
+            _, buffer = cv2.imencode(".jpg", cropped)
+            return buffer.tobytes()
+        except Exception as e:
+            logger.error(f"Error cropping image: {str(e)}")
+            raise ImageProcessingError(f"Error cropping image: {str(e)}")
+
+
+class CollageCreator:
+    """Handles the creation of collages from multiple bounding boxes."""
+
+    @staticmethod
+    def _equalize_dimensions(
+        img: np.ndarray,
+        bbox1: BoundingBox,
+        bbox2: BoundingBox,
+        direction: CollageDirection,
+    ) -> Tuple[BoundingBox, BoundingBox]:
+        """Equalize the dimensions of the bboxes for the collage."""
+        if direction == CollageDirection.VERTICAL:
+            target_width = max(bbox1.width, bbox2.width)
+            bbox1 = (
+                BoundingBoxExpander.expand_to_width(img, bbox1, target_width)
+                if bbox1.width < target_width
+                else bbox1
+            )
+            bbox2 = (
+                BoundingBoxExpander.expand_to_width(img, bbox2, target_width)
+                if bbox2.width < target_width
+                else bbox2
+            )
+        else:
+            target_height = max(bbox1.height, bbox2.height)
+            bbox1 = (
+                BoundingBoxExpander.expand_to_height(img, bbox1, target_height)
+                if bbox1.height < target_height
+                else bbox1
+            )
+            bbox2 = (
+                BoundingBoxExpander.expand_to_height(img, bbox2, target_height)
+                if bbox2.height < target_height
+                else bbox2
+            )
+
+        return bbox1, bbox2
+
+    @staticmethod
+    def _adjust_for_aspect_ratio(
+        img: np.ndarray,
+        bbox1: BoundingBox,
+        bbox2: BoundingBox,
+        direction: CollageDirection,
+        target_ratio: AspectRatio,
+    ) -> Tuple[BoundingBox, BoundingBox]:
+        """Adjust the dimensions to reach the target format."""
+        if direction == CollageDirection.VERTICAL:
+            collage_width = max(bbox1.width, bbox2.width)
+            collage_height = bbox1.height + bbox2.height
+        else:
+            collage_width = bbox1.width + bbox2.width
+            collage_height = max(bbox1.height, bbox2.height)
+
+        current_ratio = collage_width / collage_height
+        logger.info(
+            f"Initial collage: {collage_width}x{collage_height} (ratio: {current_ratio:.3f})"
+        )
+
+        target_width = int(
+            collage_height * target_ratio.value[0] / target_ratio.value[1]
+        )
+        target_height = int(
+            collage_width * target_ratio.value[1] / target_ratio.value[0]
+        )
+
+        # Choose the adjustment that requires fewer changes
+        width_diff = abs(target_width - collage_width)
+        height_diff = abs(target_height - collage_height)
+
+        logger.info(f"Target dimensions: {target_width}x{target_height}")
+        logger.info(f"Width diff: {width_diff}, Height diff: {height_diff}")
+
+        # Choose whether to expand width or height based on which requires fewer changes
+        if width_diff <= height_diff:
+            # Expand width (preferred when difference is less or equal)
+            logger.info("Choosing to expand width")
+            if target_width > collage_width:
+                if direction == CollageDirection.VERTICAL:
+                    # For vertical collages, expand both bboxes in width
+                    bbox1 = BoundingBoxExpander.expand_to_width(
+                        img, bbox1, target_width
+                    )
+                    bbox2 = BoundingBoxExpander.expand_to_width(
+                        img, bbox2, target_width
+                    )
+                else:
+                    # For horizontal collages, distribute expansion between the two bboxes
+                    extra_width = target_width - collage_width
+                    extra_per_bbox = extra_width // 2
+                    new_width1 = bbox1.width + extra_per_bbox
+                    new_width2 = bbox2.width + (extra_width - extra_per_bbox)
+                    bbox1 = BoundingBoxExpander.expand_to_width(
+                        img, bbox1, new_width1)
+                    bbox2 = BoundingBoxExpander.expand_to_width(
+                        img, bbox2, new_width2)
+        else:
+            # Expand height
+            logger.info("Choosing to expand height")
+            if target_height > collage_height:
+                if direction == CollageDirection.HORIZONTAL:
+                    # For horizontal collages, expand both bboxes in height
+                    bbox1 = BoundingBoxExpander.expand_to_height(
+                        img, bbox1, target_height
+                    )
+                    bbox2 = BoundingBoxExpander.expand_to_height(
+                        img, bbox2, target_height
+                    )
+                else:
+                    # For vertical collages, distribute expansion between the two bboxes
+                    extra_height = target_height - collage_height
+                    extra_per_bbox = extra_height // 2
+                    new_height1 = bbox1.height + extra_per_bbox
+                    new_height2 = bbox2.height + \
+                        (extra_height - extra_per_bbox)
+                    bbox1 = BoundingBoxExpander.expand_to_height(
+                        img, bbox1, new_height1
+                    )
+                    bbox2 = BoundingBoxExpander.expand_to_height(
+                        img, bbox2, new_height2
+                    )
+
+        return bbox1, bbox2
+
+    @staticmethod
+    def create_collage(
+        image_bytes: bytes,
+        bbox1: BoundingBox,
+        bbox2: BoundingBox,
+        direction: CollageDirection,
+        target_ratio: AspectRatio,
+    ) -> bytes:
+        """Create a collage from two bounding boxes."""
+        try:
+            nparr = np.frombuffer(image_bytes, np.uint8)
+            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+
+            # Equalize dimensions
+            bbox1, bbox2 = CollageCreator._equalize_dimensions(
+                img, bbox1, bbox2, direction
+            )
+
+            # Adjust for target format
+            bbox1, bbox2 = CollageCreator._adjust_for_aspect_ratio(
+                img, bbox1, bbox2, direction, target_ratio
+            )
+
+            # Crop regions
+            crop1 = img[bbox1.y1: bbox1.y2, bbox1.x1: bbox1.x2]
+            crop2 = img[bbox2.y1: bbox2.y2, bbox2.x1: bbox2.x2]
+
+            # Create collage
+            if direction == CollageDirection.VERTICAL:
+                collage = np.vstack([crop1, crop2])
+            else:
+                collage = np.hstack([crop1, crop2])
+
+            _, buffer = cv2.imencode(".jpg", collage)
+            return buffer.tobytes()
+
+        except Exception as e:
+            logger.error(f"Error creating {direction.value} collage: {str(e)}")
+            raise ImageProcessingError(f"Error creating collage: {str(e)}")
+
+
+class CollageDirectionDecider:
+    """Decide the direction of the collage based on the shapes of the bboxes."""
+
+    @staticmethod
+    def decide_direction(bbox1: BoundingBox, bbox2: BoundingBox) -> CollageDirection:
+        """Decide if a vertical or horizontal collage should be created."""
+        shape1 = bbox1.get_shape_type()
+        shape2 = bbox2.get_shape_type()
+
+        logger.info(f"Bbox shapes: {shape1} and {shape2}")
+
+        if (
+            (shape1 == "square" and shape2 == "square")
+            or (shape1 == "horizontal" and shape2 == "horizontal")
+            or (shape1 == "square" and shape2 == "horizontal")
+            or (shape1 == "horizontal" and shape2 == "square")
+        ):
+            return CollageDirection.VERTICAL
+        else:
+            return CollageDirection.HORIZONTAL
+
+
+class BoundingBoxAPIClient:
+    """Client for the bounding box detection API."""
+
+    def __init__(self, api_url: str, api_key: str):
+        self.api_url = api_url
+        self.api_key = api_key
+        self.headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        }
+
+    def _wait_for_job_completion(self, job_id: str) -> Optional[List[BoundingBox]]:
+        """Wait for the job to complete and return the bounding boxes."""
+        while True:
+            time.sleep(2)
+            status_url = f"{self.api_url.rsplit('/', 1)[0]}/status/{job_id}"
+
+            try:
+                response = requests.get(status_url, headers=self.headers)
+                response.raise_for_status()
+                data = response.json()
+
+                if data["status"] == "COMPLETED":
+                    return self._parse_bboxes(data["output"])
+                elif data["status"] == "FAILED":
+                    logger.error(f"Job failed: {data}")
+                    raise APIError(f"API job failed: {data}")
+
+            except requests.RequestException as e:
+                logger.error(f"Error checking status: {str(e)}")
+                raise APIError(f"Error checking API status: {str(e)}")
+
+    def _parse_bboxes(self, bboxes_data: List[dict]) -> List[BoundingBox]:
+        """Convert the API data to BoundingBox objects."""
+        return [
+            BoundingBox(x1=bbox["x1"], y1=bbox["y1"],
+                        x2=bbox["x2"], y2=bbox["y2"])
+            for bbox in bboxes_data
+        ]
+
+    def get_bounding_boxes(self, image_bytes: bytes) -> List[BoundingBox]:
+        """Get the bounding boxes for the given image."""
+        logger.info("Requesting bboxes from API")
+        image_b64 = base64.b64encode(image_bytes).decode("utf-8")
+
+        try:
+            payload = {"input": {"image": image_b64}}
+            response = requests.post(
+                self.api_url, json=payload, headers=self.headers)
+            response.raise_for_status()
+
+            job_id = response.json()["id"]
+            return self._wait_for_job_completion(job_id) or []
+
+        except requests.RequestException as e:
+            logger.error(f"API request failed: {str(e)}")
+            raise APIError(f"API request failed: {str(e)}")
+        except Exception as e:
+            logger.error(f"Unexpected error getting bounding boxes: {str(e)}")
+            raise APIError(f"Unexpected API error: {str(e)}")
+
+
+class SmartImageCropper:
+    """Main Smart Image Cropper class."""
+
+    def __init__(self, api_url: str, api_key: str):
+        """
+        Initialize the Smart Image Cropper.
+
+        Args:
+            api_url: URL of the bounding box detection API
+            api_key: API key for authentication
+        """
+        self.api_client = BoundingBoxAPIClient(api_url, api_key)
+        logger.info("Initialized SmartImageCropper")
+
+    def _select_best_bboxes(self, bboxes: List[BoundingBox]) -> List[BoundingBox]:
+        """Select the best bounding boxes for processing."""
+        if not bboxes:
+            return []
+
+        sorted_bboxes = sorted(bboxes, key=lambda bb: bb.area, reverse=True)
+
+        if len(sorted_bboxes) == 1:
+            return sorted_bboxes
+
+        bbox1, bbox2 = sorted_bboxes[0], sorted_bboxes[1]
+
+        area_ratio = bbox1.area / \
+            bbox2.area if bbox2.area > 0 else float("inf")
+        if area_ratio >= 5:
+            logger.info(
+                f"Area difference too large ({area_ratio:.2f}x), using only largest bbox"
+            )
+            return [bbox1]
+
+        return [bbox1, bbox2]
+
+    def process_image(self, image_input: Union[str, bytes, Image.Image]) -> bytes:
+        """
+        Process an image and return the cropped result as bytes.
+
+        Args:
+            image_input: Can be a URL string, image bytes, or PIL Image
+
+        Returns:
+            bytes: The processed image as bytes
+
+        Raises:
+            SmartCropperError: If processing fails
+        """
+        # Normalize input to bytes
+        image_bytes = ImageUtils.normalize_input(image_input)
+
+        try:
+            bboxes = self.api_client.get_bounding_boxes(image_bytes)
+            if not bboxes:
+                logger.warning(
+                    "No bounding boxes found, returning original image")
+                return image_bytes
+            else:
+                best_bboxes = self._select_best_bboxes(bboxes)
+                return self._process_bboxes(image_bytes, best_bboxes)
+
+        except Exception as e:
+            logger.error(f"Error processing image: {str(e)}")
+            raise
+
+    def _process_bboxes(self, image_bytes: bytes, bboxes: List[BoundingBox]) -> bytes:
+        """Process the bounding boxes to create the final result."""
+        if len(bboxes) == 1:
+            return self._process_single_bbox(image_bytes, bboxes[0])
+        elif len(bboxes) == 2:
+            return self._process_multiple_bboxes(image_bytes, bboxes[0], bboxes[1])
+        else:
+            logger.warning(
+                "Unexpected number of bboxes, returning original image")
+            return image_bytes
+
+    def _process_single_bbox(self, image_bytes: bytes, bbox: BoundingBox) -> bytes:
+        """Process a single bounding box."""
+        logger.info("Single bbox detected, expanding to target aspect ratio")
+
+        nparr = np.frombuffer(image_bytes, np.uint8)
+        img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+
+        target_ratio = AspectRatioCalculator.find_closest_target_ratio(
+            bbox.aspect_ratio
+        )
+        expanded_bbox = BoundingBoxExpander.expand_to_aspect_ratio(
+            img, bbox, target_ratio
+        )
+
+        return ImageCropper.crop_image(image_bytes, expanded_bbox)
+
+    def _process_multiple_bboxes(
+        self, image_bytes: bytes, bbox1: BoundingBox, bbox2: BoundingBox
+    ) -> bytes:
+        """Process two bounding boxes to create a collage."""
+        direction = CollageDirectionDecider.decide_direction(bbox1, bbox2)
+        logger.info(f"Creating {direction.value} collage")
+
+        # Calculate target format based on collage dimensions
+        if direction == CollageDirection.VERTICAL:
+            collage_width = max(bbox1.width, bbox2.width)
+            collage_height = bbox1.height + bbox2.height
+        else:
+            collage_width = bbox1.width + bbox2.width
+            collage_height = max(bbox1.height, bbox2.height)
+
+        collage_ratio = collage_width / collage_height
+        target_ratio = AspectRatioCalculator.find_closest_target_ratio(
+            collage_ratio)
+
+        return CollageCreator.create_collage(
+            image_bytes, bbox1, bbox2, direction, target_ratio
+        )

smart_image_cropper/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for Smart Image Cropper."""
+
+
+class SmartCropperError(Exception):
+    """Base exception for Smart Image Cropper."""
+    pass
+
+
+class APIError(SmartCropperError):
+    """Exception raised when API requests fail."""
+    pass
+
+
+class ImageProcessingError(SmartCropperError):
+    """Exception raised when image processing fails."""
+    pass
+
+
+class InvalidInputError(SmartCropperError):
+    """Exception raised when input is invalid."""
+    pass

smart_image_cropper/utils.py

@@ -0,0 +1,74 @@
+"""Utility functions for Smart Image Cropper."""
+
+import io
+import logging
+from typing import Union
+
+import cv2
+import numpy as np
+import requests
+from PIL import Image
+
+from .exceptions import ImageProcessingError, InvalidInputError
+
+logger = logging.getLogger(__name__)
+
+
+class ImageUtils:
+    """Utility functions for image handling."""
+
+    @staticmethod
+    def download_image_bytes(url: str, timeout: int = 30) -> bytes:
+        """Download an image from URL and return as bytes."""
+        try:
+            response = requests.get(url, timeout=timeout)
+            response.raise_for_status()
+            return response.content
+        except requests.RequestException as e:
+            logger.error(f"Failed to download image from {url}: {str(e)}")
+            raise ImageProcessingError(f"Failed to download image: {str(e)}")
+
+    @staticmethod
+    def pil_to_bytes(pil_image: Image.Image, format: str = "JPEG") -> bytes:
+        """Convert PIL Image to bytes."""
+        try:
+            img_buffer = io.BytesIO()
+            # Convert to RGB if necessary
+            if pil_image.mode in ("RGBA", "P"):
+                pil_image = pil_image.convert("RGB")
+            pil_image.save(img_buffer, format=format)
+            return img_buffer.getvalue()
+        except Exception as e:
+            logger.error(f"Failed to convert PIL image to bytes: {str(e)}")
+            raise ImageProcessingError(
+                f"Failed to convert PIL image: {str(e)}")
+
+    @staticmethod
+    def validate_image_bytes(image_bytes: bytes) -> bool:
+        """Validate that bytes represent a valid image."""
+        try:
+            nparr = np.frombuffer(image_bytes, np.uint8)
+            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+            return img is not None
+        except Exception:
+            return False
+
+    @staticmethod
+    def normalize_input(image_input: Union[str, bytes, Image.Image]) -> bytes:
+        """Normalize different input types to bytes."""
+        if isinstance(image_input, str):
+            # Assume it's a URL
+            return ImageUtils.download_image_bytes(image_input)
+        elif isinstance(image_input, bytes):
+            # Already bytes, validate
+            if not ImageUtils.validate_image_bytes(image_input):
+                raise InvalidInputError("Invalid image bytes provided")
+            return image_input
+        elif isinstance(image_input, Image.Image):
+            # PIL Image
+            return ImageUtils.pil_to_bytes(image_input)
+        else:
+            raise InvalidInputError(
+                f"Unsupported input type: {type(image_input)}. "
+                "Supported types: str (URL), bytes, PIL.Image.Image"
+            )

smart_image_cropper-1.0.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: smart-image-cropper
+Version: 1.0.0
+Summary: An intelligent image cropping library that creates smart collages
+Home-page: https://github.com/giumanuz/image_cropper
+Author: Giulio Manuzzi
+Author-email: Your Name <your.email@example.com>
+Maintainer-email: Your Name <your.email@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/smart-image-cropper
+Project-URL: Documentation, https://github.com/yourusername/smart-image-cropper#readme
+Project-URL: Repository, https://github.com/yourusername/smart-image-cropper
+Project-URL: Bug Tracker, https://github.com/yourusername/smart-image-cropper/issues
+Keywords: image processing,cropping,collage,computer vision,opencv
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.812; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Smart Image Cropper
+
+[![PyPI version](https://badge.fury.io/py/smart-image-cropper.svg)](https://badge.fury.io/py/smart-image-cropper)
+[![Python Support](https://img.shields.io/pypi/pyversions/smart-image-cropper.svg)](https://pypi.org/project/smart-image-cropper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An intelligent image cropping library that automatically detects objects in
+images and creates optimized crops or collages. The library uses AI-powered
+bounding box detection to identify the most important regions in your images and
+intelligently crops them to standard aspect ratios.
+
+## Features
+
+- 🎯 **Smart Object Detection**: Automatically detects important objects in
+  images using AI
+- 🖼️ **Intelligent Cropping**: Crops images to optimal aspect ratios (4:5, 3:4,
+  1:1, 4:3)
+- 🎨 **Automatic Collages**: Creates beautiful collages when multiple objects
+  are detected
+- 📐 **Aspect Ratio Optimization**: Automatically expands crops to reach target
+  aspect ratios
+- 🔧 **Flexible Input**: Supports URLs, bytes, and PIL Images as input
+- ⚡ **Fast Processing**: Efficient image processing with OpenCV
+- 🐍 **Pure Python**: Easy to integrate into any Python project
+
+## Installation
+
+```bash
+pip install smart-image-cropper
+```
+
+## Quick Start
+
+```python
+from smart_image_cropper import SmartImageCropper
+from PIL import Image
+
+# Initialize the cropper with your API credentials
+cropper = SmartImageCropper(
+    api_url="your-api-endpoint",
+    api_key="your-api-key"
+)
+
+# Method 1: Process from URL
+result_bytes = cropper.process_image("https://example.com/image.jpg")
+
+# Method 2: Process from bytes
+with open("image.jpg", "rb") as f:
+    image_bytes = f.read()
+result_bytes = cropper.process_image(image_bytes)
+
+# Method 3: Process from PIL Image
+pil_image = Image.open("image.jpg")
+result_bytes = cropper.process_image(pil_image)
+
+# Save the result
+with open("cropped_result.jpg", "wb") as f:
+    f.write(result_bytes)
+```
+
+## How It Works
+
+1. **Object Detection**: The library sends your image to an AI-powered bounding
+   box detection API
+2. **Smart Selection**: Identifies the most important objects based on size and
+   relevance
+3. **Intelligent Processing**:
+   - **Single Object**: Crops and expands to the nearest standard aspect ratio
+   - **Multiple Objects**: Creates a collage with optimal layout
+     (vertical/horizontal)
+4. **Aspect Ratio Optimization**: Ensures the final result matches standard
+   social media formats
+
+## Supported Aspect Ratios
+
+- **Portrait 4:5** (0.8) - Instagram posts
+- **Portrait 3:4** (0.75) - Traditional photo format
+- **Square 1:1** (1.0) - Instagram square posts
+- **Landscape 4:3** (1.33) - Traditional landscape format
+
+## API Requirements
+
+This library requires access to a bounding box detection API. The API should:
+
+- Accept POST requests with JSON payload containing base64-encoded images
+- Return a job ID for asynchronous processing
+- Provide a status endpoint to check job completion
+- Return bounding box coordinates in the format:
+  `{"x1": int, "y1": int, "x2": int, "y2": int}`
+
+### Example API Integration
+
+```python
+# Your API should accept this format:
+{
+    "input": {
+        "image": "base64-encoded-image-string"
+    }
+}
+
+# And return:
+{
+    "id": "job-id-string"
+}
+
+# Status check should return:
+{
+    "status": "COMPLETED",  # or "FAILED"
+    "output": [
+        {"x1": 100, "y1": 50, "x2": 300, "y2": 250},
+        {"x1": 400, "y1": 100, "x2": 600, "y2": 300}
+    ]
+}
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```python
+from smart_image_cropper import SmartImageCropper, SmartCropperError, APIError
+
+try:
+    cropper = SmartImageCropper(api_url="...", api_key="...")
+    result = cropper.process_image("image.jpg")
+except APIError as e:
+    print(f"API Error: {e}")
+except SmartCropperError as e:
+    print(f"Processing Error: {e}")
+```
+
+### Logging
+
+The library uses Python's logging module. Enable debug logging to see detailed
+processing information:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+# Now you'll see detailed processing logs
+```
+
+## Dependencies
+
+- **OpenCV** (`opencv-python>=4.5.0`) - Image processing
+- **NumPy** (`numpy>=1.20.0`) - Numerical operations
+- **Pillow** (`Pillow>=8.0.0`) - PIL Image support
+- **Requests** (`requests>=2.25.0`) - HTTP API calls
+
+## Development
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/smart-image-cropper.git
+cd smart-image-cropper
+
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black .
+
+# Type checking
+mypy smart_image_cropper/
+```
+
+### Running Tests
+
+```bash
+pytest tests/ -v --cov=smart_image_cropper
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major
+changes, please open an issue first to discuss what you would like to change.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+for details.
+
+## Changelog
+
+### v1.0.0
+
+- Initial release
+- Support for URL, bytes, and PIL Image inputs
+- Automatic object detection and smart cropping
+- Collage creation for multiple objects
+- Aspect ratio optimization
+
+## Support
+
+If you encounter any issues or have questions, please file an issue on the
+[GitHub issue tracker](https://github.com/yourusername/smart-image-cropper/issues).
+
+## Acknowledgments
+
+- OpenCV community for excellent image processing tools
+- PIL/Pillow developers for image handling capabilities
+- The Python packaging community for excellent tools and documentation

smart_image_cropper-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+smart_image_cropper/__init__.py,sha256=D2CqGkdST7EhoCJZYQ-iasDiM_7h7yyfBhSG9RKj_s8,373
+smart_image_cropper/cropper.py,sha256=r6rCqem8MVzzeHcN6ExnUHXB5Vv8RZKs1UhBXc37HoQ,21496
+smart_image_cropper/exceptions.py,sha256=mAAL-82BQ2n0y3aFEstSbyZ-TEakWcQQujcGlQPd3sY,462
+smart_image_cropper/utils.py,sha256=4NtIE5C2golb4_8jDcCRLL5a9J1ZNBoscReG0oh9AZ4,2688
+smart_image_cropper-1.0.0.dist-info/licenses/LICENSE,sha256=3HI2BFqRtJB9-3TEFRlMEUIXSn7v1Wsxsi6dJ1etoXg,1076
+smart_image_cropper-1.0.0.dist-info/METADATA,sha256=wyiKEpaaJW5AGGXcFxVGrO803qPSSHKLToftcsspHO8,7762
+smart_image_cropper-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+smart_image_cropper-1.0.0.dist-info/top_level.txt,sha256=BJ54dVKhPwbe2foKDOF1JFwd2nGJkHg0UscQdkCtSno,20
+smart_image_cropper-1.0.0.dist-info/RECORD,,

smart_image_cropper-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

smart_image_cropper-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2024 Smart Image Cropper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

smart_image_cropper-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+smart_image_cropper