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

ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py

@@ -16,58 +16,95 @@ mp_drawing_styles = mp.solutions.drawing_styles
 
 
 def analyze_face_mesh(
-    max_faces=1,
-    min_confidence=0.7,
-    landmarks_idx=None,
-    image_path=None,
-    np_image=None,
-    result_path=None,
-    face_mesh_obj=None
+    max_faces: int = 1,
+    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,
+    face_mesh_obj=None,
 ):
     """
-    Detect facial landmarks using MediaPipe FaceMesh.
-
-    Args:
-        max_faces (int): Maximum number of faces to detect.
-        min_confidence (float): Detection confidence threshold.
-        landmarks_idx (list, optional): Indices of landmarks to extract or draw.
-        image_path (str, optional): Path to input image file.
-        np_image (np.ndarray, optional): Image array.
-        result_path (str, optional): Save path (supports .jpg or .csv).
-        face_mesh_obj (FaceMesh, optional): External instance to reuse.
-
-    Returns:
-        str or tuple or np.ndarray or list:
-            - If `result_path` ends with `.jpg`: save/return annotated image.
-            - If `result_path` ends with `.csv`: save/return coordinates.
-            - If no result_path: returns (image, landmarks list).
+    Detect facial landmarks using MediaPipe FaceMesh on a single image (path or ndarray).
+
+    Parameters
+    ----------
+    max_faces : int, default=1
+        Maximum number of faces to detect.
+    min_confidence : float, default=0.7
+        Minimum detection confidence in [0, 1].
+    landmarks_idx : list[int] | None, optional
+        Specific landmark indices to extract/draw. If ``None``, uses the full
+        468-point mesh.
+    src_image_path : str | None, optional
+        Path to the input image (BGR/RGB supported by ``IOHandler.load_image``).
+    src_np_image : np.ndarray | None, optional
+        Image array in BGR (as returned by OpenCV). If both ``src_image_path`` and
+        ``src_np_image`` are provided, the ndarray takes precedence.
+    output_image_path : str | None, optional
+        If provided (e.g. "out.jpg"/"out.png"), the annotated image is saved there.
+    output_csv_path : str | None, optional
+        If provided (e.g. "landmarks.csv"), landmark coordinates are saved there as
+        rows: ``[face_id, index, x, y, z]`` with normalized x/y/z from MediaPipe.
+    face_mesh_obj : mediapipe.python.solutions.face_mesh.FaceMesh | None, optional
+        Reusable external FaceMesh instance. If ``None``, a new one is created
+        with ``static_image_mode=True`` and ``refine_landmarks=True``.
+
+    Returns
+    -------
+    tuple
+        ``(annotated_image: np.ndarray, all_landmarks: list[list[list[float]]])``
+        where ``all_landmarks`` is a list per face, each containing rows of
+        ``[face_id, index, x, y, z]``.
+
+    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
+        * If ``landmarks_idx`` is not a list of integers (this function).
+        * From ``IOHandler.load_image``/``save_image``/``save_csv`` on invalid argument types.
+    FileNotFoundError
+        From ``IOHandler.load_image`` when ``image_path`` does not exist.
+    IOError
+        From ``IOHandler.save_image`` when saving the image fails.
+
+    Notes
+    -----
+    * The x/y/z coordinates from MediaPipe are **normalized** to [0, 1] in image
+      space; multiply by width/height to get pixel coordinates.
+    * When ``landmarks_idx`` covers all 468 points, the full tessellation is drawn.
+      Otherwise, only the requested points are highlighted.
     """
+
+    # --- 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.")
 
-    if landmarks_idx is not None and not isinstance(landmarks_idx, list):
-        raise TypeError("'landmarks_idx' must be a list of integers or None.")
-
-    if result_path and not isinstance(result_path, str):
-        raise TypeError("'result_path' must be a string or None.")
-
-    if result_path and not result_path.endswith(('.jpg', '.csv')):
-        raise ValueError("Only '.jpg' or '.csv' formats are supported.")
+    if landmarks_idx is not None:
+        if 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 or None.")
 
+    # --- Create or reuse FaceMesh instance ----------------------------------
     if face_mesh_obj is None:
         face_Mesh = mp_face_mesh.FaceMesh(
             max_num_faces=max_faces,
             min_detection_confidence=min_confidence,
             refine_landmarks=True,
-            static_image_mode=True
+            static_image_mode=True,
         )
     else:
         face_Mesh = face_mesh_obj
 
-    np_image = IOHandler.load_image(image_path=image_path, np_image=np_image)
+    # --- Load image (path or ndarray) ---------------------------------------
+    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+
+    # Convert BGR -> RGB for MediaPipe
     rgb_image = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
     results = face_Mesh.process(rgb_image)
 
@@ -75,55 +112,68 @@ def analyze_face_mesh(
         raise ValueError("No face landmarks detected.")
 
     landmarks_idx = landmarks_idx or list(range(468))
+
     annotated = np_image.copy()
     all_landmarks = []
 
     for face_id, face_landmarks in enumerate(results.multi_face_landmarks):
-        if result_path is None or result_path.endswith('.jpg'):
-            if len(landmarks_idx) == 468:
-                mp_drawing_utils.draw_landmarks(
-                    image=annotated,
-                    landmark_list=face_landmarks,
-                    connections=mp_face_mesh.FACEMESH_TESSELATION,
-                    landmark_drawing_spec=None,
-                    connection_drawing_spec=mp_drawing_styles.get_default_face_mesh_tesselation_style()
-                )
-            else:
-                h, w = annotated.shape[:2]
-                for idx in landmarks_idx:
-                    lm = face_landmarks.landmark[idx]
-                    cx, cy = int(w * lm.x), int(h * lm.y)
-                    cv2.circle(annotated, (cx, cy), 3, (0, 0, 255), -1)
-
-        if result_path is None or result_path.endswith('.csv'):
-            face_data = [
-                [face_id, idx, lm.x, lm.y, lm.z]
-                for idx in landmarks_idx
-                for lm in [face_landmarks.landmark[idx]]
-            ]
-            all_landmarks.append(face_data)
-
-    # Output handling
-    if result_path:
-        if result_path.endswith('.jpg'):
-            return IOHandler.save_image(annotated, result_path)
-        elif result_path.endswith('.csv'):
-            flat_data = [row for face in all_landmarks for row in face]
-            return IOHandler.save_csv(flat_data, result_path)
+        # Draw either the full tessellation or specific landmark dots
+        if len(landmarks_idx) == 468:
+            mp_drawing_utils.draw_landmarks(
+                image=annotated,
+                landmark_list=face_landmarks,
+                connections=mp_face_mesh.FACEMESH_TESSELATION,
+                landmark_drawing_spec=None,
+                connection_drawing_spec=mp_drawing_styles.get_default_face_mesh_tesselation_style(),
+            )
+        else:
+            h, w = annotated.shape[:2]
+            for idx in landmarks_idx:
+                lm = face_landmarks.landmark[idx]
+                cx, cy = int(w * lm.x), int(h * lm.y)
+                cv2.circle(annotated, (cx, cy), 3, (0, 0, 255), -1)
+
+        # Collect normalized coordinates for requested indices
+        face_data = [
+            [face_id, idx, face_landmarks.landmark[idx].x, face_landmarks.landmark[idx].y, face_landmarks.landmark[idx].z]
+            for idx in landmarks_idx
+        ]
+        all_landmarks.append(face_data)
+
+    # --- Output handling -----------------------------------------------------
+    if output_image_path is not None:
+        # IOHandler.save_image returns a message/path; echo to stdout for logs
+        print(IOHandler.save_image(annotated, output_image_path))
+
+    if output_csv_path is not None:
+        flat_data = [row for face in all_landmarks for row in face]
+        print(IOHandler.save_csv(flat_data, output_csv_path))
 
     return annotated, all_landmarks
 
 
-def analyze_face_mesh_live(max_faces=1, min_confidence=0.7):
+def analyze_face_mesh_live(max_faces: int = 1, min_confidence: float = 0.7):
     """
-    Launch webcam with real-time face landmark overlay.
-
-    Args:
-        max_faces (int): Max faces to detect.
-        min_confidence (float): Detection confidence threshold.
-
-    Raises:
-        RuntimeError: If webcam can't be opened.
+    Launch webcam preview with real-time FaceMesh overlay.
+
+    Parameters
+    ----------
+    max_faces : int, default=1
+        Max number of faces to detect per frame.
+    min_confidence : float, default=0.7
+        Minimum detection confidence in [0, 1].
+
+    Raises
+    ------
+    ValueError
+        If arguments are invalid.
+    RuntimeError
+        If the webcam cannot be opened.
+
+    Notes
+    -----
+    * Uses ``static_image_mode=False`` for better performance on video streams.
+    * Press **ESC** to exit the preview window.
     """
     if not isinstance(max_faces, int) or max_faces <= 0:
         raise ValueError("'max_faces' must be a positive integer.")
@@ -135,11 +185,12 @@ def analyze_face_mesh_live(max_faces=1, min_confidence=0.7):
     if not cap.isOpened():
         raise RuntimeError("Unable to open webcam.")
 
+    # For live video, static_image_mode=False is preferred (tracking across frames)
     face_Mesh = mp_face_mesh.FaceMesh(
         max_num_faces=max_faces,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,
-        static_image_mode=True
+        static_image_mode=False,
     )
 
     try:
@@ -153,15 +204,17 @@ def analyze_face_mesh_live(max_faces=1, min_confidence=0.7):
                 result_image, _ = analyze_face_mesh(
                     max_faces=max_faces,
                     min_confidence=min_confidence,
-                    np_image=frame,
-                    face_mesh_obj=face_Mesh
+                    src_np_image=frame,
+                    face_mesh_obj=face_Mesh,
                 )
             except ValueError:
+                # No face detected in this frame; show raw frame
                 result_image = frame
 
             cv2.imshow("ImagePRO - Face Mesh", result_image)
 
-            if cv2.waitKey(1) & 0xFF == 27:  # ESC key
+            # Exit on ESC key
+            if cv2.waitKey(1) & 0xFF == 27:
                 break
     finally:
         cap.release()

ImagePRO/human_analysis/face_analysis/head_pose_estimation.py

@@ -15,36 +15,53 @@ mp_face_mesh = mp.solutions.face_mesh
 
 
 def estimate_head_pose(
-    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_csv_path: str | None = None,
+    face_mesh_obj=None,
 ):
     """
-    Estimate head pose (yaw, pitch) from facial landmarks.
-
-    Args:
-        max_faces (int): 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): Input image as array.
-        result_path (str, optional): If given, save results as CSV.
-        face_mesh_obj (FaceMesh, optional): Reusable MediaPipe instance.
-
-    Returns:
-        str or list[list]: CSV confirmation if saved, else list of [face_id, yaw, pitch].
-
-    Raises:
-        ValueError: On invalid input or no detected face.
+    Estimate head pose (yaw, pitch) from a single image using MediaPipe facial landmarks.
+
+    Parameters
+    ----------
+    max_faces : int, default=1
+        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 the input image file.
+    src_np_image : np.ndarray | None, optional
+        Input image array in BGR format. If both are provided, `src_np_image` takes precedence.
+    output_csv_path : str | None, optional
+        If provided, saves the results as CSV rows: [face_id, yaw, pitch].
+    face_mesh_obj : mediapipe.python.solutions.face_mesh.FaceMesh | None, optional
+        Optional reusable FaceMesh instance.
+
+    Returns
+    -------
+    list[list[float]] | str
+        Save message from IOHandler.save_csv if `output_csv_path` is provided,
+        otherwise list of [face_id, yaw, pitch] for each detected face.
+
+    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_csv on invalid argument types.
+    FileNotFoundError
+        From IOHandler.load_image when `src_image_path` does not exist.
     """
     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 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)
 
     # Important landmark indices (MediaPipe 468 model)
     indices = [1, 152, 33, 263, 168]  # nose_tip, chin, left_eye, right_eye, nasion
@@ -53,7 +70,7 @@ def estimate_head_pose(
         max_faces=max_faces,
         min_confidence=min_confidence,
         landmarks_idx=indices,
-        np_image=np_image,
+        src_np_image=np_image,
         face_mesh_obj=face_mesh_obj
     )
 
@@ -73,28 +90,40 @@ def estimate_head_pose(
         except KeyError:
             continue  # skip this face if any point is missing
 
-        # Simplified proportional estimation
+        # Simplified proportional estimation on normalized coords
         yaw = 100 * ((right_x - nasion_x) - (nasion_x - left_x))
         pitch = 100 * ((chin_y - nose_y) - (nose_y - nasion_y))
 
-        results.append([face[0][0], yaw, pitch])  # face_id, yaw, pitch
+        results.append([face[0][0], yaw, pitch])
 
-    if result_path:
-        return IOHandler.save_csv(results, result_path)
+    if output_csv_path:
+        print(IOHandler.save_csv(results, output_csv_path))
 
     return results
 
 
-def estimate_head_pose_live(max_faces=1, min_confidence=0.7):
+def estimate_head_pose_live(max_faces: int = 1, min_confidence: float = 0.7):
     """
-    Live head pose estimation using webcam.
-
-    Args:
-        max_faces (int): Number of faces to detect.
-        min_confidence (float): Confidence threshold (0–1).
-
-    Raises:
-        ValueError, RuntimeError: On invalid inputs or camera failure.
+    Live head pose estimation using the default webcam.
+
+    Parameters
+    ----------
+    max_faces : int, default=1
+        Number of faces to detect per frame.
+    min_confidence : float, default=0.7
+        Detection confidence threshold in [0, 1].
+
+    Raises
+    ------
+    ValueError
+        On invalid inputs.
+    RuntimeError
+        If the camera cannot be opened.
+
+    Notes
+    -----
+    * Uses static_image_mode=False for better performance on video streams.
+    * Press ESC to exit the preview window.
     """
     if not isinstance(max_faces, int) or max_faces <= 0:
         raise ValueError("'max_faces' must be a positive integer.")
@@ -109,7 +138,7 @@ def estimate_head_pose_live(max_faces=1, min_confidence=0.7):
         max_num_faces=max_faces,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,
-        static_image_mode=True
+        static_image_mode=False
     )
 
     try:
@@ -123,7 +152,7 @@ def estimate_head_pose_live(max_faces=1, min_confidence=0.7):
                 face_angles = estimate_head_pose(
                     max_faces=max_faces,
                     min_confidence=min_confidence,
-                    np_image=frame,
+                    src_np_image=frame,
                     face_mesh_obj=face_mesh
                 )
             except ValueError: