ImagePRO-Python 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

ImagePRO/pre_processing/blur.py

@@ -1,6 +1,5 @@
 import sys
 from pathlib import Path
-
 import cv2
 import numpy as np
 
@@ -8,24 +7,44 @@ import numpy as np
 parent_dir = Path(__file__).resolve().parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 
-def apply_average_blur(kernel_size=(5, 5), image_path=None, np_image=None, result_path=None):
+def apply_average_blur(
+    kernel_size: tuple[int, int] = (5, 5),
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Apply average blur (box filter) to an image.
 
-    Args:
-        kernel_size (tuple): (width, height) of the blur kernel.
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save output.
-
-    Returns:
-        str or np.ndarray: Saved message or blurred image.
-
-    Raises:
-        TypeError, ValueError: On invalid inputs.
+    Parameters
+    ----------
+    kernel_size : tuple[int, int], default=(5, 5)
+        Blur kernel size (width, height). Both must be positive integers.
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded BGR image array.
+    output_image_path : str | None, optional
+        If provided, save the blurred image.
+
+    Returns
+    -------
+    np.ndarray
+        Blurred image.
+
+    Raises
+    ------
+    ValueError
+        If kernel size is invalid.
+    TypeError
+        If input types are invalid.
+    FileNotFoundError
+        If image path does not exist.
+    IOError
+        If saving the image fails.
     """
     if (
         not isinstance(kernel_size, tuple)
@@ -34,26 +53,42 @@ def apply_average_blur(kernel_size=(5, 5), image_path=None, np_image=None, resul
     ):
         raise ValueError("'kernel_size' must be a tuple of two positive integers.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     blurred = cv2.blur(np_image, kernel_size)
-    return IOHandler.save_image(blurred, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(blurred, output_image_path))
+    return blurred
 
 
-def apply_gaussian_blur(kernel_size=(5, 5), image_path=None, np_image=None, result_path=None):
+def apply_gaussian_blur(
+    kernel_size: tuple[int, int] = (5, 5),
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Apply Gaussian blur to an image.
 
-    Args:
-        kernel_size (tuple): (width, height), both odd positive integers.
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save output.
-
-    Returns:
-        str or np.ndarray: Saved message or blurred image.
-
-    Raises:
-        TypeError, ValueError: On invalid inputs.
+    Parameters
+    ----------
+    kernel_size : tuple[int, int], default=(5, 5)
+        Kernel size (width, height), both odd positive integers.
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded BGR image array.
+    output_image_path : str | None, optional
+        If provided, save the blurred image.
+
+    Returns
+    -------
+    np.ndarray
+        Blurred image.
+
+    Raises
+    ------
+    ValueError
+        If kernel size is invalid.
     """
     if (
         not isinstance(kernel_size, tuple)
@@ -62,61 +97,92 @@ def apply_gaussian_blur(kernel_size=(5, 5), image_path=None, np_image=None, resu
     ):
         raise ValueError("'kernel_size' must be a tuple of two odd positive integers.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     blurred = cv2.GaussianBlur(np_image, kernel_size, sigmaX=0)
-    return IOHandler.save_image(blurred, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(blurred, output_image_path))
+    return blurred
 
 
-def apply_median_blur(filter_size=5, image_path=None, np_image=None, result_path=None):
+def apply_median_blur(
+    filter_size: int = 5,
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Apply median blur to remove salt-and-pepper noise.
 
-    Args:
-        filter_size (int): Must be an odd integer greater than 1.
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save output.
-
-    Returns:
-        str or np.ndarray: Saved message or blurred image.
-
-    Raises:
-        TypeError, ValueError: On invalid inputs.
+    Parameters
+    ----------
+    filter_size : int, default=5
+        Must be an odd integer greater than 1.
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded BGR image array.
+    output_image_path : str | None, optional
+        If provided, save the blurred image.
+
+    Returns
+    -------
+    np.ndarray
+        Blurred image.
+
+    Raises
+    ------
+    TypeError
+        If filter_size is not an integer.
+    ValueError
+        If filter_size is not an odd integer greater than 1.
     """
     if not isinstance(filter_size, int):
         raise TypeError("'filter_size' must be an integer.")
     if filter_size <= 1 or filter_size % 2 == 0:
         raise ValueError("'filter_size' must be an odd integer greater than 1.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     blurred = cv2.medianBlur(np_image, filter_size)
-    return IOHandler.save_image(blurred, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(blurred, output_image_path))
+    return blurred
 
 
 def apply_bilateral_blur(
-    filter_size=9,
-    sigma_color=75,
-    sigma_space=75,
-    image_path=None,
-    np_image=None,
-    result_path=None,
-):
+    filter_size: int = 9,
+    sigma_color: float = 75,
+    sigma_space: float = 75,
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Apply bilateral filter to smooth while preserving edges.
 
-    Args:
-        filter_size (int): Diameter of pixel neighborhood.
-        sigma_color (float): Color-space standard deviation.
-        sigma_space (float): Coordinate-space standard deviation.
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save output.
-
-    Returns:
-        str or np.ndarray: Saved message or blurred image.
-
-    Raises:
-        TypeError, ValueError: On invalid inputs.
+    Parameters
+    ----------
+    filter_size : int, default=9
+        Diameter of pixel neighborhood.
+    sigma_color : float, default=75
+        Color-space standard deviation.
+    sigma_space : float, default=75
+        Coordinate-space standard deviation.
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded BGR image array.
+    output_image_path : str | None, optional
+        If provided, save the blurred image.
+
+    Returns
+    -------
+    np.ndarray
+        Blurred image.
+
+    Raises
+    ------
+    ValueError
+        If parameters are invalid.
     """
     if not isinstance(filter_size, int) or filter_size < 1:
         raise ValueError("'filter_size' must be a positive integer.")
@@ -125,6 +191,8 @@ def apply_bilateral_blur(
     if not isinstance(sigma_space, (int, float)) or sigma_space <= 0:
         raise ValueError("'sigma_space' must be a positive number.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     blurred = cv2.bilateralFilter(np_image, filter_size, sigma_color, sigma_space)
-    return IOHandler.save_image(blurred, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(blurred, output_image_path))
+    return blurred

ImagePRO/pre_processing/contrast.py

@@ -1,6 +1,5 @@
 import sys
 from pathlib import Path
-
 import cv2
 import numpy as np
 
@@ -9,89 +8,134 @@ parent_dir = Path(__file__).resolve().parent.parent
 sys.path.append(str(parent_dir))
 
 from pre_processing.grayscale import convert_to_grayscale
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 
 def apply_clahe_contrast(
-    clipLimit=2.0,
-    tileGridSize=(8, 8),
-    image_path=None,
-    np_image=None,
-    result_path=None,
-):
+    clip_limit: float = 2.0,
+    tile_grid_size: tuple[int, int] = (8, 8),
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
-    Enhance contrast using CLAHE (adaptive histogram equalization).
-
-    Args:
-        clipLimit (float): Contrast threshold (must be > 0).
-        tileGridSize (tuple): Grid size for local histogram (e.g., (8, 8)).
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save result.
-
-    Returns:
-        str or np.ndarray: Confirmation if saved, else enhanced image.
-
-    Raises:
-        ValueError, TypeError: On invalid parameter values.
+    Enhance image contrast using CLAHE (adaptive histogram equalization).
+
+    Parameters
+    ----------
+    clip_limit : float, default=2.0
+        Contrast threshold (must be > 0).
+    tile_grid_size : tuple[int, int], default=(8, 8)
+        Grid size for local histogram (positive integers).
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded image.
+    output_image_path : str | None, optional
+        Path to save the enhanced image.
+
+    Returns
+    -------
+    np.ndarray
+        Enhanced grayscale image.
+
+    Raises
+    ------
+    ValueError
+        If `clip_limit` <= 0.
+    TypeError
+        If `tile_grid_size` is not valid.
+    FileNotFoundError
+        If image path is invalid.
+    IOError
+        If saving the image fails.
     """
-    if not isinstance(clipLimit, (int, float)) or clipLimit <= 0:
-        raise ValueError("'clipLimit' must be a positive number.")
+    if not isinstance(clip_limit, (int, float)) or clip_limit <= 0:
+        raise ValueError("'clip_limit' must be a positive number.")
 
     if (
-        not isinstance(tileGridSize, tuple)
-        or len(tileGridSize) != 2
-        or not all(isinstance(i, int) and i > 0 for i in tileGridSize)
+        not isinstance(tile_grid_size, tuple)
+        or len(tile_grid_size) != 2
+        or not all(isinstance(i, int) and i > 0 for i in tile_grid_size)
     ):
-        raise TypeError("'tileGridSize' must be a tuple of two positive integers.")
+        raise TypeError("'tile_grid_size' must be a tuple of two positive integers.")
 
-    np_image = convert_to_grayscale(np_image=IOHandler.load_image(image_path=image_path, np_image=np_image))
+    np_image = convert_to_grayscale(
+        np_image=IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    )
 
-    clahe = cv2.createCLAHE(clipLimit=clipLimit, tileGridSize=tileGridSize)
+    clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=tile_grid_size)
     enhanced = clahe.apply(np_image)
 
-    return IOHandler.save_image(enhanced, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(enhanced, output_image_path))
+    return enhanced
 
 
-def apply_histogram_equalization(image_path=None, np_image=None, result_path=None):
+def apply_histogram_equalization(
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Enhance contrast using global histogram equalization.
 
-    Args:
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save result.
-
-    Returns:
-        str or np.ndarray: Confirmation if saved, else enhanced image.
+    Parameters
+    ----------
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded image.
+    output_image_path : str | None, optional
+        Path to save the enhanced image.
+
+    Returns
+    -------
+    np.ndarray
+        Enhanced grayscale image.
     """
-    np_image = convert_to_grayscale(np_image=IOHandler.load_image(image_path=image_path, np_image=np_image))
+    np_image = convert_to_grayscale(
+        np_image=IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    )
     enhanced = cv2.equalizeHist(np_image)
-    return IOHandler.save_image(enhanced, result_path)
+
+    if output_image_path:
+        print(IOHandler.save_image(enhanced, output_image_path))
+    return enhanced
 
 
 def apply_contrast_stretching(
-    alpha,
-    beta,
-    image_path=None,
-    np_image=None,
-    result_path=None,
-):
+    alpha: float,
+    beta: int,
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
-    Enhance contrast by linear contrast stretching (alpha × pixel + beta).
-
-    Args:
-        alpha (float): Contrast factor (>= 0).
-        beta (int): Brightness offset (0–255).
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Path to save result.
-
-    Returns:
-        str or np.ndarray: Confirmation if saved, else enhanced image.
-
-    Raises:
-        ValueError: If parameters are out of range.
+    Enhance contrast by linear stretching: `alpha × pixel + beta`.
+
+    Parameters
+    ----------
+    alpha : float
+        Contrast factor (>= 0).
+    beta : int
+        Brightness offset (0–255).
+    src_image_path : str | None, optional
+        Path to input image.
+    src_np_image : np.ndarray | None, optional
+        Preloaded image.
+    output_image_path : str | None, optional
+        Path to save the enhanced image.
+
+    Returns
+    -------
+    np.ndarray
+        Enhanced grayscale image.
+
+    Raises
+    ------
+    ValueError
+        If `alpha` or `beta` are out of range.
     """
     if not isinstance(alpha, (int, float)) or alpha < 0:
         raise ValueError("'alpha' must be a non-negative number.")
@@ -99,7 +143,11 @@ def apply_contrast_stretching(
     if not isinstance(beta, int) or not (0 <= beta <= 255):
         raise ValueError("'beta' must be an integer between 0 and 255.")
 
-    np_image = convert_to_grayscale(np_image=IOHandler.load_image(image_path=image_path, np_image=np_image))
+    np_image = convert_to_grayscale(
+        np_image=IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    )
     enhanced = cv2.convertScaleAbs(np_image, alpha=alpha, beta=beta)
 
-    return IOHandler.save_image(enhanced, result_path)
+    if output_image_path:
+        print(IOHandler.save_image(enhanced, output_image_path))
+    return enhanced

ImagePRO/pre_processing/crop.py

@@ -1,30 +1,52 @@
 import sys
 from pathlib import Path
+import numpy as np
 
 # Add parent directory to sys.path for importing custom modules
 parent_dir = Path(__file__).resolve().parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 
-def crop_image(start_point, end_point, image_path=None, np_image=None, result_path=None):
+def crop_image(
+    start_point: tuple[int, int],
+    end_point: tuple[int, int],
+    src_image_path: str | None = None,
+    src_np_image: np.ndarray | None = None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
-    Crop image using top-left and bottom-right coordinates.
+    Crop an image using top-left and bottom-right coordinates.
 
-    Args:
-        start_point (tuple): (x1, y1) top-left corner.
-        end_point (tuple): (x2, y2) bottom-right corner.
-        image_path (str, optional): Path to input image. Overrides `np_image` if provided.
-        np_image (np.ndarray, optional): Image array. Used if `image_path` is None.
-        result_path (str, optional): Path to save cropped image.
+    Parameters
+    ----------
+    start_point : tuple[int, int]
+        (x1, y1) coordinates of the top-left corner.
+    end_point : tuple[int, int]
+        (x2, y2) coordinates of the bottom-right corner.
+    src_image_path : str | None, optional
+        Path to input image. Overrides `src_np_image` if provided.
+    src_np_image : np.ndarray | None, optional
+        Preloaded image array. Used if `src_image_path` is None.
+    output_image_path : str | None, optional
+        Path to save cropped image.
 
-    Returns:
-        str or np.ndarray: Save message if saved, else cropped image array.
+    Returns
+    -------
+    np.ndarray
+        Cropped image.
 
-    Raises:
-        TypeError: If inputs are not proper tuples of integers.
-        ValueError: If coordinates are invalid or out of image bounds.
+    Raises
+    ------
+    TypeError
+        If coordinates are not tuples of two integers.
+    ValueError
+        If coordinates are invalid or outside image bounds.
+    FileNotFoundError
+        If `src_image_path` does not exist.
+    IOError
+        If saving the image fails.
     """
     # Validate coordinates
     if (
@@ -33,7 +55,7 @@ def crop_image(start_point, end_point, image_path=None, np_image=None, result_pa
         len(start_point) != 2 or len(end_point) != 2 or
         not all(isinstance(c, int) for c in start_point + end_point)
     ):
-        raise TypeError("Both 'start_point' and 'end_point' must be (x, y) tuples of integers.")
+        raise TypeError("'start_point' and 'end_point' must be (x, y) tuples of integers.")
 
     x1, y1 = start_point
     x2, y2 = end_point
@@ -41,11 +63,14 @@ def crop_image(start_point, end_point, image_path=None, np_image=None, result_pa
     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.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     height, width = np_image.shape[:2]
 
     if x2 > width or y2 > height:
         raise ValueError(f"Crop area exceeds image bounds ({width}x{height}).")
 
     cropped = np_image[y1:y2, x1:x2]
-    return IOHandler.save_image(cropped, result_path)
+
+    if output_image_path:
+        print(IOHandler.save_image(cropped, output_image_path))
+    return cropped

ImagePRO/pre_processing/grayscale.py

@@ -1,27 +1,49 @@
 import sys
 from pathlib import Path
-
+import numpy as np
 import cv2
 
 # Add parent directory to sys.path for importing custom modules
 parent_dir = Path(__file__).resolve().parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 
-def convert_to_grayscale(image_path=None, np_image=None, result_path=None):
+def convert_to_grayscale(
+    src_image_path: str | None = None,
+    src_np_image: np.ndarray | None = None,
+    output_image_path: str | None = None
+) -> np.ndarray:
     """
     Convert a BGR image to single-channel grayscale.
 
-    Args:
-        image_path (str, optional): Path to input image file.
-        np_image (np.ndarray, optional): Image array (used if image_path is None).
-        result_path (str, optional): Path to save grayscale image.
+    Parameters
+    ----------
+    src_image_path : str | None, optional
+        Path to the input image file.
+    src_np_image : np.ndarray | None, optional
+        Preloaded BGR image. Used if `src_image_path` is None.
+    output_image_path : str | None, optional
+        Path to save the grayscale image.
+
+    Returns
+    -------
+    np.ndarray
+        Grayscale image.
 
-    Returns:
-        str or np.ndarray: Confirmation message if saved, else grayscale image.
+    Raises
+    ------
+    TypeError
+        If input types are invalid.
+    FileNotFoundError
+        If the provided `src_image_path` does not exist.
+    IOError
+        If saving the image fails.
     """
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
     grayscale = cv2.cvtColor(np_image, cv2.COLOR_BGR2GRAY)
-    return IOHandler.save_image(grayscale, result_path)
+
+    if output_image_path:
+        print(IOHandler.save_image(grayscale, output_image_path))
+    return grayscale