---
# Image Transformer
Image Transformer is a CLI tool and a python module that can do two things:
- Reads a .png image and generate a scalable .svg version of that image based on a hexagonal, triangular or square grid (or any other grid you which to implement).
- Generate a svg image from a color palette with the grid of your choice.
The a scalable .svg version generated or transformer can be used as a high-resolution wallpaper.
## Install
```bash
pip install image-transformer
```
## How to use as a CLI tool ?
### The `transform` command
Command to transform an image using specified processors and save the output. This command allows you to transform an image using various processors for the image, pixels, and output. The transformed image is then saved to the specified output directory.
```bash
image-transformer transform mona-lisa.png
```
Below all the available parameters:
| Parameter | Is Required | Default | Description |
| ------------------------ | ----------- | --------------- | ----------------------------------------------------------------------------------------- |
| `--image-path` | Yes | | Specify the path to the image to be transformed. |
| `--image-processor` | Yes | `hexagonal` | Type of grid to use (options: `hexagonal`, `square`, `triangle`). |
| `--pixels-processor` | Yes | `most-frequent` | Specify the pixels processor to use (options: `random`, `most-frequent`, `average`, etc). |
| `--output-builder` | Yes | `cairo-svg` | Specify the output builder to use. |
| `--size` | Yes | `10` | Size of the grid cells. Default is `10`. |
| `--output-directory` | Yes | `./` | Specify the directory where the output image will be saved. |
| `--verbose/--no-verbose` | No | `True` | Enable or disable verbose output. |
**Note:** for more details about all the available params use the following command: `image-transformer transform --help`.
Assuming you have an file in the same directory from where you are running the command named `mona-lisa.png` containing an image.
### The `generate` command
Generate an image with specified dimensions, colors, and processing options.
```bash
image-transformer generate --width 200 --height 100
```
Below all the available parameters:
| Parameter | Is Required | Default | Description |
| ------------------------ | ----------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| `--image-processor` | Yes | `hexagonal` | Type of grid to use (options: `hexagonal`, `square`, `triangle`). Default is `hexagonal`. |
| `--size` | Yes | `10` | Size of the grid cells. Default is `10`. |
| `--width` | Yes | `100` | Specify the width of the generated image. |
| `--height` | Yes | `100` | Specify the height of the generated image. |
| `--hex-color` | Yes | A random color palette | Specify the hex color code for the image background. |
| `--output-builder` | Yes | `cairo-svg` | Specify the output builder to use. |
| `--output-directory` | Yes | `./` | Specify the directory where the output image will be saved. |
| `--verbose/--no-verbose` | No | `True` | Enable or disable verbose output. |
| `--help` | No | | Show help message and exit. |
**Note:** for more details about all the available params use the following command: `image-transformer generate --help`.
## How to use in a program ?
Example usage:
```py
from PIL import Image
from image_transformer import ImageTransformer
from image_transformer.output_builders import CairoSvgOutputBuilder
from image_transformer.image_processors import HexagonalGridImageProcessor
from image_transformer.pixels_processors import MostFrequentPixelsProcessor
def main():
hexagon_size = 13
output_image_path = "result.svg"
# NOTE: assuming the image exists
my_image_path = "./mona-lisa.png"
image = Image.open(my_image_path)
transformer = ImageTransformer.from_pil_image(image)
output_builder = CairoSvgOutputBuilder(image.width, image.height, output_image_path)
image_processor = HexagonalGridImageProcessor(hexagon_size)
pixels_processor = MostFrequentPixelsProcessor()
transformer.transform_and_save(
image_processor=image_processor,
pixels_processor=pixels_processor,
output_builder=output_builder
)
if __name__ == "__main__":
main()
```
## Examples
### Image Transformation
<table>
<tr>
<td>Original Image</td>
<td>Hexagonal SVG Version</td>
</tr>
<tr>
<td>
<img src="data/mona-lisa.png" alt="Original Image">
</td>
<td>
<img src="data/mona-lisa.svg" alt="Generated SVG">
</td>
</tr>
<tr>
<td>
<img src="data/testing-image.jpg" alt="Original Image">
</td>
<td>
<img src="data/testing-image.svg" alt="Generated SVG">
</td>
</tr>
</table>
### Image Generation
<table>
<tr>
<td>Generated Image</td>
</tr>
<tr>
<td>
<img src="data/generated.svg" alt="Generated SVG">
</td>
</tr>
</table>
## Development and Contributions
Below are notes for development only. You don't need to give it a look unless you want to contribute or build your own library.
### Materials & Notes:
This are for people who want to dig in hexagonal grids & know how to deal with it. Ignore if you only want to use the tool.
- https://www.redblobgames.com/
- https://www.geeksforgeeks.org/creating-svg-image-using-pycairo/
- https://gamedev.stackexchange.com/a/61101
### Docs Building Notes
- `poetry add sphinx --dev`: to install sphinx.
- `poetry run sphinx-apidoc -o docs/ image_transformer/`: to generate the .rst files for each module. This command should be run each time you have a new module or there is some changes in one of your modules.
- `poetry run sphinx-build -b html docs docs/_build`: to build the documentation. Each time there is a change.
### Upload to Pypi
- `poetry config http-basic.pypi __token__ <api-toke>`: to specify your pipy credentials.
- `poetry build`: build the project.
- `poetry publish`: to publish the builded project into pypi.
### About Poetry
[Poetry Scripts Section](https://github.com/python-poetry/poetry/issues/241#issuecomment-470200353):
> It looks like there is a desire for developer/project specific helper scripts, but that's not what [tool.poetry.scripts] is for. As mentioned, scripts are entrypoints into a python packages. This section's purpose is for libraries to install useful command line tools. Libraries like pytest, poetry, and the aws cli would use this scripts section so you can call their tool from the command line.
[Reason why they don't add a `dev-scripts` section](https://github.com/python-poetry/poetry/issues/241#issuecomment-470212635).
[ ] Poetry support multi language ?
Raw data
{
"_id": null,
"home_page": "https://raideno.github.io/image-transformer/",
"name": "image-transformer",
"maintainer": "raiden",
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": "nadirkichou@hotmail.fr",
"keywords": "image-processing, image-enhancement, image-transformer",
"author": "raiden",
"author_email": "nadirkichou@hotmail.fr",
"download_url": "https://files.pythonhosted.org/packages/53/db/61691eeb87137ac31243690bafe706d3ea55408f84b9aafca8f483ce3a4a/image_transformer-0.5.0.tar.gz",
"platform": null,
"description": "\n\n\n\n---\n\n# Image Transformer\n\nImage Transformer is a CLI tool and a python module that can do two things:\n\n- Reads a .png image and generate a scalable .svg version of that image based on a hexagonal, triangular or square grid (or any other grid you which to implement).\n- Generate a svg image from a color palette with the grid of your choice.\n\nThe a scalable .svg version generated or transformer can be used as a high-resolution wallpaper.\n\n## Install\n\n```bash\npip install image-transformer\n```\n\n## How to use as a CLI tool ?\n\n### The `transform` command\n\nCommand to transform an image using specified processors and save the output. This command allows you to transform an image using various processors for the image, pixels, and output. The transformed image is then saved to the specified output directory.\n\n```bash\nimage-transformer transform mona-lisa.png\n```\n\nBelow all the available parameters:\n\n| Parameter | Is Required | Default | Description |\n| ------------------------ | ----------- | --------------- | ----------------------------------------------------------------------------------------- |\n| `--image-path` | Yes | | Specify the path to the image to be transformed. |\n| `--image-processor` | Yes | `hexagonal` | Type of grid to use (options: `hexagonal`, `square`, `triangle`). |\n| `--pixels-processor` | Yes | `most-frequent` | Specify the pixels processor to use (options: `random`, `most-frequent`, `average`, etc). |\n| `--output-builder` | Yes | `cairo-svg` | Specify the output builder to use. |\n| `--size` | Yes | `10` | Size of the grid cells. Default is `10`. |\n| `--output-directory` | Yes | `./` | Specify the directory where the output image will be saved. |\n| `--verbose/--no-verbose` | No | `True` | Enable or disable verbose output. |\n\n**Note:** for more details about all the available params use the following command: `image-transformer transform --help`.\n\nAssuming you have an file in the same directory from where you are running the command named `mona-lisa.png` containing an image.\n\n### The `generate` command\n\nGenerate an image with specified dimensions, colors, and processing options.\n\n```bash\nimage-transformer generate --width 200 --height 100\n```\n\nBelow all the available parameters:\n\n| Parameter | Is Required | Default | Description |\n| ------------------------ | ----------- | ---------------------- | ----------------------------------------------------------------------------------------- |\n| `--image-processor` | Yes | `hexagonal` | Type of grid to use (options: `hexagonal`, `square`, `triangle`). Default is `hexagonal`. |\n| `--size` | Yes | `10` | Size of the grid cells. Default is `10`. |\n| `--width` | Yes | `100` | Specify the width of the generated image. |\n| `--height` | Yes | `100` | Specify the height of the generated image. |\n| `--hex-color` | Yes | A random color palette | Specify the hex color code for the image background. |\n| `--output-builder` | Yes | `cairo-svg` | Specify the output builder to use. |\n| `--output-directory` | Yes | `./` | Specify the directory where the output image will be saved. |\n| `--verbose/--no-verbose` | No | `True` | Enable or disable verbose output. |\n| `--help` | No | | Show help message and exit. |\n\n**Note:** for more details about all the available params use the following command: `image-transformer generate --help`.\n\n## How to use in a program ?\n\nExample usage:\n\n```py\nfrom PIL import Image\n\nfrom image_transformer import ImageTransformer\nfrom image_transformer.output_builders import CairoSvgOutputBuilder\nfrom image_transformer.image_processors import HexagonalGridImageProcessor\nfrom image_transformer.pixels_processors import MostFrequentPixelsProcessor\n\ndef main():\n hexagon_size = 13\n output_image_path = \"result.svg\"\n # NOTE: assuming the image exists\n my_image_path = \"./mona-lisa.png\"\n\n image = Image.open(my_image_path)\n\n transformer = ImageTransformer.from_pil_image(image)\n\n output_builder = CairoSvgOutputBuilder(image.width, image.height, output_image_path)\n image_processor = HexagonalGridImageProcessor(hexagon_size)\n pixels_processor = MostFrequentPixelsProcessor()\n\n transformer.transform_and_save(\n image_processor=image_processor,\n pixels_processor=pixels_processor,\n output_builder=output_builder\n )\n\nif __name__ == \"__main__\":\n main()\n```\n\n## Examples\n\n### Image Transformation\n\n<table>\n <tr>\n <td>Original Image</td>\n <td>Hexagonal SVG Version</td>\n </tr>\n <tr>\n <td>\n <img src=\"data/mona-lisa.png\" alt=\"Original Image\">\n </td>\n <td>\n <img src=\"data/mona-lisa.svg\" alt=\"Generated SVG\">\n </td>\n </tr>\n <tr>\n <td>\n <img src=\"data/testing-image.jpg\" alt=\"Original Image\">\n </td>\n <td>\n <img src=\"data/testing-image.svg\" alt=\"Generated SVG\">\n </td>\n </tr>\n</table>\n\n### Image Generation\n\n<table>\n <tr>\n <td>Generated Image</td>\n </tr>\n <tr>\n <td>\n <img src=\"data/generated.svg\" alt=\"Generated SVG\">\n </td>\n </tr>\n</table>\n\n## Development and Contributions\n\nBelow are notes for development only. You don't need to give it a look unless you want to contribute or build your own library.\n\n### Materials & Notes:\n\nThis are for people who want to dig in hexagonal grids & know how to deal with it. Ignore if you only want to use the tool.\n\n- https://www.redblobgames.com/\n- https://www.geeksforgeeks.org/creating-svg-image-using-pycairo/\n- https://gamedev.stackexchange.com/a/61101\n\n### Docs Building Notes\n\n- `poetry add sphinx --dev`: to install sphinx.\n- `poetry run sphinx-apidoc -o docs/ image_transformer/`: to generate the .rst files for each module. This command should be run each time you have a new module or there is some changes in one of your modules.\n- `poetry run sphinx-build -b html docs docs/_build`: to build the documentation. Each time there is a change.\n\n### Upload to Pypi\n\n- `poetry config http-basic.pypi __token__ <api-toke>`: to specify your pipy credentials.\n- `poetry build`: build the project.\n- `poetry publish`: to publish the builded project into pypi.\n\n### About Poetry\n\n[Poetry Scripts Section](https://github.com/python-poetry/poetry/issues/241#issuecomment-470200353):\n\n> It looks like there is a desire for developer/project specific helper scripts, but that's not what [tool.poetry.scripts] is for. As mentioned, scripts are entrypoints into a python packages. This section's purpose is for libraries to install useful command line tools. Libraries like pytest, poetry, and the aws cli would use this scripts section so you can call their tool from the command line.\n\n[Reason why they don't add a `dev-scripts` section](https://github.com/python-poetry/poetry/issues/241#issuecomment-470212635).\n\n[ ] Poetry support multi language ?\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python project for enhancing images using various processing techniques.",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://raideno.github.io/image-transformer/",
"Homepage": "https://raideno.github.io/image-transformer/",
"Repository": "https://github.com/raideno/image-transformer"
},
"split_keywords": [
"image-processing",
" image-enhancement",
" image-transformer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "79fc46b4a1f6ca23431822610b54fee0a0e171bf914afce3a2ae9ceeaf0ea253",
"md5": "849c7d2740e3ebe62f91c782b52de459",
"sha256": "b894294afe6591e3c7ef02a6e4b8f798de50ba9372f1aa8e9c20819c3c5c0aff"
},
"downloads": -1,
"filename": "image_transformer-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "849c7d2740e3ebe62f91c782b52de459",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 30136,
"upload_time": "2024-10-23T15:37:24",
"upload_time_iso_8601": "2024-10-23T15:37:24.720256Z",
"url": "https://files.pythonhosted.org/packages/79/fc/46b4a1f6ca23431822610b54fee0a0e171bf914afce3a2ae9ceeaf0ea253/image_transformer-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "53db61691eeb87137ac31243690bafe706d3ea55408f84b9aafca8f483ce3a4a",
"md5": "319ec3568e91f5038ccfac4f5b034233",
"sha256": "a63d3ab8d792d76235edf6310f8497ff06592879c99eeca9b79e1d0a21fe29f9"
},
"downloads": -1,
"filename": "image_transformer-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "319ec3568e91f5038ccfac4f5b034233",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 16279,
"upload_time": "2024-10-23T15:37:26",
"upload_time_iso_8601": "2024-10-23T15:37:26.076073Z",
"url": "https://files.pythonhosted.org/packages/53/db/61691eeb87137ac31243690bafe706d3ea55408f84b9aafca8f483ce3a4a/image_transformer-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-23 15:37:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "raideno",
"github_project": "image-transformer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "image-transformer"
}
JSON
