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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.2.2
+Version: 1.3.1
 Summary: Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration.
 Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
 License: MIT
@@ -32,14 +32,19 @@ Provides-Extra: yolo
 Requires-Dist: ultralytics<9.0,>=8.2; extra == "yolo"
 Provides-Extra: mediapipe
 Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "mediapipe"
+Requires-Dist: numpy<2.0,>=1.24; extra == "mediapipe"
 Provides-Extra: insightface
 Requires-Dist: insightface<0.8,>=0.7; extra == "insightface"
 Requires-Dist: onnxruntime<2.0,>=1.16; extra == "insightface"
+Requires-Dist: numpy<2.0,>=1.24; extra == "insightface"
 Provides-Extra: full
 Requires-Dist: mediapipe<=0.10.11,>=0.10.0; extra == "full"
 Requires-Dist: ultralytics<9.0,>=8.2; extra == "full"
 Requires-Dist: insightface<0.8,>=0.7; extra == "full"
 Requires-Dist: onnxruntime<2.0,>=1.16; extra == "full"
+Requires-Dist: numpy<2.0,>=1.24; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
 Dynamic: license-file
 
 # ImagePRO
@@ -50,11 +55,10 @@ Dynamic: license-file
 
 Whether you're working on computer vision pipelines, preprocessing images for AI models, or simply automating batch image edits — **ImagePRO** gives you powerful tools with minimal effort.
 
-## ✨ Features
+## Features
 
 ### **Image I/O & Management**
 - Flexible input/output handling (file paths or numpy arrays)
-- Batch processing capabilities
 - Multiple format support (JPEG, PNG, CSV, etc.)
 
 ### **Pre-processing & Enhancement**
@@ -71,15 +75,23 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 ### **Object Detection**
 - **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
 - **Flexible Models**: Pre-trained or custom model support
-- **Batch Processing**: Efficient handling of multiple images
 
-## 🚀 Installation
+## Installation
 
 ### From PyPI
 ```bash
 pip install ImagePRO-Python
+
+# Or with optional extras:
+pip install "ImagePRO-Python[yolo]"         # YOLO object detection
+pip install "ImagePRO-Python[mediapipe]"    # MediaPipe human analysis
+pip install "ImagePRO-Python[insightface]"  # InsightFace face comparison
+pip install "ImagePRO-Python[full]"         # Everything
+pip install "ImagePRO-Python[dev]"          # Test tooling (pytest)
 ```
 
+> **Note**: The base install is lightweight — AI backends (MediaPipe, Ultralytics, InsightFace) are optional and imported lazily, only when you call a function that actually needs them. `import ImagePRO` never loads these dependencies. If a backend is missing, the function you call raises an `ImportError` telling you exactly which extra to install.
+
 ### From Source
 ```bash
 git clone https://github.com/parsasafaie/ImagePRO.git
@@ -109,7 +121,7 @@ pip install -r requirements/full.txt
 
 See the [Directory Structure](/PROJECT_STRUCTURE.md#directory-structure) section in [PROJECT_STRUCTURE.md](/PROJECT_STRUCTURE.md) for details on which modules need which requirements.
 
-## 📖 Quick Start
+## Quick Start
 
 ```python
 from ImagePRO.pre_processing.blur import apply_average_blur
@@ -126,9 +138,9 @@ image = Image.from_path("person_and_objects.jpg")
 blur_result = apply_average_blur(image=image)
 blur_result.save_as_img("blurred_output.jpg")
 
-# Analyze face mesh (468 landmarks)
+# Analyze face mesh (468 landmarks per detected face)
 face_mesh_result = analyze_face_mesh(image=image)
-print(f"Detected {len(face_mesh_result.data)} face landmarks")
+print(f"Detected {len(face_mesh_result.data)} face(s)")
 face_mesh_result.save_as_csv("face_landmarks.csv")
 
 # Detect body pose (33 landmarks)
@@ -138,8 +150,7 @@ print(f"Body pose data: {body_pose_result.data}")
 # Detect objects with YOLO
 object_detection_result = detect_objects(
     image=image,
-    accuracy_level=3,  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
-    confidence=0.5
+    accuracy_level=3  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
 )
 print(f"Detected {len(object_detection_result.data)} objects")
 object_detection_result.save_as_img("detections.jpg")
@@ -147,7 +158,7 @@ object_detection_result.save_as_img("detections.jpg")
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
 
-## 📚 Documentation
+## Documentation
 
 Each module includes comprehensive documentation with detailed examples:
 
@@ -160,24 +171,40 @@ Each module includes comprehensive documentation with detailed examples:
 
 For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
 
-## 🏗️ Architecture
+## Architecture
 
 ImagePRO is built with a modular architecture designed for extensibility and maintainability:
 
 - **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
+- **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
-- **Immutable Design**: Image objects are immutable, operations return new instances
+- **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)
 - **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
 
-## 🤝 Contributing
+## Testing
+
+The test suite uses pytest:
+
+```bash
+# Install with test tooling (editable install + dev extra)
+pip install -e ".[dev]"
+
+# Run the suite (optional heavy dependencies are mocked; base deps are enough)
+pytest
+
+# Include performance smoke guards
+pytest --run-performance
+```
+
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
@@ -185,9 +212,10 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 1. Fork the repository
 2. Create a virtual environment: `python -m venv .venv`
 3. Install dependencies: `pip install -r requirements/full.txt`
-4. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
-5. Add tests for new features
-6. Update documentation as needed
+4. Install for development with test tooling: `pip install -e ".[dev]"`
+5. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
+6. Add tests for new features and run `pytest`
+7. Update documentation as needed
 
 ### Reporting Issues
 If you encounter any bugs or have feature requests, please open an issue on the GitHub repository with:
@@ -196,5 +224,5 @@ If you encounter any bugs or have feature requests, please open an issue on the
 - Expected vs. actual behavior
 - Environment details (OS, Python version, etc.)
 
-## 📄 License 
+## License
 This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.

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

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ImagePRO-Python"
-version = "1.2.2"
+version = "1.3.1"
 description = "Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration."
 readme = "readme.md"
 requires-python = ">=3.9,<3.13"
@@ -54,20 +54,37 @@ yolo = [
     "ultralytics>=8.2,<9.0"
 ]
 
+# mediapipe<=0.10.11 and insightface 0.7.x ship binaries built against
+# the NumPy 1.x ABI, so groups that include them cap numpy below 2.0.
 mediapipe = [
-    "mediapipe>=0.10.0,<=0.10.11"
+    "mediapipe>=0.10.0,<=0.10.11",
+    "numpy>=1.24,<2.0"
 ]
 
 insightface = [
     "insightface>=0.7,<0.8",
-    "onnxruntime>=1.16,<2.0"
+    "onnxruntime>=1.16,<2.0",
+    "numpy>=1.24,<2.0"
 ]
 
 full = [
     "mediapipe>=0.10.0,<=0.10.11",
     "ultralytics>=8.2,<9.0",
     "insightface>=0.7,<0.8",
-    "onnxruntime>=1.16,<2.0"
+    "onnxruntime>=1.16,<2.0",
+    "numpy>=1.24,<2.0"
+]
+
+dev = [
+    "pytest>=8.0,<9.0"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra"
+markers = [
+    "perf: performance smoke tests (run with --run-performance)"
 ]
 
 [project.urls]
@@ -75,6 +92,3 @@ Homepage = "https://github.com/parsasafaie/ImagePRO"
 Repository = "https://github.com/parsasafaie/ImagePRO.git"
 Documentation = "https://github.com/parsasafaie/ImagePRO#readme"
 Issues = "https://github.com/parsasafaie/ImagePRO/issues"
-
-[tool.hatch.build.targets.wheel]
-packages = ["ImagePRO"]

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

@@ -6,11 +6,10 @@
 
 Whether you're working on computer vision pipelines, preprocessing images for AI models, or simply automating batch image edits — **ImagePRO** gives you powerful tools with minimal effort.
 
-## ✨ Features
+## Features
 
 ### **Image I/O & Management**
 - Flexible input/output handling (file paths or numpy arrays)
-- Batch processing capabilities
 - Multiple format support (JPEG, PNG, CSV, etc.)
 
 ### **Pre-processing & Enhancement**
@@ -27,15 +26,23 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 ### **Object Detection**
 - **YOLO Integration**: Multiple accuracy levels (nano to extra-large)
 - **Flexible Models**: Pre-trained or custom model support
-- **Batch Processing**: Efficient handling of multiple images
 
-## 🚀 Installation
+## Installation
 
 ### From PyPI
 ```bash
 pip install ImagePRO-Python
+
+# Or with optional extras:
+pip install "ImagePRO-Python[yolo]"         # YOLO object detection
+pip install "ImagePRO-Python[mediapipe]"    # MediaPipe human analysis
+pip install "ImagePRO-Python[insightface]"  # InsightFace face comparison
+pip install "ImagePRO-Python[full]"         # Everything
+pip install "ImagePRO-Python[dev]"          # Test tooling (pytest)
 ```
 
+> **Note**: The base install is lightweight — AI backends (MediaPipe, Ultralytics, InsightFace) are optional and imported lazily, only when you call a function that actually needs them. `import ImagePRO` never loads these dependencies. If a backend is missing, the function you call raises an `ImportError` telling you exactly which extra to install.
+
 ### From Source
 ```bash
 git clone https://github.com/parsasafaie/ImagePRO.git
@@ -65,7 +72,7 @@ pip install -r requirements/full.txt
 
 See the [Directory Structure](/PROJECT_STRUCTURE.md#directory-structure) section in [PROJECT_STRUCTURE.md](/PROJECT_STRUCTURE.md) for details on which modules need which requirements.
 
-## 📖 Quick Start
+## Quick Start
 
 ```python
 from ImagePRO.pre_processing.blur import apply_average_blur
@@ -82,9 +89,9 @@ image = Image.from_path("person_and_objects.jpg")
 blur_result = apply_average_blur(image=image)
 blur_result.save_as_img("blurred_output.jpg")
 
-# Analyze face mesh (468 landmarks)
+# Analyze face mesh (468 landmarks per detected face)
 face_mesh_result = analyze_face_mesh(image=image)
-print(f"Detected {len(face_mesh_result.data)} face landmarks")
+print(f"Detected {len(face_mesh_result.data)} face(s)")
 face_mesh_result.save_as_csv("face_landmarks.csv")
 
 # Detect body pose (33 landmarks)
@@ -94,8 +101,7 @@ print(f"Body pose data: {body_pose_result.data}")
 # Detect objects with YOLO
 object_detection_result = detect_objects(
     image=image,
-    accuracy_level=3,  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
-    confidence=0.5
+    accuracy_level=3  # 1=nano, 2=small, 3=medium, 4=large, 5=extra-large
 )
 print(f"Detected {len(object_detection_result.data)} objects")
 object_detection_result.save_as_img("detections.jpg")
@@ -103,7 +109,7 @@ object_detection_result.save_as_img("detections.jpg")
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
 
-## 📚 Documentation
+## Documentation
 
 Each module includes comprehensive documentation with detailed examples:
 
@@ -116,24 +122,40 @@ Each module includes comprehensive documentation with detailed examples:
 
 For detailed project structure and development guidelines, see [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
 
-## 🏗️ Architecture
+## Architecture
 
 ImagePRO is built with a modular architecture designed for extensibility and maintainability:
 
 - **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
+- **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
-- **Immutable Design**: Image objects are immutable, operations return new instances
+- **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)
 - **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
 
-## 🤝 Contributing
+## Testing
+
+The test suite uses pytest:
+
+```bash
+# Install with test tooling (editable install + dev extra)
+pip install -e ".[dev]"
+
+# Run the suite (optional heavy dependencies are mocked; base deps are enough)
+pytest
+
+# Include performance smoke guards
+pytest --run-performance
+```
+
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
@@ -141,9 +163,10 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 1. Fork the repository
 2. Create a virtual environment: `python -m venv .venv`
 3. Install dependencies: `pip install -r requirements/full.txt`
-4. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
-5. Add tests for new features
-6. Update documentation as needed
+4. Install for development with test tooling: `pip install -e ".[dev]"`
+5. Follow the coding standards outlined in [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md)
+6. Add tests for new features and run `pytest`
+7. Update documentation as needed
 
 ### Reporting Issues
 If you encounter any bugs or have feature requests, please open an issue on the GitHub repository with:
@@ -152,5 +175,5 @@ If you encounter any bugs or have feature requests, please open an issue on the
 - Expected vs. actual behavior
 - Environment details (OS, Python version, etc.)
 
-## 📄 License 
+## License
 This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.

{imagepro_python-1.2.2 → imagepro_python-1.3.1}/src/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_python-1.2.2 → imagepro_python-1.3.1}/src/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_python-1.2.2 → imagepro_python-1.3.1}/src/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_python-1.2.2 → imagepro_python-1.3.1}/src/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_python-1.2.2 → imagepro_python-1.3.1}/src/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_python-1.2.2 → imagepro_python-1.3.1}/src/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,