batch-img 0.0.7__py3-none-any.whl

batch_img/border.py

@@ -0,0 +1,86 @@
+"""class Border: add border to the image file(s)
+Copyright © 2025 John Liu
+"""
+
+from pathlib import Path
+
+import piexif
+import pillow_heif
+from loguru import logger
+from PIL import Image
+
+from batch_img.common import Common
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+
+class Border:
+    @staticmethod
+    def add_border_1_image(
+        in_path: Path, out_path: Path, border_width: int, border_color: str
+    ) -> tuple:
+        """Add internal border to an image file, not to expand the size
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+            border_width: border width int
+            border_color: border color str
+
+        Returns:
+            tuple: bool, str
+        """
+        try:
+            with Image.open(in_path) as img:
+                width, height = img.size
+                box = Common.get_crop_box(width, height, border_width)
+                cropped_img = img.crop(box)
+                bd_img = Image.new(img.mode, (width, height), border_color)
+                bd_img.paste(cropped_img, (border_width, border_width))
+
+                out_path.mkdir(parents=True, exist_ok=True)
+                out_file = out_path
+                if out_path.is_dir():
+                    filename = f"{in_path.stem}_bw{border_width}{in_path.suffix}"
+                    out_file = Path(f"{out_path}/{filename}")
+                exif_dict = None
+                if "exif" in img.info:
+                    exif_dict = piexif.load(img.info["exif"])
+                if exif_dict:
+                    exif_bytes = piexif.dump(exif_dict)
+                    bd_img.save(out_file, img.format, optimize=True, exif=exif_bytes)
+                else:
+                    bd_img.save(out_file, img.format, optimize=True)
+            logger.info(f"Saved {out_file}")
+            return True, out_file
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            return False, f"{in_path}:\n{e}"
+
+    @staticmethod
+    def add_border_all_in_dir(
+        in_path: Path, out_path: Path, border_width: int, border_color: str
+    ) -> bool:
+        """Add border to all image files in the given dir
+
+        Args:
+            in_path: input dir path
+            out_path: output dir path
+            border_width: border width int
+            border_color: border color str
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        image_files = Common.prepare_all_files(in_path, out_path)
+        if not image_files:
+            logger.error(f"No image files at {in_path}")
+            return False
+        tasks = [(f, out_path, border_width, border_color) for f in image_files]
+        files_cnt = len(tasks)
+
+        logger.info(f"Add border to {files_cnt} image files in multiprocess ...")
+        success_cnt = Common.multiprocess_progress_bar(
+            Border.add_border_1_image, "Add border to image files", tasks
+        )
+        logger.info(f"\nSuccessfully added border to {success_cnt}/{files_cnt} files")
+        return True

batch_img/common.py

@@ -0,0 +1,259 @@
+"""class Common: common utilities
+Copyright © 2025 John Liu
+"""
+
+import itertools
+import json
+import subprocess
+import tomllib
+from datetime import datetime
+from importlib.metadata import version
+from multiprocessing import Pool, cpu_count
+from os.path import getmtime, getsize
+from pathlib import Path
+
+import piexif
+import pillow_heif
+from loguru import logger
+from PIL import Image, ImageChops
+from PIL.TiffImagePlugin import IFDRational
+from tqdm import tqdm
+
+from batch_img.const import PATTERNS, PKG_NAME, TS_FORMAT, VER
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+
+class Common:
+    @staticmethod
+    def get_version() -> str:
+        """
+        Get this package version using several ways
+        """
+        try:
+            return version(PKG_NAME)
+        except (FileNotFoundError, ImportError, ValueError) as e:
+            # Use lazy % formatting in logging for efficiency
+            logger.warning(f"importlib.metadata.version Error: {e}")
+            logger.debug("Try to get version from pyproject.toml file")
+            pyproject = Path(__file__).parent.parent / "pyproject.toml"
+            with open(pyproject, "rb") as f:
+                return tomllib.load(f)["project"][VER]
+
+    @staticmethod
+    def run_cmd(cmd: str) -> tuple:
+        """Run a command on the host and get the output
+
+        Args:
+            cmd (str): a command line with options
+
+        Returns:
+            tuple: returnCode, StdOut, StdErr
+        """
+        logger.debug(f"{cmd=}")
+        try:
+            p = subprocess.run(
+                cmd, capture_output=True, text=True, shell=True, check=True
+            )
+            r_code = p.returncode
+            stdout = p.stdout
+            stderr = p.stderr
+            logger.debug(f"'{cmd}'\n {r_code=}\n {stdout=}\n {stderr=}")
+            return r_code, stdout, stderr
+        except subprocess.CalledProcessError as e:
+            logger.exception(e)
+            raise e
+
+    @staticmethod
+    def readable_file_size(in_bytes: int) -> str:
+        """Convert bytes to human-readable KB, MB, or GB
+
+        Args:
+            in_bytes: input bytes integer
+
+        Returns:
+            str
+        """
+        for _unit in ["B", "KB", "MB", "GB"]:
+            if in_bytes < 1024:
+                break
+            in_bytes /= 1024
+        res = f"{in_bytes} B" if _unit == "B" else f"{in_bytes:.1f} {_unit}"
+        return res
+
+    @staticmethod
+    def decode_exif(exif_data: str) -> dict:
+        """Decode the EXIF data
+
+        Args:
+            exif_data: str
+
+        Returns:
+            dict
+        """
+        exif_dict = piexif.load(exif_data)
+        _dict = {}
+        for ifd_name, val in exif_dict.items():
+            # Canon EOS 5D Mark II 'thumbnail': b'\xff\xd8\xff\xdb...
+            # 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte
+            if not val or ifd_name == "thumbnail":
+                continue
+            for tag_id, value in val.items():
+                tag_name = piexif.TAGS[ifd_name].get(tag_id, {}).get("name", tag_id)
+                _dict[tag_name] = value
+        # logger.info(f"{_dict=}")
+        for key in (
+            "FNumber",
+            "FocalLength",
+            "MakerNote",
+            "SceneType",
+            "SubjectArea",
+            "Software",
+            "HostComputer",
+            "UserComment",
+        ):
+            if key in _dict:
+                _dict.pop(key)
+        keys = list(_dict.keys())
+        for keyword in (
+            "DateTime",
+            "GPS",
+            "OffsetTime",
+            "SubSecTime",
+            "Tile",
+            "Pixel",
+            "Lens",
+            "Resolution",
+            "Value",
+        ):
+            for key in keys:
+                if key.startswith(keyword) or key.endswith(keyword):
+                    _dict.pop(key)
+        _res = {
+            k: (v.decode() if isinstance(v, bytes) else v) for k, v in _dict.items()
+        }
+        logger.info(f"{_res=}")
+        return _res
+
+    @staticmethod
+    def get_image_data(file: Path) -> tuple:
+        """Get image file data
+
+        Args:
+            file: image file path
+
+        Returns:
+            tuple: data, info
+        """
+        size = getsize(file)
+        m_ts = datetime.fromtimestamp(getmtime(file)).strftime(TS_FORMAT)
+        with Image.open(file) as img:
+            data = img.convert("RGB")
+            d_info = {
+                "file_size": Common.readable_file_size(size),
+                "file_ts": m_ts,
+                "format": img.format,
+                "mode": img.mode,
+                "size": img.size,
+                "info": img.info,
+            }
+            for key in ("icc_profile", "xmp"):
+                if key in img.info:
+                    img.info.pop(key)
+            if "exif" in img.info:
+                exif_data = img.info.pop("exif")
+                d_info["exif"] = Common.decode_exif(exif_data)
+
+        return data, d_info
+
+    @staticmethod
+    def jsn_serial(obj):
+        """JSON serializer for objects not serializable by default json code"""
+        if isinstance(obj, IFDRational):
+            return float(obj)
+        if isinstance(obj, bytes):
+            return obj.decode()
+        raise TypeError(
+            f"Object of type {obj.__class__.__name__} is not JSON serializable"
+        )
+
+    @staticmethod
+    def are_images_equal(path1: Path, path2: Path) -> bool:
+        """Check if two image files are visually equal pixel-wise
+
+        Args:
+            path1: image1 file path
+            path2: image2 file path
+
+        Returns:
+            bool: True - visually equal, False - not visually equal
+        """
+        data1, meta1 = Common.get_image_data(path1)
+        data2, meta2 = Common.get_image_data(path2)
+
+        logger.info(
+            f"{path1}:\n{json.dumps(meta1, indent=2, default=Common.jsn_serial)}"
+        )
+        logger.info(
+            f"{path2}:\n{json.dumps(meta2, indent=2, default=Common.jsn_serial)}"
+        )
+        return ImageChops.difference(data1, data2).getbbox() is None
+
+    @staticmethod
+    def get_crop_box(width, height, border_width) -> tuple[float, float, float, float]:
+        """Get the crop box tuple
+
+        Args:
+            width: image width int
+            height: image height int
+            border_width: border width int
+
+        Returns:
+            tuple[float, float, float, float]
+        """
+        crop_left = border_width
+        crop_top = border_width
+        crop_right = width - border_width
+        crop_bottom = height - border_width
+        return crop_left, crop_top, crop_right, crop_bottom
+
+    @staticmethod
+    def prepare_all_files(in_path: Path, out_path: Path):
+        """
+
+        Args:
+            in_path: input dir path
+            out_path: output dir path
+
+        Returns:
+            iterable: files list generator
+        """
+        out_path.mkdir(parents=True, exist_ok=True)
+        _files = itertools.chain.from_iterable(in_path.glob(p) for p in PATTERNS)
+        return _files
+
+    @staticmethod
+    def multiprocess_progress_bar(func, desc, tasks: list) -> int:
+        """Run task in multiprocess with progress bar
+
+        Args:
+            func: function to be run in multiprocess
+            desc: description str
+            tasks: tasks list for multiprocess pool
+
+        Returns:
+            int: success_cnt
+        """
+        success_cnt = 0
+        files_cnt = len(tasks)
+        workers = max(cpu_count(), 4)
+
+        with Pool(workers) as pool:
+            with tqdm(total=files_cnt, desc=desc) as pbar:
+                for ok, res in pool.starmap(func, tasks):
+                    if ok:
+                        success_cnt += 1
+                    else:
+                        tqdm.write(f"Error: {res}")
+                    pbar.update()
+        return success_cnt

batch_img/const.py

@@ -0,0 +1,26 @@
+"""const.py - define constants
+Copyright © 2025 John Liu
+"""
+
+PKG_NAME = "batch_img"
+VER = "version"
+NAME = "name"
+UNKNOWN = "unknown"
+
+MSG_OK = "✅ Processed the image file(s)"
+MSG_BAD = "❌ Failed to process the image file(s)."
+
+TS_FORMAT = "%Y-%m-%d_%H-%M-%S"
+PATTERNS = (
+    "*.HEIC",
+    "*.heic",
+    "*.JPG",
+    "*.jpg",
+    "*.JPEG",
+    "*.jpeg",
+    "*.PNG",
+    "*.png",
+)
+MAX_LENGTH = 1280
+BD_WIDTH = 5
+BD_COLOR = "green"

batch_img/defaults.py

@@ -0,0 +1,134 @@
+"""class Defaults: apply default actions to the image file(s):
+    * Resize to 1280 pixels as the max length
+    * Add the border of 5 pixel width in green color
+    * Auto-rotate if upside down or sideways
+Copyright © 2025 John Liu
+"""
+
+from pathlib import Path
+
+import piexif
+import pillow_heif
+from loguru import logger
+from PIL import Image
+
+from batch_img.common import Common
+from batch_img.const import BD_COLOR, BD_WIDTH, MAX_LENGTH
+from batch_img.orientation import Orientation
+from batch_img.rotate import Rotate
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+
+class Defaults:
+    @staticmethod
+    def resize_add_border(in_path: Path, out_path: Path) -> tuple:
+        """Resize and add border to an image file:
+        * 1280 as the max length
+        * the border of 5-pixel width in green color
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+
+        Returns:
+            tuple: bool, str
+        """
+        try:
+            with Image.open(in_path) as img:
+                # Resize
+                max_size = (MAX_LENGTH, MAX_LENGTH)
+                img.thumbnail(max_size, Image.Resampling.LANCZOS)
+
+                # Add border
+                width, height = img.size
+                logger.info(f"{width=}, {height=}")
+                box = Common.get_crop_box(width, height, BD_WIDTH)
+                cropped_img = img.crop(box)
+                bd_img = Image.new(img.mode, (width, height), BD_COLOR)
+                bd_img.paste(cropped_img, (BD_WIDTH, BD_WIDTH))
+
+                out_path.mkdir(parents=True, exist_ok=True)
+                out_file = out_path
+                if out_path.is_dir():
+                    filename = (
+                        f"{in_path.stem}_{MAX_LENGTH}_bw{BD_WIDTH}{in_path.suffix}"
+                    )
+                    out_file = Path(f"{out_path}/{filename}")
+
+                exif_dict = None
+                if "exif" in img.info:
+                    exif_dict = piexif.load(img.info["exif"])
+                if exif_dict:
+                    exif_bytes = piexif.dump(exif_dict)
+                    bd_img.save(out_file, img.format, optimize=True, exif=exif_bytes)
+                else:
+                    bd_img.save(out_file, img.format, optimize=True)
+            logger.info(f"Saved {out_file}")
+            return True, out_file
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            return False, f"{in_path}:\n{e}"
+
+    @staticmethod
+    def rotate_if_needed(in_path: Path, out_path: Path) -> tuple:
+        """Rotate if the image is upside down or sideways
+
+        Args:
+            in_path: image file path
+            out_path: output dir path
+
+        Returns:
+            tuple: bool, file path
+        """
+        # JL 2025-08-18: not get orientation from EXIF as it's unreliable
+        # cw_angle = Orientation.exif_orientation_2_cw_angle(in_path)
+        # logger.info(f"From exif: {cw_angle=}")
+        cw_angle = Orientation().get_cw_angle_by_face(in_path)
+        logger.info(f"By face: {cw_angle=}")
+        if cw_angle in {-1, 0}:
+            logger.warning(f"Skip due to bad or 0 clockwise angle: {cw_angle=}")
+            return False, in_path
+        ok, out_file = Rotate.rotate_1_image_file(in_path, out_path, cw_angle)
+        return ok, out_file
+
+    @staticmethod
+    def do_actions(in_path: Path, out_path: Path) -> tuple:
+        """Do default actions on one image file:
+        * Resize to 1280 pixels as the max length
+        * Add the border of 5 pixel width in green color
+        * Auto-rotate if upside down or sideways
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+
+        Returns:
+            tuple: bool, str
+        """
+        _, file = Defaults.rotate_if_needed(in_path, out_path)
+        return Defaults.resize_add_border(file, out_path)
+
+    @staticmethod
+    def run_on_all(in_path: Path, out_path: Path) -> bool:
+        """Apply default actions on all images in a folder
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        image_files = Common.prepare_all_files(in_path, out_path)
+        tasks = [(f, out_path) for f in image_files]
+        files_cnt = len(tasks)
+        if files_cnt == 0:
+            logger.error(f"No image files at {in_path}")
+            return False
+
+        logger.info(f"Do default actions on {files_cnt} files in multiprocess ...")
+        success_cnt = Common.multiprocess_progress_bar(
+            Defaults.do_actions, "Default action on image files", tasks
+        )
+        logger.info(f"\nFinished default actions on {success_cnt}/{files_cnt} files")
+        return True

batch_img/interface.py

@@ -0,0 +1,148 @@
+"""interface.py - define CLI interface
+Copyright © 2025 John Liu
+"""
+
+import click
+
+from batch_img.common import Common
+from batch_img.const import MSG_BAD, MSG_OK
+from batch_img.main import Main
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+@click.option("--version", is_flag=True, help="Show this tool's version")
+def cli(ctx, version):  # pragma: no cover
+    if not ctx.invoked_subcommand:
+        if version:
+            click.secho(Common.get_version())
+
+
+@cli.command(help="Add internal border to image file(s), not expand the size")
+@click.argument(
+    "src_path",
+    required=True,
+)
+@click.option(
+    "-bw",
+    "--border_width",
+    default=5,
+    show_default=True,
+    type=click.IntRange(min=0, max=30),
+    help="Add border to image file(s) with the border_width. 0 - no border",
+)
+@click.option(
+    "-bc",
+    "--border_color",
+    default="gray",
+    show_default=True,
+    help="Add border to image file(s) with the border_color string",
+)
+@click.option(
+    "-o",
+    "--output",
+    default="",
+    show_default=True,
+    type=str,
+    help="Output file path. If skipped, use the current dir path",
+)
+def border(src_path, border_width, border_color, output):
+    options = {
+        "src_path": src_path,
+        "border_width": border_width,
+        "border_color": border_color,
+        "output": output,
+    }
+    res = Main.border(options)
+    msg = MSG_OK if res else MSG_BAD
+    click.secho(msg)
+
+
+@cli.command(
+    help="Process image file(s) with default actions:\n"
+    "1) resize to 1280; 2) add 5-pixel green color border; 3) auto-rotate if needed"
+)
+@click.argument(
+    "src_path",
+    required=True,
+)
+@click.option(
+    "-o",
+    "--output",
+    default="",
+    show_default=True,
+    type=str,
+    help="Output file path. If skipped, use the current dir path",
+)
+def defaults(src_path, output):
+    """Do the default action on the image file(s):
+    * Resize to 1280 pixels as the max length
+    * Add the border of 5 pixel width in green color
+    * Auto-rotate if upside down or sideways
+    """
+    options = {"src_path": src_path, "output": output}
+    res = Main.default_run(options)
+    msg = MSG_OK if res else MSG_BAD
+    click.secho(msg)
+
+
+@cli.command(help="Resize image file(s)")
+@click.argument(
+    "src_path",
+    required=True,
+)
+@click.option(
+    "-l",
+    "--length",
+    is_flag=False,
+    default=0,
+    show_default=True,
+    type=click.IntRange(min=0),
+    help="Resize image file(s) on original aspect ratio to the length. 0 - no resize",
+)
+@click.option(
+    "-o",
+    "--output",
+    default="",
+    show_default=True,
+    type=str,
+    help="Output file path. If skipped, use the current dir path",
+)
+def resize(src_path, length, output):
+    options = {"src_path": src_path, "length": length, "output": output}
+    res = Main.resize(options)
+    msg = MSG_OK if res else MSG_BAD
+    click.secho(msg)
+
+
+@cli.command(help="Rotate image file(s)")
+@click.argument(
+    "src_path",
+    required=True,
+)
+@click.option(
+    "-a",
+    "--angle",
+    is_flag=False,
+    default=0,
+    show_default=True,
+    type=click.IntRange(min=0),
+    help="Rotate image file(s) to the clockwise angle. 0 - no rotate",
+)
+@click.option(
+    "-o",
+    "--output",
+    default="",
+    show_default=True,
+    type=str,
+    help="Output file path. If skipped, use the current dir path",
+)
+def rotate(src_path, angle, output):
+    options = {
+        "src_path": src_path,
+        "angle": angle,
+        "output": output,
+    }
+    res = Main.rotate(options)
+    msg = MSG_OK if res else MSG_BAD
+    click.secho(msg)

batch_img/main.py

@@ -0,0 +1,137 @@
+"""class Main: the entry point of the tool
+Copyright © 2025 John Liu
+"""
+
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+from loguru import logger
+
+from batch_img.border import Border
+from batch_img.const import PKG_NAME, TS_FORMAT
+from batch_img.defaults import Defaults
+from batch_img.resize import Resize
+from batch_img.rotate import Rotate
+
+
+class Main:
+    @staticmethod
+    def init_log_file() -> str:
+        """Set up the unique name log file for each run
+
+        Returns:
+            str: log file path
+        """
+        log_file = f"run_{PKG_NAME}_{datetime.now().strftime(TS_FORMAT)}.log"
+        logger.add(
+            f"{os.getcwd()}/{log_file}", backtrace=True, diagnose=True, enqueue=True
+        )
+        return log_file
+
+    @staticmethod
+    def resize(options: dict) -> bool:
+        """Resize the image file(s)
+
+        Args:
+            options: input options dict
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        logger.info(f"{json.dumps(options, indent=2)}")
+        Main.init_log_file()
+        in_path = Path(options["src_path"])
+        length = options.get("length")
+        output = options.get("output")
+        if not length or length == 0:
+            logger.warning(f"No resize due to bad {length=}")
+            return False
+        if not output:
+            output = Path(os.getcwd())
+        else:
+            output = Path(output)
+        if in_path.is_file():
+            ok, _ = Resize.resize_an_image(in_path, output, length)
+        else:
+            ok = Resize.resize_all_progress_bar(in_path, output, length)
+        return ok
+
+    @staticmethod
+    def rotate(options: dict) -> bool:
+        """Rotate the image file(s)
+
+        Args:
+            options: input options dict
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        logger.info(f"{json.dumps(options, indent=2)}")
+        Main.init_log_file()
+        in_path = Path(options["src_path"])
+        angle = options.get("angle")
+        output = options.get("output")
+        if not angle or angle == 0:
+            logger.warning(f"No rotate due to bad {angle=}")
+            return False
+        if not output:
+            output = Path(os.getcwd())
+        else:
+            output = Path(output)
+        if in_path.is_file():
+            ok, _ = Rotate.rotate_1_image_file(in_path, output, angle)
+        else:
+            ok = Rotate.rotate_all_in_dir(in_path, output, angle)
+        return ok
+
+    @staticmethod
+    def border(options: dict) -> bool:
+        """Add border to the image file(s)
+
+        Args:
+            options: input options dict
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        logger.info(f"{json.dumps(options, indent=2)}")
+        Main.init_log_file()
+        in_path = Path(options["src_path"])
+        bd_width = options.get("border_width")
+        bd_color = options.get("border_color")
+        output = options.get("output")
+        if not bd_width or bd_width == 0:
+            logger.warning(f"No add border due to bad {bd_width=}")
+            return False
+        if not output:
+            output = Path(os.getcwd())
+        else:
+            output = Path(output)
+        if in_path.is_file():
+            ok, _ = Border.add_border_1_image(in_path, output, bd_width, bd_color)
+        else:
+            ok = Border.add_border_all_in_dir(in_path, output, bd_width, bd_color)
+        return ok
+
+    @staticmethod
+    def default_run(options: dict) -> bool:
+        """Do the default action on the image file(s):
+        * Resize to 1280 pixels as the max length
+        * Add the border of 5 pixel width in green color
+        * Auto-rotate if upside down or sideways
+        """
+        logger.info(f"{json.dumps(options, indent=2)}")
+        Main.init_log_file()
+        in_path = Path(options["src_path"])
+        output = options.get("output")
+        if not output:
+            output = Path(os.getcwd())
+        else:
+            output = Path(output)
+        if in_path.is_file():
+            ok, _ = Defaults.do_actions(in_path, output)
+        else:
+            ok = Defaults.run_on_all(in_path, output)
+        return ok

batch_img/orientation.py

@@ -0,0 +1,112 @@
+"""class Orientation: detect if the image file(s) is upside down or sideways
+Copyright © 2025 John Liu
+"""
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+import pillow_heif
+from loguru import logger
+from PIL import Image
+
+from batch_img.common import Common
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+ORIENTATION_MAP = {
+    1: "normal",
+    2: "mirrored_horizontal",
+    3: "upside_down",
+    4: "mirrored_vertical",
+    5: "rotated_left_mirrored",
+    6: "rotated_left",
+    7: "rotated_right_mirrored",
+    8: "rotated_right",
+}
+EXIF_CW_ANGLE = {
+    1: 0,
+    2: 0,
+    3: 180,
+    4: 180,
+    5: 270,
+    6: 270,
+    7: 90,
+    8: 90,
+}
+
+
+class Orientation:
+    @staticmethod
+    def exif_orientation_2_cw_angle(file: Path) -> int:
+        """Get image orientation by EXIF data
+
+        Args:
+            file: image file path
+
+        Returns:
+            int: clockwise angle: 0, 90, 180, 270
+        """
+        try:
+            with Image.open(file) as img:
+                if "exif" not in img.info:
+                    logger.warning(f"No EXIF data in {file}")
+                    return -1
+                exif_info = Common.decode_exif(img.info["exif"])
+                if "Orientation" in exif_info:
+                    return EXIF_CW_ANGLE.get(exif_info["Orientation"])
+            logger.warning(f"No 'Orientation' tag in {exif_info=}")
+            return -1
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            logger.error(e)
+            return -1
+
+    @staticmethod
+    def _rotate_image(img, angle: int):
+        """Helper to rotate image by the clock wise angle degree
+
+        Args:
+            img: image data
+            angle: angle degree int: 0, 90, 180, 270
+
+        Returns:
+            image data
+        """
+        if angle == 90:
+            return cv2.rotate(img, cv2.ROTATE_90_CLOCKWISE)
+        if angle == 180:
+            return cv2.rotate(img, cv2.ROTATE_180)
+        if angle == 270:
+            return cv2.rotate(img, cv2.ROTATE_90_COUNTERCLOCKWISE)
+        return img
+
+    def get_cw_angle_by_face(self, file: Path) -> int:
+        """Detect orientation by face in mage by Haar Cascades:
+        * Fastest but least accurate
+        * Works best with frontal faces
+        * May produce false positives
+
+        Args:
+            file: image file path
+
+        Returns:
+            int: clockwise angle: 0, 90, 180, 270
+        """
+        face_cascade = cv2.CascadeClassifier(
+            cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
+        )
+        with Image.open(file) as safe_img:
+            opencv_img = np.array(safe_img)
+            if opencv_img is None:
+                raise ValueError(f"Failed to load {file}")
+            for angle_cw in (0, 90, 180, 270):
+                img = self._rotate_image(opencv_img, angle_cw)
+                gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+                faces = face_cascade.detectMultiScale(
+                    gray, scaleFactor=1.2, minNeighbors=6
+                )
+                # logger.info(f"{len(faces)=}")
+                if len(faces) > 0:
+                    return angle_cw
+        logger.warning(f"Found no face in {file}")
+        return -1

batch_img/resize.py

@@ -0,0 +1,79 @@
+"""class Resize: resize the image file(s)
+Copyright © 2025 John Liu
+"""
+
+from pathlib import Path
+
+import piexif
+import pillow_heif
+from loguru import logger
+from PIL import Image
+
+from batch_img.common import Common
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+
+class Resize:
+    @staticmethod
+    def resize_an_image(in_path: Path, out_path: Path, length: int) -> tuple:
+        """Resize an image file and save to the output dir
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+            length: max length (width or height) in pixels
+
+        Returns:
+            tuple: bool, output file path
+        """
+        try:
+            with Image.open(in_path) as img:
+                max_size = (length, length)
+                # The thumbnail() keeps the original aspect ratio
+                img.thumbnail(max_size, Image.Resampling.LANCZOS)
+
+                out_path.mkdir(parents=True, exist_ok=True)
+                out_file = out_path
+                if out_path.is_dir():
+                    filename = f"{in_path.stem}_{length}{in_path.suffix}"
+                    out_file = Path(f"{out_path}/{filename}")
+
+                exif_dict = None
+                if "exif" in img.info:
+                    exif_dict = piexif.load(img.info["exif"])
+                if exif_dict:
+                    exif_bytes = piexif.dump(exif_dict)
+                    img.save(out_file, img.format, optimize=True, exif=exif_bytes)
+                else:
+                    img.save(out_file, img.format, optimize=True)
+            logger.info(f"Saved {out_file}")
+            return True, out_file
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            return False, f"{in_path}:\n{e}"
+
+    @staticmethod
+    def resize_all_progress_bar(in_path: Path, out_path: Path, length: int) -> bool:
+        """Resize all image files in the given dir
+
+        Args:
+            in_path: input dir path
+            out_path: output dir path
+            length: max length (width or height) in pixels
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        image_files = Common.prepare_all_files(in_path, out_path)
+        if not image_files:
+            logger.error(f"No image files at {in_path}")
+            return False
+        tasks = [(f, out_path, length) for f in image_files]
+        files_cnt = len(tasks)
+
+        logger.info(f"Resize {files_cnt} image files in multiprocess ...")
+        success_cnt = Common.multiprocess_progress_bar(
+            Resize.resize_an_image, "Resize image files", tasks
+        )
+        logger.info(f"\nSuccessfully resized {success_cnt}/{files_cnt} files")
+        return True

batch_img/rotate.py

@@ -0,0 +1,121 @@
+"""class Rotate: rotate image file(s) to clockwise angle
+Copyright © 2025 John Liu
+"""
+
+import os
+from pathlib import Path
+
+import piexif
+import pillow_heif
+from loguru import logger
+from PIL import Image
+
+from batch_img.common import Common
+
+pillow_heif.register_heif_opener()  # allow Pillow to open HEIC files
+
+
+class Rotate:
+    @staticmethod
+    def set_exif_orientation(file: Path, o_val: int) -> bool:
+        """Set orientation in the EXIF of an image file
+
+        Args:
+            file: image file path
+            o_val: orientation value int
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        if o_val not in {1, 2, 3, 4, 5, 6, 7, 8}:
+            logger.error(f"Quit due to bad orientation value: {o_val=}")
+            return False
+        try:
+            tmp_file = Path(f"{file.parent}/{file.stem}_tmp{file.suffix}")
+            with Image.open(file) as img:
+                exif_dict = {"0th": {}, "Exif": {}}
+                if "exif" in img.info:
+                    exif_dict = piexif.load(img.info["exif"])
+                exif_dict["0th"][piexif.ImageIFD.Orientation] = o_val
+                exif_bytes = piexif.dump(exif_dict)
+                img.save(tmp_file, img.format, exif=exif_bytes, optimize=True)
+            logger.info(f"Saved the updated EXIF image to {tmp_file}")
+            os.replace(tmp_file, file)
+            logger.info(f"Replaced {file} with tmp_file")
+            return True
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            logger.error(e)
+            return False
+
+    @staticmethod
+    def rotate_1_image_file(in_path: Path, out_path: Path, angle_cw: int) -> tuple:
+        """Rotate an image file and save to the output dir
+
+        Args:
+            in_path: input file path
+            out_path: output dir path
+            angle_cw: rotation angle clockwise: 90, 180, or 270
+
+        Returns:
+            tuple: bool, str
+        """
+        if angle_cw not in {90, 180, 270}:
+            return False, f"Bad {angle_cw=}. Only allow 90, 180, 270"
+        try:
+            with Image.open(in_path) as img:
+                exif_dict = {"0th": {}, "Exif": {}}
+                if "exif" in img.info:
+                    exif_dict = piexif.load(img.info["exif"])
+                # logger.info(f"{exif_dict=}")
+                exif_dict["0th"][piexif.ImageIFD.Orientation] = 1
+                exif_bytes = piexif.dump(exif_dict)
+
+                out_path.mkdir(parents=True, exist_ok=True)
+                out_file = out_path
+                if out_path.is_dir():
+                    filename = f"{in_path.stem}_{angle_cw}cw{in_path.suffix}"
+                    out_file = Path(f"{out_path}/{filename}")
+                # img.rotate() for any angle (slower & slight quality loss)
+                if angle_cw == 90:
+                    rotated_img = img.transpose(Image.ROTATE_270)
+                elif angle_cw == 180:
+                    rotated_img = img.transpose(Image.ROTATE_180)
+                elif angle_cw == 270:
+                    rotated_img = img.transpose(Image.ROTATE_90)
+                else:
+                    rotated_img = img
+
+                rotated_img.save(out_file, img.format, exif=exif_bytes, optimize=True)
+            logger.info(f"Saved ({angle_cw}°) clockwise rotated to {out_file}")
+            return True, out_file
+        except (AttributeError, FileNotFoundError, ValueError) as e:
+            return False, f"{in_path}:\n{e}"
+
+    @staticmethod
+    def rotate_all_in_dir(in_path: Path, out_path: Path, angle_cw: int) -> bool:
+        """Rotate all image files in the given dir
+
+        Args:
+            in_path: input dir path
+            out_path: output dir path
+            angle_cw: rotation angle clockwise: 90, 180, or 270
+
+        Returns:
+            bool: True - Success. False - Error
+        """
+        if angle_cw not in {90, 180, 270}:
+            logger.error(f"Bad {angle_cw=}. Only allow 90, 180, 270")
+            return False
+        image_files = Common.prepare_all_files(in_path, out_path)
+        if not image_files:
+            logger.error(f"No image files at {in_path}")
+            return False
+        tasks = [(f, out_path, angle_cw) for f in image_files]
+        files_cnt = len(tasks)
+
+        logger.info(f"Rotate {files_cnt} image files in multiprocess ...")
+        success_cnt = Common.multiprocess_progress_bar(
+            Rotate.rotate_1_image_file, "Rotate image files", tasks
+        )
+        logger.info(f"\nSuccessfully rotated {success_cnt}/{files_cnt} files")
+        return True

batch_img-0.0.7.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: batch_img
+Version: 0.0.7
+Summary: Batch processing image files by utilizing Pillow / PIL library
+Author: John Liu
+Project-URL: Download, https://artifacts.some.where
+Project-URL: Homepage, https://github.com/john-liu2/batch_img
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: loguru
+Requires-Dist: piexif
+Requires-Dist: pillow
+Requires-Dist: pillow-heif
+Requires-Dist: tqdm
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Dynamic: license-file
+
+## batch_img
+
+Batch processing image files by utilizing **[Pillow / PIL](https://github.com/python-pillow/Pillow)** library.
+Resize, rotate, add border or do default actions on a single image file or all image files in a folder.
+Tested these image file formats (**HEIC, JPG, PNG**) on macOS.
+
+### Installation
+
+#### One Time Setup
+
+One time installation of the `uv` tool to prepare for **All** future Python tools installation.
+Install `uv` tool by its standalone installers:
+
+```
+# On macOS and Linux.
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+```
+# On Windows.
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+#### Install the `batch_img` tool
+
+Install the `batch_img` tool from PyPI:
+
+```
+uv pip install --upgrade batch_img
+```
+
+### Usage
+
+#### Sample command lines:
+
+```
+✗ batch_img --version
+0.0.7
+
+✗ batch_img rotate --degree 90 ~/Downloads/IMG_0070.HEIC
+...
+✅ Processed the image file(s)
+```
+
+### Help
+
+#### Top level commands help:
+
+```
+✗ batch_img --help
+Usage: batch_img [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --version  Show this tool's version
+  --help     Show this message and exit.
+
+Commands:
+  border    Add border to image file(s)
+  defaults  Process image file(s) with default actions: 1) resize to...
+  resize    Resize image file(s)
+  rotate    Rotate image file(s)
+```
+
+#### The `border` sub-command CLI options:
+
+```
+✗ batch_img border --help
+Usage: batch_img border [OPTIONS] SRC_PATH
+
+  Add internal border to image file(s), not expand the size
+
+Options:
+  -bw, --border_width INTEGER RANGE
+                                  Add border to image file(s) with the
+                                  border_width. 0 - no border  [default: 5;
+                                  0<=x<=30]
+  -bc, --border_color TEXT        Add border to image file(s) with the
+                                  border_color string  [default: gray]
+  -o, --output TEXT               Output file path. If skipped, use the
+                                  current dir path  [default: ""]
+  --help                          Show this message and exit.
+```
+
+#### The `defaults` sub-command CLI options:
+
+```
+✗ batch_img defaults --help
+Usage: batch_img defaults [OPTIONS] SRC_PATH
+
+  Process image file(s) with default actions: 1) resize to 1280; 2) add
+  5-pixel gray color border; 3) auto-rotate if needed
+
+Options:
+  -o, --output TEXT  Output file path. If skipped, use the current dir path
+                     [default: ""]
+  --help             Show this message and exit.
+```
+
+#### The `resize` sub-command CLI options:
+
+```
+✗ batch_img resize --help
+Usage: batch_img resize [OPTIONS] SRC_PATH
+
+  Resize image file(s)
+
+Options:
+  -l, --length INTEGER RANGE  Resize image file(s) on original aspect ratio to
+                              the length. 0 - no resize  [default: 0; x>=0]
+  -o, --output TEXT           Output file path. If skipped, use the current
+                              dir path  [default: ""]
+  --help                      Show this message and exit.
+```
+
+#### The `rotate` sub-command CLI options:
+
+```
+✗ batch_img rotate --help
+Usage: batch_img rotate [OPTIONS] SRC_PATH
+
+  Rotate image file(s)
+
+Options:
+  -a, --angle INTEGER RANGE  Rotate image file(s) to the clockwise angle. 0 -
+                             no rotate  [default: 0; x>=0]
+  -o, --output TEXT          Output file path. If skipped, use the current dir
+                             path  [default: ""]
+  --help                     Show this message and exit.
+```

batch_img-0.0.7.dist-info/RECORD

@@ -0,0 +1,16 @@
+batch_img/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+batch_img/border.py,sha256=BrdyiKPkIkVnXKamxiWsnkh0PdF466NfwULjCj38A_g,3058
+batch_img/common.py,sha256=M-uTuEwTcOw2CKEyGHJdKGsnyZUf08bFcxLfuIser3Q,7847
+batch_img/const.py,sha256=gy5DtaMdsV8EivfBHOI-Ur1swZU8zrKailpwLYd5e6M,439
+batch_img/defaults.py,sha256=SoImENWwfrReu_WxE7EPZlNsBAzm9MkRrX6wzkqfE74,4782
+batch_img/interface.py,sha256=4mLLAulzOYhUBA_f22mqcggHKMYqHeiLPvyKO60t7oo,3577
+batch_img/main.py,sha256=TGk9KQSNaq4K_571AVW4ydA5R54iCZ_cJREKKkFDyUg,4215
+batch_img/orientation.py,sha256=dRxN5gqGeyn6Ch4g3Bzi2TyyIaRb4YC6EDpZsJwwPKk,3243
+batch_img/resize.py,sha256=KyUZSTEsHEqt_TVlOleGEIFf_Pq-j2ZejBXNVyiOxV8,2725
+batch_img/rotate.py,sha256=wFv0gCmqFOjzThVLgTjCWb5rLQrQKE3SdvdyN7To81Y,4579
+batch_img-0.0.7.dist-info/licenses/LICENSE,sha256=2IE5k441iviLxA3Qx_pNq7f1SFbLLxT6oC5EXaGC0gY,1065
+batch_img-0.0.7.dist-info/METADATA,sha256=E7oDGQwsdjNhttKu4B_Pd5EEtMySOnKNJQZJEhdTx80,4326
+batch_img-0.0.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+batch_img-0.0.7.dist-info/entry_points.txt,sha256=o7E04t_Y7i9wcd4YMjJBKR5l0pnOaU-HiuHMf3s5Ds4,54
+batch_img-0.0.7.dist-info/top_level.txt,sha256=KUBx0Cw8yaA0XQMJf3yf0pJDm-5ojMMQtG7k1A9kYz8,10
+batch_img-0.0.7.dist-info/RECORD,,

batch_img-0.0.7.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

batch_img-0.0.7.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+batch_img = batch_img.interface:cli

batch_img-0.0.7.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

batch_img-0.0.7.dist-info/top_level.txt

@@ -0,0 +1 @@
+batch_img