[](https://github.com/mano8/imgtools_m8/actions/workflows/python-package.yml)
[](https://pypi.org/project/imgtools_m8/)
[](https://codecov.io/gh/mano8/imgtools_m8)
[](https://www.codacy.com/gh/mano8/imgtools_m8/dashboard?utm_source=github.com&utm_medium=referral&utm_content=mano8/imgtools_m8&utm_campaign=Badge_Grade)
[](https://pepy.tech/project/imgtools-m8)
[](https://snyk.io/test/github/mano8/imgtools_m8)
## Description
`imgtools_m8` is a simple image tools package that provides functionality to convert, downscale, and upscale images.
It uses deep learning and OpenCV to upscale images using pre-trained models developed by Xavier Weber (more info [here](https://towardsdatascience.com/deep-learning-based-super-resolution-with-opencv-4fd736678066)).
## Installation
You can install the package from GitHub or PyPI.
To install directly from GitHub:
```plaintext
$ python3 -m pip install "git+https://github.com/mano8/imgtools_m8 --upgrade"
```
To install from PypI :
```plaintext
python3 -m pip install imgtools_m8 --upgrade
```
## Usage
The imgtools_m8 package offers automated image processing capabilities for a designated source directory, with the output results saved to a specified output directory.
The package provides versatile resizing options, including:
- fixed_width: Resizing images to an exact width in pixels.
- fixed_height: Resizing images to an exact height in pixels.
- fixed_size: Resizing images based on the first limitation reached (height or width).
- fixed_width and fixed_height: Resizing images based on the highest limitation reached,
while allowing different height and width values.
In cases where the original image size exceeds the specified output dimensions, the package automatically applies upscaling using pre-trained models.
For more usage examples, refer to the [example's directory](https://github.com/mano8/imgtools_m8/tree/main/examples).
(See accepted extensions from [cv2 documentation](https://docs.opencv.org/4.8.0/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56))
In all the examples provided, the source_path value is set to a single image file path.
However, this package can also work with a directory path containing multiple image files.
In this scenario, the processing will be applied to all images within the specified source_path directory.
### Example 1
In this example, we demonstrate how to convert an input image to three different formats
(.jpg, .webp, and .png) without resizing.
```python
from imgtools_m8.img_tools import ImageTools
# Set up the output formats
output_formats = [
{
'formats': [
{'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1},
{'ext': '.webp', 'quality': 70},
{'ext': '.png', 'compression': 2}
]
}
]
# Create an instance of ImageTools
imgtools = ImageTools(
source_path="./tests/dummy_dir/recien_llegado.jpg",
output_path="/my/output/path/directory",
output_formats=output_formats
)
# Run the image processing
imgtools.run()
```
This code snippet converts the input image to three different formats (JPEG, WEBP, and PNG)
and saves the resulting images in the specified output directory.
The JPEG images are saved with 80% quality, progressive encoding, and optimization.
The WEBP images are saved with 70% quality,
and the PNG images are saved with compression level 2.
### Example 2
In this example, we demonstrate how to resize an input image and save it as a .jpeg format.
The source file is 340px wide and 216px high. The output file will be downscaled to 300*190 px,
and finally saved as a JPEG with 80% quality, progressive encoding, and optimization.
when fixed_width and fixed_height are set, the downscale process selects the higher coefficient as the limitation,
and in this case, it is the fixed width of 300 px.
For a fixed height of 200 px, the output will be an image of 314x200 px.
```python
from imgtools_m8.img_tools import ImageTools
# Set up the output formats
output_formats = [
{
'fixed_width': 300,
'fixed_height': 200,
'formats': [
{'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}
]
}
]
# Create an instance of ImageTools
imgtools = ImageTools(
source_path="./tests/dummy_dir/recien_llegado.jpg",
output_path="/my/output/path/directory",
output_formats=output_formats
)
# Run the image processing
imgtools.run()
```
In this example, the input image is downscaled to a fixed width of 300 pixels,
as the higher coefficient is selected.
The resulting image is then saved as a JPEG with 80% quality,
progressive encoding, and optimization.
### Example 3
In this example, we demonstrate how to resize an input image and save it as a .jpeg format.
The source file is 340px wide and 216px high. The output file will be upscaled 4x to 1360x864 px,
then downscaled to 1200x762 px, and finally saved as a JPEG with 80% quality, progressive encoding, and optimization.
By default, the package uses the pre-trained EDSR model to upscale images, automatically determining the best model scale to use.
In this case, the best choice is the EDSR_4x.pb model.
```python
from imgtools_m8.img_tools import ImageTools
# Set up the output formats
output_formats = [
{
'fixed_width': 1200,
'formats': [
{'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}
]
}
]
# Create an instance of ImageTools
imgtools = ImageTools(
source_path="./tests/dummy_dir/recien_llegado.jpg",
output_path="/my/output/path/directory",
output_formats=output_formats
)
# Run the image processing
imgtools.run()
```
This code snippet demonstrates how to resize an input image using automatic upscaling and downscaling.
The image is first upscaled using the default EDSR model to achieve a higher resolution,
then downscaled to the specified width of 1200 pixels.
The resulting image is saved as a JPEG with 80% quality, progressive encoding, and optimization.
The package automatically selects the appropriate model scale for upscaling based on the image dimensions.
### Example 4
In this example, we demonstrate how to fix the model scale for the upscale process
and resize an input image while saving it as a .jpeg format.
For various reasons, users might want to use only a preferred model scale for the upscale process.
In this case, it's necessary to define a model configuration with the selected model scale value,
which needs to be a valid model scale.
For example, the pre-trained EDSR model has valid model scales of 2x, 3x, and 4x.
Other models may have different valid scale values.
The source file is 340px wide and 216px high.
The output file will be upscaled 2x two times in this case, resulting in a size of 1360x864 px.
Then it will be downscaled to 1200x762 px, and finally saved as a JPEG with 80% quality,
progressive encoding, and optimization.
This process is slower compared to Example 3
due to the necessity of executing two upscale processes, which increases the execution time.
```python
from imgtools_m8.img_tools import ImageTools
# Set up model configuration
model_conf = {
'scale': 2
}
# Set up the output formats
output_formats = [
{
'fixed_width': 1200,
'formats': [
{'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}
]
}
]
# Create an instance of ImageTools
imgtools = ImageTools(
source_path="./tests/dummy_dir/recien_llegado.jpg",
output_path="/my/output/path/directory",
output_formats=output_formats,
model_conf=model_conf
)
# Run the image processing
imgtools.run()
```
### Example 5
In this example, we demonstrate how to use another pre-trained model.
While this package currently only contains the EDSR model,
you have the flexibility to use any available model of your choice.
To use a different model, you will need to download models with a .pb extension from [here](https://github.com/opencv/opencv_contrib/tree/master/modules/dnn_superres).
Once downloaded, place the models in a directory, and set the model configuration as shown below.
If you wish to automatically select the best model scale,
ensure you have downloaded all available model scales or only the ones you intend to use.
Keep in mind that when only one model scale is available for a model, it will be used exclusively.
This can result in slower execution times and/or lower quality results
depending on the available model scale, input image size,
and output size(s) defined in the configuration.
In this example, we use the pre-trained TF-ESPCN model to upscale images,
automatically determining the best model scale to use. In this case,
the best choice is the TF-ESPCN_4x.pb model.
```python
from imgtools_m8.img_tools import ImageTools
# Set up model configuration for downloaded TF-ESPCN models
model_conf = {
'path': "/path/to/your/downloaded/model/directory",
'model_name': 'espcn',
}
# Set up the output formats
output_formats = [
{
'fixed_width': 1200,
'formats': [
{'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}
]
}
]
# Create an instance of ImageTools
imgtools = ImageTools(
source_path="./tests/dummy_dir/recien_llegado.jpg",
output_path="/my/output/path/directory",
output_formats=output_formats,
model_conf=model_conf
)
# Run the image processing
imgtools.run()
```
## Input/Output Example :
### Input Image
The source file is 340px width and 216px height.
<div align="center">
<img src="https://raw.githubusercontent.com/mano8/imgtools_m8/main/tests/sources_test/recien_llegado.jpg" alt="Recien Llegado @Cezar llañez" width="340" height="216" />
<p>Recien llegado by <a href="https://www.ichingmaestrodelosespiritus.com/">@Cezar yañez</a></p>
</div>
### Upscaled Output
In some examples, the output is upscaled to 1200x762 px and saved as a JPEG with 80% quality,
progressive encoding, and optimization:
<div align="center">
<img src="https://raw.githubusercontent.com/mano8/imgtools_m8/main/tests/output_test/recien_llegado_1200x762.jpg" alt="Recien Llegado @Cezar llañez" width="1200px" />
<p>recien_llegado_1200x762.jpg by <a href="https://www.ichingmaestrodelosespiritus.com/">@Cezar yañez</a></p>
</div>
#License
This project is licensed under the Apache 2 License - see the [LICENSE](https://github.com/mano8/imgtools_m8/blob/main/LICENCE) file for details.
Authors
- [Eli Serra](https://github.com/mano8)
- pre-trained models by [Xavier Weber](https://towardsdatascience.com/deep-learning-based-super-resolution-with-opencv-4fd736678066).
Raw data
{
"_id": null,
"home_page": "https://github.com/mano8/imgtools_m8",
"name": "imgtools-m8",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.5.2",
"maintainer_email": "",
"keywords": "",
"author": "Eli Serra",
"author_email": "eli.serra173@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/77/ec/592f2de14ea5f2834c6af9c34b0e4b90ccf8fd17637471404388bab749c9/imgtools_m8-1.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/mano8/imgtools_m8/actions/workflows/python-package.yml)\n[](https://pypi.org/project/imgtools_m8/)\n[](https://codecov.io/gh/mano8/imgtools_m8)\n[](https://www.codacy.com/gh/mano8/imgtools_m8/dashboard?utm_source=github.com&utm_medium=referral&utm_content=mano8/imgtools_m8&utm_campaign=Badge_Grade)\n[](https://pepy.tech/project/imgtools-m8)\n[](https://snyk.io/test/github/mano8/imgtools_m8)\n## Description\n\n`imgtools_m8` is a simple image tools package that provides functionality to convert, downscale, and upscale images.\n\nIt uses deep learning and OpenCV to upscale images using pre-trained models developed by Xavier Weber (more info [here](https://towardsdatascience.com/deep-learning-based-super-resolution-with-opencv-4fd736678066)).\n\n## Installation\n\nYou can install the package from GitHub or PyPI.\n\nTo install directly from GitHub:\n\n```plaintext\n$ python3 -m pip install \"git+https://github.com/mano8/imgtools_m8 --upgrade\"\n```\n\nTo install from PypI :\n\n```plaintext\npython3 -m pip install imgtools_m8 --upgrade\n```\n\n## Usage\n\nThe imgtools_m8 package offers automated image processing capabilities for a designated source directory, with the output results saved to a specified output directory.\n\nThe package provides versatile resizing options, including:\n\n - fixed_width: Resizing images to an exact width in pixels.\n - fixed_height: Resizing images to an exact height in pixels.\n - fixed_size: Resizing images based on the first limitation reached (height or width).\n - fixed_width and fixed_height: Resizing images based on the highest limitation reached,\n while allowing different height and width values.\n\nIn cases where the original image size exceeds the specified output dimensions, the package automatically applies upscaling using pre-trained models.\n\nFor more usage examples, refer to the [example's directory](https://github.com/mano8/imgtools_m8/tree/main/examples).\n\n(See accepted extensions from [cv2 documentation](https://docs.opencv.org/4.8.0/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56))\n\nIn all the examples provided, the source_path value is set to a single image file path.\nHowever, this package can also work with a directory path containing multiple image files.\nIn this scenario, the processing will be applied to all images within the specified source_path directory.\n\n### Example 1\n\nIn this example, we demonstrate how to convert an input image to three different formats\n(.jpg, .webp, and .png) without resizing.\n\n```python\nfrom imgtools_m8.img_tools import ImageTools\n\n# Set up the output formats\noutput_formats = [\n {\n 'formats': [\n {'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1},\n {'ext': '.webp', 'quality': 70},\n {'ext': '.png', 'compression': 2}\n ]\n \n }\n]\n\n# Create an instance of ImageTools\nimgtools = ImageTools(\n source_path=\"./tests/dummy_dir/recien_llegado.jpg\",\n output_path=\"/my/output/path/directory\",\n output_formats=output_formats\n)\n# Run the image processing\nimgtools.run()\n```\nThis code snippet converts the input image to three different formats (JPEG, WEBP, and PNG)\nand saves the resulting images in the specified output directory.\n\nThe JPEG images are saved with 80% quality, progressive encoding, and optimization. \nThe WEBP images are saved with 70% quality, \nand the PNG images are saved with compression level 2.\n\n### Example 2\n\nIn this example, we demonstrate how to resize an input image and save it as a .jpeg format.\n\nThe source file is 340px wide and 216px high. The output file will be downscaled to 300*190 px,\nand finally saved as a JPEG with 80% quality, progressive encoding, and optimization.\n\nwhen fixed_width and fixed_height are set, the downscale process selects the higher coefficient as the limitation,\nand in this case, it is the fixed width of 300 px.\n\nFor a fixed height of 200 px, the output will be an image of 314x200 px.\n```python\nfrom imgtools_m8.img_tools import ImageTools\n\n# Set up the output formats\noutput_formats = [\n {\n 'fixed_width': 300,\n 'fixed_height': 200,\n 'formats': [\n {'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}\n ]\n }\n]\n\n# Create an instance of ImageTools\nimgtools = ImageTools(\n source_path=\"./tests/dummy_dir/recien_llegado.jpg\",\n output_path=\"/my/output/path/directory\",\n output_formats=output_formats\n)\n# Run the image processing\nimgtools.run()\n```\n\nIn this example, the input image is downscaled to a fixed width of 300 pixels,\nas the higher coefficient is selected.\nThe resulting image is then saved as a JPEG with 80% quality,\nprogressive encoding, and optimization.\n\n### Example 3\n\nIn this example, we demonstrate how to resize an input image and save it as a .jpeg format.\n\nThe source file is 340px wide and 216px high. The output file will be upscaled 4x to 1360x864 px,\nthen downscaled to 1200x762 px, and finally saved as a JPEG with 80% quality, progressive encoding, and optimization.\n\nBy default, the package uses the pre-trained EDSR model to upscale images, automatically determining the best model scale to use.\nIn this case, the best choice is the EDSR_4x.pb model.\n```python\nfrom imgtools_m8.img_tools import ImageTools\n\n# Set up the output formats\noutput_formats = [\n {\n 'fixed_width': 1200,\n 'formats': [\n {'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}\n ]\n }\n]\n\n# Create an instance of ImageTools\nimgtools = ImageTools(\n source_path=\"./tests/dummy_dir/recien_llegado.jpg\",\n output_path=\"/my/output/path/directory\",\n output_formats=output_formats\n)\n# Run the image processing\nimgtools.run()\n```\nThis code snippet demonstrates how to resize an input image using automatic upscaling and downscaling.\n\nThe image is first upscaled using the default EDSR model to achieve a higher resolution,\nthen downscaled to the specified width of 1200 pixels.\n\nThe resulting image is saved as a JPEG with 80% quality, progressive encoding, and optimization.\n\nThe package automatically selects the appropriate model scale for upscaling based on the image dimensions.\n\n### Example 4\nIn this example, we demonstrate how to fix the model scale for the upscale process \nand resize an input image while saving it as a .jpeg format.\n\nFor various reasons, users might want to use only a preferred model scale for the upscale process.\nIn this case, it's necessary to define a model configuration with the selected model scale value,\nwhich needs to be a valid model scale.\n\nFor example, the pre-trained EDSR model has valid model scales of 2x, 3x, and 4x.\nOther models may have different valid scale values.\n\nThe source file is 340px wide and 216px high.\nThe output file will be upscaled 2x two times in this case, resulting in a size of 1360x864 px.\nThen it will be downscaled to 1200x762 px, and finally saved as a JPEG with 80% quality,\nprogressive encoding, and optimization.\n\nThis process is slower compared to Example 3\ndue to the necessity of executing two upscale processes, which increases the execution time.\n\n```python\nfrom imgtools_m8.img_tools import ImageTools\n\n# Set up model configuration\nmodel_conf = {\n 'scale': 2\n}\n\n# Set up the output formats\noutput_formats = [\n {\n 'fixed_width': 1200,\n 'formats': [\n {'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}\n ]\n }\n]\n\n# Create an instance of ImageTools\nimgtools = ImageTools(\n source_path=\"./tests/dummy_dir/recien_llegado.jpg\",\n output_path=\"/my/output/path/directory\",\n output_formats=output_formats,\n model_conf=model_conf\n)\n# Run the image processing\nimgtools.run()\n```\n\n### Example 5\nIn this example, we demonstrate how to use another pre-trained model.\nWhile this package currently only contains the EDSR model,\nyou have the flexibility to use any available model of your choice.\n\nTo use a different model, you will need to download models with a .pb extension from [here](https://github.com/opencv/opencv_contrib/tree/master/modules/dnn_superres).\nOnce downloaded, place the models in a directory, and set the model configuration as shown below.\n\nIf you wish to automatically select the best model scale,\nensure you have downloaded all available model scales or only the ones you intend to use.\nKeep in mind that when only one model scale is available for a model, it will be used exclusively.\nThis can result in slower execution times and/or lower quality results\ndepending on the available model scale, input image size,\nand output size(s) defined in the configuration.\n\nIn this example, we use the pre-trained TF-ESPCN model to upscale images,\nautomatically determining the best model scale to use. In this case,\nthe best choice is the TF-ESPCN_4x.pb model.\n\n```python\nfrom imgtools_m8.img_tools import ImageTools\n\n# Set up model configuration for downloaded TF-ESPCN models\nmodel_conf = {\n 'path': \"/path/to/your/downloaded/model/directory\",\n 'model_name': 'espcn',\n}\n\n# Set up the output formats\noutput_formats = [\n {\n 'fixed_width': 1200,\n 'formats': [\n {'ext': '.jpg', 'quality': 80, 'progressive': 1, 'optimize': 1}\n ]\n }\n]\n\n# Create an instance of ImageTools\nimgtools = ImageTools(\n source_path=\"./tests/dummy_dir/recien_llegado.jpg\",\n output_path=\"/my/output/path/directory\",\n output_formats=output_formats,\n model_conf=model_conf\n)\n# Run the image processing\nimgtools.run()\n```\n\n## Input/Output Example : \n\n### Input Image\nThe source file is 340px width and 216px height.\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/mano8/imgtools_m8/main/tests/sources_test/recien_llegado.jpg\" alt=\"Recien Llegado @Cezar lla\u00f1ez\" width=\"340\" height=\"216\" /> \n <p>Recien llegado by <a href=\"https://www.ichingmaestrodelosespiritus.com/\">@Cezar ya\u00f1ez</a></p>\n</div>\n\n### Upscaled Output\nIn some examples, the output is upscaled to 1200x762 px and saved as a JPEG with 80% quality,\nprogressive encoding, and optimization:\n<div align=\"center\">\n <img src=\"https://raw.githubusercontent.com/mano8/imgtools_m8/main/tests/output_test/recien_llegado_1200x762.jpg\" alt=\"Recien Llegado @Cezar lla\u00f1ez\" width=\"1200px\" />\n <p>recien_llegado_1200x762.jpg by <a href=\"https://www.ichingmaestrodelosespiritus.com/\">@Cezar ya\u00f1ez</a></p>\n</div>\n\n#License\nThis project is licensed under the Apache 2 License - see the [LICENSE](https://github.com/mano8/imgtools_m8/blob/main/LICENCE) file for details.\n\nAuthors\n - [Eli Serra](https://github.com/mano8)\n - pre-trained models by [Xavier Weber](https://towardsdatascience.com/deep-learning-based-super-resolution-with-opencv-4fd736678066).\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "Simple image tools package. Used to convert, downscale or upscale images.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/mano8/imgtools_m8"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1fc82c5c1244d1a6415d4a6c853ce699cde4f276a35c1b2afa2779c7664a95c3",
"md5": "2d03381a7d799a42bd5da539ca292b72",
"sha256": "7de14df4ff0a1dec3a4d98ec0e910f94557bdb9674e1c84430ba5a38c2626f82"
},
"downloads": -1,
"filename": "imgtools_m8-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2d03381a7d799a42bd5da539ca292b72",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.5.2",
"size": 94819733,
"upload_time": "2023-08-31T15:14:53",
"upload_time_iso_8601": "2023-08-31T15:14:53.340733Z",
"url": "https://files.pythonhosted.org/packages/1f/c8/2c5c1244d1a6415d4a6c853ce699cde4f276a35c1b2afa2779c7664a95c3/imgtools_m8-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77ec592f2de14ea5f2834c6af9c34b0e4b90ccf8fd17637471404388bab749c9",
"md5": "1543d3ca72e86ffca8b167b8f1bb7d1d",
"sha256": "5637ed5bb3deb22d75a1d6dbd8a7a6f6826bb2c3ad62254a6acfb86b4fd0cbe6"
},
"downloads": -1,
"filename": "imgtools_m8-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1543d3ca72e86ffca8b167b8f1bb7d1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.5.2",
"size": 94817600,
"upload_time": "2023-08-31T15:14:58",
"upload_time_iso_8601": "2023-08-31T15:14:58.965061Z",
"url": "https://files.pythonhosted.org/packages/77/ec/592f2de14ea5f2834c6af9c34b0e4b90ccf8fd17637471404388bab749c9/imgtools_m8-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-31 15:14:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mano8",
"github_project": "imgtools_m8",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "imgtools-m8"
}
JSON
