<p align="center"><img src="https://i.imgur.com/rMze8u5.png" width="1000"></p>
<p align="center"><b>Python package and CLI utility to create photo mosaics.</b></p>
<p align="center">
<a href="https://github.com/loiccoyle/phomo/actions"><img src="https://github.com/loiccoyle/phomo/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://loiccoyle.com/phomo"><img src="https://img.shields.io/github/deployments/loiccoyle/phomo/github-pages?label=docs"></a>
<a href="https://pypi.org/project/phomo/"><img src="https://img.shields.io/pypi/v/phomo"></a>
<a href="./LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
<img src="https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-informational">
</p>
`phomo` lets you create [photographic mosaics](https://en.wikipedia.org/wiki/Photographic_mosaic).
It arranges the tile images to best recreate a master image. To achieve this, `phomo` computes a distance matrix between all the tiles and the master image regions, looking not just at the average colour but the norm of the colour distributions differences.
Once this distance matrix is computed, each tile is assigned to the optimal master image region by solving the linear sum assignment problem.
## 📦 Installation
In a terminal:
```sh
pip install phomo
# or for GPU acceleration:
pip install 'phomo[cuda]'
```
As always, it is usually a good idea to use a [virtual environment](https://docs.python.org/3/library/venv.html).
If you're just interested in command line usage, consider using [pipx](https://pypa.github.io/pipx/).
> [!NOTE]
> For GPU acceleration you'll need a CUDA compatible GPU and the CUDA toolkit installed. See [numba docs](https://numba.readthedocs.io/en/stable/cuda/overview.html#requirements) for details.
## 📋 Usage
### Python package
Check out the [docs](https://loiccoyle.com/phomo) and the [`examples`](./examples).
### CLI
Once it is installed, you can use the `phomo` command.
It would go something like:
```sh
phomo master.png tile_directory/ -S 20 20 -o mosaic.png
```
If in doubt see the help:
<!-- help start -->
```console
$ phomo -h
usage: phomo [-h] [-o OUTPUT] [-c MASTER_CROP_RATIO]
[-s MASTER_SIZE [MASTER_SIZE ...]] [-C TILE_CROP_RATIO]
[-S TILE_SIZE [TILE_SIZE ...]] [-n N_APPEARANCES] [-b] [-g]
[-d SUBDIVISIONS [SUBDIVISIONS ...]] [-G]
[-m {greyscale,norm,luv_approx}] [-j WORKERS] [-e]
[--match-master-to-tiles] [--match-tiles-to-master] [-v]
master tile_dir
positional arguments:
master Master image path.
tile_dir Directory containing the tile images.
options:
-h, --help show this help message and exit
-o OUTPUT, --output OUTPUT
Mosiac output path.
-c MASTER_CROP_RATIO, --master-crop-ratio MASTER_CROP_RATIO
Crop the master image to width/height ratio.
-s MASTER_SIZE [MASTER_SIZE ...], --master-size MASTER_SIZE [MASTER_SIZE ...]
Resize master image to width, height.
-C TILE_CROP_RATIO, --tile-crop-ratio TILE_CROP_RATIO
Crop the tile images to width/height ratio.
-S TILE_SIZE [TILE_SIZE ...], --tile-size TILE_SIZE [TILE_SIZE ...]
Resize tile images to width, height.
-n N_APPEARANCES, --n-appearances N_APPEARANCES
The number of times a tile can appear in the mosaic.
-b, --black-and-white
Convert master and tile images to black and white.
-g, --show-grid Show the tile grid, don't build the mosiac.
-d SUBDIVISIONS [SUBDIVISIONS ...], --subdivisions SUBDIVISIONS [SUBDIVISIONS ...]
Grid subdivision thresholds.
-G, --gpu Use GPU for distance matrix computation. Requires
installing with `pip install 'phomo[cuda]'`.
-m {greyscale,norm,luv_approx}, --metric {greyscale,norm,luv_approx}
Distance metric.
-j WORKERS, --workers WORKERS
Number of workers use to run when computing the
distance matrix.
-e, --equalize Equalize the colour distributions to cover the full
colour space.
--match-master-to-tiles
Match the master image's colour distribution with the
tile image colours.
--match-tiles-to-master
Match the tile images' colour distribution with the
master image colours.
-v, --verbose Verbosity.
```
<!-- help end -->
## 🤩 Credit
- [photomosaic](https://pypi.org/project/photomosaic/) for the grid subdivision feature.
Raw data
{
"_id": null,
"home_page": "https://github.com/loiccoyle/phomo",
"name": "phomo",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "photomosaic, photographic, mosaic, art, image",
"author": "Loic Coyle",
"author_email": "loic.coyle@hotmail.fr",
"download_url": "https://files.pythonhosted.org/packages/e7/41/eeb3e79caa80f3b2858fa453c8008b7429fa1ea8866497357d443c8c50a5/phomo-1.1.1.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img src=\"https://i.imgur.com/rMze8u5.png\" width=\"1000\"></p>\n<p align=\"center\"><b>Python package and CLI utility to create photo mosaics.</b></p>\n\n<p align=\"center\">\n <a href=\"https://github.com/loiccoyle/phomo/actions\"><img src=\"https://github.com/loiccoyle/phomo/actions/workflows/ci.yml/badge.svg\"></a>\n <a href=\"https://loiccoyle.com/phomo\"><img src=\"https://img.shields.io/github/deployments/loiccoyle/phomo/github-pages?label=docs\"></a>\n <a href=\"https://pypi.org/project/phomo/\"><img src=\"https://img.shields.io/pypi/v/phomo\"></a>\n <a href=\"./LICENSE.md\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\"></a>\n <img src=\"https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-informational\">\n</p>\n\n`phomo` lets you create [photographic mosaics](https://en.wikipedia.org/wiki/Photographic_mosaic).\nIt arranges the tile images to best recreate a master image. To achieve this, `phomo` computes a distance matrix between all the tiles and the master image regions, looking not just at the average colour but the norm of the colour distributions differences.\nOnce this distance matrix is computed, each tile is assigned to the optimal master image region by solving the linear sum assignment problem.\n\n## \ud83d\udce6 Installation\n\nIn a terminal:\n\n```sh\npip install phomo\n\n# or for GPU acceleration:\n\npip install 'phomo[cuda]'\n```\n\nAs always, it is usually a good idea to use a [virtual environment](https://docs.python.org/3/library/venv.html).\n\nIf you're just interested in command line usage, consider using [pipx](https://pypa.github.io/pipx/).\n\n> [!NOTE]\n> For GPU acceleration you'll need a CUDA compatible GPU and the CUDA toolkit installed. See [numba docs](https://numba.readthedocs.io/en/stable/cuda/overview.html#requirements) for details.\n\n## \ud83d\udccb Usage\n\n### Python package\n\nCheck out the [docs](https://loiccoyle.com/phomo) and the [`examples`](./examples).\n\n### CLI\n\nOnce it is installed, you can use the `phomo` command.\n\nIt would go something like:\n\n```sh\nphomo master.png tile_directory/ -S 20 20 -o mosaic.png\n```\n\nIf in doubt see the help:\n\n<!-- help start -->\n\n```console\n$ phomo -h\nusage: phomo [-h] [-o OUTPUT] [-c MASTER_CROP_RATIO]\n [-s MASTER_SIZE [MASTER_SIZE ...]] [-C TILE_CROP_RATIO]\n [-S TILE_SIZE [TILE_SIZE ...]] [-n N_APPEARANCES] [-b] [-g]\n [-d SUBDIVISIONS [SUBDIVISIONS ...]] [-G]\n [-m {greyscale,norm,luv_approx}] [-j WORKERS] [-e]\n [--match-master-to-tiles] [--match-tiles-to-master] [-v]\n master tile_dir\n\npositional arguments:\n master Master image path.\n tile_dir Directory containing the tile images.\n\noptions:\n -h, --help show this help message and exit\n -o OUTPUT, --output OUTPUT\n Mosiac output path.\n -c MASTER_CROP_RATIO, --master-crop-ratio MASTER_CROP_RATIO\n Crop the master image to width/height ratio.\n -s MASTER_SIZE [MASTER_SIZE ...], --master-size MASTER_SIZE [MASTER_SIZE ...]\n Resize master image to width, height.\n -C TILE_CROP_RATIO, --tile-crop-ratio TILE_CROP_RATIO\n Crop the tile images to width/height ratio.\n -S TILE_SIZE [TILE_SIZE ...], --tile-size TILE_SIZE [TILE_SIZE ...]\n Resize tile images to width, height.\n -n N_APPEARANCES, --n-appearances N_APPEARANCES\n The number of times a tile can appear in the mosaic.\n -b, --black-and-white\n Convert master and tile images to black and white.\n -g, --show-grid Show the tile grid, don't build the mosiac.\n -d SUBDIVISIONS [SUBDIVISIONS ...], --subdivisions SUBDIVISIONS [SUBDIVISIONS ...]\n Grid subdivision thresholds.\n -G, --gpu Use GPU for distance matrix computation. Requires\n installing with `pip install 'phomo[cuda]'`.\n -m {greyscale,norm,luv_approx}, --metric {greyscale,norm,luv_approx}\n Distance metric.\n -j WORKERS, --workers WORKERS\n Number of workers use to run when computing the\n distance matrix.\n -e, --equalize Equalize the colour distributions to cover the full\n colour space.\n --match-master-to-tiles\n Match the master image's colour distribution with the\n tile image colours.\n --match-tiles-to-master\n Match the tile images' colour distribution with the\n master image colours.\n -v, --verbose Verbosity.\n```\n\n<!-- help end -->\n\n## \ud83e\udd29 Credit\n\n- [photomosaic](https://pypi.org/project/photomosaic/) for the grid subdivision feature.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package and CLI utility to create photo mosaics.",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/loiccoyle/phomo",
"Repository": "https://github.com/loiccoyle/phomo"
},
"split_keywords": [
"photomosaic",
" photographic",
" mosaic",
" art",
" image"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c78a6935ea030845d6e9fe0a28751fa01be4701142ab4c4194436f9c14c6e3e7",
"md5": "3f82cccbf398e3db8b92950a42c4d910",
"sha256": "0ee236e514eccc0b5f8075c45e9cd0a745bfe641f31cced43c56cf200c809390"
},
"downloads": -1,
"filename": "phomo-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f82cccbf398e3db8b92950a42c4d910",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 19698,
"upload_time": "2024-08-03T20:58:27",
"upload_time_iso_8601": "2024-08-03T20:58:27.132647Z",
"url": "https://files.pythonhosted.org/packages/c7/8a/6935ea030845d6e9fe0a28751fa01be4701142ab4c4194436f9c14c6e3e7/phomo-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e741eeb3e79caa80f3b2858fa453c8008b7429fa1ea8866497357d443c8c50a5",
"md5": "d084ae3a36873139999052de0d89ddac",
"sha256": "87127d341bfdbb2c0972a7e85323c81cc7dffba7c5d41411d4b78b4450879727"
},
"downloads": -1,
"filename": "phomo-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d084ae3a36873139999052de0d89ddac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 17245,
"upload_time": "2024-08-03T20:58:28",
"upload_time_iso_8601": "2024-08-03T20:58:28.559424Z",
"url": "https://files.pythonhosted.org/packages/e7/41/eeb3e79caa80f3b2858fa453c8008b7429fa1ea8866497357d443c8c50a5/phomo-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-03 20:58:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "loiccoyle",
"github_project": "phomo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "phomo"
}
JSON
