image_batch_processor.py

# image_processor.py
# This script offers resizing, rotating, flipping, and cropping images.
# pip install Pillow for the following import.

from PIL import Image
from pathlib import Path
import os


class ImageProcessor:
    """
    Batch image processing utility.

    Responsibilities
    ---------------
    - Validate input directory existence + read permissions
    - Create an output folder "processed_images" inside the input directory
    - Discover image files based on file type patterns (optionally recursive)
    - Apply operations (resize/rotate/flip/crop) to all discovered images
    - Save processed images into the output folder with a suffix

    Notes
    -----
    - The same input set is processed separately for each operation you call.
    - Output filenames are derived from original stem + suffix + original extension.
    """

    def __init__(self, input_dir, recursive, file_types):
        """
        Initialize the processor.

        Parameters
        ----------
        input_dir : str
            Directory path where images exist.
        recursive : bool
            True to include subdirectories; False to only scan the top-level directory.
        file_types : tuple[str, ...]
            File glob patterns for images, e.g. ("*.jpg", "*.png").

        Raises
        ------
        FileNotFoundError
            If the input directory does not exist.
        PermissionError
            If input directory is not readable or output directory is not writable.
        OSError
            If output directory creation fails due to OS-level issues.
        """
        try:
            # Define input parameters in the main() function.
            self.input_dir = Path(input_dir)

            # Check if input directory exists.
            if not self.input_dir.exists():
                raise FileNotFoundError(
                    f"Input directory '{input_dir}' \ndoes not exist"
                )

            # Check if input directory is accessible.
            if not os.access(self.input_dir, os.R_OK):
                raise PermissionError(
                    f"No read permission for directory \n'{input_dir}'"
                )

            # Store scan behavior.
            self.include_subdirs = recursive

            # Normalize file types to lowercase (pattern strings).
            self.file_types = tuple(map(str.lower, file_types))

            # Output directory path: <input_dir>/processed_images
            self.output_dir = self.input_dir / "processed_images"

            # Create output directory with permission check.
            try:
                self.output_dir.mkdir(exist_ok=True)

                # Verify write permission for output directory.
                if not os.access(self.output_dir, os.W_OK):
                    raise PermissionError(
                        f"No write permission for output \ndirectory '{self.output_dir}'"
                    )

            except PermissionError as e:
                # Raised when folder cannot be created or is not writable.
                raise PermissionError(f"Cannot create output directory: {e}")
            except OSError as e:
                # Covers other filesystem issues: invalid path, I/O, etc.
                raise OSError(f"Failed to create output directory: {e}")

        except (FileNotFoundError, PermissionError, OSError) as e:
            # Bubble up initialization errors with consistent prefix.
            raise type(e)(f"Initialization failed: {e}")

    def get_image_files(self):
        """
        Collect image file paths according to recursive flag and file type patterns.

        Returns
        -------
        list[str]
            A list of file paths converted to strings.

        Behavior
        --------
        - Uses Path.glob() to match file patterns.
        - If recursive=True uses "**/*" prefix.
        - Each pattern in self.file_types is appended to the prefix.
        """
        try:
            # Get list of image files based on specifications.
            image_files = []
            pattern = "**/*" if self.include_subdirs else "*"

            # For each file type pattern (e.g., "*.jpg"), glob matching files.
            for file_type in self.file_types:
                image_files.extend(self.input_dir.glob(pattern + file_type))

            # Convert Path objects to strings for compatibility
            return [str(file) for file in image_files]

        except Exception as e:
            # Any unexpected errors while scanning are handled gracefully.
            print(f"Error accessing image files: {e}")
            return []

    def resize(self, width=None, height=None, output_suffix="_resized"):
        """
        Resize all discovered images.

        Parameters
        ----------
        width : int | None
            Target width. If height is None, aspect ratio is maintained.
        height : int | None
            Target height. If width is None, aspect ratio is maintained.
        output_suffix : str
            Suffix appended to the output filename (before extension).

        Rules
        -----
        - At least one of width or height must be provided.
        - If both provided: image is resized to exact dimensions.
        - If only one provided: other dimension is computed to preserve aspect ratio.
        """
        # Resize all images to specified width or height, maintaining aspect
        # ratio if either is None.
        if width is None and height is None:
            raise ValueError("At least one of width or height must be specified")

        for image_path in self.get_image_files():
            try:
                with Image.open(image_path) as img:
                    # Original dimensions.
                    orig_width, orig_height = img.size

                    # Calculate dimensions based on input.
                    if width is not None and height is not None:
                        new_width, new_height = width, height
                    elif width is not None:
                        new_width = width
                        new_height = int((width / orig_width) * orig_height)
                    else:  # height is not None
                        new_height = height
                        new_width = int((height / orig_height) * orig_width)

                    # Perform resize.
                    resized_image = img.resize(
                        (new_width, new_height), Image.Resampling.LANCZOS
                    )

                    # Create output file path.
                    output_path = self._get_output_path(image_path, output_suffix)

                    # Save resized image.
                    try:
                        resized_image.save(output_path)
                        print(
                            f"Resized image saved to: {output_path} ({new_width}x{new_height})"
                        )
                    except (PermissionError, OSError) as e:
                        print(f"Error saving resized image {output_path}: {e}")

            except (FileNotFoundError, PermissionError, OSError) as e:
                print(f"Error resizing {image_path}: {e}")

    def rotate(self, degrees, output_suffix="_rotated"):
        """
        Rotate all discovered images.

        Parameters
        ----------
        degrees : int | float
            Degrees to rotate (Pillow rotates counter-clockwise for positive values).
        output_suffix : str
            Suffix appended to the output filename (before extension).

        Notes
        -----
        - expand=True increases the output canvas so the full rotated image fits.
        """
        # Rotate all images by specified degrees.
        for image_path in self.get_image_files():
            try:
                with Image.open(image_path) as img:
                    rotated_image = img.rotate(degrees, expand=True)
                    output_path = self._get_output_path(image_path, output_suffix)
                    try:
                        rotated_image.save(output_path)
                        print(f"Rotated image saved to: {output_path}")
                    except (PermissionError, OSError) as e:
                        print(f"Error saving rotated image {output_path}: {e}")
            except (FileNotFoundError, PermissionError, OSError) as e:
                print(f"Error rotating {image_path}: {e}")

    def flip(self, direction="horizontal", output_suffix="_flipped"):
        """
        Flip all discovered images horizontally or vertically.

        Parameters
        ----------
        direction : str
            "horizontal" or "vertical"
        output_suffix : str
            Suffix appended to the output filename (before extension).

        Raises
        ------
        ValueError
            If direction is not "horizontal" or "vertical".
        """
        # Flip all images horizontally or vertically.
        for image_path in self.get_image_files():
            try:
                with Image.open(image_path) as img:
                    if direction.lower() == "horizontal":
                        flipped_image = img.transpose(Image.FLIP_LEFT_RIGHT)
                    elif direction.lower() == "vertical":
                        flipped_image = img.transpose(Image.FLIP_TOP_BOTTOM)
                    else:
                        raise ValueError(
                            "Direction must be 'horizontal' or \n'vertical'"
                        )

                    output_path = self._get_output_path(image_path, output_suffix)
                    try:
                        flipped_image.save(output_path)
                        print(f"Flipped image saved to: {output_path}")
                    except (PermissionError, OSError) as e:
                        print(f"Error saving flipped image {output_path}: {e}")
            except (FileNotFoundError, PermissionError, OSError, ValueError) as e:
                print(f"Error flipping {image_path}: {e}")

    def crop(self, left, top, right, bottom, output_suffix="_cropped"):
        """
        Crop all discovered images using a fixed rectangle.

        Parameters
        ----------
        left, top, right, bottom : int
            Bounding box coordinates (left, top, right, bottom).
        output_suffix : str
            Suffix appended to the output filename (before extension).
        """
        # Crop all images using specified coordinates.
        for image_path in self.get_image_files():
            try:
                with Image.open(image_path) as img:
                    cropped_image = img.crop((left, top, right, bottom))
                    output_path = self._get_output_path(image_path, output_suffix)
                    try:
                        cropped_image.save(output_path)
                        print(f"Cropped image saved to: {output_path}")
                    except (PermissionError, OSError) as e:
                        print(f"Error saving cropped image {output_path}: {e}")
            except (FileNotFoundError, PermissionError, OSError) as e:
                print(f"Error cropping {image_path}: {e}")

    def _get_output_path(self, input_path, suffix):
        """
        Generate output path for a processed file.

        Parameters
        ----------
        input_path : str
            Original file path.
        suffix : str
            Suffix to append before extension.

        Returns
        -------
        str
            Output path string for saving.

        Notes
        -----
        - Uses Path.stem and Path.suffix to preserve extension.
        - If path parsing fails, falls back to: processed_images/error<suffix>.jpg
        """
        # Generate output file path with suffix.
        try:
            input_path = Path(input_path)
            filename = input_path.stem
            extension = input_path.suffix
            return str(self.output_dir / f"{filename}{suffix}{extension}")
        except Exception as e:
            print(f"Error generating output path for {input_path}: {e}")
            return str(self.output_dir / f"error{suffix}.jpg")  # Fallback path


def main():
    """
    Example usage.

    Adjust:
    - input_directory to your folder
    - recursive to include or exclude subfolders
    - file_types to control which image types are processed
    """
    try:
        # Replace with your directory path.
        input_directory = r"C:\Users\Badar-Butt\Pictures\Screenshots"
        # Mac path example
        # input_directory = "/Users/alan/Practice/Img Process"
        # True to include subdirectories
        recursive = True
        # Define as tuple inside parentheses. Must be raster image types.
        file_types = ("*.jpg", "*.jpeg", "*.png", "*.webp")

        # Create processor instance with custom parameters.
        processor = ImageProcessor(input_directory, recursive, file_types)

        # Perform various operations on all matching images.
        # Comment out any operation you don't want to perform.

        # Resize to 512px width, auto height
        processor.resize(width=512, height=None)

        # Resize to 512px height, auto width.
        # processor.resize(width=None, height=512)

        # Resize to exactly 512x512.
        # processor.resize(width=512, height=512)

        # Rotate 90 degrees.
        processor.rotate(90)

        # Flip horizontally.
        processor.flip("horizontal")

        # Flip vertically.
        processor.flip("vertical")

        # Crop to 256x256 from (100,100).
        processor.crop(100, 100, 356, 356)

    except (FileNotFoundError, PermissionError, OSError) as e:
        print(f"Error in main execution: {e}")
        return


if __name__ == "__main__":
    main()