ImagePRO-Python 1.3.0__py3-none-any.whl → 1.4.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.0"
+__version__ = "1.4.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/__init__.py

@@ -1,17 +1,11 @@
 # Body Analysis Module
 # Provides body pose estimation and hand tracking capabilities
 #
-# Both modules need the optional mediapipe dependency; they are imported
-# guardedly so the package stays importable without it.
+# 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.
 
-try:  # requires mediapipe
-    from . import body_pose_estimation
-except ImportError:
-    body_pose_estimation = None
-
-try:  # requires mediapipe
-    from . import hand_tracking
-except ImportError:
-    hand_tracking = None
+from . import body_pose_estimation
+from . import hand_tracking
 
 __all__ = ["body_pose_estimation", "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
@@ -69,6 +71,16 @@ def detect_body_pose(
     ):
         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(
@@ -133,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
@@ -79,6 +81,16 @@ def detect_hands(
     ):
         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(
@@ -168,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,34 +1,15 @@
 # Face Analysis Module
 # Provides facial landmark detection, pose estimation, and eye status analysis
 #
-# The mediapipe-based modules and the insightface-based module are imported
-# guardedly so that importing the package works with only the dependencies
-# a caller actually needs; unavailable modules are set to None.
+# 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.
 
-try:  # requires mediapipe
-    from . import eye_status_analysis
-except ImportError:
-    eye_status_analysis = None
-
-try:  # requires insightface
-    from . import face_comparison
-except ImportError:
-    face_comparison = None
-
-try:  # requires mediapipe
-    from . import face_detection
-except ImportError:
-    face_detection = None
-
-try:  # requires mediapipe
-    from . import face_mesh_analysis
-except ImportError:
-    face_mesh_analysis = None
-
-try:  # requires mediapipe
-    from . import head_pose_estimation
-except ImportError:
-    head_pose_estimation = None
+from . import eye_status_analysis
+from . import face_comparison
+from . import face_detection
+from . import face_mesh_analysis
+from . import head_pose_estimation
 
 __all__ = [
     "eye_status_analysis",

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(

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

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")
@@ -88,6 +87,18 @@ def analyze_face_mesh(
     ):
         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(
@@ -195,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
@@ -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,9 +1,9 @@
 # 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.
 
-try:  # object_detection needs the optional ultralytics dependency
-    from . import object_detection
-except ImportError:
-    object_detection = None
+from . import object_detection
 
 __all__ = ["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,11 +10,12 @@ _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
 MODEL_MAPPING = {
@@ -65,15 +67,24 @@ 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)
 

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"]

ImagePRO/pipeline/pipeline.py

@@ -0,0 +1,362 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Callable, Iterator
+
+# Add src directory to path for absolute imports
+_file_path = Path(__file__).resolve()
+_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))
+
+import numpy as np
+
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
+
+
+class Step:
+    """
+    A single operation in a Pipeline, with optional keyword arguments.
+
+    Wraps any callable that accepts an Image as its first positional argument
+    and returns a Result (or a numpy.ndarray, treated as the output image).
+    Keyword arguments given to the constructor are forwarded to the wrapped
+    function on every call, so a Step fully describes one stage of a pipeline.
+
+    Example:
+        >>> from ImagePRO.pre_processing.blur import apply_gaussian_blur
+        >>> step = Step(apply_gaussian_blur, kernel_size=(7, 7))
+        >>> result = step(image)  # Same as apply_gaussian_blur(image, kernel_size=(7, 7))
+
+    Attributes:
+        function (Callable):
+            The wrapped function to execute.
+        kwargs (dict[str, Any]):
+            Keyword-only arguments forwarded to the function on each call.
+    """
+
+    def __init__(self, function: Callable[..., Result], **kwargs: Any) -> None:
+        """
+        Create a Step from a function and its keyword arguments.
+
+        Args:
+            function (Callable):
+                Function to wrap. Must be callable and accept an Image as its
+                first positional argument.
+            **kwargs (Any):
+                Keyword-only arguments forwarded to the function on every call.
+
+        Raises:
+            TypeError: If function is not callable.
+        """
+        if not callable(function):
+            raise TypeError("'function' must be a callable.")
+        self.function = function
+        self.kwargs: dict[str, Any] = dict(kwargs)
+
+    @property
+    def name(self) -> str:
+        """
+        Human-readable name of the wrapped function, used in pipeline metadata.
+
+        Returns:
+            str: The function's __name__ when available, otherwise the name
+            of its type (e.g. 'partial' for functools.partial objects).
+        """
+        return getattr(self.function, "__name__", type(self.function).__name__)
+
+    def __call__(self, image: Image) -> Result:
+        """
+        Execute the wrapped function on an image.
+
+        Args:
+            image (Image):
+                Input image passed to the wrapped function.
+
+        Returns:
+            Result: Whatever the wrapped function returns.
+
+        Raises:
+            TypeError: If image is not an Image instance (raised by the
+                wrapped function's own validation).
+            ValueError: If wrapped function arguments are invalid (raised by
+                the wrapped function's own validation).
+        """
+        return self.function(image, **self.kwargs)
+
+    def __repr__(self) -> str:
+        """
+        Return a readable representation of the step.
+
+        Returns:
+            str: Representation including the function name and arguments.
+        """
+        args = ", ".join(f"{key}={value!r}" for key, value in self.kwargs.items())
+        return f"Step({self.name}{', ' + args if args else ''})"
+
+
+class Pipeline:
+    """
+    A reusable, ordered chain of image processing operations.
+
+    A Pipeline is defined once from a sequence of functions and can then be
+    run on any input as many times as needed. Each operation receives an
+    Image and its output image is automatically wrapped and fed to the next
+    operation; the final Result is returned with pipeline metadata attached.
+
+    Operations are the standard ImagePRO functions (which take an Image and
+    return a Result) or any custom callable following the same convention.
+    A custom function may also return a plain numpy.ndarray, which is treated
+    as the output image. Per-operation keyword arguments are configured with
+    Step, or fluently via apply().
+
+    Pipelines are immutable: apply() returns a new Pipeline and leaves the
+    original untouched, and run() never mutates the pipeline, so a single
+    Pipeline instance is safe to reuse across many inputs.
+
+    Example:
+        >>> from ImagePRO.pre_processing.blur import apply_gaussian_blur
+        >>> 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)),
+        ... ])
+        >>> result = pipeline.run("photo.jpg")   # Any Image, ndarray or path
+        >>> result.save_as_img("processed.jpg")
+    """
+
+    def __init__(self, *operations: Any) -> None:
+        """
+        Create a Pipeline from one or more operations.
+
+        Operations can be passed as separate arguments or as a single
+        list/tuple. Passing another Pipeline as an operation nests it: the
+        inner pipeline runs as a single step.
+
+        Args:
+            *operations (Callable | Step | list | tuple):
+                Functions to execute in order. Each element must be callable;
+                Step instances carry their keyword arguments. A single
+                list/tuple of operations is also accepted.
+
+        Raises:
+            TypeError: If any operation is not callable.
+        """
+        if len(operations) == 1 and isinstance(operations[0], (list, tuple)):
+            operations = tuple(operations[0])
+
+        steps: list[Step] = []
+        for operation in operations:
+            if not callable(operation):
+                raise TypeError(
+                    "All pipeline operations must be callable; got "
+                    f"{type(operation).__name__}. Wrap keyword arguments with "
+                    "Step, e.g. Step(resize_image, new_size=(800, 600))."
+                )
+            steps.append(operation if isinstance(operation, Step) else Step(operation))
+        self._operations = steps
+
+    @property
+    def operations(self) -> tuple[Step, ...]:
+        """
+        The ordered steps of this pipeline.
+
+        Returns:
+            tuple[Step, ...]: Step objects in execution order.
+        """
+        return tuple(self._operations)
+
+    def apply(self, function: Callable[..., Result], **kwargs: Any) -> Pipeline:
+        """
+        Return a new Pipeline with one more operation appended.
+
+        The current pipeline is not modified, following ImagePRO's
+        non-destructive design principle.
+
+        Args:
+            function (Callable):
+                Function to append. Must be callable and accept an Image as
+                its first positional argument.
+            **kwargs (Any):
+                Keyword-only arguments forwarded to the function on every run.
+
+        Returns:
+            Pipeline: New pipeline containing all existing steps plus this one.
+
+        Raises:
+            TypeError: If function is not callable.
+
+        Example:
+            >>> pipeline = Pipeline(apply_gaussian_blur).apply(
+            ...     resize_image, new_size=(800, 600)
+            ... )
+        """
+        return Pipeline(*self._operations, Step(function, **kwargs))
+
+    def run(self, image: Image | np.ndarray | str | Path) -> Result:
+        """
+        Execute all pipeline operations in order on the given input.
+
+        The input is first normalized to an Image (file paths are loaded and
+        NumPy arrays are wrapped, assuming BGR for 3-channel and GRAY for 2D
+        arrays). Each operation then receives an Image built from the previous
+        operation's output; 2D intermediates are tagged as GRAY and
+        multi-channel ones keep the incoming colorspace.
+
+        The returned Result carries the final operation's image and data. Its
+        metadata contains the pipeline information (operation, steps,
+        step_meta, source) merged over the final operation's own metadata.
+
+        Args:
+            image (Image | np.ndarray | str | Path):
+                Input to process. Can be an Image instance, a NumPy array
+                (BGR for 3-channel, GRAY for 2D), or a path to an image file.
+
+        Returns:
+            Result: Result object of the final operation.
+                - image (np.ndarray | list[np.ndarray] | None): Final output image(s)
+                - data (Any): Structured data of the final operation
+                - meta (dict): Final operation metadata plus pipeline info:
+                  'operation' ("pipeline"), 'steps' (list of step names),
+                  'step_meta' (per-step metadata list), 'source' (input Image)
+
+        Raises:
+            TypeError: If image is not an Image, ndarray, or path.
+            TypeError: If an operation returns an unsupported type.
+            ValueError: If the pipeline has no operations.
+            ValueError: If a non-final operation returns no image, so the
+                chain cannot continue.
+            TypeError/ValueError: As raised by the operations themselves for
+                invalid inputs or arguments.
+        """
+        # Normalize input to an Image (cheap validation before any step runs)
+        if isinstance(image, Image):
+            current = image
+        elif isinstance(image, np.ndarray):
+            colorspace = "GRAY" if image.ndim == 2 else "BGR"
+            current = Image.from_array(image, colorspace=colorspace)
+        elif isinstance(image, (str, Path)):
+            current = Image.from_path(image)
+        else:
+            raise TypeError(
+                "'image' must be an Image instance, a numpy.ndarray, or a "
+                "file path (str or pathlib.Path)."
+            )
+
+        if not self._operations:
+            raise ValueError(
+                "Cannot run an empty pipeline. Add operations at construction "
+                "or with apply()."
+            )
+
+        source = current
+        step_names: list[str] = []
+        step_metas: list[dict[str, Any]] = []
+        final_image: Any = None
+        final_data: Any = None
+        final_meta: dict[str, Any] = {}
+
+        for index, step in enumerate(self._operations):
+            is_last = index == len(self._operations) - 1
+            output = step(current)
+
+            # Normalize the step output (Result is the convention; a plain
+            # ndarray from custom functions is accepted as the output image)
+            if isinstance(output, Result):
+                final_image = output.image
+                final_data = output.data
+                final_meta = dict(output.meta)
+            elif isinstance(output, np.ndarray):
+                final_image = output
+                final_data = None
+                final_meta = {}
+            else:
+                raise TypeError(
+                    f"Step {index} ('{step.name}') returned "
+                    f"{type(output).__name__}; pipeline operations must "
+                    "return a Result object or a numpy.ndarray."
+                )
+
+            step_names.append(step.name)
+            step_metas.append(final_meta)
+
+            if is_last:
+                break
+
+            # Prepare the input of the next operation
+            if final_image is None:
+                raise ValueError(
+                    f"Step {index} ('{step.name}') returned no image, so the "
+                    "pipeline cannot continue. Only the final step of a "
+                    "pipeline may return a result without an image."
+                )
+            if not isinstance(final_image, np.ndarray):
+                raise ValueError(
+                    f"Step {index} ('{step.name}') did not return a single "
+                    "image array, so the pipeline cannot continue. Only the "
+                    "final step of a pipeline may return multi-image results."
+                )
+
+            colorspace = "GRAY" if final_image.ndim == 2 else current.colorspace
+            current = Image.from_array(final_image, colorspace=colorspace)
+
+        meta = dict(final_meta)
+        meta.update({
+            "source": source,
+            "operation": "pipeline",
+            "steps": step_names,
+            "step_meta": step_metas,
+        })
+        return Result(image=final_image, data=final_data, meta=meta)
+
+    def __call__(self, image: Image | np.ndarray | str | Path) -> Result:
+        """
+        Run the pipeline on an input; shorthand for run().
+
+        Args:
+            image (Image | np.ndarray | str | Path):
+                Input to process, as accepted by run().
+
+        Returns:
+            Result: Result object of the final operation.
+
+        Raises:
+            TypeError: If image is not an Image, ndarray, or path.
+            ValueError: If the pipeline has no operations or a non-final
+                operation returns no image.
+        """
+        return self.run(image)
+
+    def __len__(self) -> int:
+        """
+        Return the number of operations in the pipeline.
+
+        Returns:
+            int: Number of steps.
+        """
+        return len(self._operations)
+
+    def __iter__(self) -> Iterator[Step]:
+        """
+        Iterate over the pipeline's steps in execution order.
+
+        Returns:
+            Iterator[Step]: Iterator of Step objects.
+        """
+        return iter(self._operations)
+
+    def __repr__(self) -> str:
+        """
+        Return a readable representation of the pipeline.
+
+        Returns:
+            str: Representation listing the step names in order.
+        """
+        if not self._operations:
+            return "Pipeline(<empty>)"
+        return f"Pipeline({' -> '.join(step.name for step in self._operations)})"

ImagePRO/pre_processing/__init__.py

@@ -1,19 +1,18 @@
 # 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
 from . import crop
+from . import dataset_generator
 from . import grayscale
 from . import resize
 from . import rotate
 from . import sharpen
 
-try:  # dataset_generator needs the optional mediapipe dependency
-    from . import dataset_generator
-except ImportError:
-    dataset_generator = None
-
 __all__ = [
     "blur",
     "contrast",

ImagePRO/pre_processing/dataset_generator.py

@@ -12,7 +12,6 @@ if str(_src_path) not in sys.path:
     sys.path.insert(0, str(_src_path))
 
 import cv2
-import mediapipe as mp
 
 from ImagePRO.human_analysis.face_analysis.face_detection import detect_faces
 from ImagePRO.pre_processing import blur, grayscale, resize, rotate, sharpen
@@ -95,6 +94,14 @@ def capture_bulk_pictures(
     if not isinstance(delay, (int, float)) or delay < 0:
         raise ValueError("'delay' must be a non-negative number")
 
+    try:
+        import mediapipe as mp
+    except ImportError as err:
+        raise ImportError(
+            "The optional 'mediapipe' dependency is required for dataset "
+            'generation. Install it with: pip install "ImagePRO-Python[mediapipe]"'
+        ) from err
+
     # Setup output directory structure
     base_dir = Path(folder_path)
     face_folder = base_dir / str(face_id)

{imagepro_python-1.3.0.dist-info → imagepro_python-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.3.0
+Version: 1.4.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
@@ -90,6 +95,8 @@ 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
@@ -152,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.
@@ -165,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).
@@ -176,6 +200,8 @@ 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

imagepro_python-1.4.0.dist-info/RECORD

@@ -0,0 +1,33 @@
+ImagePRO/__init__.py,sha256=3B8cQH4zhV6EEAvVMKYMsJHok_hpGLTgu4QfP33DV08,1081
+ImagePRO/human_analysis/__init__.py,sha256=uSU0lM1p1HM6TNGv6u0nPHWy9QY505v43lqTkhClddM,190
+ImagePRO/human_analysis/body_analysis/__init__.py,sha256=uUWG5eOxLQjZoYddmNkRlF66l6vSVyJpUFz1wDddXkk,374
+ImagePRO/human_analysis/body_analysis/body_pose_estimation.py,sha256=yqEV18ZEZwV__Oqt1Hi72EGmbTNes-mrY068SBT9RbU,6245
+ImagePRO/human_analysis/body_analysis/hand_tracking.py,sha256=SpdIZNgvaHzINpWu7rgNawSHvuuawzFtQ7JiHHQ0fqA,7578
+ImagePRO/human_analysis/face_analysis/__init__.py,sha256=297IQuoO2Wb_PyigS_2NOuVnM7FpNPceu5jhJp6YdG0,604
+ImagePRO/human_analysis/face_analysis/eye_status_analysis.py,sha256=Q_EUNPpXoF7Vi-Kd0gURNxs9X3U5J4Yi3coL_6lkeb8,7773
+ImagePRO/human_analysis/face_analysis/face_comparison.py,sha256=lIr490PAf8R6C_Zhv-zBN1Un1EPiwxi4W7ahgkqXAVc,4724
+ImagePRO/human_analysis/face_analysis/face_detection.py,sha256=F3Bq_0rAcQklmNAu-JvxGBIxUnWmyM-SHuZawHXJeac,4009
+ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py,sha256=rv08Mx_IBB-hjTh09bFaaPjaOm0tFbBs0brc4mE66mg,8723
+ImagePRO/human_analysis/face_analysis/head_pose_estimation.py,sha256=2_ZVpwavyIzCIH4x3d2bvCPvv-X5gpmSYxtk5jlgCYw,7688
+ImagePRO/object_analysis/__init__.py,sha256=eVQpYlHO89RYKT0CHjPfJjjif5X_Jx3AtAUpR5m0Yms,292
+ImagePRO/object_analysis/object_detection.py,sha256=1qPd3Xfo2Vi4JnBs5wD8-k3WR6ZkYNdT9tco2Ze1ICQ,3385
+ImagePRO/pipeline/__init__.py,sha256=-32hbR492qwxutXau7EfnysXbhW8fKKMywkV0ejIMFE,301
+ImagePRO/pipeline/pipeline.py,sha256=-CRWfWXB_lFdjrqg3gdyYFFvq0vZAednrJnod6b4WYA,13802
+ImagePRO/pre_processing/__init__.py,sha256=pw6-J5sdbkdBG4RlTxOzQKaspGnlPIGo3m_NXH2bVCE,559
+ImagePRO/pre_processing/blur.py,sha256=3zNTNpvLZPdrtRtBziB6X8ys8M7cIvyPDhojTqR63jo,7950
+ImagePRO/pre_processing/contrast.py,sha256=4UT78ggW1rh_iaEI8FObDB4kpEmRRFWjdJES60SnHDM,5064
+ImagePRO/pre_processing/crop.py,sha256=3Nwerzo57kx1sZPr9m355P-qf1NuZSZEA5iUn2Q1704,2406
+ImagePRO/pre_processing/dataset_generator.py,sha256=i7UM4o8hznFUfUgbYI6H01EkQJOqt4IsI9IrjzzN8gQ,7921
+ImagePRO/pre_processing/grayscale.py,sha256=MRCsFRIaL45sYVHzhuNyZBXsP7PF-yorn0Wt7xONvpY,1781
+ImagePRO/pre_processing/histogram.py,sha256=sNTWWZXr5VLpOrF_PTTJ6TD8yv1zR1l9cMyXHe7JFIM,2596
+ImagePRO/pre_processing/resize.py,sha256=Rnde8l_PXck5OWQBEMOHgLeW2YkTz9Xfr6fGmz0sdm8,1760
+ImagePRO/pre_processing/rotate.py,sha256=wQj3nQpN-ilM0HHwovN--UdGEJkPCY0BJ0zAdyBxv-o,4174
+ImagePRO/pre_processing/sharpen.py,sha256=hOkY7QhzgMp9LXQwt56AP4enn24ntXlmFLe57Bxssvw,3682
+ImagePRO/utils/__init__.py,sha256=McVd-o9KtKOpAVYbLi19KxsatPPFFF-Qbt0gdgY3Ln8,170
+ImagePRO/utils/image.py,sha256=Y64mD97rTiJb8_uNYlyG227VZodeb4U1aGezMkj7MnM,4025
+ImagePRO/utils/result.py,sha256=ToQaOmUlTtobJkC65BG0YO_6BkBleMBn-0Qydko7cZc,6138
+imagepro_python-1.4.0.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
+imagepro_python-1.4.0.dist-info/METADATA,sha256=POgVUYD-3fKBCKxkjSgKTZqCt5BWjvtfDBqlrn7Qg9I,11121
+imagepro_python-1.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+imagepro_python-1.4.0.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
+imagepro_python-1.4.0.dist-info/RECORD,,

imagepro_python-1.3.0.dist-info/RECORD

@@ -1,31 +0,0 @@
-ImagePRO/__init__.py,sha256=yY-6-5p9OyeNlmPnYMeht-2yJJun8DJvH7yi0b-tMOE,997
-ImagePRO/human_analysis/__init__.py,sha256=uSU0lM1p1HM6TNGv6u0nPHWy9QY505v43lqTkhClddM,190
-ImagePRO/human_analysis/body_analysis/__init__.py,sha256=ezFnUJNwQXW47n9Bfxcmk4BNgvt_Bqs3Y5VESxgz2Sg,494
-ImagePRO/human_analysis/body_analysis/body_pose_estimation.py,sha256=QkqF27YOHYoOVq5KMz0AaU455CQcRVfTbFStPZGYUA8,5565
-ImagePRO/human_analysis/body_analysis/hand_tracking.py,sha256=fYOQGu5mcrYgqtWu5wW0xApx76fOXGDxz3hZRUhvW9k,6910
-ImagePRO/human_analysis/face_analysis/__init__.py,sha256=nABUIg9Z-yL6JfAxMb2fqwfxmSfJmvSxfwnQuKSIOGg,1028
-ImagePRO/human_analysis/face_analysis/eye_status_analysis.py,sha256=9ydxEj4EhVCNf954gdFBQemS1uRNA-XGCMzyliI2AsQ,7126
-ImagePRO/human_analysis/face_analysis/face_comparison.py,sha256=vHYqWTuXEadoeZn-z81ZazXlpBri702Gz37XdWPJirw,4303
-ImagePRO/human_analysis/face_analysis/face_detection.py,sha256=9LFMotGJ0KlAUb5yTfrXaAH_Ztr3OO3vbXLhXTN8M9M,3896
-ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py,sha256=TBSZELe_CdXcXDRRiaAYkDqHHpktRhi_koC-2iwk2Gk,8038
-ImagePRO/human_analysis/face_analysis/head_pose_estimation.py,sha256=CovQITnmLNiLlEWffuL0idAJNBOC_nnZlC-4G9pFXxs,7328
-ImagePRO/object_analysis/__init__.py,sha256=KcFRxVKnC0qU82zS31P4CriZIKqZdyGqQwdrMy9N4pc,267
-ImagePRO/object_analysis/object_detection.py,sha256=REfu73vNSvUIbIzel24jygyCumZKvYr7_d6YyLDhdwY,2943
-ImagePRO/pre_processing/__init__.py,sha256=d10ZfQzWM0JRJrFrMHOr-mxF4XYnObj6GYPTLaqzqDA,536
-ImagePRO/pre_processing/blur.py,sha256=3zNTNpvLZPdrtRtBziB6X8ys8M7cIvyPDhojTqR63jo,7950
-ImagePRO/pre_processing/contrast.py,sha256=4UT78ggW1rh_iaEI8FObDB4kpEmRRFWjdJES60SnHDM,5064
-ImagePRO/pre_processing/crop.py,sha256=3Nwerzo57kx1sZPr9m355P-qf1NuZSZEA5iUn2Q1704,2406
-ImagePRO/pre_processing/dataset_generator.py,sha256=7sL9uI_i272eOO1U_XFAaAoo7pfnU5ryuRuLERilzgo,7667
-ImagePRO/pre_processing/grayscale.py,sha256=MRCsFRIaL45sYVHzhuNyZBXsP7PF-yorn0Wt7xONvpY,1781
-ImagePRO/pre_processing/histogram.py,sha256=sNTWWZXr5VLpOrF_PTTJ6TD8yv1zR1l9cMyXHe7JFIM,2596
-ImagePRO/pre_processing/resize.py,sha256=Rnde8l_PXck5OWQBEMOHgLeW2YkTz9Xfr6fGmz0sdm8,1760
-ImagePRO/pre_processing/rotate.py,sha256=wQj3nQpN-ilM0HHwovN--UdGEJkPCY0BJ0zAdyBxv-o,4174
-ImagePRO/pre_processing/sharpen.py,sha256=hOkY7QhzgMp9LXQwt56AP4enn24ntXlmFLe57Bxssvw,3682
-ImagePRO/utils/__init__.py,sha256=McVd-o9KtKOpAVYbLi19KxsatPPFFF-Qbt0gdgY3Ln8,170
-ImagePRO/utils/image.py,sha256=Y64mD97rTiJb8_uNYlyG227VZodeb4U1aGezMkj7MnM,4025
-ImagePRO/utils/result.py,sha256=ToQaOmUlTtobJkC65BG0YO_6BkBleMBn-0Qydko7cZc,6138
-imagepro_python-1.3.0.dist-info/licenses/LICENSE,sha256=sehkHN7dbe5umrINZJyJjIf9VTemZSgTfJlq6iIsbJQ,1069
-imagepro_python-1.3.0.dist-info/METADATA,sha256=8Rl5PyW1UcO7Zc_nZuzHCYtU7u-lUbhY8d-J2qR6B1A,9435
-imagepro_python-1.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-imagepro_python-1.3.0.dist-info/top_level.txt,sha256=UOuPzsoWrVKXgUupOSI96shJ6wE8Fhz-8bm8oMlLC3s,9
-imagepro_python-1.3.0.dist-info/RECORD,,