ImagePRO-Python 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

ImagePRO/__init__.py

@@ -15,7 +15,7 @@ Features:
 - Real-time processing capabilities
 """
 
-__version__ = "1.0.0"
+__version__ = "1.3.0"
 __author__ = "Parsa Safaie"
 __email__ = "parsasafaie.2568@proton.me"
 
@@ -27,7 +27,7 @@ from . import object_analysis
 
 __all__ = [
     "utils",
-    "pre_processing", 
+    "pre_processing",
     "human_analysis",
     "object_analysis"
 ]

ImagePRO/human_analysis/body_analysis/__init__.py

@@ -1,7 +1,17 @@
 # Body Analysis Module
 # Provides body pose estimation and hand tracking capabilities
+#
+# Both modules need the optional mediapipe dependency; they are imported
+# guardedly so the package stays importable without it.
 
-from . import body_pose_estimation
-from . import hand_tracking
+try:  # requires mediapipe
+    from . import body_pose_estimation
+except ImportError:
+    body_pose_estimation = None
+
+try:  # requires mediapipe
+    from . import hand_tracking
+except ImportError:
+    hand_tracking = None
 
 __all__ = ["body_pose_estimation", "hand_tracking"]

ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -64,7 +64,7 @@ def detect_body_pose(
         raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        not isinstance(landmarks_idx, list)
         or not all(isinstance(i, int) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
@@ -97,7 +97,8 @@ def detect_body_pose(
                 img_copy,
                 result.pose_landmarks,
                 mp_pose.POSE_CONNECTIONS,
-                landmark_drawing_spec=mp.solutions.drawing_styles.get_default_pose_landmarks_style()
+                landmark_drawing_spec=mp.solutions.drawing_styles
+                .get_default_pose_landmarks_style()
             )
         else:
             # Draw only selected points

ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -74,7 +74,7 @@ def detect_hands(
         raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        not isinstance(landmarks_idx, list)
         or not all(isinstance(i, int) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
@@ -109,8 +109,10 @@ def detect_hands(
                     image=img_copy,
                     landmark_list=hand_landmarks,
                     connections=mp_hands.HAND_CONNECTIONS,
-                    landmark_drawing_spec=mp.solutions.drawing_styles.get_default_hand_landmarks_style(),
-                    connection_drawing_spec=mp.solutions.drawing_styles.get_default_hand_connections_style()
+                    landmark_drawing_spec=mp.solutions.drawing_styles
+                    .get_default_hand_landmarks_style(),
+                    connection_drawing_spec=mp.solutions.drawing_styles
+                    .get_default_hand_connections_style()
                 )
             else:
                 # Draw only selected points

ImagePRO/human_analysis/face_analysis/__init__.py

@@ -1,16 +1,39 @@
 # Face Analysis Module
 # Provides facial landmark detection, pose estimation, and eye status analysis
+#
+# The mediapipe-based modules and the insightface-based module are imported
+# guardedly so that importing the package works with only the dependencies
+# a caller actually needs; unavailable modules are set to None.
 
-from . import eye_status_analysis
-from . import face_comparison
-from . import face_detection
-from . import face_mesh_analysis
-from . import head_pose_estimation
+try:  # requires mediapipe
+    from . import eye_status_analysis
+except ImportError:
+    eye_status_analysis = None
+
+try:  # requires insightface
+    from . import face_comparison
+except ImportError:
+    face_comparison = None
+
+try:  # requires mediapipe
+    from . import face_detection
+except ImportError:
+    face_detection = None
+
+try:  # requires mediapipe
+    from . import face_mesh_analysis
+except ImportError:
+    face_mesh_analysis = None
+
+try:  # requires mediapipe
+    from . import head_pose_estimation
+except ImportError:
+    head_pose_estimation = None
 
 __all__ = [
     "eye_status_analysis",
     "face_comparison",
-    "face_detection", 
+    "face_detection",
     "face_mesh_analysis",
     "head_pose_estimation"
 ]

ImagePRO/human_analysis/face_analysis/face_comparison.py

@@ -85,8 +85,8 @@ def compare_faces(
 
     try:
         # Save images to disk if needed
-        path_1 = save_temp_image(image_1._data, 'tmp1.jpg')
-        path_2 = save_temp_image(image_2._data, 'tmp2.jpg')
+        path_1 = save_temp_image(image_1, 'tmp1.jpg')
+        path_2 = save_temp_image(image_2, 'tmp2.jpg')
 
         # Load and preprocess images
         img1 = load_rgb_image(path_1)

ImagePRO/human_analysis/face_analysis/face_detection.py

@@ -29,7 +29,7 @@ FACE_OUTLINE_INDICES = [
 
 
 def detect_faces(
-    image: Image, 
+    image: Image,
     *,
     max_faces: int = DEFAULT_MAX_FACES,
     min_confidence: float = DEFAULT_MIN_CONFIDENCE,

ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py

@@ -83,7 +83,7 @@ def analyze_face_mesh(
         raise ValueError("'min_confidence' must be between 0 and 1")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        not isinstance(landmarks_idx, list)
         or not all(isinstance(i, int) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
@@ -99,11 +99,8 @@ def analyze_face_mesh(
     else:
         face_mesh = face_mesh_obj
 
-    # Prepare image
-    img_copy = image._data.copy()
-    img_rgb = cv2.cvtColor(img_copy, cv2.COLOR_BGR2RGB)
-    
-    # Detect facial landmarks
+    # Detect facial landmarks (cvtColor allocates a new RGB array)
+    img_rgb = cv2.cvtColor(image._data, cv2.COLOR_BGR2RGB)
     results = face_mesh.process(img_rgb)
 
     # Handle no detections
@@ -121,11 +118,14 @@ def analyze_face_mesh(
             }
         )
 
+    # Allocate the annotation canvas only when a face was found
+    img_copy = image._data.copy()
+
     # Use all landmarks if none specified
     landmarks_idx = landmarks_idx or list(range(TOTAL_FACE_LANDMARKS))
     # Process each detected face
     landmarks = []
-    
+
     for face_id, face_landmarks in enumerate(results.multi_face_landmarks):
         # Draw landmarks
         if len(landmarks_idx) == TOTAL_FACE_LANDMARKS:
@@ -146,11 +146,10 @@ def analyze_face_mesh(
                 cv2.circle(img_copy, (cx, cy), 3, (0, 0, 255), -1)
 
         # Extract coordinates
-        face_data = [
-            [face_id, idx, lm.x, lm.y, lm.z]
-            for idx in landmarks_idx
-            for lm in [face_landmarks.landmark[idx]]
-        ]
+        face_data = []
+        for idx in landmarks_idx:
+            lm = face_landmarks.landmark[idx]
+            face_data.append([face_id, idx, lm.x, lm.y, lm.z])
         landmarks.append(face_data)
 
     return Result(

ImagePRO/human_analysis/face_analysis/head_pose_estimation.py

@@ -97,7 +97,7 @@ def estimate_head_pose(
     for face in landmarks:
         # Map landmarks by index
         points = {lm[1]: lm for lm in face}
-        
+
         try:
             # Extract key points
             nose_x, nose_y = points[1][2:4]      # Nose tip

ImagePRO/object_analysis/__init__.py

@@ -1,6 +1,9 @@
 # Object Analysis Module
 # Provides object detection capabilities using YOLO models
 
-from . import object_detection
+try:  # object_detection needs the optional ultralytics dependency
+    from . import object_detection
+except ImportError:
+    object_detection = None
 
 __all__ = ["object_detection"]

ImagePRO/object_analysis/object_detection.py

@@ -16,10 +16,9 @@ from ImagePRO.utils.result import Result
 
 # Constants
 DEFAULT_ACCURACY_LEVEL = 1
-DEFAULT_CONFIDENCE = 0.5
 MODEL_MAPPING = {
     1: "yolo11n.pt",
-    2: "yolo11s.pt", 
+    2: "yolo11s.pt",
     3: "yolo11m.pt",
     4: "yolo11l.pt",
     5: "yolo11x.pt"
@@ -56,6 +55,7 @@ def detect_objects(
         Result object with detections and metadata:
         - image: Original with bounding boxes drawn
         - data: List of [class_id, [x1,y1,x2,y2], confidence]
+          with box coordinates normalized to [0, 1]
         - meta: Operation info and model used
 
     Raises:
@@ -73,12 +73,12 @@ def detect_objects(
                 f"'accuracy_level' must be in {list(MODEL_MAPPING.keys())}, "
                 f"got {accuracy_level}"
             )
-        
+
         model_name = MODEL_MAPPING[accuracy_level]
         model = YOLO(model=model_name)
 
-    # Run inference
-    result = model(image._data.copy())[0]
+    # Run inference (ultralytics does not mutate the input array)
+    result = model(image._data)[0]
     boxes = result.boxes
 
     # Process detections
@@ -92,7 +92,7 @@ def detect_objects(
     # Show visualization if requested
     if show_result:
         result.show()
-    
+
     return Result(
         image=result.plot(),
         data=detections,

ImagePRO/pre_processing/__init__.py

@@ -4,15 +4,19 @@
 from . import blur
 from . import contrast
 from . import crop
-from . import dataset_generator
 from . import grayscale
 from . import resize
 from . import rotate
 from . import sharpen
 
+try:  # dataset_generator needs the optional mediapipe dependency
+    from . import dataset_generator
+except ImportError:
+    dataset_generator = None
+
 __all__ = [
     "blur",
-    "contrast", 
+    "contrast",
     "crop",
     "dataset_generator",
     "grayscale",

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,13 @@ _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))
 
-from ImagePRO.human_analysis.face_analysis.face_detection import detect_faces
-from ImagePRO.pre_processing import blur, grayscale, rotate, sharpen, resize
-from ImagePRO.utils.image import Image
-
-import random
-import time
-
 import cv2
 import mediapipe as mp
 
+from ImagePRO.human_analysis.face_analysis.face_detection import detect_faces
+from ImagePRO.pre_processing import blur, grayscale, resize, rotate, sharpen
+from ImagePRO.utils.image import Image
+
 # Constants
 DEFAULT_NUM_IMAGES = 200
 DEFAULT_START_INDEX = 0
@@ -40,7 +39,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 +49,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.
@@ -135,7 +134,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:

{imagepro_python-1.2.1.dist-info → imagepro_python-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.2.1
+Version: 1.3.0
 Summary: Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration.
 Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
 License: MIT
@@ -32,14 +32,19 @@ Provides-Extra: yolo
 Requires-Dist: ultralytics<9.0,>=8.2; extra == "yolo"
 Provides-Extra: mediapipe
 Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "mediapipe"
+Requires-Dist: numpy<2.0,>=1.24; extra == "mediapipe"
 Provides-Extra: insightface
 Requires-Dist: insightface<0.8,>=0.7; extra == "insightface"
 Requires-Dist: onnxruntime<2.0,>=1.16; extra == "insightface"
+Requires-Dist: numpy<2.0,>=1.24; extra == "insightface"
 Provides-Extra: full
 Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "full"
 Requires-Dist: ultralytics<9.0,>=8.2; extra == "full"
 Requires-Dist: insightface<0.8,>=0.7; extra == "full"
 Requires-Dist: onnxruntime<2.0,>=1.16; extra == "full"
+Requires-Dist: numpy<2.0,>=1.24; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
 Dynamic: license-file
 
 # ImagePRO
@@ -50,11 +55,10 @@ Dynamic: license-file
 
 Whether you're working on computer vision pipelines, preprocessing images for AI models, or simply automating batch image edits — **ImagePRO** gives you powerful tools with minimal effort.
 
-## ✨ Features
+## Features
 
 ### **Image I/O & Management**
 - Flexible input/output handling (file paths or numpy arrays)
-- Batch processing capabilities
 - Multiple format support (JPEG, PNG, CSV, etc.)
 
 ### **Pre-processing & Enhancement**
@@ -71,13 +75,19 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 ### **Object Detection**
 - **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
 - **Flexible Models**: Pre-trained or custom model support
-- **Batch Processing**: Efficient handling of multiple images
 
-## 🚀 Installation
+## Installation
 
 ### From PyPI
 ```bash
 pip install ImagePRO-Python
+
+# Or with optional extras:
+pip install "ImagePRO-Python[yolo]"         # YOLO object detection
+pip install "ImagePRO-Python[mediapipe]"    # MediaPipe human analysis
+pip install "ImagePRO-Python[insightface]"  # InsightFace face comparison
+pip install "ImagePRO-Python[full]"         # Everything
+pip install "ImagePRO-Python[dev]"          # Test tooling (pytest)
 ```
 
 ### From Source
@@ -109,7 +119,7 @@ pip install -r requirements/full.txt
 
 See the [Directory Structure](/PROJECT_STRUCTURE.md#directory-structure) section in [PROJECT_STRUCTURE.md](/PROJECT_STRUCTURE.md) for details on which modules need which requirements.
 
-## 📖 Quick Start
+## Quick Start
 
 ```python
 from ImagePRO.pre_processing.blur import apply_average_blur
@@ -126,9 +136,9 @@ image = Image.from_path("person_and_objects.jpg")
 blur_result = apply_average_blur(image=image)
 blur_result.save_as_img("blurred_output.jpg")
 
-# Analyze face mesh (468 landmarks)
+# Analyze face mesh (468 landmarks per detected face)
 face_mesh_result = analyze_face_mesh(image=image)
-print(f"Detected {len(face_mesh_result.data)} face landmarks")
+print(f"Detected {len(face_mesh_result.data)} face(s)")
 face_mesh_result.save_as_csv("face_landmarks.csv")
 
 # Detect body pose (33 landmarks)
@@ -138,8 +148,7 @@ print(f"Body pose data: {body_pose_result.data}")
 # Detect objects with YOLO
 object_detection_result = detect_objects(
     image=image,
-    accuracy_level=3,  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
-    confidence=0.5
+    accuracy_level=3  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
 )
 print(f"Detected {len(object_detection_result.data)} objects")
 object_detection_result.save_as_img("detections.jpg")
@@ -147,7 +156,7 @@ object_detection_result.save_as_img("detections.jpg")
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
 
-## 📚 Documentation
+## Documentation
 
 Each module includes comprehensive documentation with detailed examples:
 
@@ -160,7 +169,7 @@ Each module includes comprehensive documentation with detailed examples:
 
 For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
 
-## 🏗️ Architecture
+## Architecture
 
 ImagePRO is built with a modular architecture designed for extensibility and maintainability:
 
@@ -172,12 +181,27 @@ ImagePRO is built with a modular architecture designed for extensibility and mai
 - **Documentation**: Google-style docstrings for all functions
 
 ### Key Design Principles
-- **Immutable Design**: Image objects are immutable, operations return new instances
+- **Non-Destructive Operations**: Operations never write into the input image; they return results in new `Result` objects (note: `crop_image` returns a view into the source array)
 - **Functional Style**: Stateless functions that can be easily composed
 - **Result Objects**: Unified return type containing image, data, and metadata
 - **Keyword Arguments**: All optional parameters use keyword-only syntax
 
-## 🤝 Contributing
+## Testing
+
+The test suite uses pytest:
+
+```bash
+# Install with test tooling (editable install + dev extra)
+pip install -e ".[dev]"
+
+# Run the suite (optional heavy dependencies are mocked; base deps are enough)
+pytest
+
+# Include performance smoke guards
+pytest --run-performance
+```
+
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
@@ -185,9 +209,10 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 1. Fork the repository
 2. Create a virtual environment: `python -m venv .venv`
 3. Install dependencies: `pip install -r requirements/full.txt`
-4. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
-5. Add tests for new features
-6. Update documentation as needed
+4. Install for development with test tooling: `pip install -e ".[dev]"`
+5. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
+6. Add tests for new features and run `pytest`
+7. Update documentation as needed
 
 ### Reporting Issues
 If you encounter any bugs or have feature requests, please open an issue on the GitHub repository with:
@@ -196,5 +221,5 @@ If you encounter any bugs or have feature requests, please open an issue on the
 - Expected vs. actual behavior
 - Environment details (OS, Python version, etc.)
 
-## 📄 License 
+## License
 This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.

imagepro_python-1.3.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+ImagePRO/__init__.py,sha256=yY-6-5p9OyeNlmPnYMeht-2yJJun8DJvH7yi0b-tMOE,997
+ImagePRO/human_analysis/__init__.py,sha256=uSU0lM1p1HM6TNGv6u0nPHWy9QY505v43lqTkhClddM,190
+ImagePRO/human_analysis/body_analysis/__init__.py,sha256=ezFnUJNwQXW47n9Bfxcmk4BNgvt_Bqs3Y5VESxgz2Sg,494
+ImagePRO/human_analysis/body_analysis/body_pose_estimation.py,sha256=QkqF27YOHYoOVq5KMz0AaU455CQcRVfTbFStPZGYUA8,5565
+ImagePRO/human_analysis/body_analysis/hand_tracking.py,sha256=fYOQGu5mcrYgqtWu5wW0xApx76fOXGDxz3hZRUhvW9k,6910
+ImagePRO/human_analysis/face_analysis/__init__.py,sha256=nABUIg9Z-yL6JfAxMb2fqwfxmSfJmvSxfwnQuKSIOGg,1028
+ImagePRO/human_analysis/face_analysis/eye_status_analysis.py,sha256=9ydxEj4EhVCNf954gdFBQemS1uRNA-XGCMzyliI2AsQ,7126
+ImagePRO/human_analysis/face_analysis/face_comparison.py,sha256=vHYqWTuXEadoeZn-z81ZazXlpBri702Gz37XdWPJirw,4303
+ImagePRO/human_analysis/face_analysis/face_detection.py,sha256=9LFMotGJ0KlAUb5yTfrXaAH_Ztr3OO3vbXLhXTN8M9M,3896
+ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py,sha256=TBSZELe_CdXcXDRRiaAYkDqHHpktRhi_koC-2iwk2Gk,8038
+ImagePRO/human_analysis/face_analysis/head_pose_estimation.py,sha256=CovQITnmLNiLlEWffuL0idAJNBOC_nnZlC-4G9pFXxs,7328
+ImagePRO/object_analysis/__init__.py,sha256=KcFRxVKnC0qU82zS31P4CriZIKqZdyGqQwdrMy9N4pc,267
+ImagePRO/object_analysis/object_detection.py,sha256=REfu73vNSvUIbIzel24jygyCumZKvYr7_d6YyLDhdwY,2943
+ImagePRO/pre_processing/__init__.py,sha256=d10ZfQzWM0JRJrFrMHOr-mxF4XYnObj6GYPTLaqzqDA,536
+ImagePRO/pre_processing/blur.py,sha256=3zNTNpvLZPdrtRtBziB6X8ys8M7cIvyPDhojTqR63jo,7950
+ImagePRO/pre_processing/contrast.py,sha256=4UT78ggW1rh_iaEI8FObDB4kpEmRRFWjdJES60SnHDM,5064
+ImagePRO/pre_processing/crop.py,sha256=3Nwerzo57kx1sZPr9m355P-qf1NuZSZEA5iUn2Q1704,2406
+ImagePRO/pre_processing/dataset_generator.py,sha256=7sL9uI_i272eOO1U_XFAaAoo7pfnU5ryuRuLERilzgo,7667
+ImagePRO/pre_processing/grayscale.py,sha256=MRCsFRIaL45sYVHzhuNyZBXsP7PF-yorn0Wt7xONvpY,1781
+ImagePRO/pre_processing/histogram.py,sha256=sNTWWZXr5VLpOrF_PTTJ6TD8yv1zR1l9cMyXHe7JFIM,2596
+ImagePRO/pre_processing/resize.py,sha256=Rnde8l_PXck5OWQBEMOHgLeW2YkTz9Xfr6fGmz0sdm8,1760
+ImagePRO/pre_processing/rotate.py,sha256=wQj3nQpN-ilM0HHwovN--UdGEJkPCY0BJ0zAdyBxv-o,4174
+ImagePRO/pre_processing/sharpen.py,sha256=hOkY7QhzgMp9LXQwt56AP4enn24ntXlmFLe57Bxssvw,3682
+ImagePRO/utils/__init__.py,sha256=McVd-o9KtKOpAVYbLi19KxsatPPFFF-Qbt0gdgY3Ln8,170
+ImagePRO/utils/image.py,sha256=Y64mD97rTiJb8_uNYlyG227VZodeb4U1aGezMkj7MnM,4025
+ImagePRO/utils/result.py,sha256=ToQaOmUlTtobJkC65BG0YO_6BkBleMBn-0Qydko7cZc,6138
+imagepro_python-1.3.0.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
+imagepro_python-1.3.0.dist-info/METADATA,sha256=8Rl5PyW1UcO7Zc_nZuzHCYtU7u-lUbhY8d-J2qR6B1A,9435
+imagepro_python-1.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+imagepro_python-1.3.0.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
+imagepro_python-1.3.0.dist-info/RECORD,,

{imagepro_python-1.2.1.dist-info → imagepro_python-1.3.0.dist-info}/WHEEL

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

imagepro_python-1.2.1.dist-info/RECORD

@@ -1,31 +0,0 @@
-ImagePRO/__init__.py,sha256=LUqZaUWVUISpR6bm5K2cO6KjiVP3ZDPADZGZW051xGk,998
-ImagePRO/human_analysis/__init__.py,sha256=uSU0lM1p1HM6TNGv6u0nPHWy9QY505v43lqTkhClddM,190
-ImagePRO/human_analysis/body_analysis/__init__.py,sha256=czQoJJIrDAWz0UUY0h0mwxymSQ6L6CaZYYHhYFHyf4U,203
-ImagePRO/human_analysis/body_analysis/body_pose_estimation.py,sha256=69ybYkrbFl9EkuAc4ejCu2TW4m9TFLTn2Ae5fm_92lE,5549
-ImagePRO/human_analysis/body_analysis/hand_tracking.py,sha256=T7yM_VZN6mBZsDFJV6C-amCVzgklatvsZrtgcBrzVSg,6869
-ImagePRO/human_analysis/face_analysis/__init__.py,sha256=dKVZ6pq-0aQHL9vhMSt0BHs3WV_cTW65QPLJGnSiUgM,405
-ImagePRO/human_analysis/face_analysis/eye_status_analysis.py,sha256=9ydxEj4EhVCNf954gdFBQemS1uRNA-XGCMzyliI2AsQ,7126
-ImagePRO/human_analysis/face_analysis/face_comparison.py,sha256=RU-eSjFwpRIrV-QX8po8Mr-RhGwYEsCo3_Nt-IiA5Us,4315
-ImagePRO/human_analysis/face_analysis/face_detection.py,sha256=__s-lI6Egf-JgruncL_MfAkmwCq8Oe3F5Vvk9x9S_2Q,3897
-ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py,sha256=8kLyEEnhMfdEALteltSHu2L2zbiFSNfzC73EuV0I5iQ,7964
-ImagePRO/human_analysis/face_analysis/head_pose_estimation.py,sha256=IidB4U0lQryw9T4J4_T-QmC-DgANUEgueto06RkKi2Q,7336
-ImagePRO/object_analysis/__init__.py,sha256=pj1vjY8uVUqeVONpaCacWufUzHF7rS5-nmy_C5IfI2w,148
-ImagePRO/object_analysis/object_detection.py,sha256=ZhxOpX5Zkiu-gq-2CRYPNzSo7ai1PRFZ3qopQeODIkQ,2890
-ImagePRO/pre_processing/__init__.py,sha256=nXUhE8RnDyW7T93fKsSDPfqzGHIW50OvgQvznY5UH0E,417
-ImagePRO/pre_processing/blur.py,sha256=zPWUKLEoKiL6kYwnZOtGRWBHM-dgEQ8WWdDt8_wGc0s,7961
-ImagePRO/pre_processing/contrast.py,sha256=XG69VsX3EKWIPDcQYm4D9qT7sA_BSP-sppSAa8qRUhA,5247
-ImagePRO/pre_processing/crop.py,sha256=p0esuZcn4-YsqcniDUmsVfPoWasxVH1OqzNBra8Pw4M,2442
-ImagePRO/pre_processing/dataset_generator.py,sha256=ekd_TnyflWKjJ6sYCiWc3vN2Q14cKiwZ1InOCslxoFM,7653
-ImagePRO/pre_processing/grayscale.py,sha256=MRCsFRIaL45sYVHzhuNyZBXsP7PF-yorn0Wt7xONvpY,1781
-ImagePRO/pre_processing/histogram.py,sha256=t1ykGUwB9ZbvO6J3bGPh4fDvrk4AJua1dN2BWzHIRIQ,2888
-ImagePRO/pre_processing/resize.py,sha256=GH3ObPe67ypPQG3a7ncrNR5WNDqGibXebAiuRXr6L10,1760
-ImagePRO/pre_processing/rotate.py,sha256=wqV2Qm7mIyvKTSFdwzr1tNAGnMG7rl5M3BRqC5m2oZE,4185
-ImagePRO/pre_processing/sharpen.py,sha256=C5AOxQNBL80JenkztlyRBV7yuCHqxG5dTGbRhtVRT9M,3544
-ImagePRO/utils/__init__.py,sha256=McVd-o9KtKOpAVYbLi19KxsatPPFFF-Qbt0gdgY3Ln8,170
-ImagePRO/utils/image.py,sha256=x93cBNycNOgET20a__TxZ9ZQo_2G84uB7QjXjBo9f8M,3973
-ImagePRO/utils/result.py,sha256=rGZX0FJ-dpA4v_m_GUO6ni0kCfcNJRnOjztbyRX9d88,6065
-imagepro_python-1.2.1.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
-imagepro_python-1.2.1.dist-info/METADATA,sha256=KVaRtAoER1Ss2HS1R8w6YrIrfwt8zH5bw5u_29sMjGA,8513
-imagepro_python-1.2.1.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
-imagepro_python-1.2.1.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
-imagepro_python-1.2.1.dist-info/RECORD,,