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

ImagePRO/human_analysis/face_analysis/face_detection.py

@@ -1,15 +1,13 @@
-import sys
-from pathlib import Path
+from __future__ import annotations
 
 import cv2
+import mediapipe as mp
 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 ImagePRO.human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
-from utils.io_handler import IOHandler
-from human_analysis.face_analysis.face_mesh_analysis import analyze_face_mesh
 
 # Constants
 DEFAULT_MAX_FACES = 1
@@ -22,93 +20,102 @@ FACE_OUTLINE_INDICES = [
 
 
 def detect_faces(
+    image: Image, 
+    *,
     max_faces: int = DEFAULT_MAX_FACES,
     min_confidence: float = DEFAULT_MIN_CONFIDENCE,
-    src_image_path: str | None = None,
-    src_np_image=None,
-    output_image_path: str | None = None,
-    face_mesh_obj=None,
-):
+    face_mesh_obj: mp.solutions.face_mesh.FaceMesh | None = None
+) -> Result:
+    """Detect and crop face regions using facial landmarks.
+
+    Uses face mesh to locate face outline points,
+    then extracts rectangular regions containing each face.
+
+    Args:
+        image: Input image to process.
+        max_faces: Maximum number of faces to detect.
+            Must be positive.
+            Default: 1
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
+        face_mesh_obj: Pre-initialized face mesh detector.
+            If None, creates new instance.
+            Default: None
+
+    Returns:
+        Result object with detections:
+        - image: List of cropped face images
+            None if no faces detected
+        - data: List of face outline polygons
+            None if no faces detected
+        - meta: Operation info and parameters
+            Includes error info if detection fails
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If max_faces is not positive
+        ValueError: If min_confidence not in [0,1]
     """
-    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(image, Image):
+        raise TypeError("'image' must be an Image instance")
+
     if not isinstance(max_faces, int) or max_faces <= 0:
-        raise ValueError("'max_faces' must be a positive integer.")
+        raise ValueError("'max_faces' must be positive")
 
     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.")
+        raise ValueError("'min_confidence' must be 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]
+    # Get image dimensions
+    height, width = image.shape[:2]
 
-    # Selected face outline landmark indices (MediaPipe 468-point model)
-    face_outline_indices = FACE_OUTLINE_INDICES
-
-    # --- Run face mesh analysis ----------------------------------------------
-    _, raw_landmarks = analyze_face_mesh(
+    # Get face landmarks
+    result_mesh = analyze_face_mesh(
+        image=image,
         max_faces=max_faces,
         min_confidence=min_confidence,
-        landmarks_idx=face_outline_indices,
-        src_np_image=np_image,
+        landmarks_idx=FACE_OUTLINE_INDICES,
         face_mesh_obj=face_mesh_obj
     )
+    raw_landmarks = result_mesh.data
 
+    # Handle no detections
     if not raw_landmarks:
-        raise ValueError("No face landmarks detected in the input image.")
-
-    # --- Convert normalized landmark coordinates to pixel positions ----------
-    all_polygons = []
+        return Result(
+            image=None,
+            data=None,
+            meta={
+                "source": image,
+                "operation": "detect_faces",
+                "max_faces": max_faces,
+                "min_confidence": min_confidence,
+                "error": "No face landmarks detected"
+            }
+        )
+
+    # Convert landmarks to pixel coordinates
+    face_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))
+        face_polygons.append(np.array(polygon, dtype=np.int32))
 
-    # --- Crop faces using boundingRect ---------------------------------------
-    cropped_faces = []
-    for polygon in all_polygons:
+    # Extract face regions
+    face_regions = []
+    for polygon in face_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
+        face_region = image._data[y:y + h, x:x + w]
+        face_regions.append(face_region)
+
+    return Result(
+        image=face_regions,
+        data=face_polygons,
+        meta={
+            "source": image,
+            "operation": "detect_faces",
+            "max_faces": max_faces,
+            "min_confidence": min_confidence
+        }
+    )

ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py

@@ -1,14 +1,10 @@
-import sys
-from pathlib import Path
+from __future__ import annotations
 
 import cv2
 import mediapipe as mp
 
-# Add parent directory to 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 ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
 
 # Constants
 mp_face_mesh = mp.solutions.face_mesh
@@ -20,210 +16,222 @@ TOTAL_FACE_LANDMARKS = 468
 
 
 def analyze_face_mesh(
+    image: Image,
+    *,
     max_faces: int = DEFAULT_MAX_FACES,
     min_confidence: float = DEFAULT_MIN_CONFIDENCE,
-    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 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.
+    landmarks_idx: list[int] | None = None,
+    face_mesh_obj: mp.solutions.face_mesh.FaceMesh | None = None
+) -> Result:
+    """Detect facial landmarks using MediaPipe FaceMesh.
+
+    Extracts 3D facial mesh coordinates for precise face analysis.
+    Can focus on specific landmarks or detect full 468-point mesh.
+
+    Args:
+        image: Input image to process.
+        max_faces: Maximum number of faces to detect.
+            Must be positive.
+            Default: 1
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
+        landmarks_idx: Specific landmark indices to detect.
+            If None, uses all 468 points.
+            Default: None
+        face_mesh_obj: Pre-initialized face mesh detector.
+            If None, creates new instance.
+            Default: None
+
+    Returns:
+        Result object with detections and visualization:
+        - image: Input image with landmarks drawn
+            None if no faces detected
+        - data: List of [face_id, point_id, x, y, z]
+            None if no faces detected
+        - meta: Operation info and parameters
+            Includes error info if detection fails
+
+    Raises:
+        TypeError: If image is not an Image instance
+        ValueError: If max_faces is not positive
+        ValueError: If min_confidence not in [0,1]
+        TypeError: If landmarks_idx is not list[int]
+
+    Notes:
+        - Coordinates are normalized [0,1]. Multiply by width/height for pixels
+        - Full mesh (468 points) shows tessellation, specific points show dots
     """
 
-    # --- Validate inputs -----------------------------------------------------
+    # Validate inputs
+    if not isinstance(image, Image):
+        raise TypeError("'image' must be an Image instance")
+
     if not isinstance(max_faces, int) or max_faces <= 0:
-        raise ValueError("'max_faces' must be a positive integer.")
+        raise ValueError("'max_faces' must be positive")
 
     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.")
+        raise ValueError("'min_confidence' must be between 0 and 1")
 
-    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.")
+    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")
 
-    # --- Create or reuse FaceMesh instance ----------------------------------
+    # Initialize detector if needed
     if face_mesh_obj is None:
-        face_Mesh = mp_face_mesh.FaceMesh(
+        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
-
-    # --- Load image (path or ndarray) ---------------------------------------
-    np_image = IOHandler.load_image(image_path=src_image_path, np_image=src_np_image)
+        face_mesh = face_mesh_obj
 
-    # Convert BGR -> RGB for MediaPipe
-    rgb_image = cv2.cvtColor(np_image, cv2.COLOR_BGR2RGB)
-    results = face_Mesh.process(rgb_image)
+    # Prepare image
+    img_copy = image._data.copy()
+    img_rgb = cv2.cvtColor(img_copy, cv2.COLOR_BGR2RGB)
+    
+    # Detect facial landmarks
+    results = face_mesh.process(img_rgb)
 
+    # Handle no detections
     if not results.multi_face_landmarks:
-        raise ValueError("No face landmarks detected.")
-
-    landmarks_idx = landmarks_idx or list(range(468))
-
-    annotated = np_image.copy()
-    all_landmarks = []
+        return Result(
+            image=None,
+            data=None,
+            meta={
+                "source": image,
+                "operation": "analyze_face_mesh",
+                "landmarks_idx": landmarks_idx,
+                "max_faces": max_faces,
+                "min_confidence": min_confidence,
+                "error": "No face landmarks detected"
+            }
+        )
 
+    # 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 either the full tessellation or specific landmark dots
+        # Draw landmarks
         if len(landmarks_idx) == TOTAL_FACE_LANDMARKS:
+            # Draw full face mesh
             mp_drawing_utils.draw_landmarks(
-                image=annotated,
+                image=img_copy,
                 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(),
+                connection_drawing_spec=mp_drawing_styles.get_default_face_mesh_tesselation_style()
             )
         else:
-            h, w = annotated.shape[:2]
+            # Draw specific points
+            h, w = img_copy.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)
+                cv2.circle(img_copy, (cx, cy), 3, (0, 0, 255), -1)
 
-        # Collect normalized coordinates for requested indices
+        # Extract coordinates
         face_data = [
-            [face_id, idx, face_landmarks.landmark[idx].x, face_landmarks.landmark[idx].y, face_landmarks.landmark[idx].z]
+            [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 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
+        landmarks.append(face_data)
+
+    return Result(
+        image=img_copy,
+        data=landmarks,
+        meta={
+            "source": image,
+            "operation": "analyze_face_mesh",
+            "landmarks_idx": landmarks_idx,
+            "max_faces": max_faces,
+            "min_confidence": min_confidence
+        }
+    )
 
 
-def analyze_face_mesh_live(max_faces: int = DEFAULT_MAX_FACES, min_confidence: float = DEFAULT_MIN_CONFIDENCE):
-    """
-    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.
+def analyze_face_mesh_live(
+    *,
+    max_faces: int = DEFAULT_MAX_FACES,
+    min_confidence: float = DEFAULT_MIN_CONFIDENCE
+) -> None:
+    """Start live webcam feed with real-time face mesh visualization.
+
+    Opens default camera and shows face landmarks in real-time.
+    Uses tracking mode for better performance on video.
+    Press ESC to exit.
+
+    Args:
+        max_faces: Maximum number of faces to track.
+            Must be positive.
+            Default: 1
+        min_confidence: Detection confidence threshold.
+            Must be between 0 and 1.
+            Default: 0.7
+
+    Raises:
+        ValueError: If parameters are invalid
+        RuntimeError: If camera cannot be accessed
     """
+    # Validate parameters
     if not isinstance(max_faces, int) or max_faces <= 0:
-        raise ValueError("'max_faces' must be a positive integer.")
+        raise ValueError("'max_faces' must be positive")
 
     if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
-        raise ValueError("'min_confidence' must be between 0 and 1.")
+        raise ValueError("'min_confidence' must be between 0 and 1")
 
+    # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
-        raise RuntimeError("Unable to open webcam.")
+        raise RuntimeError("Cannot access webcam")
 
-    # For live video, static_image_mode=False is preferred (tracking across frames)
-    face_Mesh = mp_face_mesh.FaceMesh(
+    # Initialize detector in tracking mode for better performance
+    face_mesh = mp_face_mesh.FaceMesh(
         max_num_faces=max_faces,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,
-        static_image_mode=False,
+        static_image_mode=False
     )
 
     try:
         while True:
+            # Get frame
             success, frame = cap.read()
             if not success:
-                print("Skipping empty frame.")
+                print("Failed to capture frame, skipping...")
                 continue
 
+            # Process frame
             try:
-                result_image, _ = analyze_face_mesh(
+                result = analyze_face_mesh(
+                    image=Image.from_array(frame),
                     max_faces=max_faces,
                     min_confidence=min_confidence,
-                    src_np_image=frame,
-                    face_mesh_obj=face_Mesh,
+                    face_mesh_obj=face_mesh
                 )
-            except ValueError:
-                # No face detected in this frame; show raw frame
-                result_image = frame
+                display_frame = result.image if result.image is not None else frame
+            except (TypeError, ValueError):
+                # Fall back to raw frame if detection fails
+                display_frame = frame
 
-            cv2.imshow("ImagePRO - Face Mesh", result_image)
+            # Show result
+            cv2.imshow("ImagePRO - Face Mesh", display_frame)
 
-            # Exit on ESC key
+            # Check for ESC key
             if cv2.waitKey(1) & 0xFF == 27:
                 break
     finally:
+        # Clean up resources
         cap.release()
         cv2.destroyAllWindows()
 
 
 if __name__ == "__main__":
-    analyze_face_mesh_live(max_faces=1)
+    analyze_face_mesh_live()