ImagePRO-Python 0.5.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

ImagePRO/__init__.py

@@ -0,0 +1,33 @@
+"""
+ImagePRO - Professional & Modular Image Processing Library in Python
+
+A clean, modular, and easy-to-use Python library for image processing tasks,
+built with OpenCV, MediaPipe, YOLO and designed to be extensible for developers.
+
+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:
+- Image I/O management and batch processing
+- Pre-processing: resize, crop, rotate, blur, sharpen, contrast enhancement
+- Human analysis: face mesh, pose estimation, hand tracking
+- Object detection with YOLO models
+- Real-time processing capabilities
+"""
+
+__version__ = "1.0.0"
+__author__ = "Parsa Safaie"
+__email__ = "parsasafaie.2568@proton.me"
+
+# Core modules
+from . import utils
+from . import pre_processing
+from . import human_analysis
+from . import object_analysis
+
+__all__ = [
+    "utils",
+    "pre_processing", 
+    "human_analysis",
+    "object_analysis"
+]

ImagePRO/human_analysis/__init__.py

@@ -0,0 +1,7 @@
+# Human Analysis Module
+# Provides face and body analysis capabilities using MediaPipe
+
+from . import face_analysis
+from . import body_analysis
+
+__all__ = ["face_analysis", "body_analysis"]

ImagePRO/human_analysis/body_analysis/__init__.py

@@ -0,0 +1,7 @@
+# Body Analysis Module
+# Provides body pose estimation and hand tracking capabilities
+
+from . import body_pose_estimation
+from . import hand_tracking
+
+__all__ = ["body_pose_estimation", "hand_tracking"]

ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -1,130 +1,167 @@
-import sys
-from pathlib import Path
+from __future__ import annotations
 
 import cv2
 import mediapipe as mp
 
-# Add parent directory to import custom modules
-parent_dir = Path(__file__).resolve().parent.parent.parent
-sys.path.append(str(parent_dir))
-
-from utils.io_handler import IOHandler
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
+# Constants
 mp_pose = mp.solutions.pose
+TOTAL_LANDMARKS = 33
+DEFAULT_CONFIDENCE = 0.7
+LANDMARK_RADIUS = 3
+LANDMARK_COLOR = (0, 0, 255)  # Red color for landmarks
 
 def detect_body_pose(
-    model_accuracy: float = 0.7,
-    landmarks_idx: list | None = None,
-    src_image_path: str | None = None,
-    src_np_image=None,
-    output_image_path: str | None = None,
-    output_csv_path: str | None = None,
-    pose_obj=None
-):
-    """
-    Detect body landmarks from an image using MediaPipe Pose.
-
-    Parameters
-    ----------
-    model_accuracy : float, default=0.7
-        Minimum detection confidence [0, 1].
-    landmarks_idx : list[int] | None, optional
-        Indices of landmarks to extract. Default: all 33.
-    src_image_path : str | None, optional
-        Path to image file.
-    src_np_image : np.ndarray | None, optional
-        Preloaded BGR image array.
-    output_image_path : str | None, optional
-        If provided, saves annotated image.
-    output_csv_path : str | None, optional
-        If provided, saves landmarks CSV.
-    pose_obj : mp.solutions.pose.Pose | None, optional
-        Optional pre-initialized pose model.
-
-    Returns
-    -------
-    tuple[np.ndarray, list]
-        Annotated image and landmarks list.
-
-    Raises
-    ------
-    ValueError, TypeError, FileNotFoundError, IOError
+    image: Image,
+    *,
+    min_confidence: float = DEFAULT_CONFIDENCE,
+    landmarks_idx: list[int] | None = None,
+    pose_obj: mp.solutions.pose.Pose | None = None
+) -> Result:
+    """Detect body landmarks in an image using MediaPipe Pose.
+
+    Extracts 3D body landmark coordinates and optionally draws them.
+    Can focus on specific landmarks or detect all 33 points.
+
+    Args:
+        image: Input image to process.
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
+        landmarks_idx: Specific landmark indices to detect.
+            If None, detects all 33 landmarks.
+            Default: None
+        pose_obj: Pre-initialized pose detector.
+            If None, creates new instance.
+            Default: None
+
+    Returns:
+        Result object with detections and visualization:
+        - image: Input image with landmarks drawn
+        - data: List of [idx, x, y, z] coordinates
+        - meta: Operation info and parameters
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If min_confidence not in [0,1]
+        TypeError: If landmarks_idx is not list[int]
     """
-    if landmarks_idx is not None and (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 ints or None.")
+    if not isinstance(image, Image):
+        raise TypeError("'image' must be an Image instance")
 
-    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
+        raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
-    if landmarks_idx is None:
-        landmarks_idx = list(range(33))
+    if landmarks_idx is not None and (
+        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")
 
+    # Initialize detector if needed
     if pose_obj is None:
         pose_obj = mp_pose.Pose(
-            min_detection_confidence=model_accuracy,
+            min_detection_confidence=min_confidence,
             static_image_mode=True
         )
 
-    image_rgb = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
-    result = pose_obj.process(image_rgb)
+    # Use all landmarks if none specified
+    if landmarks_idx is None:
+        landmarks_idx = list(range(TOTAL_LANDMARKS))
+
+    # Prepare image
+    h, w = image.shape[:2]
+    img_copy = image._data.copy()
+    img_rgb = cv2.cvtColor(img_copy, cv2.COLOR_BGR2RGB)
 
-    annotated_image = np_image.copy()
-    all_landmarks = []
+    # Detect pose
+    result = pose_obj.process(img_rgb)
+    landmarks = []
 
     if result.pose_landmarks:
-        if len(landmarks_idx) == 33:
+        # Visualize landmarks
+        if len(landmarks_idx) == TOTAL_LANDMARKS:
+            # Draw full skeleton
             mp.solutions.drawing_utils.draw_landmarks(
-                annotated_image,
+                img_copy,
                 result.pose_landmarks,
                 mp_pose.POSE_CONNECTIONS,
                 landmark_drawing_spec=mp.solutions.drawing_styles.get_default_pose_landmarks_style()
             )
         else:
-            h, w, _ = annotated_image.shape
+            # Draw only selected points
             for idx in landmarks_idx:
                 lm = result.pose_landmarks.landmark[idx]
                 x, y = int(w * lm.x), int(h * lm.y)
-                cv2.circle(annotated_image, (x, y), 3, (0, 0, 255), -1)
+                cv2.circle(img_copy, (x, y), LANDMARK_RADIUS, LANDMARK_COLOR, -1)
 
+        # Extract coordinates
         for idx in landmarks_idx:
             lm = result.pose_landmarks.landmark[idx]
-            all_landmarks.append([idx, lm.x, lm.y, lm.z])
+            landmarks.append([idx, lm.x, lm.y, lm.z])
+
+    return Result(
+        image=img_copy,
+        data=landmarks,
+        meta={
+            "source": image,
+            "operation": "detect_body_pose",
+            "min_confidence": min_confidence,
+            "landmarks_idx": landmarks_idx
+        }
+    )
 
-    if output_image_path:
-        print(IOHandler.save_image(annotated_image, output_image_path))
-    if output_csv_path:
-        print(IOHandler.save_csv(all_landmarks, output_csv_path))
 
-    return annotated_image, all_landmarks
+def detect_body_pose_live() -> None:
+    """Start live webcam feed with real-time body pose detection.
 
+    Opens the default camera and shows pose landmarks in real-time.
+    Press ESC to exit the application.
 
-def detect_body_pose_live():
-    """Starts webcam and shows real-time body pose detection. Press ESC to exit."""
+    Raises:
+        RuntimeError: If camera cannot be accessed
+    """
+    # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
-        raise RuntimeError("Failed to open webcam.")
+        raise RuntimeError("Cannot access webcam")
 
+    # Initialize pose detector in tracking mode
     pose_obj = mp_pose.Pose(
-        min_detection_confidence=0.7,
+        min_detection_confidence=DEFAULT_CONFIDENCE,
         static_image_mode=False
     )
 
     try:
         while True:
+            # Get frame
             success, frame = cap.read()
             if not success:
-                print("Ignoring empty camera frame.")
+                print("Failed to capture frame, skipping...")
                 continue
 
+            # Process frame
             try:
-                annotated_img, _ = detect_body_pose(src_np_image=frame, pose_obj=pose_obj)
-            except ValueError:
-                annotated_img = frame
-
-            cv2.imshow('ImagePRO - Live Body Pose Detection', annotated_img)
-
+                result = detect_body_pose(
+                    image=Image.from_array(frame),
+                    min_confidence=DEFAULT_CONFIDENCE,
+                    pose_obj=pose_obj
+                )
+                display_frame = result.image
+            except (TypeError, ValueError):
+                # Fall back to raw frame if detection fails
+                display_frame = frame
+
+            # Show result
+            cv2.imshow('ImagePRO - Live Body Pose Detection', display_frame)
+
+            # Check for ESC key
             if cv2.waitKey(5) & 0xFF == 27:
                 break
     finally:
+        # Clean up resources
         cap.release()
         cv2.destroyAllWindows()
 

ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -1,68 +1,76 @@
-import sys
-from pathlib import Path
+from __future__ import annotations
 
 import cv2
 import mediapipe as mp
 
-# Add parent directory to import custom modules
-parent_dir = Path(__file__).resolve().parent.parent.parent
-sys.path.append(str(parent_dir))
-
-from utils.io_handler import IOHandler
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
+# Constants
 mp_hands = mp.solutions.hands
+DEFAULT_MAX_HANDS = 2
+DEFAULT_MIN_CONFIDENCE = 0.7
+TOTAL_HAND_LANDMARKS = 21
+LANDMARK_RADIUS = 3
+LANDMARK_COLOR = (0, 0, 255)  # Red color for landmarks
 
 
 def detect_hands(
-    max_hands: int = 2,
-    min_confidence: float = 0.7,
-    landmarks_idx: list | None = None,
-    src_image_path: str | None = None,
-    src_np_image=None,
-    output_image_path: str | None = None,
-    output_csv_path: str | None = None,
-    hands_obj=None
-):
-    """
-    Detect hand landmarks in an image using MediaPipe Hands.
-
-    Parameters
-    ----------
-    max_hands : int, default=2
-        Max number of hands to detect.
-    min_confidence : float, default=0.7
-        Minimum detection confidence [0, 1].
-    landmarks_idx : list[int] | None, optional
-        Landmark indices to extract (default: all 21).
-    src_image_path : str | None, optional
-        Path to image file.
-    src_np_image : np.ndarray | None, optional
-        Preloaded BGR image array.
-    output_image_path : str | None, optional
-        If provided, saves annotated image.
-    output_csv_path : str | None, optional
-        If provided, saves landmarks CSV.
-    hands_obj : mp.solutions.hands.Hands | None, optional
-        Optional pre-initialized model.
-
-    Returns
-    -------
-    tuple[np.ndarray, list]
-        Annotated image and landmarks list.
-
-    Raises
-    ------
-    ValueError, TypeError, FileNotFoundError, IOError
+    image: Image,
+    *,
+    max_hands: int = DEFAULT_MAX_HANDS,
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE,
+    landmarks_idx: list[int] | None = None,
+    hands_obj: mp.solutions.hands.Hands | None = None
+) -> Result:
+    """Detect hand landmarks in an image using MediaPipe Hands.
+
+    Identifies hand positions and extracts 3D coordinates of
+    key points (joints, fingertips, etc.).
+
+    Args:
+        image: Input image to process.
+        max_hands: Maximum number of hands to detect.
+            Must be positive.
+            Default: 2
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
+        landmarks_idx: Specific landmark indices to detect.
+            If None, detects all 21 points per hand.
+            Default: None
+        hands_obj: Pre-initialized hand detector.
+            If None, creates new instance.
+            Default: None
+
+    Returns:
+        Result object with detections and visualization:
+        - image: Input image with landmarks drawn
+        - data: List of [hand_id, point_id, x, y, z]
+        - meta: Operation info and parameters
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If max_hands is not positive
+        ValueError: If min_confidence not in [0,1]
+        TypeError: If landmarks_idx is not list[int]
     """
+    if not isinstance(image, Image):
+        raise TypeError("'image' must be an Image instance")
+
     if not isinstance(max_hands, int) or max_hands <= 0:
-        raise ValueError("'max_hands' must be a positive integer.")
+        raise ValueError("'max_hands' must be positive")
+
     if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
-        raise ValueError("'min_confidence' must be a float between 0.0 and 1.0.")
-    if landmarks_idx is not None and (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 ints or None.")
+        raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
-    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    if landmarks_idx is not None and (
+        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")
 
+    # Initialize detector if needed
     if hands_obj is None:
         hands_obj = mp_hands.Hands(
             min_detection_confidence=min_confidence,
@@ -70,55 +78,91 @@ def detect_hands(
             static_image_mode=True
         )
 
+    # Use all landmarks if none specified
     if landmarks_idx is None:
-        landmarks_idx = list(range(21))
+        landmarks_idx = list(range(TOTAL_HAND_LANDMARKS))
 
-    rgb_image = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
-    results = hands_obj.process(rgb_image)
+    # Prepare image
+    img_copy = image._data.copy()
+    img_rgb = cv2.cvtColor(img_copy, cv2.COLOR_BGR2RGB)
 
-    annotated_image = np_image.copy()
-    all_landmarks = []
+    # Detect hands
+    results = hands_obj.process(img_rgb)
+    landmarks = []
 
+    # Process detections
     if results.multi_hand_landmarks:
         for hand_id, hand_landmarks in enumerate(results.multi_hand_landmarks):
-            if len(landmarks_idx) == 21:
+            # Visualize landmarks
+            if len(landmarks_idx) == TOTAL_HAND_LANDMARKS:
+                # Draw full hand skeleton
                 mp.solutions.drawing_utils.draw_landmarks(
-                    image=annotated_image,
+                    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()
                 )
             else:
-                h, w, _ = annotated_image.shape
+                # Draw only selected points
+                h, w, _ = img_copy.shape
                 for idx in landmarks_idx:
                     lm = hand_landmarks.landmark[idx]
                     x, y = int(w * lm.x), int(h * lm.y)
-                    cv2.circle(annotated_image, (x, y), 3, (0, 0, 255), -1)
+                    cv2.circle(img_copy, (x, y), LANDMARK_RADIUS, LANDMARK_COLOR, -1)
 
+            # Extract coordinates
             for idx in landmarks_idx:
                 lm = hand_landmarks.landmark[idx]
-                all_landmarks.append([hand_id, idx, lm.x, lm.y, lm.z])
+                landmarks.append([hand_id, idx, lm.x, lm.y, lm.z])
+
+    return Result(
+        image=img_copy,
+        data=landmarks,
+        meta={
+            "source": image,
+            "operation": "detect_hands",
+            "max_hands": max_hands,
+            "min_confidence": min_confidence,
+            "landmarks_idx": landmarks_idx
+        }
+    )
+
 
-    if output_image_path:
-        print(IOHandler.save_image(annotated_image, output_image_path))
-    if output_csv_path:
-        print(IOHandler.save_csv(all_landmarks, output_csv_path))
+def detect_hands_live(
+    max_hands: int = DEFAULT_MAX_HANDS,
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE
+) -> None:
+    """Start live webcam feed with real-time hand detection.
 
-    return annotated_image, all_landmarks
+    Opens the default camera and shows hand landmarks in real-time.
+    Press ESC to exit.
 
+    Args:
+        max_hands: Maximum number of hands to track.
+            Must be positive.
+            Default: 2
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
 
-def detect_hands_live(max_hands: int = 2, min_confidence: float = 0.7):
-    """Real-time hand detection via webcam. Press ESC to exit."""
+    Raises:
+        ValueError: If parameters are invalid
+        RuntimeError: If camera cannot be accessed
+    """
+    # Validate parameters
     if not isinstance(max_hands, int) or max_hands <= 0:
-        raise ValueError("'max_hands' must be a positive integer.")
+        raise ValueError("'max_hands' must be positive")
+
     if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
-        raise ValueError("'min_confidence' must be a float between 0.0 and 1.0.")
+        raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
+    # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
-        raise RuntimeError("Failed to open webcam.")
+        raise RuntimeError("Cannot access webcam")
 
+    # Initialize hand detector in tracking mode
     hands_obj = mp_hands.Hands(
         min_detection_confidence=min_confidence,
         max_num_hands=max_hands,
@@ -127,26 +171,32 @@ def detect_hands_live(max_hands: int = 2, min_confidence: float = 0.7):
 
     try:
         while True:
+            # Get frame
             success, frame = cap.read()
             if not success:
-                print("Ignoring empty camera frame.")
+                print("Failed to capture frame, skipping...")
                 continue
 
-            annotated_img, _ = detect_hands(
+            # Process frame
+            result = detect_hands(
+                image=Image.from_array(frame),
                 max_hands=max_hands,
                 min_confidence=min_confidence,
-                src_np_image=frame,
                 hands_obj=hands_obj
             )
+            display_frame = result.image if result.image is not None else frame
 
-            cv2.imshow('Live hand detector - ImagePRO', annotated_img)
+            # Show result
+            cv2.imshow('ImagePRO - Live Hand Detection', display_frame)
 
+            # Check for ESC key
             if cv2.waitKey(5) & 0xFF == 27:
                 break
     finally:
+        # Clean up resources
         cap.release()
         cv2.destroyAllWindows()
 
 
 if __name__ == "__main__":
-    detect_hands_live(max_hands=2)
+    detect_hands_live()

ImagePRO/human_analysis/face_analysis/__init__.py

@@ -0,0 +1,16 @@
+# Face Analysis Module
+# Provides facial landmark detection, pose estimation, and eye status analysis
+
+from . import eye_status_analysis
+from . import face_comparison
+from . import face_detection
+from . import face_mesh_analysis
+from . import head_pose_estimation
+
+__all__ = [
+    "eye_status_analysis",
+    "face_comparison",
+    "face_detection", 
+    "face_mesh_analysis",
+    "head_pose_estimation"
+]