{"id":18773145,"url":"https://github.com/raideno/image-transformer","last_synced_at":"2025-10-05T20:35:03.592Z","repository":{"id":258645100,"uuid":"872616271","full_name":"raideno/image-transformer","owner":"raideno","description":"This repository contains a python cli tool to convert images into an svg hex representation","archived":false,"fork":false,"pushed_at":"2024-10-23T15:36:44.000Z","size":8286,"stargazers_count":3,"open_issues_count":19,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-28T06:03:21.004Z","etag":null,"topics":["hexgrid","image-processing","poetry","svg"],"latest_commit_sha":null,"homepage":"https://raideno.github.io/image-transformer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raideno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-14T18:48:47.000Z","updated_at":"2025-09-13T12:21:31.000Z","dependencies_parsed_at":"2024-10-23T16:38:38.479Z","dependency_job_id":"f7fc97d5-741f-4a39-bfd7-ca3579e96c82","html_url":"https://github.com/raideno/image-transformer","commit_stats":null,"previous_names":["raideno/image-transformer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/raideno/image-transformer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fimage-transformer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fimage-transformer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fimage-transformer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fimage-transformer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raideno","download_url":"https://codeload.github.com/raideno/image-transformer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raideno%2Fimage-transformer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277560738,"owners_count":25839103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-29T02:00:09.175Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hexgrid","image-processing","poetry","svg"],"created_at":"2024-11-07T19:33:03.877Z","updated_at":"2025-10-05T20:35:03.553Z","avatar_url":"https://github.com/raideno.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Coverage](coverage.svg)\n![Python](https://img.shields.io/badge/Python-3.12%2B-blue)\n![Poetry](https://img.shields.io/badge/Poetry-1.1.0%2B-blue)\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\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eOriginal Image\u003c/td\u003e\n        \u003ctd\u003eHexagonal SVG Version\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            \u003cimg src=\"data/mona-lisa.png\" alt=\"Original Image\"\u003e\n        \u003c/td\u003e\n        \u003ctd\u003e\n            \u003cimg src=\"data/mona-lisa.svg\" alt=\"Generated SVG\"\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            \u003cimg src=\"data/testing-image.jpg\" alt=\"Original Image\"\u003e\n        \u003c/td\u003e\n        \u003ctd\u003e\n            \u003cimg src=\"data/testing-image.svg\" alt=\"Generated SVG\"\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n### Image Generation\n\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eGenerated Image\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\n            \u003cimg src=\"data/generated.svg\" alt=\"Generated SVG\"\u003e\n        \u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\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 \u0026 Notes:\n\nThis are for people who want to dig in hexagonal grids \u0026 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__ \u003capi-toke\u003e`: 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\u003e 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraideno%2Fimage-transformer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraideno%2Fimage-transformer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraideno%2Fimage-transformer/lists"}