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

ImagePRO/__init__.py

@@ -12,10 +12,11 @@ Features:
 - Pre-processing: resize, crop, rotate, blur, sharpen, contrast enhancement
 - Human analysis: face mesh, pose estimation, hand tracking
 - Object detection with YOLO models
+- Reusable pipelines for chaining operations
 - Real-time processing capabilities
 """
 
-__version__ = "1.3.1"
+__version__ = "1.5.0"
 __author__ = "Parsa Safaie"
 __email__ = "parsasafaie.2568@proton.me"
 
@@ -24,10 +25,12 @@ from . import utils
 from . import pre_processing
 from . import human_analysis
 from . import object_analysis
+from . import pipeline
 
 __all__ = [
     "utils",
     "pre_processing",
     "human_analysis",
-    "object_analysis"
+    "object_analysis",
+    "pipeline"
 ]

ImagePRO/human_analysis/body_analysis/body_pose_estimation.py

@@ -23,6 +23,11 @@ TOTAL_LANDMARKS = 33
 DEFAULT_CONFIDENCE = 0.7
 LANDMARK_RADIUS = 3
 LANDMARK_COLOR = (0, 0, 255)  # Red color for landmarks
+# Backend-agnostic capture: the DSHOW backend only exists on Windows, so
+# the default leaves the choice to OpenCV. Tests inject a fake through
+# this hook.
+DEFAULT_CAMERA_BACKEND = None
+
 
 def detect_body_pose(
     image: Image,
@@ -62,12 +67,13 @@ def detect_body_pose(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
+    if isinstance(min_confidence, bool) or 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")
 
     if landmarks_idx is not None and (
         not isinstance(landmarks_idx, list)
-        or not all(isinstance(i, int) for i in landmarks_idx)
+        or not all(isinstance(i, int) and not isinstance(i, bool) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
 
@@ -153,8 +159,8 @@ def detect_body_pose_live() -> None:
             'detection. Install it with: pip install "ImagePRO-Python[mediapipe]"'
         ) from err
 
-    # Initialize camera
-    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
+    # Initialize camera (backend-agnostic; see DEFAULT_CAMERA_BACKEND)
+    cap = cv2.VideoCapture(0, DEFAULT_CAMERA_BACKEND)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 

ImagePRO/human_analysis/body_analysis/hand_tracking.py

@@ -24,6 +24,10 @@ DEFAULT_MIN_CONFIDENCE = 0.7
 TOTAL_HAND_LANDMARKS = 21
 LANDMARK_RADIUS = 3
 LANDMARK_COLOR = (0, 0, 255)  # Red color for landmarks
+# Backend-agnostic capture: the DSHOW backend only exists on Windows, so
+# the default leaves the choice to OpenCV. Tests inject a fake through
+# this hook.
+DEFAULT_CAMERA_BACKEND = None
 
 
 def detect_hands(
@@ -69,15 +73,16 @@ def detect_hands(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(max_hands, int) or max_hands <= 0:
+    if not isinstance(max_hands, int) or isinstance(max_hands, bool) or max_hands <= 0:
         raise ValueError("'max_hands' must be positive")
 
-    if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
+    if isinstance(min_confidence, bool) or 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")
 
     if landmarks_idx is not None and (
         not isinstance(landmarks_idx, list)
-        or not all(isinstance(i, int) for i in landmarks_idx)
+        or not all(isinstance(i, int) and not isinstance(i, bool) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
 
@@ -174,10 +179,11 @@ def detect_hands_live(
         RuntimeError: If camera cannot be accessed
     """
     # Validate parameters
-    if not isinstance(max_hands, int) or max_hands <= 0:
+    if not isinstance(max_hands, int) or isinstance(max_hands, bool) or max_hands <= 0:
         raise ValueError("'max_hands' must be positive")
 
-    if not isinstance(min_confidence, (int, float)) or not (0.0 <= min_confidence <= 1.0):
+    if isinstance(min_confidence, bool) or 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:
@@ -188,8 +194,8 @@ def detect_hands_live(
             'tracking. Install it with: pip install "ImagePRO-Python[mediapipe]"'
         ) from err
 
-    # Initialize camera
-    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
+    # Initialize camera (backend-agnostic; see DEFAULT_CAMERA_BACKEND)
+    cap = cv2.VideoCapture(0, DEFAULT_CAMERA_BACKEND)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 

ImagePRO/human_analysis/face_analysis/eye_status_analysis.py

@@ -23,6 +23,10 @@ if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
 DEFAULT_MIN_CONFIDENCE = 0.7
 DEFAULT_THRESHOLD = 0.2
 RIGHT_EYE_INDICES = [386, 374, 263, 362]  # MediaPipe right eye landmarks
+# Backend-agnostic capture: the DSHOW backend only exists on Windows, so
+# the default leaves the choice to OpenCV. Tests inject a fake through
+# this hook.
+DEFAULT_CAMERA_BACKEND = None
 
 
 def analyze_eye_status(
@@ -62,7 +66,7 @@ def analyze_eye_status(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(min_confidence, (int, float)):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)):
         raise TypeError("'min_confidence' must be a number")
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
@@ -178,7 +182,7 @@ def analyze_eye_status_live(
         RuntimeError: If webcam cannot be accessed
     """
     # Validate inputs
-    if not isinstance(min_confidence, (int, float)):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)):
         raise TypeError("'min_confidence' must be a number")
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
@@ -191,8 +195,8 @@ def analyze_eye_status_live(
             'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
         ) from err
 
-    # Initialize webcam
-    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
+    # Initialize webcam (backend-agnostic; see DEFAULT_CAMERA_BACKEND)
+    cap = cv2.VideoCapture(0, DEFAULT_CAMERA_BACKEND)
     if not cap.isOpened():
         raise RuntimeError("Failed to access webcam")
 
@@ -221,7 +225,8 @@ def analyze_eye_status_live(
                     face_mesh_obj=face_mesh,
                     threshold=threshold
                 )
-                status = "Open" if result.data else "Closed"
+                status = "No face" if result.data is None else \
+                    ("Open" if result.data else "Closed")
             except (TypeError, ValueError):
                 status = "No face"
 

ImagePRO/human_analysis/face_analysis/face_comparison.py

@@ -10,8 +10,6 @@ _src_path = _file_path.parents[3]  # Go up to src directory
 if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
-import os
-
 import cv2
 import numpy as np
 
@@ -36,7 +34,9 @@ def compare_faces(
     """Compare two face images to determine if they are the same person.
 
     Uses InsightFace's FaceAnalysis model to extract facial embeddings
-    and compares them using cosine similarity.
+    and compares them using cosine similarity. Arrays are passed to the
+    model in memory; only path-based images are read from disk, so no
+    temporary files are written.
 
     Args:
         image_1: First image to compare.
@@ -57,7 +57,7 @@ def compare_faces(
 
     Raises:
         TypeError: If either image is not an Image instance
-        FileNotFoundError: If image data cannot be loaded
+        FileNotFoundError: If a path-based image cannot be loaded
     """
     # Validate inputs
     if not isinstance(image_1, Image):
@@ -82,69 +82,62 @@ def compare_faces(
         )
         app.prepare(ctx_id=0)  # Use CPU
 
-    def save_temp_image(image: Image, temp_name: str) -> str:
-        """Save image data to temporary file if needed."""
+    def load_rgb_image(image: Image) -> np.ndarray:
+        """Return the image as an RGB array, via disk only if required."""
         if image.source_type == 'path':
-            return image.path
-        temp_path = os.path.join(os.getcwd(), temp_name)
-        cv2.imwrite(temp_path, image._data)
-        return temp_path
-
-    def load_rgb_image(path: str) -> np.ndarray | None:
-        """Load image file and convert to RGB."""
-        img = cv2.imread(str(path))
-        return cv2.cvtColor(img, cv2.COLOR_BGR2RGB) if img is not None else None
-
-    try:
-        # Save images to disk if needed
-        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)
-        img2 = load_rgb_image(path_2)
-
-        if img1 is None or img2 is None:
-            raise FileNotFoundError("Failed to load one or both images")
-
-        # Detect faces
-        faces1 = app.get(img1)
-        faces2 = app.get(img2)
-
-        # Validate detections
-        if not faces1 or not faces2:
-            return Result(
-                image=None,
-                data=None,
-                meta={
-                    "source": (image_1, image_2),
-                    "operation": "compare_faces",
-                    "error": "No face detected in one or both images"
-                }
-            )
-
-        # Extract embeddings
-        emb1 = faces1[0].embedding
-        emb2 = faces2[0].embedding
-
-        # Calculate similarity
-        similarity = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))
-        is_match = similarity > DEFAULT_SIMILARITY_THRESHOLD
-
+            # honor the declared colorspace when reading from disk
+            img = cv2.imread(str(image.path))
+            if img is None:
+                raise FileNotFoundError(f"Failed to load image from {image.path}")
+            if image.colorspace == "RGB":
+                return img
+            if image.colorspace == "GRAY":
+                return cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+            return cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+
+        # InsightFace accepts in-memory arrays; no temp file is written.
+        if image.colorspace == "RGB":
+            return image._data
+        if image.colorspace == "GRAY":
+            return cv2.cvtColor(image._data, cv2.COLOR_GRAY2RGB)
+        return cv2.cvtColor(image._data, cv2.COLOR_BGR2RGB)
+
+    img1 = load_rgb_image(image_1)
+    img2 = load_rgb_image(image_2)
+
+    # Detect faces
+    faces1 = app.get(img1)
+    faces2 = app.get(img2)
+
+    # Validate detections
+    if not faces1 or not faces2:
         return Result(
             image=None,
-            data=is_match,
+            data=None,
             meta={
                 "source": (image_1, image_2),
                 "operation": "compare_faces",
-                "similarity": float(similarity),
-                "threshold": DEFAULT_SIMILARITY_THRESHOLD
+                "error": "No face detected in one or both images"
             }
         )
 
-    finally:
-        # Cleanup temporary files
-        if image_1.source_type != 'path' and os.path.exists('tmp1.jpg'):
-            os.remove('tmp1.jpg')
-        if image_2.source_type != 'path' and os.path.exists('tmp2.jpg'):
-            os.remove('tmp2.jpg')
+    # Extract embeddings
+    emb1 = faces1[0].embedding
+    emb2 = faces2[0].embedding
+
+    # Calculate similarity
+    similarity = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))
+    # Cast to a plain bool: np.dot yields np.bool_, which fails `is True`
+    # checks and serializes oddly in CSV/JSON output.
+    is_match = bool(similarity > DEFAULT_SIMILARITY_THRESHOLD)
+
+    return Result(
+        image=None,
+        data=is_match,
+        meta={
+            "source": (image_1, image_2),
+            "operation": "compare_faces",
+            "similarity": float(similarity),
+            "threshold": DEFAULT_SIMILARITY_THRESHOLD
+        }
+    )

ImagePRO/human_analysis/face_analysis/face_detection.py

@@ -72,10 +72,11 @@ def detect_faces(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(max_faces, int) or max_faces <= 0:
+    if not isinstance(max_faces, int) or isinstance(max_faces, bool) or max_faces <= 0:
         raise ValueError("'max_faces' must be positive")
 
-    if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)) \
+            or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 1")
 
     # Get image dimensions

ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py

@@ -22,6 +22,10 @@ if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
 DEFAULT_MAX_FACES = 1
 DEFAULT_MIN_CONFIDENCE = 0.7
 TOTAL_FACE_LANDMARKS = 468
+# Backend-agnostic capture: the DSHOW backend only exists on Windows, so
+# the default leaves the choice to OpenCV. Tests inject a fake through
+# this hook.
+DEFAULT_CAMERA_BACKEND = None
 
 
 def analyze_face_mesh(
@@ -38,7 +42,7 @@ def analyze_face_mesh(
     Can focus on specific landmarks or detect full 468-point mesh.
 
     Args:
-        image: Input image to process.
+        image: Input image to process (BGR, RGB, or grayscale).
         max_faces: Maximum number of faces to detect.
             Must be positive.
             Default: 1
@@ -75,15 +79,16 @@ def analyze_face_mesh(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(max_faces, int) or max_faces <= 0:
+    if not isinstance(max_faces, int) or isinstance(max_faces, bool) or max_faces <= 0:
         raise ValueError("'max_faces' must be positive")
 
-    if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)) \
+            or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 1")
 
     if landmarks_idx is not None and (
         not isinstance(landmarks_idx, list)
-        or not all(isinstance(i, int) for i in landmarks_idx)
+        or not all(isinstance(i, int) and not isinstance(i, bool) for i in landmarks_idx)
     ):
         raise TypeError("'landmarks_idx' must be a list of integers")
 
@@ -110,9 +115,14 @@ def analyze_face_mesh(
     else:
         face_mesh = face_mesh_obj
 
-    # Detect facial landmarks (cvtColor allocates a new RGB array)
-    img_rgb = cv2.cvtColor(image._data, cv2.COLOR_BGR2RGB)
-    results = face_mesh.process(img_rgb)
+    # MediaPipe expects RGB; grayscale input needs channels added back.
+    if image.colorspace == "GRAY":
+        model_input = cv2.cvtColor(image._data, cv2.COLOR_GRAY2RGB)
+    elif image.colorspace == "RGB":
+        model_input = image._data
+    else:  # BGR is the default
+        model_input = cv2.cvtColor(image._data, cv2.COLOR_BGR2RGB)
+    results = face_mesh.process(model_input)
 
     # Handle no detections
     if not results.multi_face_landmarks:
@@ -214,8 +224,9 @@ def analyze_face_mesh_live(
             'analysis. Install it with: pip install "ImagePRO-Python[mediapipe]"'
         ) from err
 
-    # Initialize camera
-    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
+    # Initialize camera (backend-agnostic; DEFAULT_CAMERA_BACKEND is a
+    # module-level hook tests can monkeypatch)
+    cap = cv2.VideoCapture(0, DEFAULT_CAMERA_BACKEND)
     if not cap.isOpened():
         raise RuntimeError("Cannot access webcam")
 

ImagePRO/human_analysis/face_analysis/head_pose_estimation.py

@@ -23,6 +23,10 @@ if TYPE_CHECKING:  # mediapipe is imported lazily inside the functions
 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
+# Backend-agnostic capture: the DSHOW backend only exists on Windows, so
+# the default leaves the choice to OpenCV. Tests inject a fake through
+# this hook.
+DEFAULT_CAMERA_BACKEND = None
 
 
 def estimate_head_pose(
@@ -37,6 +41,12 @@ def estimate_head_pose(
     Calculates approximate yaw and pitch angles based on relative
     positions of key facial landmarks (nose, eyes, chin).
 
+    The values are unscaled proportional scores, not degrees: each is the
+    normalized landmark asymmetry multiplied by an arbitrary constant of
+    100. They are useful for thresholds and trends (e.g. detecting when a
+    face turns away), not for measuring absolute angles. Mirror-image
+    webcam feeds flip the sign of yaw.
+
     Args:
         image: Input image to process.
         max_faces: Maximum number of faces to analyze.
@@ -55,6 +65,7 @@ def estimate_head_pose(
             None if no faces detected
         - meta: Operation info and parameters
             Includes error info if detection fails
+        - image: None
 
     Raises:
         TypeError: If image is not an Image instance
@@ -64,10 +75,11 @@ def estimate_head_pose(
     if not isinstance(image, Image):
         raise TypeError("'image' must be an Image instance")
 
-    if not isinstance(max_faces, int) or max_faces <= 0:
+    if not isinstance(max_faces, int) or isinstance(max_faces, bool) or max_faces <= 0:
         raise ValueError("'max_faces' must be positive")
 
-    if not isinstance(min_confidence, (int, float)) or not (0 <= min_confidence <= 1):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)) \
+            or not (0 <= min_confidence <= 1):
         raise ValueError("'min_confidence' must be between 0 and 1")
 
     # Get face landmarks
@@ -120,7 +132,8 @@ def estimate_head_pose(
                 }
             )
 
-        # Calculate angles
+        # Calculate angles. The ×100 constant is arbitrary; the values are
+        # proportional scores for thresholding, not degrees.
         yaw = 100 * ((right_x - nasion_x) - (nasion_x - left_x))    # Horizontal rotation
         pitch = 100 * ((chin_y - nose_y) - (nose_y - nasion_y))     # Vertical rotation
         pose_data.append([face[0][0], yaw, pitch])
@@ -162,11 +175,11 @@ def estimate_head_pose_live(
         RuntimeError: If webcam cannot be accessed
     """
     # Validate inputs
-    if not isinstance(max_faces, int):
+    if not isinstance(max_faces, int) or isinstance(max_faces, bool):
         raise TypeError("'max_faces' must be an integer")
     if max_faces <= 0:
         raise ValueError("'max_faces' must be positive")
-    if not isinstance(min_confidence, (int, float)):
+    if isinstance(min_confidence, bool) or not isinstance(min_confidence, (int, float)):
         raise TypeError("'min_confidence' must be a number")
     if not 0 <= min_confidence <= 1:
         raise ValueError("'min_confidence' must be between 0 and 1")
@@ -179,8 +192,8 @@ def estimate_head_pose_live(
             'estimation. Install it with: pip install "ImagePRO-Python[mediapipe]"'
         ) from err
 
-    # Initialize webcam
-    cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
+    # Initialize webcam (backend-agnostic; see DEFAULT_CAMERA_BACKEND)
+    cap = cv2.VideoCapture(0, DEFAULT_CAMERA_BACKEND)
     if not cap.isOpened():
         raise RuntimeError("Failed to access webcam")
 

ImagePRO/object_analysis/object_detection.py

@@ -18,6 +18,7 @@ if TYPE_CHECKING:  # ultralytics is imported lazily inside the function
 
 # Constants
 DEFAULT_ACCURACY_LEVEL = 1
+DEFAULT_DEVICE = "cpu"  # CUDA builds fail on older GPUs (sm_50 and lower)
 MODEL_MAPPING = {
     1: "yolo11n.pt",
     2: "yolo11s.pt",
@@ -32,7 +33,8 @@ def detect_objects(
     *,
     model: YOLO | None = None,
     accuracy_level: int = DEFAULT_ACCURACY_LEVEL,
-    show_result: bool = False
+    show_result: bool = False,
+    device: str = DEFAULT_DEVICE
 ) -> Result:
     """Detect objects in an image using YOLO models.
 
@@ -52,6 +54,12 @@ def detect_objects(
             Default: 1
         show_result: Show detection visualization window.
             Default: False
+        device: Torch device for inference ("cpu", "cuda", "0", ...).
+            Defaults to "cpu" because CUDA wheels no longer support older
+            GPUs (compute capability below 5.0 is unsupported by cu12/cu13
+            builds) and fail with cudaErrorNoKernelImageForDevice; pass
+            "cuda" explicitly to use the GPU.
+            Default: "cpu"
 
     Returns:
         Result object with detections and metadata:
@@ -89,7 +97,7 @@ def detect_objects(
         model = YOLO(model=model_name)
 
     # Run inference (ultralytics does not mutate the input array)
-    result = model(image._data)[0]
+    result = model(image._data, device=device)[0]
     boxes = result.boxes
 
     # Process detections
@@ -110,6 +118,7 @@ def detect_objects(
         meta={
             "source": image,
             "operation": "detect_objects",
-            "model": model_name or "custom"
+            "model": model_name or "custom",
+            "device": device
         }
     )

ImagePRO/pipeline/__init__.py

@@ -0,0 +1,9 @@
+# Pipeline Module
+# Provides a reusable, ordered chain of image processing operations
+#
+# Uses only base dependencies (numpy); all operations handed to a Pipeline
+# may come from any module, including those with optional backends.
+
+from .pipeline import Pipeline, Step
+
+__all__ = ["Pipeline", "Step"]