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

{imagepro_python-1.5.0 → imagepro_python-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ImagePRO-Python
-Version: 1.5.0
+Version: 1.6.0
 Summary: Professional & modular image processing library with OpenCV, MediaPipe, and YOLO integration.
 Author-email: Parsa Safaie <parsasafaie.2568@proton.me>
 License: MIT
@@ -81,6 +81,12 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 - **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
 
+### **Batch Processing**
+- **Many Images at Once**: Run any function, `Step`, or `Pipeline` over a folder, a glob pattern, or a list of images
+- **Ordered Results**: One result per input, in input order, with per-input failure reporting
+- **Optional Output Saving**: Mirror results into an output directory with collision-safe names
+- **Progress Reporting**: Optional progress callback; optional worker threads
+
 ## Installation
 
 ### From PyPI
@@ -175,6 +181,12 @@ pipeline = Pipeline([
 pipeline_result = pipeline.run("person_and_objects.jpg")
 pipeline_result.save_as_img("processed_output.jpg")
 print(pipeline_result.meta["steps"])  # Executed step names
+
+# Or run the same pipeline over a whole folder at once
+from ImagePRO.batch import batch_process
+
+batch = batch_process("photos/", pipeline, output_dir="processed/")
+print(batch.meta["succeeded"], "images processed")
 ```
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
@@ -189,6 +201,7 @@ Each module includes comprehensive documentation with detailed examples:
   - [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
+- **[Batch Processing](src/ImagePRO/batch/README.md)**: Run any operation over many images at once
 - **[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).
@@ -201,6 +214,7 @@ ImagePRO is built with a modular architecture designed for extensibility and mai
 - **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
+- **Batch Processing**: Run any operation or pipeline over many images at once, with ordered per-input results
 - **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.5.0 → imagepro_python-1.6.0}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ImagePRO-Python"
-version = "1.5.0"
+version = "1.6.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.5.0 → imagepro_python-1.6.0}/readme.md

@@ -32,6 +32,12 @@ Whether you're working on computer vision pipelines, preprocessing images for AI
 - **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
 
+### **Batch Processing**
+- **Many Images at Once**: Run any function, `Step`, or `Pipeline` over a folder, a glob pattern, or a list of images
+- **Ordered Results**: One result per input, in input order, with per-input failure reporting
+- **Optional Output Saving**: Mirror results into an output directory with collision-safe names
+- **Progress Reporting**: Optional progress callback; optional worker threads
+
 ## Installation
 
 ### From PyPI
@@ -126,6 +132,12 @@ pipeline = Pipeline([
 pipeline_result = pipeline.run("person_and_objects.jpg")
 pipeline_result.save_as_img("processed_output.jpg")
 print(pipeline_result.meta["steps"])  # Executed step names
+
+# Or run the same pipeline over a whole folder at once
+from ImagePRO.batch import batch_process
+
+batch = batch_process("photos/", pipeline, output_dir="processed/")
+print(batch.meta["succeeded"], "images processed")
 ```
 
 > **Note**: These are basic examples. Each module contains many more functions with extensive customization options. Explore the module-specific README files for detailed documentation.
@@ -140,6 +152,7 @@ Each module includes comprehensive documentation with detailed examples:
   - [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
+- **[Batch Processing](src/ImagePRO/batch/README.md)**: Run any operation over many images at once
 - **[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).
@@ -152,6 +165,7 @@ ImagePRO is built with a modular architecture designed for extensibility and mai
 - **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
+- **Batch Processing**: Run any operation or pipeline over many images at once, with ordered per-input results
 - **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.5.0 → imagepro_python-1.6.0}/src/ImagePRO/__init__.py

@@ -13,10 +13,11 @@ Features:
 - Human analysis: face mesh, pose estimation, hand tracking
 - Object detection with YOLO models
 - Reusable pipelines for chaining operations
+- Batch processing: run any operation over many images at once
 - Real-time processing capabilities
 """
 
-__version__ = "1.5.0"
+__version__ = "1.6.0"
 __author__ = "Parsa Safaie"
 __email__ = "parsasafaie.2568@proton.me"
 
@@ -26,11 +27,13 @@ from . import pre_processing
 from . import human_analysis
 from . import object_analysis
 from . import pipeline
+from . import batch
 
 __all__ = [
     "utils",
     "pre_processing",
     "human_analysis",
     "object_analysis",
-    "pipeline"
+    "pipeline",
+    "batch"
 ]

imagepro_python-1.6.0/src/ImagePRO/batch/__init__.py

@@ -0,0 +1,14 @@
+# Batch Module
+# Runs a single operation over many inputs at once
+#
+# Uses only base dependencies (numpy); the operation handed to
+# batch_process may come from any module, including those with optional
+# backends (mediapipe, ultralytics, insightface).
+
+from .batch import BatchFailure, BatchResult, batch_process
+
+__all__ = [
+    "BatchFailure",
+    "BatchResult",
+    "batch_process"
+]

imagepro_python-1.6.0/src/ImagePRO/batch/batch.py

@@ -0,0 +1,529 @@
+"""Batch processing for ImagePRO: run one operation over many images.
+
+Exposes ``batch_process`` (the runner), ``BatchResult`` (the aggregate
+return value), and ``BatchFailure`` (one input that could not be
+processed). The module itself needs only the base dependencies; the
+operation handed to ``batch_process`` may come from any module, including
+those with optional backends.
+"""
+
+from __future__ import annotations
+
+import glob
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+# 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.pipeline import Pipeline, Step
+from ImagePRO.utils.image import Image
+from ImagePRO.utils.result import Result
+
+
+# Constants
+IMAGE_EXTENSIONS = frozenset({
+    ".bmp", ".jpeg", ".jpg", ".png", ".tif", ".tiff", ".webp",
+})
+GLOB_MAGIC_CHARS = "*?["
+ON_ERROR_MODES = ("raise", "collect")
+DEFAULT_ON_ERROR = "raise"
+DEFAULT_WORKERS = 1
+DEFAULT_RECURSIVE = False
+
+InputLike = Union[Image, np.ndarray, str, Path]
+InputsLike = Union[InputLike, list[InputLike], tuple[InputLike, ...]]
+Operation = Callable[..., Result]
+
+
+@dataclass(frozen=True, eq=False)
+class BatchFailure:
+    """
+    One input that could not be processed.
+
+    Only produced when ``batch_process`` runs with ``on_error="collect"``;
+    the other inputs keep processing and the batch still returns.
+
+    Attributes:
+        index (int):
+            Position of the failed input in the original input list (or in
+            the directory/glob listing order).
+        source (Any):
+            The original input item: a file path (``pathlib.Path``), an
+            ``Image``, or a ``numpy.ndarray``.
+        error_type (str):
+            Name of the exception class (e.g. "ValueError").
+        error (str):
+            The exception message.
+    """
+
+    index: int
+    source: Any
+    error_type: str
+    error: str
+
+
+@dataclass
+class BatchResult:
+    """
+    Aggregate result of a batch run.
+
+    Holds one entry per input, in input order, plus the batch-level
+    metadata (counts, configuration, timing).
+
+    Attributes:
+        results (list[Optional[Result]]):
+            One slot per input, in input order. Successful inputs hold
+            their ``Result`` object (exactly what the operation returned
+            for that image). Slots are ``None`` for failed inputs — only
+            possible with ``on_error="collect"``, since the default
+            "raise" mode aborts the batch on the first failure.
+        failures (list[BatchFailure]):
+            Failed inputs, ordered by index. Empty unless
+            ``on_error="collect"``.
+        meta (dict[str, Any]):
+            Batch metadata: "operation", "total", "succeeded", "failed",
+            "on_error", "workers", "recursive", "duration_seconds", and
+            "output_dir" (``None`` when results were kept in memory only).
+    """
+
+    results: list[Optional[Result]] = field(default_factory=list)
+    failures: list[BatchFailure] = field(default_factory=list)
+    meta: dict[str, Any] = field(default_factory=dict)
+
+
+def batch_process(
+    inputs: InputsLike,
+    operation: Operation,
+    *,
+    on_error: str = DEFAULT_ON_ERROR,
+    output_dir: Optional[str | Path] = None,
+    recursive: bool = DEFAULT_RECURSIVE,
+    workers: int = DEFAULT_WORKERS,
+    progress_callback: Optional[Callable[[int, int], None]] = None,
+    **kwargs: Any,
+) -> BatchResult:
+    """Run one operation over many images and collect the results.
+
+    Collects every input — a directory, a glob pattern, or a list of file
+    paths, Image instances and NumPy arrays — then runs ``operation`` on
+    each one, in input order. Inputs are loaded one at a time, so a folder
+    with thousands of images never has to fit in memory at once.
+
+    The operation can be any ImagePRO function (which takes an ``Image``
+    and returns a ``Result``), a ``Step``, a ``Pipeline``, or any custom
+    callable following the same convention. Returning a plain
+    ``numpy.ndarray`` is accepted and wrapped in a ``Result``. Keyword
+    arguments given here are forwarded to the operation on every input,
+    exactly like ``Step``.
+
+    Args:
+        inputs (list | tuple | str | Path | Image | np.ndarray):
+            What to process. Accepts:
+            - A directory path: every image file inside it (case-
+              insensitive extension match against ``.bmp .jpeg .jpg .png
+              .tif .tiff .webp``), sorted by path. Sub-directories are
+              included only with ``recursive=True``.
+            - A glob pattern (containing ``*``, ``?`` or ``[``): matching
+              image files, sorted by path.
+            - A single file path, ``Image``, or NumPy array: that one
+              input.
+            - A list/tuple mixing file paths, ``Image`` instances and
+              NumPy arrays.
+        operation (Callable):
+            The callable to run on each input. Pre-loaded detectors can be
+            injected through it — e.g. ``Step(detect_objects, model=my_model)``
+            — which matters a lot for heavy backends: without a pre-loaded
+            model, a fresh detector is constructed for every image.
+        on_error (str, optional):
+            What to do when an input fails. "raise" (default) re-raises
+            the operation's own error unchanged, like every other ImagePRO
+            function. "collect" keeps processing the remaining inputs and
+            records the failure in ``BatchResult.failures``. Either way,
+            an ``ImportError`` for a missing optional backend always
+            propagates: it is a setup problem, not a bad input.
+        output_dir (str | Path, optional):
+            If given, each successful result's image is saved there: the
+            output name mirrors the input name (relative sub-paths are
+            preserved for directory inputs) and name clashes get a numeric
+            suffix (``a.png``, ``a_1.png``, ...). Results without an image
+            (data-only results) are not saved. Defaults to None (keep
+            results in memory only).
+        recursive (bool, optional):
+            Include sub-directories when ``inputs`` is a directory.
+            Defaults to False.
+        workers (int, optional):
+            Number of worker threads. Defaults to 1 (fully sequential,
+            deterministic order). With more than one, inputs are processed
+            concurrently but ``BatchResult.results`` still follows input
+            order. Detector objects injected into the operation (MediaPipe,
+            YOLO, InsightFace) are not guaranteed thread-safe: keep
+            ``workers=1`` unless the operation is pure image processing
+            (e.g. OpenCV filters, which release the GIL).
+        progress_callback (Callable[[int, int], None], optional):
+            Called after each input completes with ``(completed, total)``.
+            Always called from the calling thread, never from a worker.
+            Defaults to None.
+        **kwargs (Any):
+            Forwarded to the operation on every input, like ``Step``.
+
+    Returns:
+        BatchResult: One entry per input (``results``, input order),
+            ``failures`` (empty in "raise" mode), and batch ``meta``.
+
+    Raises:
+        TypeError: If ``inputs``, ``operation``, ``output_dir``,
+            ``progress_callback`` or ``recursive`` has an invalid type.
+        ValueError: If ``on_error`` or ``workers`` is invalid, if
+            ``output_dir`` points at an existing non-directory, or if
+            keyword arguments are combined with a ``Step``/``Pipeline``
+            operation (attach them to the Step instead).
+        FileNotFoundError: If a single input path does not exist.
+        TypeError/ValueError: Propagated unchanged from the operation or
+            from input normalization when ``on_error="raise"``.
+
+    Note:
+        The batch options (``on_error``, ``output_dir``, ``recursive``,
+        ``workers``, ``progress_callback``) are reserved: to pass a
+        parameter with one of these names to the operation itself, wrap
+        the operation in a ``Step`` or ``functools.partial`` instead of
+        passing it here.
+
+        Inputs are read one at a time, but the returned ``BatchResult``
+        keeps every result, and each result keeps its input in
+        ``meta["source"]``. A batch therefore holds about the whole
+        dataset (inputs plus outputs) in memory; ``output_dir`` writes
+        images to disk without releasing them. For very large inputs, call
+        ``batch_process`` once per chunk of the input list so each
+        ``BatchResult`` can be dropped before the next one is built.
+
+    Example:
+        >>> from ImagePRO.pre_processing.blur import apply_gaussian_blur
+        >>> batch = batch_process("photos/", apply_gaussian_blur, kernel_size=(9, 9))
+        >>> batch.meta["succeeded"]
+        2
+        >>> batch.results[0].save_as_img("first_blurred.png")
+    """
+    # Validate the batch configuration before touching any input, so an
+    # invalid call never leaves partial state (e.g. a created folder)
+    # behind.
+    if not callable(operation):
+        raise TypeError(
+            "'operation' must be a callable that accepts an Image as its "
+            "first positional argument (an ImagePRO function, a Step, or a "
+            "Pipeline)."
+        )
+    if on_error not in ON_ERROR_MODES:
+        raise ValueError(
+            f"'on_error' must be one of {list(ON_ERROR_MODES)}, got {on_error!r}."
+        )
+    if not isinstance(workers, int) or isinstance(workers, bool) or workers < 1:
+        raise ValueError("'workers' must be a positive integer.")
+    if not isinstance(recursive, bool):
+        raise TypeError("'recursive' must be a boolean.")
+    if output_dir is not None:
+        if not isinstance(output_dir, (str, Path)):
+            raise TypeError("'output_dir' must be a string or pathlib.Path.")
+        out_root = Path(output_dir)
+        if out_root.exists() and not out_root.is_dir():
+            raise ValueError(
+                f"'output_dir' exists and is not a directory: {out_root}"
+            )
+        out_root.mkdir(parents=True, exist_ok=True)
+    else:
+        out_root = None
+    if progress_callback is not None and not callable(progress_callback):
+        raise TypeError("'progress_callback' must be a callable.")
+    if kwargs and isinstance(operation, (Step, Pipeline)):
+        raise ValueError(
+            "Keyword arguments cannot be combined with a Step or Pipeline "
+            "operation; their keyword arguments are already fixed at "
+            "construction time. Attach them to the Step instead, e.g. "
+            "Step(resize_image, new_size=(800, 600))."
+        )
+
+    # Collect all inputs up front; paths are only read during processing,
+    # one at a time. Output paths are pre-assigned here (rather than per
+    # worker) so collision suffixes stay deterministic and thread-safe.
+    sources = _collect_sources(inputs, recursive=recursive)
+    total = len(sources)
+    taken_names: set[Path] = set()
+    if out_root is not None:
+        output_paths = [
+            _assign_output_path(out_root, name, taken_names)
+            for _, name in sources
+        ]
+    else:
+        output_paths = [None] * total
+
+    operation_name = getattr(operation, "__name__", type(operation).__name__)
+
+    def run_item(index: int) -> tuple[int, Optional[Result], Optional[Exception]]:
+        """Process one input; returns (index, result, error)."""
+        source = sources[index][0]
+        out_path = output_paths[index]
+        try:
+            image = _as_image(source)
+            output = operation(image, **kwargs)
+            if isinstance(output, Result):
+                result = output
+            elif isinstance(output, np.ndarray):
+                result = Result(image=output, meta={"operation": operation_name})
+            else:
+                raise TypeError(
+                    f"The operation returned {type(output).__name__}; batch "
+                    "operations must return a Result object or a numpy.ndarray."
+                )
+            if out_path is not None and result.image is not None:
+                result.save_as_img(out_path)
+            return index, result, None
+        except ImportError:
+            # A missing optional backend is a setup problem, not a bad
+            # input: collect mode must not swallow it N times over.
+            raise
+        except Exception as exc:
+            return index, None, exc
+
+    results: list[Optional[Result]] = [None] * total
+    failures: list[BatchFailure] = []
+    completed = 0
+    started = time.monotonic()
+
+    def record_item(index: int, result: Optional[Result], error: Optional[Exception]) -> None:
+        """Record one finished item and report progress from this thread."""
+        nonlocal completed
+        if error is not None:
+            failures.append(BatchFailure(
+                index=index,
+                source=sources[index][0],
+                error_type=type(error).__name__,
+                error=str(error),
+            ))
+        else:
+            results[index] = result
+        completed += 1
+        if progress_callback is not None:
+            progress_callback(completed, total)
+
+    if on_error == "raise":
+        if workers > 1 and total > 1:
+            with ThreadPoolExecutor(max_workers=workers) as executor:
+                futures = {executor.submit(run_item, index): index for index in range(total)}
+                try:
+                    for future in as_completed(futures):
+                        index, result, error = future.result()
+                        if error is not None:
+                            raise error
+                        record_item(index, result, None)
+                finally:
+                    for future in futures:
+                        future.cancel()
+        else:
+            for index in range(total):
+                _, result, error = run_item(index)
+                if error is not None:
+                    raise error
+                record_item(index, result, None)
+    else:  # on_error == "collect"
+        if workers > 1 and total > 1:
+            with ThreadPoolExecutor(max_workers=workers) as executor:
+                futures = {executor.submit(run_item, index): index for index in range(total)}
+                for future in as_completed(futures):
+                    index, result, error = future.result()
+                    record_item(index, result, error)
+        else:
+            for index in range(total):
+                _, result, error = run_item(index)
+                record_item(index, result, error)
+
+    # as_completed order is not deterministic; sort for reproducible
+    # failure listings regardless of the worker count.
+    failures.sort(key=lambda failure: failure.index)
+
+    meta = {
+        "operation": operation_name,
+        "total": total,
+        "succeeded": sum(1 for result in results if result is not None),
+        "failed": len(failures),
+        "on_error": on_error,
+        "workers": workers,
+        "recursive": recursive,
+        "duration_seconds": round(time.monotonic() - started, 6),
+        "output_dir": str(out_root) if out_root is not None else None,
+    }
+    return BatchResult(results=results, failures=failures, meta=meta)
+
+
+def _as_image(source: Any) -> Image:
+    """
+    Normalize one collected input into an Image.
+
+    Mirrors the input normalization of ``Pipeline.run``: file paths are
+    loaded from disk and NumPy arrays are wrapped, assuming BGR for
+    3-channel and GRAY for 2D arrays.
+
+    Args:
+        source (Any): A ``pathlib.Path``, ``Image``, or NumPy array.
+
+    Returns:
+        Image: The normalized input.
+    """
+    if isinstance(source, Image):
+        return source
+    if isinstance(source, np.ndarray):
+        colorspace = "GRAY" if source.ndim == 2 else "BGR"
+        return Image.from_array(source, colorspace=colorspace)
+    return Image.from_path(source)
+
+
+def _collect_sources(inputs: InputsLike, *, recursive: bool) -> list[tuple[Any, Any]]:
+    """
+    Turn the ``inputs`` argument into (source, output name) pairs.
+
+    Every pair is one work item: ``source`` is a file path, an ``Image``
+    or a NumPy array handed to the operation; ``output name`` is the name
+    used for saving under ``output_dir`` (a relative path for directory
+    inputs, a file name for list inputs, ``image_<index>`` for arrays).
+
+    Args:
+        inputs (InputsLike): The raw ``inputs`` argument.
+        recursive (bool): Whether directory scans descend into
+            sub-directories.
+
+    Returns:
+        list[tuple[Any, Any]]: One (source, output name) pair per input,
+            in input order.
+
+    Raises:
+        TypeError: If ``inputs`` or one of its items has an invalid type.
+        FileNotFoundError: If a single input path does not exist.
+    """
+    if isinstance(inputs, (Image, np.ndarray)):
+        return [(inputs, "image_0")]
+    if isinstance(inputs, (list, tuple)):
+        sources: list[tuple[Any, Any]] = []
+        for index, item in enumerate(inputs):
+            if isinstance(item, (str, Path)):
+                sources.append((Path(item), Path(item).name))
+            elif isinstance(item, (Image, np.ndarray)):
+                sources.append((item, f"image_{index}"))
+            else:
+                raise TypeError(
+                    "Every input must be a file path (str or pathlib.Path), "
+                    "an Image instance, or a numpy.ndarray; got "
+                    f"{type(item).__name__} at index {index}."
+                )
+        return sources
+    if isinstance(inputs, (str, Path)):
+        return _collect_from_path(inputs, recursive=recursive)
+    raise TypeError(
+        "'inputs' must be a list/tuple of images, a directory path, a glob "
+        "pattern, or a single Image or numpy.ndarray; got "
+        f"{type(inputs).__name__}."
+    )
+
+
+def _collect_from_path(value: str | Path, *, recursive: bool) -> list[tuple[Path, Any]]:
+    """
+    Expand a single string/path input into its work items.
+
+    Args:
+        value (str | Path): A directory path, a glob pattern, or a file
+            path.
+        recursive (bool): Whether directory scans descend into
+            sub-directories.
+
+    Returns:
+        list[tuple[Path, Any]]: One (source, output name) pair per match,
+            sorted by path.
+
+    Raises:
+        FileNotFoundError: If the path is neither a glob pattern nor an
+            existing file or directory.
+    """
+    if any(char in str(value) for char in GLOB_MAGIC_CHARS):
+        return [(match, match.name) for match in _expand_glob(str(value))]
+    path = Path(value)
+    if path.is_dir():
+        return [
+            (match, match.relative_to(path))
+            for match in _scan_directory(path, recursive=recursive)
+        ]
+    if path.is_file():
+        return [(path, path.name)]
+    raise FileNotFoundError(f"Input path does not exist: {path}")
+
+
+def _scan_directory(root: Path, *, recursive: bool) -> list[Path]:
+    """
+    List the image files inside a directory, sorted by path.
+
+    Args:
+        root (Path): Directory to scan.
+        recursive (bool): Whether to descend into sub-directories.
+
+    Returns:
+        list[Path]: Matching files, sorted for deterministic order.
+    """
+    pattern = "**/*" if recursive else "*"
+    return sorted(
+        match for match in root.glob(pattern)
+        if match.is_file() and match.suffix.lower() in IMAGE_EXTENSIONS
+    )
+
+
+def _expand_glob(pattern: str) -> list[Path]:
+    """
+    Expand a glob pattern into its image file matches, sorted by path.
+
+    Args:
+        pattern (str): Glob pattern (``**`` is supported).
+
+    Returns:
+        list[Path]: Matching files, sorted for deterministic order.
+    """
+    return sorted(
+        match for match in (Path(found) for found in glob.glob(pattern, recursive=True))
+        if match.is_file() and match.suffix.lower() in IMAGE_EXTENSIONS
+    )
+
+
+def _assign_output_path(base_dir: Path, name: Any, taken: set[Path]) -> Path:
+    """
+    Return a collision-free output path under ``base_dir`` for ``name``.
+
+    A relative name keeps its sub-paths (``sub/a.png``), so directory
+    inputs are mirrored. When two inputs would write to the same path, the
+    later one gets a numeric suffix (``a.png``, ``a_1.png``), matching the
+    convention of ``Result.save_as_img``.
+
+    Args:
+        base_dir (Path): Output root directory.
+        name (Any): Relative output name (str or Path) for this input.
+        taken (set[Path]): Paths already assigned; updated in place.
+
+    Returns:
+        Path: The output path for this input.
+    """
+    candidate = base_dir.joinpath(*Path(name).parts)
+    if candidate not in taken:
+        taken.add(candidate)
+        return candidate
+    stem, suffix = candidate.stem, candidate.suffix
+    parent = candidate.parent
+    counter = 1
+    while True:
+        alternative = parent / f"{stem}_{counter}{suffix}"
+        if alternative not in taken:
+            taken.add(alternative)
+            return alternative
+        counter += 1