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

ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -8,42 +8,52 @@ import mediapipe as mp
 parent_dir = Path(__file__).resolve().parent.parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 mp_pose = mp.solutions.pose
 
 def detect_body_pose(
-    model_accuracy=0.7,
-    landmarks_idx=None,
-    image_path=None,
-    np_image=None,
-    result_path=None,
+    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
 ):
     """
-    Detects body landmarks from an image using MediaPipe Pose.
-
-    Args:
-        model_accuracy (float): Confidence threshold (0.0 to 1.0).
-        landmarks_idx (list[int] | None): Indices to extract (default: all 33).
-        image_path (str | None): Path to image file.
-        np_image (np.ndarray | None): Already loaded image (used if image_path is None).
-        result_path (str | None): Path to save image (.jpg) or coordinates (.csv).
-        pose_obj (mp.solutions.pose.Pose | None): Optional pre-initialized pose model.
-
-    Returns:
-        str | tuple[np.ndarray, list]: Output message or annotated image and landmark list.
+    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):
-        raise TypeError("'landmarks_idx' must be a list or None.")
+    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 result_path:
-        if not isinstance(result_path, str):
-            raise TypeError("'result_path' must be a string.")
-        if not (result_path.endswith('.jpg') or result_path.endswith('.csv')):
-            raise ValueError("Supported extensions: '.jpg', '.csv'.")
-
-    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)
 
     if landmarks_idx is None:
         landmarks_idx = list(range(33))
@@ -61,47 +71,41 @@ def detect_body_pose(
     all_landmarks = []
 
     if result.pose_landmarks:
-        if result_path is None or result_path.endswith('.jpg'):
-            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)
-
-        if result_path is None or result_path.endswith('.csv'):
+        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]
-                all_landmarks.append([idx, lm.x, lm.y, lm.z])
+                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))
 
-    if result_path:
-        if result_path.endswith('.jpg'):
-            return IOHandler.save_image(annotated_image, result_path)
-        elif result_path.endswith('.csv'):
-            return IOHandler.save_csv(all_landmarks, result_path)
-    else:
-        return annotated_image, all_landmarks
+    return annotated_image, all_landmarks
 
 
 def detect_body_pose_live():
-    """
-    Starts webcam and shows real-time body pose detection.
-    Press ESC to exit.
-    """
+    """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=True
+        static_image_mode=False
     )
 
     try:
@@ -112,7 +116,7 @@ def detect_body_pose_live():
                 continue
 
             try:
-                annotated_img, _ = detect_body_pose(np_image=frame, pose_obj=pose_obj)
+                annotated_img, _ = detect_body_pose(src_np_image=frame, pose_obj=pose_obj)
             except ValueError:
                 annotated_img = frame
 

ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -8,51 +8,60 @@ import mediapipe as mp
 parent_dir = Path(__file__).resolve().parent.parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 
 mp_hands = mp.solutions.hands
 
 
 def detect_hands(
-    max_hands=2,
-    min_confidence=0.7,
-    landmarks_idx=None,
-    image_path=None,
-    np_image=None,
-    result_path=None,
+    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
 ):
     """
-    Detects hand landmarks in an image using MediaPipe.
-
-    Args:
-        max_hands (int): Max number of hands to detect.
-        min_confidence (float): Minimum confidence for detection.
-        landmarks_idx (list[int] | None): Landmark indices to extract (default: all 21).
-        image_path (str | None): Image file path.
-        np_image (np.ndarray | None): Preloaded image array.
-        result_path (str | None): Path to save output image (.jpg) or landmarks (.csv).
-        hands_obj (mp.solutions.hands.Hands | None): Optional pre-initialized model.
-
-    Returns:
-        np.ndarray | list: Annotated image and landmarks list, or saved file confirmation.
+    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.")
 
-    if landmarks_idx is not None and not isinstance(landmarks_idx, list):
-        raise TypeError("'landmarks_idx' must be a list or None.")
-
-    if result_path:
-        if not isinstance(result_path, str):
-            raise TypeError("'result_path' must be a string.")
-        if not (result_path.endswith('.jpg') or result_path.endswith('.csv')):
-            raise ValueError("Only '.jpg' and '.csv' extensions are supported.")
-
-    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)
 
     if hands_obj is None:
         hands_obj = mp_hands.Hands(
@@ -72,49 +81,35 @@ def detect_hands(
 
     if results.multi_hand_landmarks:
         for hand_id, hand_landmarks in enumerate(results.multi_hand_landmarks):
-            if result_path is None or result_path.endswith('.jpg'):
-                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)
-
-            if result_path is None or result_path.endswith('.csv'):
-                hand_data = []
+            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]
-                    hand_data.append([hand_id, idx, lm.x, lm.y, lm.z])
-                all_landmarks.append(hand_data)
-    else:
-        return np_image, []
-
-    if result_path:
-        if result_path.endswith('.jpg'):
-            return IOHandler.save_image(annotated_image, result_path)
-        elif result_path.endswith('.csv'):
-            flat_landmarks = [item for sublist in all_landmarks for item in sublist]
-            return IOHandler.save_csv(flat_landmarks, result_path)
-    else:
-        return annotated_image, all_landmarks
-
-
-def detect_hands_live(max_hands=2, min_confidence=0.7):
-    """
-    Real-time hand detection via webcam.
+                    x, y = int(w * lm.x), int(h * lm.y)
+                    cv2.circle(annotated_image, (x, y), 3, (0, 0, 255), -1)
 
-    Args:
-        max_hands (int): Maximum hands to detect.
-        min_confidence (float): Detection confidence threshold.
-    """
+            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):
@@ -127,7 +122,7 @@ def detect_hands_live(max_hands=2, min_confidence=0.7):
     hands_obj = mp_hands.Hands(
         min_detection_confidence=min_confidence,
         max_num_hands=max_hands,
-        static_image_mode=True
+        static_image_mode=False
     )
 
     try:
@@ -140,7 +135,7 @@ def detect_hands_live(max_hands=2, min_confidence=0.7):
             annotated_img, _ = detect_hands(
                 max_hands=max_hands,
                 min_confidence=min_confidence,
-                np_image=frame,
+                src_np_image=frame,
                 hands_obj=hands_obj
             )
 

ImagePRO/human_analysis/face_analysis/eye_status_analysis.py

@@ -8,58 +8,78 @@ import mediapipe as mp
 parent_dir = Path(__file__).resolve().parent.parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 from human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
 
 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/human_analysis/face_analysis/face_detection.py

@@ -8,64 +8,85 @@ import numpy as np
 parent_dir = Path(__file__).resolve().parent.parent.parent
 sys.path.append(str(parent_dir))
 
-from io_handler import IOHandler
+from utils.io_handler import IOHandler
 from human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
 
 
 def detect_faces(
-    max_faces=1,
-    min_confidence=0.7,
-    image_path=None,
-    np_image=None,
-    result_path=None,
-    face_mesh_obj=None
+    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 face landmarks.
-
-    Args:
-        max_faces (int): Maximum number of faces to detect.
-        min_confidence (float): Confidence threshold (0–1).
-        image_path (str, optional): Path to input image.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Save path for cropped face(s).
-        face_mesh_obj (FaceMesh, optional): Reusable MediaPipe instance.
-
-    Returns:
-        str or list[np.ndarray]: Confirmation message if saved, else list of cropped face images.
-
-    Raises:
-        TypeError, ValueError: On invalid inputs or if no faces detected.
+    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.")
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    # --- 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 (based on MediaPipe's 468-point model)
+    # 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
+    # --- Run face mesh analysis ----------------------------------------------
     _, raw_landmarks = analyze_face_mesh(
         max_faces=max_faces,
         min_confidence=min_confidence,
         landmarks_idx=face_outline_indices,
-        np_image=np_image,
+        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
+    # --- Convert normalized landmark coordinates to pixel positions ----------
     all_polygons = []
     for face in raw_landmarks:
         polygon = [
@@ -74,11 +95,15 @@ def detect_faces(
         ]
         all_polygons.append(np.array(polygon, dtype=np.int32))
 
-    # Crop faces using boundingRect
+    # --- 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)
 
-    return IOHandler.save_image(cropped_faces, result_path)
+    # --- Output handling ------------------------------------------------------
+    if output_image_path:
+        print(IOHandler.save_image(cropped_faces, output_image_path))
+
+    return cropped_faces