ImagePRO-Python 1.2.2__py3-none-any.whl → 1.3.1__py3-none-any.whl

ImagePRO/__init__.py

@@ -15,7 +15,7 @@ Features:
 - Real-time processing capabilities
 """
 
-__version__ = "1.0.0"
+__version__ = "1.3.1"
 __author__ = "Parsa Safaie"
 __email__ = "parsasafaie.2568@proton.me"
 
@@ -27,7 +27,7 @@ from . import object_analysis
 
 __all__ = [
     "utils",
-    "pre_processing", 
+    "pre_processing",
     "human_analysis",
     "object_analysis"
 ]

ImagePRO/human_analysis/body_analysis/__init__.py

@@ -1,5 +1,9 @@
 # Body Analysis Module
 # Provides body pose estimation and hand tracking capabilities
+#
+# The mediapipe dependency is optional and imported lazily inside the
+# functions that need it, so both submodules are safe to import without
+# any AI extras installed.
 
 from . import body_pose_estimation
 from . import hand_tracking

ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -13,10 +14,11 @@ from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
 import cv2
-import mediapipe as mp
+
+if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
+    import mediapipe as mp
 
 # Constants
-mp_pose = mp.solutions.pose
 TOTAL_LANDMARKS = 33
 DEFAULT_CONFIDENCE = 0.7
 LANDMARK_RADIUS = 3
@@ -64,11 +66,21 @@ def detect_body_pose(
         raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        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")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for body pose "
+            'detection. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
+    mp_pose = mp.solutions.pose
+
     # Initialize detector if needed
     if pose_obj is None:
         pose_obj = mp_pose.Pose(
@@ -97,7 +109,8 @@ def detect_body_pose(
                 img_copy,
                 result.pose_landmarks,
                 mp_pose.POSE_CONNECTIONS,
-                landmark_drawing_spec=mp.solutions.drawing_styles.get_default_pose_landmarks_style()
+                landmark_drawing_spec=mp.solutions.drawing_styles
+                .get_default_pose_landmarks_style()
             )
         else:
             # Draw only selected points
@@ -132,13 +145,21 @@ def detect_body_pose_live() -> None:
     Raises:
         RuntimeError: If camera cannot be accessed
     """
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for body pose "
+            'detection. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 
     # Initialize pose detector in tracking mode
-    pose_obj = mp_pose.Pose(
+    pose_obj = mp.solutions.pose.Pose(
         min_detection_confidence=DEFAULT_CONFIDENCE,
         static_image_mode=False
     )

ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -13,10 +14,11 @@ from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
 import cv2
-import mediapipe as mp
+
+if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
+    import mediapipe as mp
 
 # Constants
-mp_hands = mp.solutions.hands
 DEFAULT_MAX_HANDS = 2
 DEFAULT_MIN_CONFIDENCE = 0.7
 TOTAL_HAND_LANDMARKS = 21
@@ -74,11 +76,21 @@ def detect_hands(
         raise ValueError("'min_confidence' must be between 0.0 and 1.0")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        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")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for hand "
+            'tracking. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
+    mp_hands = mp.solutions.hands
+
     # Initialize detector if needed
     if hands_obj is None:
         hands_obj = mp_hands.Hands(
@@ -109,8 +121,10 @@ def detect_hands(
                     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()
+                    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:
                 # Draw only selected points
@@ -166,13 +180,21 @@ def detect_hands_live(
     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")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for hand "
+            'tracking. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 
     # Initialize hand detector in tracking mode
-    hands_obj = mp_hands.Hands(
+    hands_obj = mp.solutions.hands.Hands(
         min_detection_confidence=min_confidence,
         max_num_hands=max_hands,
         static_image_mode=False

ImagePRO/human_analysis/face_analysis/__init__.py

@@ -1,5 +1,9 @@
 # Face Analysis Module
 # Provides facial landmark detection, pose estimation, and eye status analysis
+#
+# The mediapipe and insightface dependencies are optional and imported
+# lazily inside the functions that need them, so every submodule is safe
+# to import regardless of which extras are installed.
 
 from . import eye_status_analysis
 from . import face_comparison
@@ -10,7 +14,7 @@ from . import head_pose_estimation
 __all__ = [
     "eye_status_analysis",
     "face_comparison",
-    "face_detection", 
+    "face_detection",
     "face_mesh_analysis",
     "head_pose_estimation"
 ]

ImagePRO/human_analysis/face_analysis/eye_status_analysis.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -14,10 +15,11 @@ from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
 import cv2
-import mediapipe as mp
+
+if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
+    import mediapipe as mp
 
 # Constants
-mp_face_mesh = mp.solutions.face_mesh
 DEFAULT_MIN_CONFIDENCE = 0.7
 DEFAULT_THRESHOLD = 0.2
 RIGHT_EYE_INDICES = [386, 374, 263, 362]  # MediaPipe right eye landmarks
@@ -65,12 +67,20 @@ def analyze_eye_status(
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for eye status "
+            'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Get image dimensions
     h, w = image.shape[:2]
 
     # Initialize detector if needed
     if face_mesh_obj is None:
-        face_mesh_obj = mp_face_mesh.FaceMesh(
+        face_mesh_obj = mp.solutions.face_mesh.FaceMesh(
             min_detection_confidence=min_confidence,
             refine_landmarks=True,
             static_image_mode=True
@@ -173,13 +183,21 @@ def analyze_eye_status_live(
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for eye status "
+            'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Initialize webcam
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
         raise RuntimeError("Failed to access webcam")
 
     # Initialize face mesh detector for video
-    face_mesh = mp_face_mesh.FaceMesh(
+    face_mesh = mp.solutions.face_mesh.FaceMesh(
         max_num_faces=1,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,

ImagePRO/human_analysis/face_analysis/face_comparison.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -13,11 +14,13 @@ import os
 
 import cv2
 import numpy as np
-from insightface.app import FaceAnalysis
 
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
+if TYPE_CHECKING:  # insightface is imported lazily inside the function
+    from insightface.app import FaceAnalysis
+
 # Constants
 DEFAULT_SIMILARITY_THRESHOLD = 0.5
 DEFAULT_MODEL_NAME = "buffalo_l"
@@ -62,6 +65,15 @@ def compare_faces(
     if not isinstance(image_2, Image):
         raise TypeError("'image_2' must be an Image instance")
 
+    try:
+        from insightface.app import FaceAnalysis
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'insightface' dependency is required for face "
+            'comparison. Install it with: pip install '
+            '"ImagePRO-Python[insightface]"'
+        ) from err
+
     # Initialize model if needed
     if app is None:
         app = FaceAnalysis(
@@ -85,8 +97,8 @@ def compare_faces(
 
     try:
         # Save images to disk if needed
-        path_1 = save_temp_image(image_1._data, 'tmp1.jpg')
-        path_2 = save_temp_image(image_2._data, 'tmp2.jpg')
+        path_1 = save_temp_image(image_1, 'tmp1.jpg')
+        path_2 = save_temp_image(image_2, 'tmp2.jpg')
 
         # Load and preprocess images
         img1 = load_rgb_image(path_1)

ImagePRO/human_analysis/face_analysis/face_detection.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -10,13 +11,15 @@ if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
 import cv2
-import mediapipe as mp
 import numpy as np
 
 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
 
+if TYPE_CHECKING:  # mediapipe is imported lazily inside analyze_face_mesh
+    import mediapipe as mp
+
 
 # Constants
 DEFAULT_MAX_FACES = 1
@@ -29,7 +32,7 @@ FACE_OUTLINE_INDICES = [
 
 
 def detect_faces(
-    image: Image, 
+    image: Image,
     *,
     max_faces: int = DEFAULT_MAX_FACES,
     min_confidence: float = DEFAULT_MIN_CONFIDENCE,

ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -13,12 +14,11 @@ from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
 import cv2
-import mediapipe as mp
+
+if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
+    import mediapipe as mp
 
 # Constants
-mp_face_mesh = mp.solutions.face_mesh
-mp_drawing_utils = mp.solutions.drawing_utils
-mp_drawing_styles = mp.solutions.drawing_styles
 DEFAULT_MAX_FACES = 1
 DEFAULT_MIN_CONFIDENCE = 0.7
 TOTAL_FACE_LANDMARKS = 468
@@ -71,7 +71,6 @@ def analyze_face_mesh(
         - Coordinates are normalized [0,1]. Multiply by width/height for pixels
         - Full mesh (468 points) shows tessellation, specific points show dots
     """
-
     # Validate inputs
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
@@ -83,11 +82,23 @@ def analyze_face_mesh(
         raise ValueError("'min_confidence' must be between 0 and 1")
 
     if landmarks_idx is not None and (
-        not isinstance(landmarks_idx, list) 
+        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")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for face mesh "
+            'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
+    mp_face_mesh = mp.solutions.face_mesh
+    mp_drawing_utils = mp.solutions.drawing_utils
+    mp_drawing_styles = mp.solutions.drawing_styles
+
     # Initialize detector if needed
     if face_mesh_obj is None:
         face_mesh = mp_face_mesh.FaceMesh(
@@ -99,11 +110,8 @@ def analyze_face_mesh(
     else:
         face_mesh = face_mesh_obj
 
-    # Prepare image
-    img_copy = image._data.copy()
-    img_rgb = cv2.cvtColor(img_copy, cv2.COLOR_BGR2RGB)
-    
-    # Detect facial landmarks
+    # Detect facial landmarks (cvtColor allocates a new RGB array)
+    img_rgb = cv2.cvtColor(image._data, cv2.COLOR_BGR2RGB)
     results = face_mesh.process(img_rgb)
 
     # Handle no detections
@@ -121,11 +129,14 @@ def analyze_face_mesh(
             }
         )
 
+    # Allocate the annotation canvas only when a face was found
+    img_copy = image._data.copy()
+
     # 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 landmarks
         if len(landmarks_idx) == TOTAL_FACE_LANDMARKS:
@@ -146,11 +157,10 @@ def analyze_face_mesh(
                 cv2.circle(img_copy, (cx, cy), 3, (0, 0, 255), -1)
 
         # Extract coordinates
-        face_data = [
-            [face_id, idx, lm.x, lm.y, lm.z]
-            for idx in landmarks_idx
-            for lm in [face_landmarks.landmark[idx]]
-        ]
+        face_data = []
+        for idx in landmarks_idx:
+            lm = face_landmarks.landmark[idx]
+            face_data.append([face_id, idx, lm.x, lm.y, lm.z])
         landmarks.append(face_data)
 
     return Result(
@@ -196,13 +206,21 @@ def analyze_face_mesh_live(
     if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 1")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for face mesh "
+            'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Initialize camera
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 
     # Initialize detector in tracking mode for better performance
-    face_mesh = mp_face_mesh.FaceMesh(
+    face_mesh = mp.solutions.face_mesh.FaceMesh(
         max_num_faces=max_faces,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,

ImagePRO/human_analysis/face_analysis/head_pose_estimation.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -14,10 +15,11 @@ from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
 import cv2
-import mediapipe as mp
+
+if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
+    import mediapipe as mp
 
 # Constants
-mp_face_mesh = mp.solutions.face_mesh
 DEFAULT_MAX_FACES = 1
 DEFAULT_MIN_CONFIDENCE = 0.7
 HEAD_POSE_INDICES = [1, 152, 33, 263, 168]  # nose_tip, chin, left_eye, right_eye, nasion
@@ -97,7 +99,7 @@ def estimate_head_pose(
     for face in landmarks:
         # Map landmarks by index
         points = {lm[1]: lm for lm in face}
-        
+
         try:
             # Extract key points
             nose_x, nose_y = points[1][2:4]      # Nose tip
@@ -169,13 +171,21 @@ def estimate_head_pose_live(
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for head pose "
+            'estimation. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Initialize webcam
     cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
     if not cap.isOpened():
         raise RuntimeError("Failed to access webcam")
 
     # Initialize face mesh detector for video
-    face_mesh = mp_face_mesh.FaceMesh(
+    face_mesh = mp.solutions.face_mesh.FaceMesh(
         max_num_faces=max_faces,
         min_detection_confidence=min_confidence,
         refine_landmarks=True,

ImagePRO/object_analysis/__init__.py

@@ -1,5 +1,8 @@
 # Object Analysis Module
 # Provides object detection capabilities using YOLO models
+#
+# The ultralytics dependency is optional and imported lazily inside the
+# functions that need it, so this package imports cleanly without it.
 
 from . import object_detection
 

ImagePRO/object_analysis/object_detection.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 # Add src directory to path for absolute imports
 _file_path = Path(__file__).resolve()
@@ -9,17 +10,17 @@ _src_path = _file_path.parents[2]  # Go up to src directory
 if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
-from ultralytics import YOLO
-
 from ImagePRO.utils.image import Image
 from ImagePRO.utils.result import Result
 
+if TYPE_CHECKING:  # ultralytics is imported lazily inside the function
+    from ultralytics import YOLO
+
 # Constants
 DEFAULT_ACCURACY_LEVEL = 1
-DEFAULT_CONFIDENCE = 0.5
 MODEL_MAPPING = {
     1: "yolo11n.pt",
-    2: "yolo11s.pt", 
+    2: "yolo11s.pt",
     3: "yolo11m.pt",
     4: "yolo11l.pt",
     5: "yolo11x.pt"
@@ -56,6 +57,7 @@ def detect_objects(
         Result object with detections and metadata:
         - image: Original with bounding boxes drawn
         - data: List of [class_id, [x1,y1,x2,y2], confidence]
+          with box coordinates normalized to [0, 1]
         - meta: Operation info and model used
 
     Raises:
@@ -65,20 +67,29 @@ def detect_objects(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
+    # accuracy_level only applies when no model is given
+    if model is None and accuracy_level not in MODEL_MAPPING:
+        raise ValueError(
+            f"'accuracy_level' must be in {list(MODEL_MAPPING.keys())}, "
+            f"got {accuracy_level}"
+        )
+
+    try:
+        from ultralytics import YOLO
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'ultralytics' dependency is required for object "
+            'detection. Install it with: pip install "ImagePRO-Python[yolo]"'
+        ) from err
+
     # Initialize model
     model_name = None
     if model is None:
-        if accuracy_level not in MODEL_MAPPING:
-            raise ValueError(
-                f"'accuracy_level' must be in {list(MODEL_MAPPING.keys())}, "
-                f"got {accuracy_level}"
-            )
-        
         model_name = MODEL_MAPPING[accuracy_level]
         model = YOLO(model=model_name)
 
-    # Run inference
-    result = model(image._data.copy())[0]
+    # Run inference (ultralytics does not mutate the input array)
+    result = model(image._data)[0]
     boxes = result.boxes
 
     # Process detections
@@ -92,7 +103,7 @@ def detect_objects(
     # Show visualization if requested
     if show_result:
         result.show()
-    
+
     return Result(
         image=result.plot(),
         data=detections,

ImagePRO/pre_processing/__init__.py

@@ -1,5 +1,8 @@
 # Pre-processing Module
 # Provides image manipulation, filtering, and enhancement capabilities
+#
+# dataset_generator uses the optional mediapipe dependency, imported
+# lazily inside its functions, so it is safe to import here regardless.
 
 from . import blur
 from . import contrast
@@ -12,7 +15,7 @@ from . import sharpen
 
 __all__ = [
     "blur",
-    "contrast", 
+    "contrast",
     "crop",
     "dataset_generator",
     "grayscale",