| Name | imgdiet JSON |
| Version |
1.0.3
JSON |
| download |
| home_page | None |
| Summary | A Python package for minimizing file size of images with minimal quality loss |
| upload_time | 2025-01-14 12:30:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | MIT License Copyright (c) 2025 Yonghye Kwon 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. |
| keywords |
image
compression
webp
psnr
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `imgdiet`
**A Python package for minimizing file size of images with negligible quality loss**
| PNG Image | WebP Image (Optimized by `imgdiet`) |
|--------------------------------------------|--------------------------------------------|
| <img src="./assets/20250105_164724.png" alt="PNG Image" width="300"> | <img src="./assets/20250105_164724.webp" alt="WebP Image" width="300"> |
| File Size: 26.9 MB | File Size : 4.1 MB, Target PSNR: 40 dB |
| JPG Image | WebP Image (Optimized by `imgdiet`) |
|--------------------------------------------|--------------------------------------------|
| <img src="./assets/xp.jpg" alt="PNG Image" width="300"> | <img src="./assets/xp.webp" alt="WebP Image" width="300"> |
| File Size: 1.5 MB | File Size : 0.3 MB, Target PSNR: 40 dB |
| JPG Image | WebP Image (Optimized by `imgdiet`) |
|--------------------------------------------|--------------------------------------------|
| <img src="./assets/pexels-wildlittlethingsphoto-1388069.jpg" alt="PNG Image" width="300"> | <img src="./assets/pexels-wildlittlethingsphoto-1388069.webp" alt="WebP Image" width="300"> |
| File Size: 2.4 MB | File Size : 1.9 MB, Target PSNR: 38 dB |
## Installation
To install `imgdiet`, use `pip`:
```bash
pip install imgdiet
```
Alternatively, you can install the package directly from the source repository:
```bash
git clone https://github.com/developer0hye/imgdiet.git
cd imgdiet
pip install .
```
## Features
- Compress images to the WebP format while preserving folder structure.
- Lossless and lossy compression options.
- Automatically optimizes compression level using PSNR (Peak Signal-to-Noise Ratio) targets.
- Supports multi-threaded processing for batch compression.
- Preserves ICC profiles and handles EXIF orientation.
- Supports various input formats including JPG, PNG, BMP, and TIFF.
## Usage
### Command-Line Interface
`imgdiet` provides a convenient CLI for compressing images:
```bash
imgdiet --source <input_path> --target <output_path> [--psnr <value>] [--verbose]
```
#### Arguments:
- `--source`: Path to an image or a directory containing images.
- `--target`: Path to the output directory or a single WebP file.
- `--psnr`: Target Peak Signal-to-Noise Ratio (default: 40.0). Use `0` for lossless compression. Higher values mean better quality but larger file size.
- `--verbose`: Enable detailed logging for the process.
#### Examples:
**Compress a single image:**
```bash
imgdiet --source image.png --target compressed_image.webp --psnr 40.0
```
**Compress a single image and save a compressed version in a directory:**
```bash
imgdiet --source ./images/image.png --target ./compressed_images/ --psnr 40.0
```
**Compress all images in a directory:**
```bash
imgdiet --source ./images --target ./compressed_images --psnr 40.0 --verbose
```
### Python API
You can also use `imgdiet` programmatically in your Python projects:
```python
from imgdiet import save
# Compress a single image
save(
source="image.png",
target="compressed_image.webp",
target_psnr=40.0,
verbose=True
)
# Compress a single image and save a compressed version in a directory
save(
source="./images/image.png",
target="./compressed_images/",
target_psnr=40.0,
verbose=True
)
# Compress all images in a directory
save(
source="./images",
target="./compressed_images",
target_psnr=40.0,
verbose=False
)
```
## How It Works
1. **Lossless Compression:** If the target PSNR is `0`, the image is compressed in lossless WebP format.
2. **Lossy Compression:** If the target PSNR is greater than `0`, the package performs a binary search to find the optimal WebP quality that meets the PSNR target.
3. **PSNR and Size Trade-off:** Higher PSNR values result in better image quality but also larger file sizes. Conversely, lower PSNR values reduce file sizes at the cost of image quality. You can adjust the PSNR to balance quality and file size according to your needs.
4. **ICC Profile Preservation:** The package retains the ICC color profile of the input image for consistent color rendering.
5. **EXIF Handling:** Automatically rotates images based on their EXIF orientation metadata.
6. **Original Image Retention:** If the compressed WebP image is larger than the original, the original image is saved instead to ensure no increase in file size.
## Supported Formats
Input formats:
- JPG / JPEG
- PNG
- BMP
- TIFF / TIF
Output format:
- WebP
## Requirements
- Python 3.8+
- Pillow (for image processing)
- tqdm (for progress bars in multi-threaded tasks)
## Limitations
- The output format is currently limited to WebP.
- ICC profile conversion to sRGB requires the `ImageCms` module, which may not be available in some environments.
## Future Plans
- **AVIF and JPEG XL Support:** We plan to add support for AVIF and JPEG XL formats in future versions. These formats offer superior compression efficiency and image quality. However, their integration requires optional dependencies since they are not natively supported by OpenCV or Pillow at this time. Once these dependencies become more accessible, they will be incorporated into `imgdiet`.
## Contributing
Contributions are welcome! If you'd like to contribute, please:
1. Fork the repository.
2. Create a feature branch (`git checkout -b feature-name`).
3. Commit your changes (`git commit -m "Add feature-name"`).
4. Push to the branch (`git push origin feature-name`).
5. Open a pull request.
## License
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
---
Enjoy compressing your images efficiently with `imgdiet`!
## Acknowledgements
This project was developed with assistance from advanced AI tools 🤖, including ChatGPT, Claude 3.5 Sonnet, and Cursor AI, which provided guidance and feedback throughout the process.
Raw data
{
"_id": null,
"home_page": null,
"name": "imgdiet",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "image, compression, webp, psnr",
"author": null,
"author_email": "Yonghye Kwon <developer.0hye@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/61/f6/5ba3701048409c2af74e2eeb56b6c605d4956c6dbf224667980f2f515f2c/imgdiet-1.0.3.tar.gz",
"platform": null,
"description": "# `imgdiet`\n\n**A Python package for minimizing file size of images with negligible quality loss**\n\n| PNG Image | WebP Image (Optimized by `imgdiet`) |\n|--------------------------------------------|--------------------------------------------|\n| <img src=\"./assets/20250105_164724.png\" alt=\"PNG Image\" width=\"300\"> | <img src=\"./assets/20250105_164724.webp\" alt=\"WebP Image\" width=\"300\"> |\n| File Size: 26.9 MB | File Size : 4.1 MB, Target PSNR: 40 dB |\n\n| JPG Image | WebP Image (Optimized by `imgdiet`) |\n|--------------------------------------------|--------------------------------------------|\n| <img src=\"./assets/xp.jpg\" alt=\"PNG Image\" width=\"300\"> | <img src=\"./assets/xp.webp\" alt=\"WebP Image\" width=\"300\"> |\n| File Size: 1.5 MB | File Size : 0.3 MB, Target PSNR: 40 dB |\n\n| JPG Image | WebP Image (Optimized by `imgdiet`) |\n|--------------------------------------------|--------------------------------------------|\n| <img src=\"./assets/pexels-wildlittlethingsphoto-1388069.jpg\" alt=\"PNG Image\" width=\"300\"> | <img src=\"./assets/pexels-wildlittlethingsphoto-1388069.webp\" alt=\"WebP Image\" width=\"300\"> |\n| File Size: 2.4 MB | File Size : 1.9 MB, Target PSNR: 38 dB |\n\n## Installation\n\nTo install `imgdiet`, use `pip`:\n\n```bash\npip install imgdiet\n```\n\nAlternatively, you can install the package directly from the source repository:\n\n```bash\ngit clone https://github.com/developer0hye/imgdiet.git\ncd imgdiet\npip install .\n```\n\n## Features\n\n- Compress images to the WebP format while preserving folder structure.\n- Lossless and lossy compression options.\n- Automatically optimizes compression level using PSNR (Peak Signal-to-Noise Ratio) targets.\n- Supports multi-threaded processing for batch compression.\n- Preserves ICC profiles and handles EXIF orientation.\n- Supports various input formats including JPG, PNG, BMP, and TIFF.\n\n## Usage\n\n### Command-Line Interface\n\n`imgdiet` provides a convenient CLI for compressing images:\n\n```bash\nimgdiet --source <input_path> --target <output_path> [--psnr <value>] [--verbose]\n```\n\n#### Arguments:\n\n- `--source`: Path to an image or a directory containing images.\n- `--target`: Path to the output directory or a single WebP file.\n- `--psnr`: Target Peak Signal-to-Noise Ratio (default: 40.0). Use `0` for lossless compression. Higher values mean better quality but larger file size.\n- `--verbose`: Enable detailed logging for the process.\n\n#### Examples:\n\n**Compress a single image:**\n```bash\nimgdiet --source image.png --target compressed_image.webp --psnr 40.0\n```\n\n**Compress a single image and save a compressed version in a directory:**\n```bash\nimgdiet --source ./images/image.png --target ./compressed_images/ --psnr 40.0\n```\n\n**Compress all images in a directory:**\n```bash\nimgdiet --source ./images --target ./compressed_images --psnr 40.0 --verbose\n```\n\n### Python API\n\nYou can also use `imgdiet` programmatically in your Python projects:\n\n```python\nfrom imgdiet import save\n\n# Compress a single image\nsave(\n source=\"image.png\",\n target=\"compressed_image.webp\",\n target_psnr=40.0,\n verbose=True\n)\n\n# Compress a single image and save a compressed version in a directory\nsave(\n source=\"./images/image.png\",\n target=\"./compressed_images/\",\n target_psnr=40.0,\n verbose=True\n)\n\n# Compress all images in a directory\nsave(\n source=\"./images\",\n target=\"./compressed_images\",\n target_psnr=40.0,\n verbose=False\n)\n```\n\n## How It Works\n\n1. **Lossless Compression:** If the target PSNR is `0`, the image is compressed in lossless WebP format.\n2. **Lossy Compression:** If the target PSNR is greater than `0`, the package performs a binary search to find the optimal WebP quality that meets the PSNR target.\n3. **PSNR and Size Trade-off:** Higher PSNR values result in better image quality but also larger file sizes. Conversely, lower PSNR values reduce file sizes at the cost of image quality. You can adjust the PSNR to balance quality and file size according to your needs.\n4. **ICC Profile Preservation:** The package retains the ICC color profile of the input image for consistent color rendering.\n5. **EXIF Handling:** Automatically rotates images based on their EXIF orientation metadata.\n6. **Original Image Retention:** If the compressed WebP image is larger than the original, the original image is saved instead to ensure no increase in file size.\n\n## Supported Formats\n\nInput formats:\n\n- JPG / JPEG\n- PNG\n- BMP\n- TIFF / TIF\n\nOutput format:\n\n- WebP\n\n## Requirements\n\n- Python 3.8+\n- Pillow (for image processing)\n- tqdm (for progress bars in multi-threaded tasks)\n\n## Limitations\n\n- The output format is currently limited to WebP.\n- ICC profile conversion to sRGB requires the `ImageCms` module, which may not be available in some environments.\n\n## Future Plans\n\n- **AVIF and JPEG XL Support:** We plan to add support for AVIF and JPEG XL formats in future versions. These formats offer superior compression efficiency and image quality. However, their integration requires optional dependencies since they are not natively supported by OpenCV or Pillow at this time. Once these dependencies become more accessible, they will be incorporated into `imgdiet`.\n\n## Contributing\n\nContributions are welcome! If you'd like to contribute, please:\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature-name`).\n3. Commit your changes (`git commit -m \"Add feature-name\"`).\n4. Push to the branch (`git push origin feature-name`).\n5. Open a pull request.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n---\n\nEnjoy compressing your images efficiently with `imgdiet`!\n\n## Acknowledgements\n\nThis project was developed with assistance from advanced AI tools \ud83e\udd16, including ChatGPT, Claude 3.5 Sonnet, and Cursor AI, which provided guidance and feedback throughout the process.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Yonghye Kwon 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. ",
"summary": "A Python package for minimizing file size of images with minimal quality loss",
"version": "1.0.3",
"project_urls": null,
"split_keywords": [
"image",
" compression",
" webp",
" psnr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c82386cdc143dac3092e47bf6740e532a95deadaf7e706b29f4b27c7383fe176",
"md5": "8fcebe74c2a77f5653b6cc81fe9f21d4",
"sha256": "95825d9e454b3cc932189328d77eed13d20e45568f9cbaca878142559f9030ae"
},
"downloads": -1,
"filename": "imgdiet-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8fcebe74c2a77f5653b6cc81fe9f21d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10204,
"upload_time": "2025-01-14T12:30:46",
"upload_time_iso_8601": "2025-01-14T12:30:46.598773Z",
"url": "https://files.pythonhosted.org/packages/c8/23/86cdc143dac3092e47bf6740e532a95deadaf7e706b29f4b27c7383fe176/imgdiet-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "61f65ba3701048409c2af74e2eeb56b6c605d4956c6dbf224667980f2f515f2c",
"md5": "99c0b65ad4ce25fef79ca8d4321c62ad",
"sha256": "a94a6ac4d7c0de0fdcd50998a93beea43080c4e6cebd4c6afaa419fe39c5ec24"
},
"downloads": -1,
"filename": "imgdiet-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "99c0b65ad4ce25fef79ca8d4321c62ad",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11528,
"upload_time": "2025-01-14T12:30:49",
"upload_time_iso_8601": "2025-01-14T12:30:49.310462Z",
"url": "https://files.pythonhosted.org/packages/61/f6/5ba3701048409c2af74e2eeb56b6c605d4956c6dbf224667980f2f515f2c/imgdiet-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-14 12:30:49",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "imgdiet"
}
