imagekit-python 0.0.1a1__py3-none-any.whl

imagekit_python/__init__.py

@@ -0,0 +1,15 @@
+from .smart_image import (
+    ImageFormat,
+    SmartImage,
+    ImageEmpty,
+    ImageTooLarge,
+    InvalidImage,
+)
+
+__all__ = [
+    "ImageFormat",
+    "SmartImage",
+    "ImageEmpty",
+    "ImageTooLarge",
+    "InvalidImage",
+]

imagekit_python/smart_image.py

@@ -0,0 +1,474 @@
+import io
+import cv2
+import base64
+import numpy as np
+from PIL import Image
+from cv2.typing import MatLike
+from dataclasses import dataclass
+from typing import ClassVar, Literal, Optional
+
+
+# Custom Errors
+class ImageEmpty(Exception):
+    """Raised when image is empty or has no data."""
+
+    def __init__(self, message: str = "Image is empty"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class InvalidImage(Exception):
+    """Raised when image is invalid or corrupted."""
+
+    def __init__(self, message: str = "Image is invalid or corrupted"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class ImageTooLarge(Exception):
+    """Raised when image size exceeds maximum allowed size."""
+
+    def __init__(self, max_mb: float, message: str = None):
+        self.max_mb = max_mb
+        self.message = (
+            message or f"Image size exceeds maximum allowed size of {max_mb} MB"
+        )
+        super().__init__(self.message)
+
+
+class InvalidAngle(Exception):
+    """Raised when image size exceeds maximum allowed size."""
+
+    def __init__(self, message: str = "Only 90, 180, 270 supported"):
+        self.message = message
+        super().__init__(self.message)
+
+
+ImageFormat = Literal["JPEG", "PNG"]
+
+
+@dataclass(frozen=True)
+class SmartImage:
+    _image: MatLike
+    _sharpening_kernel: ClassVar[np.ndarray] = np.array(
+        [[-1, -1, -1], [-1, 9, -1], [-1, -1, -1]]
+    )
+
+    # -----------------------------
+    # Constructors
+    # -----------------------------
+    @classmethod
+    def from_bytes(cls, image_bytes: bytes):
+        if not image_bytes:
+            raise ImageEmpty()
+
+        cls.verify_bytes(image_bytes)
+
+        image = SmartImage.bytes_to_cv2(image_bytes)
+
+        if image is None:
+            raise InvalidImage()
+
+        return cls(_image=image)
+
+    @classmethod
+    def from_cv2(cls, image: MatLike) -> "SmartImage":
+        if image is None or image.size == 0:
+            raise ImageEmpty()
+        return cls(_image=image.copy())
+
+    @classmethod
+    def from_pillow(cls, image: Image.Image) -> "SmartImage":
+        if image is None:
+            raise ImageEmpty()
+        return cls.from_cv2(SmartImage.pillow_to_cv2(image))
+
+    # -----------------------------
+    # Calculated Property
+    # -----------------------------
+    @property
+    def shape(self):
+        return self._image.shape
+
+    # -----------------------------
+    # Conversions (On Demand)
+    # -----------------------------
+    def to_cv2(self) -> MatLike:
+        return self._image.copy()
+
+    def to_pillow(self) -> Image.Image:
+        return SmartImage.cv2_to_pillow(self._image)
+
+    def to_bytes(self, format: ImageFormat = "JPEG", quality: int = 80) -> bytes:
+        return SmartImage.cv2_to_bytes(self._image, format, quality)
+
+    def to_base64(self, format: ImageFormat = "JPEG", quality: int = 80) -> str:
+        return base64.b64encode(self.to_bytes(format=format, quality=quality)).decode(
+            "utf-8"
+        )
+
+    # -----------------------------
+    # Transformations (Pure)
+    # -----------------------------
+    def resize(self, width: int = None, height: int = None):
+        return SmartImage.from_cv2(SmartImage.resize_image(self._image, width, height))
+
+    def crop(self, bbox: tuple[int, int, int, int], padding_factor: float = 0):
+        return SmartImage.from_cv2(
+            SmartImage.crop_image(self._image, bbox, padding_factor)
+        )
+
+    def rotate(self, angle: int):
+        return SmartImage.from_cv2(SmartImage.rotate_image(self._image, angle))
+
+    def sharpen_v1(self):
+        return SmartImage.from_cv2(SmartImage.sharpened_image_v1(self._image))
+
+    def sharpen_v2(self):
+        return SmartImage.from_cv2(SmartImage.sharpened_image_v2(self._image))
+
+    def adjust_quality(self, format: ImageFormat, quality: int = 80):
+        return SmartImage.from_cv2(
+            SmartImage.adjust_quality_image(self._image, format, quality),
+        )
+
+    def apply(self, fn):
+        new_img = fn(self._image.copy())
+        return SmartImage.from_cv2(new_img)
+
+    # -----------------------------
+    # Document Related
+    # -----------------------------
+    def ensure_document_upright(self, tolerance: float = 10):
+        return SmartImage.from_cv2(
+            SmartImage.ensure_document_upright_image(self._image, tolerance),
+        )
+
+    def ensure_document_portrait(self):
+        return SmartImage.from_cv2(
+            SmartImage.ensure_document_portrait_image(self._image)
+        )
+
+    def ensure_document_landscape(self):
+        return SmartImage.from_cv2(
+            SmartImage.ensure_document_landscape_image(self._image)
+        )
+
+    def unwarp_document(self, pts: list[tuple[int, int]], padding_ratio: float = 0.01):
+        return SmartImage.from_cv2(
+            SmartImage.unwarp_document_image(self._image, pts, padding_ratio)
+        )
+
+    # -----------------------------
+    # Validation Helpers
+    # -----------------------------
+
+    @staticmethod
+    def verify_bytes(image_bytes: bytes):
+        try:
+            Image.open(io.BytesIO(image_bytes)).verify()
+        except Exception:
+            raise InvalidImage()
+
+    @staticmethod
+    def validate_size(image_bytes: bytes, max_size_mb: Optional[float]):
+        if max_size_mb:
+            size_mb = len(image_bytes) / (1024 * 1024)
+            if size_mb > max_size_mb:
+                raise ImageTooLarge(max_size_mb)
+        return True
+
+    # -----------------------------
+    # Static Methods
+    # -----------------------------
+
+    @staticmethod
+    def bytes_to_cv2(image: bytes):
+        np_arr = np.frombuffer(image, np.uint8)
+        return cv2.imdecode(np_arr, cv2.IMREAD_COLOR)
+
+    @staticmethod
+    def bytes_to_base64(image: bytes):
+        return base64.b64encode(image).decode("utf-8")
+
+    @staticmethod
+    def bytes_to_pillow(image: bytes):
+        """Converts raw bytes into a PIL Image object."""
+        return Image.open(io.BytesIO(image))
+
+    @staticmethod
+    def cv2_to_bytes(image: MatLike, format: ImageFormat = "JPEG", quality: int = 80):
+        # Set JPEG quality (0 to 100, higher = better quality, larger size)
+        if format.upper() == "PNG":
+            # PNG is lossless, so quality is ignored (uses compression level 0-9 instead)
+            success, image_bytes = cv2.imencode(".png", image)
+        else:
+            encode_params = [int(cv2.IMWRITE_JPEG_QUALITY), quality]
+            success, image_bytes = cv2.imencode(".jpg", image, encode_params)
+
+        if not success:
+            raise InvalidImage()
+        return image_bytes.tobytes()
+
+    @staticmethod
+    def cv2_to_base64(image: MatLike, format: ImageFormat = "JPEG", quality: int = 80):
+        image_bytes = SmartImage.cv2_to_bytes(image, format, quality)
+        return SmartImage.bytes_to_base64(image_bytes)
+
+    @staticmethod
+    def cv2_to_pillow(image: MatLike):
+        rgb_image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        return Image.fromarray(rgb_image)
+
+    @staticmethod
+    def pillow_to_bytes(
+        image: Image.Image, format: ImageFormat = "JPEG", quality: int = 80
+    ):
+        buffer = io.BytesIO()
+        # PNG doesn't use the quality kwarg
+        if format.upper() == "PNG":
+            image.save(buffer, format="PNG")
+        else:
+            image.save(buffer, format="JPEG", quality=quality)
+        return buffer.getvalue()
+
+    @staticmethod
+    def pillow_to_cv2(image: Image.Image):
+        rgb_arr = np.array(image)
+        return cv2.cvtColor(rgb_arr, cv2.COLOR_RGB2BGR)
+
+    @staticmethod
+    def pillow_to_base64(
+        image: Image.Image, format: ImageFormat = "JPEG", quality: int = 80
+    ) -> str:
+        image_bytes = SmartImage.pillow_to_bytes(image, format, quality)
+        return SmartImage.bytes_to_base64(image_bytes)
+
+    @staticmethod
+    def crop_image(
+        image: MatLike, bbox: tuple[int, int, int, int], padding_factor: float = 0
+    ):
+        result_image = image.copy()
+        try:
+            x1, y1, x2, y2 = bbox
+            img_h, img_w = result_image.shape[:2]
+
+            # Calculate dynamic padding as a percentage of the image dimensions
+            padding = int(min(img_h, img_w) * padding_factor)
+
+            # Apply padding and clamp to image boundaries
+            x1 = max(0, x1 - padding)
+            y1 = max(0, y1 - padding)
+            x2 = min(img_w, x2 + padding)
+            y2 = min(img_h, y2 + padding)
+
+            # Validate the cropped region
+            if x1 >= x2 or y1 >= y2:
+                return None
+
+            result_image = result_image[y1:y2, x1:x2]
+            if result_image.size == 0:
+                return None
+
+            return result_image
+
+        except Exception:
+            return result_image
+
+    @staticmethod
+    def resize_image(image: MatLike, width: int = None, height: int = None):
+
+        if not width and not height:
+            raise ValueError("Either width or height must be provided")
+
+        h, w = image.shape[:2]
+
+        if width and height:
+            resized = cv2.resize(image, (width, height))
+        elif width:
+            ratio = width / w
+            resized = cv2.resize(image, (width, int(h * ratio)))
+        elif height:
+            ratio = height / h
+            resized = cv2.resize(image, (int(w * ratio), height))
+        else:
+            return image
+
+        return resized
+
+    @staticmethod
+    def adjust_quality_image(image: MatLike, format: ImageFormat, quality: int = 80):
+        return SmartImage.bytes_to_cv2(SmartImage.cv2_to_bytes(image, format, quality))
+
+    @staticmethod
+    def sharpened_image_v1(image: MatLike):
+        blurred_image = cv2.GaussianBlur(image, (5, 5), 0)
+        sharpened_image = cv2.filter2D(blurred_image, -1, SmartImage._sharpening_kernel)
+        return sharpened_image
+
+    @staticmethod
+    def sharpened_image_v2(image: MatLike):
+        kernel = np.array([[-1, -1, -1], [-1, 9, -1], [-1, -1, -1]])
+        return cv2.filter2D(image, -1, kernel)
+
+    @staticmethod
+    def rotate_image(image: MatLike, angle: Literal[90, 180, 270]):
+        if angle == 90:
+            rotated = cv2.rotate(image, cv2.ROTATE_90_CLOCKWISE)
+        elif angle == 180:
+            rotated = cv2.rotate(image, cv2.ROTATE_180)
+        elif angle == 270:
+            rotated = cv2.rotate(image, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        else:
+            raise InvalidAngle()
+
+        return rotated
+
+    @staticmethod
+    def __order_points(pts: list[tuple[int, int]]):
+        # Convert to numpy array if not already
+        np_pts = np.array(pts, dtype=np.float32)
+
+        # Sum and difference to sort the points
+        s = np_pts.sum(axis=1)
+        diff = np.diff(pts, axis=1)
+
+        ordered = np.zeros((4, 2), dtype=np.float32)
+        ordered[0] = np_pts[np.argmin(s)]  # Top-left
+        ordered[2] = np_pts[np.argmax(s)]  # Bottom-right
+        ordered[1] = np_pts[np.argmin(diff)]  # Top-right
+        ordered[3] = np_pts[np.argmax(diff)]  # Bottom-left
+
+        return ordered
+
+    @staticmethod
+    def __get_max_dimensions(np_pts: np.ndarray[tuple[int, int], np.dtype[np.float32]]):
+        (tl, tr, br, bl) = np_pts
+
+        widthA = np.linalg.norm(br - bl)
+        widthB = np.linalg.norm(tr - tl)
+        maxWidth = max(int(widthA), int(widthB))
+
+        heightA = np.linalg.norm(tr - br)
+        heightB = np.linalg.norm(tl - bl)
+        maxHeight = max(int(heightA), int(heightB))
+
+        return maxWidth, maxHeight
+
+    # @staticmethod
+    # def unwarp_document(image: np.ndarray, pts: list[tuple[int, int]]):
+    #     rect = ImageService.__order_points(pts)
+    #     maxWidth, maxHeight = ImageService.__get_max_dimensions(rect)
+
+    #     # Destination points for the "rectified" image
+    #     dst = np.array([
+    #         [0, 0],
+    #         [maxWidth - 1, 0],
+    #         [maxWidth - 1, maxHeight - 1],
+    #         [0, maxHeight - 1]], dtype=np.float32)
+
+    #     # Compute the perspective transform matrix and apply it
+    #     M = cv2.getPerspectiveTransform(rect, dst)
+    #     warped = cv2.warpPerspective(image, M, (maxWidth, maxHeight))
+
+    #     return warped
+
+    @staticmethod
+    def unwarp_document_image(
+        image: MatLike, pts: list[tuple[int, int]], padding_ratio: float = 0.01
+    ):
+        rect = SmartImage.__order_points(pts)
+        maxWidth, maxHeight = SmartImage.__get_max_dimensions(rect)
+
+        # Calculate proportional padding in pixels
+        padding = int(max(maxWidth, maxHeight) * padding_ratio)
+
+        # Destination points for the "rectified" image
+        dst = np.array(
+            [
+                [padding, padding],
+                [maxWidth - 1 + padding, padding],
+                [maxWidth - 1 + padding, maxHeight - 1 + padding],
+                [padding, maxHeight - 1 + padding],
+            ],
+            dtype=np.float32,
+        )
+
+        # Compute the perspective transform matrix and apply it
+        M = cv2.getPerspectiveTransform(rect, dst)
+        warped = cv2.warpPerspective(
+            image, M, (maxWidth + padding * 2, maxHeight + padding * 2)
+        )
+
+        return warped
+
+    @staticmethod
+    def ensure_document_landscape_image(image: MatLike):
+        """
+        Rotates the image 90 degrees counter-clockwise if it is in portrait orientation
+        (i.e., height > width), so that the output is in landscape orientation.
+
+        Args:
+            image (MatLike): Input image.
+
+        Returns:
+            MatLike Rotated (if needed) image in landscape orientation.
+        """
+        h, w = image.shape[:2]
+        result_image = image.copy()
+        if h > w:
+            result_image = cv2.rotate(result_image, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        return result_image
+
+    @staticmethod
+    def ensure_document_portrait_image(image: MatLike):
+        """
+        Rotates the image 90 degrees counter-clockwise if it is in landscape orientation
+        (i.e., width > height), so that the output is in portrait orientation.
+
+        Args:
+            image (MatLike): Input image.
+
+        Returns:
+            MatLike Rotated (if needed) image in landscape orientation.
+        """
+        h, w = image.shape[:2]
+        result_image = image.copy()
+        if w > h:
+            result_image = cv2.rotate(result_image, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        return result_image
+
+    @staticmethod
+    def ensure_document_upright_image(image: MatLike, tolerance: float = 10) -> MatLike:
+        """
+        Checks image orientation using pytesseract and rotates it by 180 degrees
+        if rotation angle is close to 180.
+
+        Args:
+            img (MatLike): Input image (as a NumPy array).
+
+        Returns:
+            MatLike: Rotated or original image.
+        """
+        try:
+            import pytesseract
+        except ImportError as e:
+            raise RuntimeError(
+                "pytesseract is required for OCR. "
+                "Install with `pip install imagekit-python[pytesseract]`"
+            ) from e
+        result_image = image.copy()
+        try:
+            orientation_data = pytesseract.image_to_osd(
+                result_image, output_type=pytesseract.Output.DICT
+            )
+            print(orientation_data)
+            angle = orientation_data["rotate"]
+
+            if abs(angle - 180) < tolerance:
+                result_image = cv2.rotate(result_image, cv2.ROTATE_180)
+
+        except pytesseract.pytesseract.TesseractError as e:
+            print("Tesseract OSD error:", e)
+
+        return result_image

imagekit_python-0.0.1a1.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: imagekit-python
+Version: 0.0.1a1
+Summary: A Python library that provides a unified interface for handling images across multiple formats and performing common image processing tasks.
+Project-URL: Repository, https://github.com/Hoopoes/imagekit
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: opencv-python-headless>=4.13.0.92
+Requires-Dist: pillow>=9.5.0
+Requires-Dist: pydantic>=2.5.3
+Provides-Extra: all
+Requires-Dist: pytesseract; extra == 'all'
+Provides-Extra: pytesseract
+Requires-Dist: pytesseract>=0.3.13; extra == 'pytesseract'
+Description-Content-Type: text/markdown
+
+# Imagekit
+
+`ImageKit` is a Python library that provides a unified interface for handling images across multiple formats (`bytes`, OpenCV `cv2`, Pillow `Image`) and performing common image processing tasks. It is designed for developers who want all-in-one image handling and processing, including conversion, cropping, resizing, rotation, and document unwarping.
+
+
+
+## Installation
+
+```bash
+coming soon
+```
+
+
+## Quick Start 🚀 
+
+### Basic Usage
+
+```python
+coming soon
+```
+
+
+## Parameters
+
+
+
+
+
+
+
+## License
+
+MIT License

imagekit_python-0.0.1a1.dist-info/RECORD

@@ -0,0 +1,6 @@
+imagekit_python/__init__.py,sha256=vekDkQ92P7wCwBEsISCufiwloXh50xNHNfriFrISefU,241
+imagekit_python/smart_image.py,sha256=s1A5EEyE7vg6hVuCQOOmwsNw-C0W9GQ3EDq7MEmDIVM,15980
+imagekit_python-0.0.1a1.dist-info/METADATA,sha256=zO2WuWnn3gSx8Z7YnodZrGiGHCoydTSNGRKjK5SbSKk,1880
+imagekit_python-0.0.1a1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+imagekit_python-0.0.1a1.dist-info/licenses/LICENSE,sha256=vvtkYZ1iMd5ly1zrMSW1oX1iMgL4z1eVa9KT3ijlA5E,1085
+imagekit_python-0.0.1a1.dist-info/RECORD,,

imagekit_python-0.0.1a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

imagekit_python-0.0.1a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hoopoes
+
+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.