ImagePRO-Python 1.3.1__tar.gz → 1.5.0__tar.gz

{imagepro_python-1.3.1/src/ImagePRO_Python.egg-info → imagepro_python-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.3.1
+Version: 1.5.0
 Summary: Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration.
 Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
 License: MIT
@@ -76,6 +76,11 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 - **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
 - **Flexible Models**: Pre-trained or custom model support
 
+### **Pipelines**
+- **Reusable Operation Chains**: Define a sequence of functions once, then run it on any input (Image, NumPy array, or file path)
+- **Flexible Steps**: Any ImagePRO function or custom callable; per-step keyword arguments via `Step`
+- **Pipeline Metadata**: Every result lists the executed steps and each step's parameters
+
 ## Installation
 
 ### From PyPI
@@ -154,6 +159,22 @@ object_detection_result = detect_objects(
 )
 print(f"Detected {len(object_detection_result.data)} objects")
 object_detection_result.save_as_img("detections.jpg")
+
+# Chain operations into a reusable pipeline
+from ImagePRO.pipeline import Pipeline, Step
+from ImagePRO.pre_processing.grayscale import convert_to_grayscale
+from ImagePRO.pre_processing.resize import resize_image
+
+pipeline = Pipeline([
+    Step(apply_gaussian_blur, kernel_size=(7, 7)),
+    convert_to_grayscale,
+    Step(resize_image, new_size=(800, 600)),
+])
+
+# Run it on any input: an Image, a NumPy array, or a file path
+pipeline_result = pipeline.run("person_and_objects.jpg")
+pipeline_result.save_as_img("processed_output.jpg")
+print(pipeline_result.meta["steps"])  # Executed step names
 ```
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
@@ -167,6 +188,7 @@ Each module includes comprehensive documentation with detailed examples:
   - [Face Analysis](src/ImagePRO/human_analysis/face_analysis/README.md): Face mesh, pose estimation, eye status, comparison
   - [Body Analysis](src/ImagePRO/human_analysis/body_analysis/README.md): Body pose and hand tracking
 - **[Object Analysis](src/ImagePRO/object_analysis/README.md)**: YOLO-based object detection
+- **[Pipeline](src/ImagePRO/pipeline/README.md)**: Reusable chains of image processing operations
 - **[Utils](src/ImagePRO/utils/README.md)**: Shared utilities and I/O handling
 
 For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
@@ -178,13 +200,14 @@ ImagePRO is built with a modular architecture designed for extensibility and mai
 - **Clean Separation of Concerns**: Each module handles a specific domain
 - **Consistent API Patterns**: All functions follow the same input/output conventions
 - **Shared Utilities**: Common `Image` and `Result` classes for unified I/O
+- **Reusable Pipelines**: Chain any operations into a `Pipeline` and run it on any input
 - **Lazy Optional Imports**: Heavy AI dependencies (MediaPipe, Ultralytics, InsightFace) are only imported inside the functions that use them, keeping `import ImagePRO` fast and independent of installed extras
 - **Professional Error Handling**: Comprehensive validation with clear error messages
 - **Type Safety**: Full type hints throughout the codebase
 - **Documentation**: Google-style docstrings for all functions
 
 ### Key Design Principles
-- **Non-Destructive Operations**: Operations never write into the input image; they return results in new `Result` objects (note: `crop_image` returns a view into the source array)
+- **Non-Destructive Operations**: Operations never write into the input image; they return results in new `Result` objects
 - **Functional Style**: Stateless functions that can be easily composed
 - **Result Objects**: Unified return type containing image, data, and metadata
 - **Keyword Arguments**: All optional parameters use keyword-only syntax

{imagepro_python-1.3.1 → imagepro_python-1.5.0}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ImagePRO-Python"
-version = "1.3.1"
+version = "1.5.0"
 description = "Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration."
 readme = "readme.md"
 requires-python = ">=3.9,<3.13"

{imagepro_python-1.3.1 → imagepro_python-1.5.0}/readme.md

@@ -27,6 +27,11 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 - **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
 - **Flexible Models**: Pre-trained or custom model support
 
+### **Pipelines**
+- **Reusable Operation Chains**: Define a sequence of functions once, then run it on any input (Image, NumPy array, or file path)
+- **Flexible Steps**: Any ImagePRO function or custom callable; per-step keyword arguments via `Step`
+- **Pipeline Metadata**: Every result lists the executed steps and each step's parameters
+
 ## Installation
 
 ### From PyPI
@@ -105,6 +110,22 @@ object_detection_result = detect_objects(
 )
 print(f"Detected {len(object_detection_result.data)} objects")
 object_detection_result.save_as_img("detections.jpg")
+
+# Chain operations into a reusable pipeline
+from ImagePRO.pipeline import Pipeline, Step
+from ImagePRO.pre_processing.grayscale import convert_to_grayscale
+from ImagePRO.pre_processing.resize import resize_image
+
+pipeline = Pipeline([
+    Step(apply_gaussian_blur, kernel_size=(7, 7)),
+    convert_to_grayscale,
+    Step(resize_image, new_size=(800, 600)),
+])
+
+# Run it on any input: an Image, a NumPy array, or a file path
+pipeline_result = pipeline.run("person_and_objects.jpg")
+pipeline_result.save_as_img("processed_output.jpg")
+print(pipeline_result.meta["steps"])  # Executed step names
 ```
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
@@ -118,6 +139,7 @@ Each module includes comprehensive documentation with detailed examples:
   - [Face Analysis](src/ImagePRO/human_analysis/face_analysis/README.md): Face mesh, pose estimation, eye status, comparison
   - [Body Analysis](src/ImagePRO/human_analysis/body_analysis/README.md): Body pose and hand tracking
 - **[Object Analysis](src/ImagePRO/object_analysis/README.md)**: YOLO-based object detection
+- **[Pipeline](src/ImagePRO/pipeline/README.md)**: Reusable chains of image processing operations
 - **[Utils](src/ImagePRO/utils/README.md)**: Shared utilities and I/O handling
 
 For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
@@ -129,13 +151,14 @@ ImagePRO is built with a modular architecture designed for extensibility and mai
 - **Clean Separation of Concerns**: Each module handles a specific domain
 - **Consistent API Patterns**: All functions follow the same input/output conventions
 - **Shared Utilities**: Common `Image` and `Result` classes for unified I/O
+- **Reusable Pipelines**: Chain any operations into a `Pipeline` and run it on any input
 - **Lazy Optional Imports**: Heavy AI dependencies (MediaPipe, Ultralytics, InsightFace) are only imported inside the functions that use them, keeping `import ImagePRO` fast and independent of installed extras
 - **Professional Error Handling**: Comprehensive validation with clear error messages
 - **Type Safety**: Full type hints throughout the codebase
 - **Documentation**: Google-style docstrings for all functions
 
 ### Key Design Principles
-- **Non-Destructive Operations**: Operations never write into the input image; they return results in new `Result` objects (note: `crop_image` returns a view into the source array)
+- **Non-Destructive Operations**: Operations never write into the input image; they return results in new `Result` objects
 - **Functional Style**: Stateless functions that can be easily composed
 - **Result Objects**: Unified return type containing image, data, and metadata
 - **Keyword Arguments**: All optional parameters use keyword-only syntax

{imagepro_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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_python-1.3.1 → imagepro_python-1.5.0}/src/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")