ImagePRO-Python 1.2.2__py3-none-any.whl → 1.3.1__py3-none-any.whl

ImagePRO/pre_processing/blur.py

@@ -60,9 +60,9 @@ def apply_average_blur(
     ):
         raise ValueError("'kernel_size' must be a tuple of two positive integers.")
 
-    # Apply box filter blur
-    blurred = cv2.blur(image._data.copy(), kernel_size)
-    
+    # Apply box filter blur (cv2.blur never mutates its input)
+    blurred = cv2.blur(image._data, kernel_size)
+
     return Result(
         image=blurred,
         meta={
@@ -112,8 +112,8 @@ def apply_gaussian_blur(
         raise ValueError("'kernel_size' must be a tuple of two odd positive integers.")
 
     # Apply Gaussian blur with automatic sigma calculation
-    blurred = cv2.GaussianBlur(image._data.copy(), kernel_size, 0)
-    
+    blurred = cv2.GaussianBlur(image._data, kernel_size, 0)
+
     return Result(
         image=blurred,
         meta={
@@ -160,8 +160,8 @@ def apply_median_blur(
         raise ValueError("'filter_size' must be an odd integer greater than 1.")
 
     # Apply median filtering
-    blurred = cv2.medianBlur(image._data.copy(), filter_size)
-    
+    blurred = cv2.medianBlur(image._data, filter_size)
+
     return Result(
         image=blurred,
         meta={
@@ -203,7 +203,7 @@ def apply_bilateral_blur(
         Result: Result object with smoothed image.
             - image (np.ndarray): Edge-preserving smoothed output
             - data (None): No additional data
-            - meta (dict): Contains filter *,parameters and operation info
+            - meta (dict): Contains filter parameters and operation info
 
     Raises:
         TypeError: If image is not an Image instance
@@ -221,12 +221,12 @@ def apply_bilateral_blur(
 
     # Apply bilateral filter
     blurred = cv2.bilateralFilter(
-        image._data.copy(),
+        image._data,
         filter_size,
         sigma_color,
         sigma_space
     )
-    
+
     return Result(
         image=blurred,
         meta={

ImagePRO/pre_processing/contrast.py

@@ -13,14 +13,11 @@ import cv2
 
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
-from ImagePRO.pre_processing.grayscale import convert_to_grayscale
 
 
 # Constants for contrast enhancement
 DEFAULT_CLIP_LIMIT = 2.0      # For CLAHE
 DEFAULT_TILE_GRID_SIZE = (8, 8)  # For CLAHE
-DEFAULT_ALPHA = 1.5           # For linear stretching
-DEFAULT_BETA = 10            # For linear stretching
 
 
 def apply_clahe_contrast(
@@ -65,8 +62,8 @@ def apply_clahe_contrast(
     ):
         raise TypeError("'tile_grid_size' must be a tuple of two positive integers")
 
-    # Convert and apply CLAHE
-    grayscale = convert_to_grayscale(image=Image.from_array(image._data.copy()))
+    # Convert and apply CLAHE (cvtColor returns a new array; input untouched)
+    grayscale = cv2.cvtColor(image._data, cv2.COLOR_BGR2GRAY)
     clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=tile_grid_size)
     enhanced = clahe.apply(grayscale)
 
@@ -105,7 +102,7 @@ def apply_histogram_equalization(
         raise TypeError("'image' must be an Image instance")
 
     # Convert and apply global histogram equalization
-    grayscale = convert_to_grayscale(image=Image.from_array(image._data.copy()))
+    grayscale = cv2.cvtColor(image._data, cv2.COLOR_BGR2GRAY)
     enhanced = cv2.equalizeHist(grayscale)
 
     return Result(
@@ -156,7 +153,7 @@ def apply_contrast_stretching(
         raise ValueError("'beta' must be an integer between 0 and 255")
 
     # Convert and apply linear stretching
-    grayscale = convert_to_grayscale(image=Image.from_array(image._data.copy()))
+    grayscale = cv2.cvtColor(image._data, cv2.COLOR_BGR2GRAY)
     enhanced = cv2.convertScaleAbs(grayscale, alpha=alpha, beta=beta)
 
     return Result(

ImagePRO/pre_processing/crop.py

@@ -12,10 +12,6 @@ if str(_src_path) not in sys.path:
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
-# Constants
-DEFAULT_START_POINT = (0, 0)
-DEFAULT_END_POINT = (100, 100)
-
 
 def crop_image(
     image: Image,
@@ -59,7 +55,10 @@ def crop_image(
     x2, y2 = end_point
 
     if x1 < 0 or y1 < 0 or x2 <= x1 or y2 <= y1:
-        raise ValueError("Invalid crop coordinates: ensure (x1, y1) is top-left and (x2, y2) is bottom-right")
+        raise ValueError(
+            "Invalid crop coordinates: ensure (x1, y1) is top-left "
+            "and (x2, y2) is bottom-right"
+        )
 
     height, width = image.shape[:2]
 

ImagePRO/pre_processing/dataset_generator.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import random
 import sys
+import time
 from pathlib import Path
 
 # Add src directory to path for absolute imports
@@ -9,16 +11,12 @@ _src_path = _file_path.parents[2]  # Go up to src directory
 if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
+import cv2
+
 from ImagePRO.human_analysis.face_analysis.face_detection import detect_faces
-from ImagePRO.pre_processing import blur, grayscale, rotate, sharpen, resize
+from ImagePRO.pre_processing import blur, grayscale, resize, rotate, sharpen
 from ImagePRO.utils.image import Image
 
-import random
-import time
-
-import cv2
-import mediapipe as mp
-
 # Constants
 DEFAULT_NUM_IMAGES = 200
 DEFAULT_START_INDEX = 0
@@ -40,7 +38,7 @@ def capture_bulk_pictures(
     apply_grayscale: bool = False,
     apply_sharpen: bool = False,
     apply_rotate: bool = False,
-    apply_resize: tuple = False,
+    apply_resize: tuple[int, int] | bool = False,
     delay: float = DEFAULT_DELAY
 ) -> None:
     """Generate a dataset by capturing faces from webcam.
@@ -50,7 +48,7 @@ def capture_bulk_pictures(
     face recognition datasets with data augmentation.
 
     Processing pipeline (if enabled):
-    average blur → laplacian sharpen → grayscale → resize → random rotate
+    median blur → laplacian sharpen → grayscale → resize → random rotate
 
     Args:
         folder_path: Base directory for dataset.
@@ -96,6 +94,14 @@ def capture_bulk_pictures(
     if not isinstance(delay, (int, float)) or delay < 0:
         raise ValueError("'delay' must be a non-negative number")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for dataset "
+            'generation. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Setup output directory structure
     base_dir = Path(folder_path)
     face_folder = base_dir / str(face_id)
@@ -135,7 +141,7 @@ def capture_bulk_pictures(
 
             if apply_blur:
                 # Reduce noise while preserving facial features
-                processed = blur.apply_average_blur(
+                processed = blur.apply_median_blur(
                     image=Image.from_array(processed),
                     filter_size=3
                 ).image

ImagePRO/pre_processing/histogram.py

@@ -15,73 +15,61 @@ import matplotlib.pyplot as plt
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
+
 def show_histogram(image: Image) -> Result:
     """
-    Displays the histogram of an image with customizable options.
-    
-    This function visualizes the intensity distribution of an image. It handles both grayscale
-    and color images, with automatic detection of image type. For color images, it displays
-    histograms for each color channel (BGR or RGB) with appropriate colors.
+    Builds a matplotlib histogram figure for an image.
+
+    This function creates the histogram plot of the intensity distribution of
+    an image. It handles both grayscale and color images, with automatic
+    detection of image type. For color images, it plots a histogram for each
+    color channel (BGR or RGB) with appropriate colors. The pyplot module is
+    returned in ``data``; call ``matplotlib.pyplot.show()`` to display the
+    figure.
 
     Args:
         image (Image):
-            Input image to convert. Must be BGR, RGB or Grayscale format.
+            Input image to analyze. Must be BGR, RGB or Grayscale format.
 
     Returns:
         Result: Result object with histogram plot.
-            - image (np.ndarray): None
-            - data (None): matplotlib.pyplot object
+            - image: None
+            - data: The matplotlib.pyplot module (figure is created, not shown)
             - meta (dict): Contains source object and operation info
 
     Raises:
         TypeError: If image is not an Image instance
-        ValueError: If image colorspace is not defined.
+        ValueError: If image colorspace is not supported.
     """
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance.")
 
-    if image.colorspace == "BGR":
-        colors = ('blue', 'green', 'red')
-        plt.figure(figsize=(10, 6))
+    if image.colorspace in ("BGR", "RGB"):
+        if image.colorspace == "BGR":
+            colors = ("blue", "green", "red")
+            labels = ("Blue Channel", "Green Channel", "Red Channel")
+        else:
+            colors = ("red", "green", "blue")
+            labels = ("Red Channel", "Green Channel", "Blue Channel")
+        channels = list(enumerate(colors))
+    elif image.colorspace == "GRAY":
+        channels = [(0, "black")]
+        labels = None
+    else:
+        raise ValueError(f"Unknown colorspace: {image.colorspace}")
 
-        for i, color in enumerate(colors):
-            hist = cv2.calcHist([image._data], [i], None, [256], [0, 256])
-            plt.plot(hist, color=color)
-            plt.xlim([0, 256])
-            
-        
-        plt.title('Histogram of BGR Channels')
-        plt.xlabel('Pixel Intensity')
-        plt.ylabel('Frequency')
-        plt.legend(['Blue Channel', 'Green Channel', 'Red Channel'])
-           
-            
-    elif image.colorspace == "RGB":
-        colors = ('red', 'green', 'blue')
-        plt.figure(figsize=(10, 6))
+    plt.figure(figsize=(10, 6))
+    for channel, color in channels:
+        hist = cv2.calcHist([image._data], [channel], None, [256], [0, 256])
+        plt.plot(hist, color=color)
 
-        for i, color in enumerate(colors):
-            hist = cv2.calcHist([image._data], [i], None, [256], [0, 256])
-            plt.plot(hist, color=color)
-            plt.xlim([0, 256])
-            
-        
-        plt.title('Histogram of RGB Channels')
-        plt.xlabel('Pixel Intensity')
-        plt.ylabel('Frequency')
-        plt.legend(['Red Channel', 'Green Channel', 'Blue Channel'])
-            
-            
-    elif image.colorspace == 'GRAY':
-        plt.figure(figsize=(10, 6))
+    if labels is not None:
+        plt.title(f"Histogram of {image.colorspace} Channels")
+        plt.legend(labels)
+        plt.xlabel("Pixel Intensity")
+        plt.ylabel("Frequency")
 
-        hist = cv2.calcHist([image._data], [0], None, [256], [0, 256])
-        plt.plot(hist, color='black')
-        plt.xlim([0, 256])
-        
-    else:
-        return ValueError('Unknown colorspace')
-        
+    plt.xlim([0, 256])
 
     return Result(
         image=None,

ImagePRO/pre_processing/resize.py

@@ -22,7 +22,7 @@ def resize_image(
 ) -> Result:
     """Resize an image to specified dimensions.
 
-    Changes image size while maintaining aspect ratio.
+    Changes image size to the exact (width, height) given.
     Uses bilinear interpolation for smooth resizing.
 
     Args:
@@ -52,7 +52,7 @@ def resize_image(
 
     # Resize using bilinear interpolation
     resized = cv2.resize(image._data, new_size, interpolation=cv2.INTER_LINEAR)
-    
+
     return Result(
         image=resized,
         meta={

ImagePRO/pre_processing/rotate.py

@@ -10,7 +10,6 @@ if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
 import cv2
-import numpy as np
 
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
@@ -18,7 +17,6 @@ from ImagePRO.utils.result import Result
 
 # Constants for rotation operations
 DEFAULT_SCALE = 1.0
-DEFAULT_ANGLE = 45.0
 
 
 def rotate_image_90(image: Image) -> Result:
@@ -39,7 +37,7 @@ def rotate_image_90(image: Image) -> Result:
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    rotated = cv2.rotate(image._data.copy(), cv2.ROTATE_90_CLOCKWISE)
+    rotated = cv2.rotate(image._data, cv2.ROTATE_90_CLOCKWISE)
     return Result(
         image=rotated,
         meta={
@@ -68,7 +66,7 @@ def rotate_image_180(image: Image) -> Result:
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    rotated = cv2.rotate(image._data.copy(), cv2.ROTATE_180)
+    rotated = cv2.rotate(image._data, cv2.ROTATE_180)
     return Result(
         image=rotated,
         meta={
@@ -97,7 +95,7 @@ def rotate_image_270(image: Image) -> Result:
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    rotated = cv2.rotate(image._data.copy(), cv2.ROTATE_90_COUNTERCLOCKWISE)
+    rotated = cv2.rotate(image._data, cv2.ROTATE_90_COUNTERCLOCKWISE)
     return Result(
         image=rotated,
         meta={
@@ -117,7 +115,8 @@ def rotate_image_custom(
     """Rotate image by custom angle with optional scaling.
 
     Rotates around image center. Positive angles are counter-clockwise.
-    Image is resized to contain full rotated content.
+    The output canvas keeps the original image dimensions, so corners of
+    the rotated image may be clipped.
 
     Args:
         image: Input image to rotate.
@@ -144,7 +143,7 @@ def rotate_image_custom(
 
     h, w = image.shape[:2]
     matrix = cv2.getRotationMatrix2D((w/2, h/2), angle, scale)
-    rotated = cv2.warpAffine(image._data.copy(), matrix, (w, h))
+    rotated = cv2.warpAffine(image._data, matrix, (w, h))
 
     return Result(
         image=rotated,

ImagePRO/pre_processing/sharpen.py

@@ -14,7 +14,7 @@ import numpy as np
 
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
-from ImagePRO.pre_processing.blur import apply_average_blur
+from ImagePRO.pre_processing.blur import DEFAULT_KERNEL_SIZE
 
 # Constants
 DEFAULT_LAPLACIAN_COEFFICIENT = 3.0
@@ -52,13 +52,16 @@ def apply_laplacian_sharpening(
     if not isinstance(coefficient, (int, float)) or coefficient < 0:
         raise ValueError("'coefficient' must be a non-negative number")
 
-    # Apply Laplacian edge detection
-    laplacian = cv2.Laplacian(image._data.copy(), cv2.CV_64F)
-    laplacian = np.uint8(np.absolute(laplacian))
+    # Apply Laplacian edge detection, then enhance edges while keeping
+    # float arithmetic identical to: image + coefficient * |laplacian|
+    laplacian = cv2.Laplacian(image._data, cv2.CV_64F)
+    np.absolute(laplacian, out=laplacian)
+    laplacian = laplacian.astype(np.uint8)
 
-    # Enhance edges
-    sharpened = image._data + coefficient * laplacian
-    sharpened = np.uint8(np.clip(sharpened, 0, 255))
+    sharpened = laplacian * coefficient
+    sharpened += image._data
+    np.clip(sharpened, 0, 255, out=sharpened)
+    sharpened = sharpened.astype(np.uint8)
 
     return Result(
         image=sharpened,
@@ -102,15 +105,15 @@ def apply_unsharp_masking(
         raise ValueError("'coefficient' must be a non-negative number")
 
     # Create the mask from original vs blurred difference
-    blurred = apply_average_blur(image=Image.from_array(image._data.copy()))
+    blurred = cv2.blur(image._data, DEFAULT_KERNEL_SIZE)
     mask = cv2.subtract(image._data, blurred)
-    
+
     # Apply unsharp masking
     sharpened = cv2.addWeighted(
-        image._data, 
-        1 + coefficient, 
-        mask, 
-        -coefficient, 
+        image._data,
+        1 + coefficient,
+        mask,
+        -coefficient,
         0
     )
 

ImagePRO/utils/image.py

@@ -18,8 +18,9 @@ class Image:
     """
     Lightweight, immutable image wrapper for ImagePRO.
 
-    Use factory constructors to create instances. All methods return new Image objects.
-    Images are handled in BGR format by default to match OpenCV conventions.
+    Use factory constructors to create instances; instances are lightweight
+    wrappers and are not modified by ImagePRO operations. Images are handled
+    in BGR format by default to match OpenCV conventions.
 
     Attributes:
         _data (np.ndarray):
@@ -35,7 +36,7 @@ class Image:
         >>> # Load from file (default BGR)
         >>> img = Image.from_path('input.jpg', colorspace="BGR")
         >>> print(img.shape)  # (H, W, 3)
-        >>> 
+        >>>
         >>> # Or wrap a NumPy array
         >>> img = Image.from_array(np_array, colorspace="RGB")
     """
@@ -47,7 +48,7 @@ class Image:
 
     @classmethod
     def from_path(
-        cls, 
+        cls,
         path: str | Path,
         colorspace: Colorspace = "BGR"
     ) -> Image:
@@ -58,7 +59,8 @@ class Image:
             path (str | Path):
                 Path to the image file.
             colorspace (Colorspace, optional):
-                Colorspace of the image array in that path ("BGR", "RGB", or "GRAY"). Defaults to "BGR".
+                Colorspace of the image array in that path
+                ("BGR", "RGB", or "GRAY"). Defaults to "BGR".
 
         Returns:
             Image: New Image instance loaded from disk.
@@ -124,4 +126,3 @@ class Image:
             np.dtype: Data type of the image array.
         """
         return self._data.dtype
-        

ImagePRO/utils/result.py

@@ -143,22 +143,25 @@ class Result:
             raise IOError(f"Failed to write CSV to {out_path}: {exc}") from exc
         return self
 
-def flatten_rows(data):
+
+def flatten_rows(data: Any) -> list[list[Any]]:
     """
     Flatten nested lists/tuples into rows suitable for CSV writing.
-    
+
     Recursively processes nested data structures to create a flat list of rows
     that can be written to a CSV file. Handles mixed nesting levels gracefully.
-    
+
     Args:
         data: Nested list/tuple structure containing data to flatten.
-        
+
     Returns:
         list[list[Any]]: Flattened list of rows, where each row is a list of values.
-        
+
     Example:
-        >>> flatten_rows([[1, 2], [3, [4, 5]]])
-        [[1, 2], [3, 4, 5]]
+        >>> flatten_rows([[1, 2], [3, 4]])
+        [[1, 2], [3, 4]]
+        >>> flatten_rows([[[1, 2], [3, 4]], [5]])
+        [[1, 2], [3, 4], [5]]
     """
     rows = []
     for item in data: