ImagePRO-Python 0.1.1__tar.gz → 0.3.0__tar.gz

{imagepro_python-0.1.1/src/ImagePRO_Python.egg-info → imagepro_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 0.1.1
+Version: 0.3.0
 Summary: clean, modular, and easy-to-use Python library for image processing tasks.
 Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
 License: MIT

{imagepro_python-0.1.1 → imagepro_python-0.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ImagePRO-Python"
-version = "0.1.1"
+version = "0.3.0"
 description = "clean, modular, and easy-to-use Python library for image processing tasks."
 readme = "README.md"
 requires-python = "==3.10.*"

imagepro_python-0.3.0/src/ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -0,0 +1,133 @@
+import sys
+from pathlib import Path
+
+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
+
+mp_pose = mp.solutions.pose
+
+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
+    """
+    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.")
+
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+
+    if landmarks_idx is None:
+        landmarks_idx = list(range(33))
+
+    if pose_obj is None:
+        pose_obj = mp_pose.Pose(
+            min_detection_confidence=model_accuracy,
+            static_image_mode=True
+        )
+
+    image_rgb = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
+    result = pose_obj.process(image_rgb)
+
+    annotated_image = np_image.copy()
+    all_landmarks = []
+
+    if result.pose_landmarks:
+        if len(landmarks_idx) == 33:
+            mp.solutions.drawing_utils.draw_landmarks(
+                annotated_image,
+                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
+            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)
+
+        for idx in landmarks_idx:
+            lm = result.pose_landmarks.landmark[idx]
+            all_landmarks.append([idx, lm.x, lm.y, lm.z])
+
+    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():
+    """Starts webcam and shows real-time body pose detection. Press ESC to exit."""
+    cap = cv2.VideoCapture(0)
+    if not cap.isOpened():
+        raise RuntimeError("Failed to open webcam.")
+
+    pose_obj = mp_pose.Pose(
+        min_detection_confidence=0.7,
+        static_image_mode=False
+    )
+
+    try:
+        while True:
+            success, frame = cap.read()
+            if not success:
+                print("Ignoring empty camera frame.")
+                continue
+
+            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)
+
+            if cv2.waitKey(5) & 0xFF == 27:
+                break
+    finally:
+        cap.release()
+        cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    detect_body_pose_live()

imagepro_python-0.3.0/src/ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -0,0 +1,152 @@
+import sys
+from pathlib import Path
+
+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
+
+mp_hands = mp.solutions.hands
+
+
+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
+    """
+    if not isinstance(max_hands, int) or max_hands <= 0:
+        raise ValueError("'max_hands' must be a positive integer.")
+    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.")
+
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+
+    if hands_obj is None:
+        hands_obj = mp_hands.Hands(
+            min_detection_confidence=min_confidence,
+            max_num_hands=max_hands,
+            static_image_mode=True
+        )
+
+    if landmarks_idx is None:
+        landmarks_idx = list(range(21))
+
+    rgb_image = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
+    results = hands_obj.process(rgb_image)
+
+    annotated_image = np_image.copy()
+    all_landmarks = []
+
+    if results.multi_hand_landmarks:
+        for hand_id, hand_landmarks in enumerate(results.multi_hand_landmarks):
+            if len(landmarks_idx) == 21:
+                mp.solutions.drawing_utils.draw_landmarks(
+                    image=annotated_image,
+                    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
+                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)
+
+            for idx in landmarks_idx:
+                lm = hand_landmarks.landmark[idx]
+                all_landmarks.append([hand_id, idx, lm.x, lm.y, lm.z])
+
+    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_hands_live(max_hands: int = 2, min_confidence: float = 0.7):
+    """Real-time hand detection via webcam. Press ESC to exit."""
+    if not isinstance(max_hands, int) or max_hands <= 0:
+        raise ValueError("'max_hands' must be a positive integer.")
+    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.")
+
+    cap = cv2.VideoCapture(0)
+    if not cap.isOpened():
+        raise RuntimeError("Failed to open webcam.")
+
+    hands_obj = mp_hands.Hands(
+        min_detection_confidence=min_confidence,
+        max_num_hands=max_hands,
+        static_image_mode=False
+    )
+
+    try:
+        while True:
+            success, frame = cap.read()
+            if not success:
+                print("Ignoring empty camera frame.")
+                continue
+
+            annotated_img, _ = detect_hands(
+                max_hands=max_hands,
+                min_confidence=min_confidence,
+                src_np_image=frame,
+                hands_obj=hands_obj
+            )
+
+            cv2.imshow('Live hand detector - ImagePRO', annotated_img)
+
+            if cv2.waitKey(5) & 0xFF == 27:
+                break
+    finally:
+        cap.release()
+        cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    detect_hands_live(max_hands=2)

{imagepro_python-0.1.1 → imagepro_python-0.3.0}/src/ImagePRO/human_analysis/face_analysis/eye_status_analysis.py

@@ -15,51 +15,71 @@ mp_face_mesh = mp.solutions.face_mesh
 
 
 def analyze_eye_status(
-    min_confidence=0.7,
-    image_path=None,
-    np_image=None,
+    min_confidence: float = 0.7,
+    src_image_path: str | None = None,
+    src_np_image=None,
     face_mesh_obj=None,
-    threshold=0.2
-):
+    threshold: float = 0.2,
+) -> bool:
     """
-    Analyze eye open/closed status using Eye Aspect Ratio (EAR).
-
-    Args:
-        min_confidence (float): Minimum confidence for FaceMesh detection.
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        face_mesh_obj (FaceMesh, optional): Reusable instance of FaceMesh.
-        threshold (float): EAR threshold below which eye is considered closed.
-
-    Returns:
-        bool: True if eye is open, False if closed.
-
-    Raises:
-        ValueError: If landmarks are not detected or inputs are invalid.
+    Analyze right-eye open/closed status via Eye Aspect Ratio (EAR).
+
+    Parameters
+    ----------
+    min_confidence : float, default=0.7
+        Minimum detection confidence for FaceMesh in [0, 1].
+    src_image_path : str | None, optional
+        Path to input image file.
+    src_np_image : np.ndarray | None, optional
+        Image array in BGR (OpenCV). If both provided, ``src_np_image`` takes precedence.
+    face_mesh_obj : mediapipe.python.solutions.face_mesh.FaceMesh | None, optional
+        Reusable FaceMesh instance; if ``None``, one is created (static image mode).
+    threshold : float, default=0.2
+        EAR threshold below which the eye is considered closed.
+
+    Returns
+    -------
+    bool
+        ``True`` if eye is open, ``False`` if closed.
+
+    Raises
+    ------
+    ValueError
+        * If ``min_confidence`` is out of range, or landmarks are not detected.
+        * From ``IOHandler.load_image`` when both inputs are ``None`` or image loading fails.
+    TypeError
+        From ``IOHandler.load_image`` on invalid argument types.
+    FileNotFoundError
+        From ``IOHandler.load_image`` when ``src_image_path`` does not exist.
+
+    Notes
+    -----
+    * Uses MediaPipe indices for the right eye:
+      386 (upper lid), 374 (lower lid), 263 (outer corner), 362 (inner corner).
+    * EAR is computed as ``vertical / horizontal`` on pixel coordinates.
     """
     if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 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)
     h, w = np_image.shape[:2]
 
     if face_mesh_obj is None:
         face_mesh_obj = mp_face_mesh.FaceMesh(
             min_detection_confidence=min_confidence,
             refine_landmarks=True,
-            static_image_mode=True
+            static_image_mode=True,
         )
 
-    # Landmark indices for right eye (from MediaPipe's model)
-    # 386 (top eyelid), 374 (bottom eyelid), 263 (outer corner), 362 (inner corner)
+    # Landmark indices for right eye (MediaPipe 468-point model)
     indices = [386, 374, 263, 362]
 
     _, landmarks = analyze_face_mesh(
         max_faces=1,
         min_confidence=min_confidence,
         landmarks_idx=indices,
-        np_image=np_image,
-        face_mesh_obj=face_mesh_obj
+        src_np_image=np_image,
+        face_mesh_obj=face_mesh_obj,
     )
 
     if not landmarks:
@@ -72,8 +92,8 @@ def analyze_eye_status(
         bottom_y = eye_points[374][3] * h
         left_x = eye_points[263][2] * w
         right_x = eye_points[362][2] * w
-    except KeyError:
-        raise ValueError("Missing necessary eye landmarks.")
+    except KeyError as e:
+        raise ValueError("Missing necessary eye landmarks.") from e
 
     vertical_dist = abs(bottom_y - top_y)
     horizontal_dist = abs(right_x - left_x)
@@ -85,17 +105,28 @@ def analyze_eye_status(
     return ear > threshold
 
 
-def analyze_eye_status_live(min_confidence=0.7, threshold=0.2):
+def analyze_eye_status_live(min_confidence: float = 0.7, threshold: float = 0.2) -> None:
     """
-    Perform live eye open/closed detection using webcam input.
-
-    Args:
-        min_confidence (float): Minimum confidence for detection.
-        threshold (float): EAR threshold to consider eyes open.
-
-    Raises:
-        ValueError: If confidence value is invalid.
-        RuntimeError: If webcam cannot be accessed.
+    Live eye open/closed detection using the default webcam.
+
+    Parameters
+    ----------
+    min_confidence : float, default=0.7
+        Minimum detection confidence in [0, 1].
+    threshold : float, default=0.2
+        EAR threshold to consider eyes open.
+
+    Raises
+    ------
+    ValueError
+        If ``min_confidence`` is invalid.
+    RuntimeError
+        If the webcam cannot be accessed.
+
+    Notes
+    -----
+    * Uses ``static_image_mode=False`` for better performance on video streams.
+    * Press **ESC** to exit.
     """
     if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 1.")
@@ -108,7 +139,7 @@ def analyze_eye_status_live(min_confidence=0.7, threshold=0.2):
         max_num_faces=1,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,
-        static_image_mode=True
+        static_image_mode=False,  # better for live video
     )
 
     try:
@@ -121,9 +152,9 @@ def analyze_eye_status_live(min_confidence=0.7, threshold=0.2):
             try:
                 is_open = analyze_eye_status(
                     min_confidence=min_confidence,
-                    np_image=frame,
+                    src_np_image=frame,
                     face_mesh_obj=face_mesh,
-                    threshold=threshold
+                    threshold=threshold,
                 )
                 status = "Open" if is_open else "Closed"
             except ValueError:
@@ -136,13 +167,12 @@ def analyze_eye_status_live(min_confidence=0.7, threshold=0.2):
                 cv2.FONT_HERSHEY_SIMPLEX,
                 0.7,
                 (0, 255, 0) if status == "Open" else (0, 0, 255),
-                2
+                2,
             )
 
             cv2.imshow("ImagePRO - Eye Status (ESC to Exit)", frame)
             if cv2.waitKey(5) & 0xFF == 27:
                 break
-
     finally:
         cap.release()
         cv2.destroyAllWindows()

imagepro_python-0.3.0/src/ImagePRO/human_analysis/face_analysis/face_detection.py

@@ -0,0 +1,109 @@
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+# Add parent directory to sys.path for custom module imports
+parent_dir = Path(__file__).resolve().parent.parent.parent
+sys.path.append(str(parent_dir))
+
+from utils.io_handler import IOHandler
+from human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
+
+
+def detect_faces(
+    max_faces: int = 1,
+    min_confidence: float = 0.7,
+    src_image_path: str | None = None,
+    src_np_image=None,
+    output_image_path: str | None = None,
+    face_mesh_obj=None,
+):
+    """
+    Detect and crop face regions using MediaPipe facial landmarks.
+
+    Parameters
+    ----------
+    max_faces : int, default=1
+        Maximum number of faces to detect.
+    min_confidence : float, default=0.7
+        Detection confidence threshold in [0, 1].
+    src_image_path : str | None, optional
+        Path to input image file.
+    src_np_image : np.ndarray | None, optional
+        Image array in BGR format. If both provided, `src_np_image` takes precedence.
+    output_image_path : str | None, optional
+        If provided, saves cropped faces to disk (single path used as base name for multiple faces).
+    face_mesh_obj : mediapipe.python.solutions.face_mesh.FaceMesh | None, optional
+        Optional reusable FaceMesh instance.
+
+    Returns
+    -------
+    list[np.ndarray] | str
+        If `output_image_path` is provided, returns the save message from
+        `IOHandler.save_image`. Otherwise, returns a list of cropped face images.
+
+    Raises
+    ------
+    ValueError
+        * If inputs are invalid or no face landmarks are detected (this function).
+        * From IOHandler.load_image when both inputs are None or image loading fails.
+    TypeError
+        From IOHandler.load_image/save_image on invalid argument types.
+    FileNotFoundError
+        From IOHandler.load_image when `src_image_path` does not exist.
+    IOError
+        From IOHandler.save_image when saving the image fails.
+    """
+    # --- Validate inputs -----------------------------------------------------
+    if not isinstance(max_faces, int) or max_faces <= 0:
+        raise ValueError("'max_faces' must be a positive integer.")
+
+    if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
+        raise ValueError("'min_confidence' must be a float between 0 and 1.")
+
+    # --- Load image -----------------------------------------------------------
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+    height, width = np_image.shape[:2]
+
+    # Selected face outline landmark indices (MediaPipe 468-point model)
+    face_outline_indices = [
+        10, 338, 297, 332, 284, 251, 389, 356, 454, 323,
+        361, 288, 397, 365, 379, 378, 400, 377, 152, 148,
+        176, 149, 150, 136, 164, 163, 153, 157
+    ]
+
+    # --- Run face mesh analysis ----------------------------------------------
+    _, raw_landmarks = analyze_face_mesh(
+        max_faces=max_faces,
+        min_confidence=min_confidence,
+        landmarks_idx=face_outline_indices,
+        src_np_image=np_image,
+        face_mesh_obj=face_mesh_obj
+    )
+
+    if not raw_landmarks:
+        raise ValueError("No face landmarks detected in the input image.")
+
+    # --- Convert normalized landmark coordinates to pixel positions ----------
+    all_polygons = []
+    for face in raw_landmarks:
+        polygon = [
+            (int(x * width), int(y * height))
+            for _, _, x, y, _ in face
+        ]
+        all_polygons.append(np.array(polygon, dtype=np.int32))
+
+    # --- Crop faces using boundingRect ---------------------------------------
+    cropped_faces = []
+    for polygon in all_polygons:
+        x, y, w, h = cv2.boundingRect(polygon)
+        cropped = np_image[y:y + h, x:x + w]
+        cropped_faces.append(cropped)
+
+    # --- Output handling ------------------------------------------------------
+    if output_image_path:
+        print(IOHandler.save_image(cropped_faces, output_image_path))
+
+    return cropped_faces