## batch_img
Batch process (**resize, rotate, remove background, remove GPS, add border,
set transparency, auto do all**) image files (**HEIC, JPG, PNG**) by
utilizing **[Pillow / PIL](https://github.com/python-pillow/Pillow)** library.
It can apply the action(s) on a single image file or all image files in the input
folder / directory. Tested working on **macOS** and **Windows**.
### Installation
#### Requirements
```
python: >=3.12, <3.14
```
#### One-time Setup
Install the Astral's [`uv`](https://github.com/astral-sh/uv) tool one-time to
prepare for **all** Python tools and packages installation. Install the Astral's
[`uv`](https://github.com/astral-sh/uv) by its standalone installers:
```
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install the latest Python by uv command
uv python install 3.13
# Create the Python virtualenv by uv command
uv venv
# Activate the Python virtualenv
source .venv/bin/activate
```
```
# On Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# Add uv command into environment search path
$env:Path = "C:\Users\{your_user_name}\.local\bin:$env:Path"
# Create the Python virtualenv by uv command
uv venv
# Activate the Python virtualenv
.venv\Scripts\activate
```
#### Install the `batch_img` tool
Install the `batch_img` tool from PyPI by the Astral's
[`uv`](https://github.com/astral-sh/uv) command:
```
uv pip install --upgrade batch_img
```
### Usage
#### Sample command line usage:
```
✗ batch_img --version
0.3.5
✗ batch_img auto ~/Documents
Resize to 1920-pixel max length. Remove GPS location info. Add 5-pixel width black color border.
...
Auto processed 8/8 files
✅ Processed the image file(s)
```
### Contribution
Contributions are welcome!
Please see the details in [Contribution Guidelines](https://github.com/john-liu2/batch_img/blob/main/CONTRIBUTING.md)
### Help
#### Top level commands help:
```
✗ batch_img --help
Usage: batch_img [OPTIONS] COMMAND [ARGS]...
Options:
--update Update the tool to the latest version.
--version Show the tool's version.
--help Show this message and exit.
Commands:
auto Auto process (resize to 1920-px, remove GPS, add border)...
border Add internal border to image file(s), not expand the size.
do-effect Do special effect to image file(s).
remove-bg Remove background (make background transparent) in image...
remove-gps Remove GPS location info in image file(s).
resize Resize image file(s).
rotate Rotate image file(s).
transparent Set transparency on image file(s).
```
#### The `auto` sub-command CLI options:
```
✗ batch_img auto --help
Usage: batch_img auto [OPTIONS] SRC_PATH
Auto process (resize to 1920, remove GPS, add border) image file(s).
Options:
-ar, --auto_rotate Auto-rotate image (experimental)
-o, --output TEXT Output file path. If not specified, replace the input
file. [default: ""]
--help Show this message and exit.
```
#### 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 not specified, replace
the input file. [default: ""]
--help Show this message and exit.
```
#### The `do-effect` sub-command CLI options:
```
✗ batch_img do-effect --help
Usage: batch_img do-effect [OPTIONS] SRC_PATH
Do special effect to image file(s).
Options:
-e, --effect [blur|hdr|neon] Do special effect to image file(s): blur, hdr,
neon. [default: neon]
-o, --output TEXT Output dir path. If not specified, add special
effect image file(s) to the same path as the
input file(s). [default: ""]
--help Show this message and exit.
```
#### The `remove-bg` sub-command CLI options:
```
✗ batch_img remove-bg --help
Usage: batch_img remove-bg [OPTIONS] SRC_PATH
Remove background (make background transparent) in image file(s).
Options:
-o, --output TEXT Output file path. If not specified, replace the input
file. [default: ""]
--help Show this message and exit.
```
#### The `remove-gps` sub-command CLI options:
```
✗ batch_img remove-gps --help
Usage: batch_img remove-gps [OPTIONS] SRC_PATH
Remove GPS location info in image file(s).
Options:
-o, --output TEXT Output file path. If not specified, replace the input
file. [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 max side length. 0 - no resize. [default:
0; x>=0]
-o, --output TEXT Output file path. If not specified, replace the
input file. [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 [0|90|180|270] Rotate image file(s) to the clockwise angle. 0 -
no rotate. [default: 0]
-o, --output TEXT Output file path. If not specified, replace the
input file. [default: ""]
--help Show this message and exit.
```
#### The `transparent` sub-command CLI options:
```
✗ batch_img transparent --help
Usage: batch_img transparent [OPTIONS] SRC_PATH
Set transparency on image file(s).
Options:
-o, --output TEXT Output file path. If not specified, replace
the input file. If the input file is JPEG,
it will be saved as PNG file because JPEG
does not support transparency [default: ""]
-t, --transparency INTEGER RANGE
Set transparency on image file(s). 0 - fully
transparent, 255 - completely opaque.
[default: 127; 0<=x<=255]
-w, --white Make white pixels fully transparent.
--help Show this message and exit.
```
### License
**batch_img** is distributed under MIT License. Please see details in
[LICENSE](https://github.com/john-liu2/batch_img/blob/main/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "batch-img",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "cli-tool, image-processing, batch-processing, special-effect, remove-background, remove-gps, resize-image, rotate-image",
"author": null,
"author_email": "John Liu <rim2rim@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/fd/225dc2a8c4ccf9c1a8aba1e94c360051787d08c0edd5d4100c2d671f6e69/batch_img-0.3.5.tar.gz",
"platform": null,
"description": "## batch_img\n\nBatch process (**resize, rotate, remove background, remove GPS, add border,\nset transparency, auto do all**) image files (**HEIC, JPG, PNG**) by\nutilizing **[Pillow / PIL](https://github.com/python-pillow/Pillow)** library.\nIt can apply the action(s) on a single image file or all image files in the input\nfolder / directory. Tested working on **macOS** and **Windows**.\n\n### Installation\n\n#### Requirements\n\n```\npython: >=3.12, <3.14\n```\n\n#### One-time Setup\n\nInstall the Astral's [`uv`](https://github.com/astral-sh/uv) tool one-time to\nprepare for **all** Python tools and packages installation. Install the Astral's\n[`uv`](https://github.com/astral-sh/uv) by its standalone installers:\n\n```\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Install the latest Python by uv command\nuv python install 3.13\n\n# Create the Python virtualenv by uv command\nuv venv\n\n# Activate the Python virtualenv\nsource .venv/bin/activate\n```\n\n```\n# On Windows (PowerShell)\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Add uv command into environment search path\n$env:Path = \"C:\\Users\\{your_user_name}\\.local\\bin:$env:Path\"\n\n# Create the Python virtualenv by uv command\nuv venv\n\n# Activate the Python virtualenv\n.venv\\Scripts\\activate\n```\n\n#### Install the `batch_img` tool\n\nInstall the `batch_img` tool from PyPI by the Astral's\n[`uv`](https://github.com/astral-sh/uv) command:\n\n```\nuv pip install --upgrade batch_img\n```\n\n### Usage\n\n#### Sample command line usage:\n\n```\n\u2717 batch_img --version\n0.3.5\n\n\n\u2717 batch_img auto ~/Documents\nResize to 1920-pixel max length. Remove GPS location info. Add 5-pixel width black color border.\n...\nAuto processed 8/8 files\n\u2705 Processed the image file(s)\n```\n\n### Contribution\n\nContributions are welcome!\nPlease see the details in [Contribution Guidelines](https://github.com/john-liu2/batch_img/blob/main/CONTRIBUTING.md)\n\n### Help\n\n#### Top level commands help:\n\n```\n\u2717 batch_img --help\nUsage: batch_img [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n --update Update the tool to the latest version.\n --version Show the tool's version.\n --help Show this message and exit.\n\nCommands:\n auto Auto process (resize to 1920-px, remove GPS, add border)...\n border Add internal border to image file(s), not expand the size.\n do-effect Do special effect to image file(s).\n remove-bg Remove background (make background transparent) in image...\n remove-gps Remove GPS location info in image file(s).\n resize Resize image file(s).\n rotate Rotate image file(s).\n transparent Set transparency on image file(s).\n```\n\n#### The `auto` sub-command CLI options:\n\n```\n\u2717 batch_img auto --help\nUsage: batch_img auto [OPTIONS] SRC_PATH\n\n Auto process (resize to 1920, remove GPS, add border) image file(s).\n\nOptions:\n -ar, --auto_rotate Auto-rotate image (experimental)\n -o, --output TEXT Output file path. If not specified, replace the input\n file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `border` sub-command CLI options:\n\n```\n\u2717 batch_img border --help\nUsage: batch_img border [OPTIONS] SRC_PATH\n\n Add internal border to image file(s), not expand the size.\n\nOptions:\n -bw, --border_width INTEGER RANGE\n Add border to image file(s) with the\n border_width. 0 - no border. [default: 5;\n 0<=x<=30]\n -bc, --border_color TEXT Add border to image file(s) with the\n border_color string. [default: gray]\n -o, --output TEXT Output file path. If not specified, replace\n the input file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `do-effect` sub-command CLI options:\n\n```\n\u2717 batch_img do-effect --help\nUsage: batch_img do-effect [OPTIONS] SRC_PATH\n\n Do special effect to image file(s).\n\nOptions:\n -e, --effect [blur|hdr|neon] Do special effect to image file(s): blur, hdr,\n neon. [default: neon]\n -o, --output TEXT Output dir path. If not specified, add special\n effect image file(s) to the same path as the\n input file(s). [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `remove-bg` sub-command CLI options:\n\n```\n\u2717 batch_img remove-bg --help\nUsage: batch_img remove-bg [OPTIONS] SRC_PATH\n\n Remove background (make background transparent) in image file(s).\n\nOptions:\n -o, --output TEXT Output file path. If not specified, replace the input\n file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `remove-gps` sub-command CLI options:\n\n```\n\u2717 batch_img remove-gps --help\nUsage: batch_img remove-gps [OPTIONS] SRC_PATH\n\n Remove GPS location info in image file(s).\n\nOptions:\n -o, --output TEXT Output file path. If not specified, replace the input\n file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `resize` sub-command CLI options:\n\n```\n\u2717 batch_img resize --help\nUsage: batch_img resize [OPTIONS] SRC_PATH\n\n Resize image file(s).\n\nOptions:\n -l, --length INTEGER RANGE Resize image file(s) on original aspect ratio to\n the max side length. 0 - no resize. [default:\n 0; x>=0]\n -o, --output TEXT Output file path. If not specified, replace the\n input file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `rotate` sub-command CLI options:\n\n```\n\u2717 batch_img rotate --help\nUsage: batch_img rotate [OPTIONS] SRC_PATH\n\n Rotate image file(s).\n\nOptions:\n -a, --angle [0|90|180|270] Rotate image file(s) to the clockwise angle. 0 -\n no rotate. [default: 0]\n -o, --output TEXT Output file path. If not specified, replace the\n input file. [default: \"\"]\n --help Show this message and exit.\n```\n\n#### The `transparent` sub-command CLI options:\n\n```\n\u2717 batch_img transparent --help\nUsage: batch_img transparent [OPTIONS] SRC_PATH\n\n Set transparency on image file(s).\n\nOptions:\n -o, --output TEXT Output file path. If not specified, replace\n the input file. If the input file is JPEG,\n it will be saved as PNG file because JPEG\n does not support transparency [default: \"\"]\n -t, --transparency INTEGER RANGE\n Set transparency on image file(s). 0 - fully\n transparent, 255 - completely opaque.\n [default: 127; 0<=x<=255]\n -w, --white Make white pixels fully transparent.\n --help Show this message and exit.\n```\n\n### License\n\n**batch_img** is distributed under MIT License. Please see details in\n[LICENSE](https://github.com/john-liu2/batch_img/blob/main/LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "Batch process (resize, rotate, remove background, remove GPS, add border, set transparency, auto do all) image files (HEIC, JPG, PNG)",
"version": "0.3.5",
"project_urls": {
"Download": "https://pypi.org/project/batch-img/",
"Homepage": "https://github.com/john-liu2/batch_img"
},
"split_keywords": [
"cli-tool",
" image-processing",
" batch-processing",
" special-effect",
" remove-background",
" remove-gps",
" resize-image",
" rotate-image"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5874d7bae276a77d4ef880b59de6c48e8c2772d4fe675bb026dec88210e10445",
"md5": "6d5b20fb0187c4ab2359d61a3d6f13be",
"sha256": "438c730da76a1d96a4689692743ac37dc2aee5f9e2b838830b30ee456e6d42fd"
},
"downloads": -1,
"filename": "batch_img-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d5b20fb0187c4ab2359d61a3d6f13be",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 29153,
"upload_time": "2025-10-11T21:56:29",
"upload_time_iso_8601": "2025-10-11T21:56:29.265991Z",
"url": "https://files.pythonhosted.org/packages/58/74/d7bae276a77d4ef880b59de6c48e8c2772d4fe675bb026dec88210e10445/batch_img-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0efd225dc2a8c4ccf9c1a8aba1e94c360051787d08c0edd5d4100c2d671f6e69",
"md5": "df685019899b5ff58a87b128503ba509",
"sha256": "43b048ba93fd4e0f713d371119b4c971c03659ae738e78e1f6a8583357df07cb"
},
"downloads": -1,
"filename": "batch_img-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "df685019899b5ff58a87b128503ba509",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 22408,
"upload_time": "2025-10-11T21:56:30",
"upload_time_iso_8601": "2025-10-11T21:56:30.226657Z",
"url": "https://files.pythonhosted.org/packages/0e/fd/225dc2a8c4ccf9c1a8aba1e94c360051787d08c0edd5d4100c2d671f6e69/batch_img-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 21:56:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "john-liu2",
"github_project": "batch_img",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "batch-img"
}
JSON
