batch-img 0.0.7__tar.gz

batch_img-0.0.7/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/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md
+recursive-include batch_img *.sh
+prune tests

batch_img-0.0.7/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,129 @@
+## 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/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-0.0.7/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-0.0.7/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"