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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.3.1
+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
@@ -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,6 +200,7 @@ 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

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

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ImagePRO-Python"
-version = "1.3.1"
+version = "1.4.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.4.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,6 +151,7 @@ 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

{imagepro_python-1.3.1 → imagepro_python-1.4.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.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_python-1.4.0/src/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_python-1.4.0/src/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_python-1.3.1 → imagepro_python-1.4.0/src/ImagePRO_Python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.3.1
+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
@@ -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,6 +200,7 @@ 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

{imagepro_python-1.3.1 → imagepro_python-1.4.0}/src/ImagePRO_Python.egg-info/SOURCES.txt

@@ -14,6 +14,8 @@ src/ImagePRO/human_analysis/face_analysis/face_mesh_analysis.py
 src/ImagePRO/human_analysis/face_analysis/head_pose_estimation.py
 src/ImagePRO/object_analysis/__init__.py
 src/ImagePRO/object_analysis/object_detection.py
+src/ImagePRO/pipeline/__init__.py
+src/ImagePRO/pipeline/pipeline.py
 src/ImagePRO/pre_processing/__init__.py
 src/ImagePRO/pre_processing/blur.py
 src/ImagePRO/pre_processing/contrast.py
@@ -48,6 +50,7 @@ tests/test_histogram.py
 tests/test_image.py
 tests/test_integration.py
 tests/test_object_detection.py
+tests/test_pipeline.py
 tests/test_resize.py
 tests/test_result.py
 tests/test_rotate.py

imagepro_python-1.4.0/tests/test_pipeline.py

@@ -0,0 +1,357 @@
+"""Unit tests for ImagePRO.pipeline."""
+
+from __future__ import annotations
+
+from functools import partial
+
+import numpy as np
+import pytest
+
+from ImagePRO.pipeline import Pipeline, Step
+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
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
+
+
+@pytest.fixture
+def multiply_function():
+    """Custom operation following the Image -> Result convention."""
+
+    def function(image, *, scale=1):
+        output = image._data if scale == 1 else np.clip(image._data * scale, 0, 255).astype(np.uint8)
+        return Result(image=output, meta={"operation": "multiply", "scale": scale})
+
+    return function
+
+
+@pytest.fixture
+def colorspace_recorder():
+    """Custom operation recording the colorspace of every Image received."""
+    seen = []
+
+    def function(image):
+        seen.append(image.colorspace)
+        return Result(image=image._data)
+
+    function.seen = seen
+    return function
+
+
+class TestStep:
+    def test_forwards_kwargs_to_function(self, sample_bgr_image):
+        step = Step(apply_gaussian_blur, kernel_size=(9, 9))
+        result = step(sample_bgr_image)
+        assert result.meta["kernel_size"] == (9, 9)
+
+    def test_works_without_kwargs(self, sample_bgr_image):
+        step = Step(apply_gaussian_blur)
+        result = step(sample_bgr_image)
+        assert result.meta["kernel_size"] == (5, 5)
+
+    def test_name_property(self):
+        assert Step(apply_gaussian_blur).name == "apply_gaussian_blur"
+
+    def test_name_falls_back_to_type_name(self):
+        step = Step(partial(apply_gaussian_blur, kernel_size=(3, 3)))
+        assert step.name == "partial"
+
+    def test_non_callable_raises(self):
+        with pytest.raises(TypeError):
+            Step("not callable")
+
+    def test_repr_shows_name_and_kwargs(self):
+        step = Step(apply_gaussian_blur, kernel_size=(7, 7))
+        assert "apply_gaussian_blur" in repr(step)
+        assert "kernel_size=(7, 7)" in repr(step)
+
+
+class TestConstruction:
+    def test_from_list(self):
+        pipeline = Pipeline([apply_gaussian_blur, convert_to_grayscale])
+        assert len(pipeline) == 2
+
+    def test_from_tuple(self):
+        pipeline = Pipeline((apply_gaussian_blur, convert_to_grayscale))
+        assert len(pipeline) == 2
+
+    def test_from_varargs(self):
+        pipeline = Pipeline(apply_gaussian_blur, convert_to_grayscale)
+        assert len(pipeline) == 2
+
+    def test_from_single_callable(self):
+        pipeline = Pipeline(apply_gaussian_blur)
+        assert len(pipeline) == 1
+
+    def test_from_single_step(self):
+        pipeline = Pipeline(Step(apply_gaussian_blur, kernel_size=(7, 7)))
+        assert len(pipeline) == 1
+        assert pipeline.operations[0].kwargs == {"kernel_size": (7, 7)}
+
+    def test_mixed_callables_and_steps(self):
+        pipeline = Pipeline(
+            Step(apply_gaussian_blur, kernel_size=(3, 3)),
+            convert_to_grayscale,
+        )
+        assert len(pipeline) == 2
+        assert isinstance(pipeline.operations[0], Step)
+        assert isinstance(pipeline.operations[1], Step)
+
+    def test_empty_pipeline_is_allowed(self):
+        assert len(Pipeline()) == 0
+
+    def test_plain_callables_are_wrapped_in_steps(self):
+        pipeline = Pipeline(apply_gaussian_blur)
+        assert isinstance(pipeline.operations[0], Step)
+        assert pipeline.operations[0].function is apply_gaussian_blur
+
+    def test_operations_property_returns_tuple(self):
+        pipeline = Pipeline(apply_gaussian_blur, convert_to_grayscale)
+        assert isinstance(pipeline.operations, tuple)
+        assert [step.name for step in pipeline.operations] == [
+            "apply_gaussian_blur",
+            "convert_to_grayscale",
+        ]
+
+    @pytest.mark.parametrize("bad", [42, "blur", None, 3.14])
+    def test_non_callable_operation_raises(self, bad):
+        with pytest.raises(TypeError):
+            Pipeline(bad)
+
+    def test_non_callable_inside_list_raises(self):
+        with pytest.raises(TypeError):
+            Pipeline([apply_gaussian_blur, 42])
+
+
+class TestApply:
+    def test_returns_new_pipeline(self):
+        original = Pipeline(apply_gaussian_blur)
+        extended = original.apply(convert_to_grayscale)
+        assert extended is not original
+        assert len(original) == 1
+        assert len(extended) == 2
+
+    def test_is_chainable(self):
+        pipeline = (
+            Pipeline()
+            .apply(apply_gaussian_blur, kernel_size=(3, 3))
+            .apply(convert_to_grayscale)
+            .apply(resize_image, new_size=(16, 12))
+        )
+        assert len(pipeline) == 3
+        assert [step.name for step in pipeline] == [
+            "apply_gaussian_blur",
+            "convert_to_grayscale",
+            "resize_image",
+        ]
+
+    def test_forwards_kwargs(self, sample_bgr_image):
+        pipeline = Pipeline().apply(apply_gaussian_blur, kernel_size=(9, 9))
+        result = pipeline.run(sample_bgr_image)
+        assert result.meta["step_meta"][0]["kernel_size"] == (9, 9)
+
+    def test_non_callable_raises(self):
+        with pytest.raises(TypeError):
+            Pipeline().apply(42)
+
+
+class TestRun:
+    def test_single_step_returns_result(self, sample_bgr_image):
+        result = Pipeline(apply_gaussian_blur).run(sample_bgr_image)
+        assert isinstance(result, Result)
+        assert result.image.shape == sample_bgr_image.shape
+        assert result.image.dtype == np.uint8
+
+    def test_multi_step_matches_manual_application(self, sample_bgr_image):
+        pipeline = Pipeline([
+            apply_gaussian_blur,
+            convert_to_grayscale,
+            Step(resize_image, new_size=(16, 12)),
+        ])
+        result = pipeline.run(sample_bgr_image)
+
+        blurred = apply_gaussian_blur(image=sample_bgr_image).image
+        gray = convert_to_grayscale(
+            image=Image.from_array(blurred, colorspace="BGR")
+        ).image
+        resized = resize_image(
+            image=Image.from_array(gray, colorspace="GRAY"), new_size=(16, 12)
+        ).image
+        assert np.array_equal(result.image, resized)
+
+    def test_meta_contents(self, sample_bgr_image):
+        pipeline = Pipeline([
+            Step(apply_gaussian_blur, kernel_size=(7, 7)),
+            convert_to_grayscale,
+        ])
+        result = pipeline.run(sample_bgr_image)
+        assert result.meta["operation"] == "pipeline"
+        assert result.meta["steps"] == ["apply_gaussian_blur", "convert_to_grayscale"]
+        assert len(result.meta["step_meta"]) == 2
+        assert result.meta["step_meta"][0]["kernel_size"] == (7, 7)
+        assert result.meta["step_meta"][1]["operation"] == "convert_to_grayscale"
+        assert result.meta["source"] is sample_bgr_image
+
+    def test_final_step_meta_is_merged(self, sample_bgr_image):
+        result = Pipeline(
+            Step(apply_gaussian_blur, kernel_size=(7, 7))
+        ).run(sample_bgr_image)
+        # Pipeline keys win over the final step's own metadata
+        assert result.meta["operation"] == "pipeline"
+        assert result.meta["source"] is sample_bgr_image
+        # The final step's own keys survive the merge
+        assert result.meta["kernel_size"] == (7, 7)
+
+    def test_input_as_ndarray(self, sample_bgr_array):
+        result = Pipeline(apply_gaussian_blur).run(sample_bgr_array)
+        assert result.image.shape == sample_bgr_array.shape
+
+    def test_input_as_2d_ndarray_is_treated_as_gray(self, sample_gray_image):
+        result = Pipeline(apply_gaussian_blur).run(sample_gray_image._data)
+        assert result.meta["source"].colorspace == "GRAY"
+
+    def test_input_as_path(self, image_file):
+        result = Pipeline(convert_to_grayscale).run(image_file)
+        assert result.image.ndim == 2
+
+    def test_input_as_str_path(self, image_file):
+        result = Pipeline(convert_to_grayscale).run(str(image_file))
+        assert result.image.ndim == 2
+
+    def test_invalid_input_type_raises(self, sample_bgr_image):
+        pipeline = Pipeline(apply_gaussian_blur)
+        with pytest.raises(TypeError):
+            pipeline.run(123)
+        with pytest.raises(TypeError):
+            pipeline.run(None)
+        with pytest.raises(TypeError):
+            pipeline.run([sample_bgr_image])
+
+    def test_empty_pipeline_raises(self, sample_bgr_image):
+        with pytest.raises(ValueError):
+            Pipeline().run(sample_bgr_image)
+
+    def test_pipeline_is_reusable_across_inputs(self, multiply_function):
+        pipeline = Pipeline(multiply_function)
+        first = pipeline.run(Image.from_array(np.full((8, 8, 3), 10, np.uint8)))
+        second = pipeline.run(Image.from_array(np.full((12, 6, 3), 200, np.uint8)))
+        assert len(pipeline) == 1
+        assert first.image.shape == (8, 8, 3)
+        assert second.image.shape == (12, 6, 3)
+
+    def test_reruns_do_not_interfere(self, sample_bgr_image):
+        pipeline = Pipeline(apply_gaussian_blur)
+        first = pipeline.run(sample_bgr_image)
+        second = pipeline.run(sample_bgr_image)
+        assert np.array_equal(first.image, second.image)
+        assert first.image is not second.image
+
+    def test_custom_operation_returning_ndarray(self, sample_bgr_image):
+        def double(image):
+            return np.clip(image._data * 2, 0, 255).astype(np.uint8)
+
+        result = Pipeline(double).run(sample_bgr_image)
+        assert isinstance(result, Result)
+        assert result.meta["steps"] == ["double"]
+        expected = np.clip(sample_bgr_image._data * 2, 0, 255).astype(np.uint8)
+        assert np.array_equal(result.image, expected)
+
+    def test_unsupported_operation_return_raises(self, sample_bgr_image):
+        def bad_operation(image):
+            return "not an image or result"
+
+        with pytest.raises(TypeError):
+            Pipeline(bad_operation).run(sample_bgr_image)
+
+    def test_non_final_step_without_image_raises(self, sample_bgr_image):
+        def data_only(image):
+            return Result(image=None, data=[1, 2, 3])
+
+        pipeline = Pipeline(data_only, apply_gaussian_blur)
+        with pytest.raises(ValueError):
+            pipeline.run(sample_bgr_image)
+
+    def test_final_step_may_omit_image(self, sample_bgr_image):
+        def data_only(image):
+            return Result(image=None, data=[1, 2, 3])
+
+        result = Pipeline(data_only).run(sample_bgr_image)
+        assert result.image is None
+        assert result.data == [1, 2, 3]
+        assert result.meta["steps"] == ["data_only"]
+
+    def test_final_step_may_return_image_list(self, sample_bgr_image):
+        def two_images(image):
+            return Result(image=[image._data, image._data.copy()])
+
+        result = Pipeline(two_images).run(sample_bgr_image)
+        assert isinstance(result.image, list)
+        assert len(result.image) == 2
+
+    def test_non_final_step_with_image_list_raises(self, sample_bgr_image):
+        def two_images(image):
+            return Result(image=[image._data, image._data.copy()])
+
+        pipeline = Pipeline(two_images, apply_gaussian_blur)
+        with pytest.raises(ValueError):
+            pipeline.run(sample_bgr_image)
+
+    def test_colorspace_propagates_through_chain(
+        self, sample_bgr_image, colorspace_recorder
+    ):
+        Pipeline(convert_to_grayscale, colorspace_recorder).run(sample_bgr_image)
+        assert colorspace_recorder.seen == ["GRAY"]
+
+    def test_bgr_colorspace_propagates(self, sample_bgr_image, colorspace_recorder):
+        Pipeline(apply_gaussian_blur, colorspace_recorder).run(sample_bgr_image)
+        assert colorspace_recorder.seen == ["BGR"]
+
+    def test_operation_validation_errors_propagate(self, sample_gray_image):
+        # convert_to_grayscale refuses already-gray images; the pipeline
+        # must surface that error unchanged.
+        with pytest.raises(ValueError):
+            Pipeline(convert_to_grayscale).run(sample_gray_image)
+
+    def test_nested_pipeline_runs_as_single_step(self, sample_bgr_image):
+        inner = Pipeline(apply_gaussian_blur)
+        outer = Pipeline(inner, convert_to_grayscale)
+        result = outer.run(sample_bgr_image)
+        assert result.image.ndim == 2
+        assert result.meta["steps"][0] == "Pipeline"
+
+    def test_source_meta_is_original_input(self, image_file):
+        image = Image.from_path(image_file)
+        result = Pipeline(apply_gaussian_blur).run(image)
+        assert result.meta["source"] is image
+
+
+class TestCall:
+    def test_call_is_shorthand_for_run(self, sample_bgr_image):
+        pipeline = Pipeline(apply_gaussian_blur)
+        by_call = pipeline(sample_bgr_image)
+        by_run = pipeline.run(sample_bgr_image)
+        assert np.array_equal(by_call.image, by_run.image)
+        assert by_call.meta["operation"] == "pipeline"
+
+
+class TestDunders:
+    def test_len(self):
+        assert len(Pipeline()) == 0
+        assert len(Pipeline(apply_gaussian_blur, convert_to_grayscale)) == 2
+
+    def test_iter_yields_steps(self):
+        pipeline = Pipeline(apply_gaussian_blur, convert_to_grayscale)
+        steps = list(pipeline)
+        assert all(isinstance(step, Step) for step in steps)
+        assert [step.name for step in steps] == [
+            "apply_gaussian_blur",
+            "convert_to_grayscale",
+        ]
+
+    def test_repr_lists_step_names(self):
+        pipeline = Pipeline(apply_gaussian_blur, convert_to_grayscale)
+        assert repr(pipeline) == "Pipeline(apply_gaussian_blur -> convert_to_grayscale)"
+
+    def test_repr_of_empty_pipeline(self):
+        assert repr(Pipeline()) == "Pipeline(<empty>)"