Image Mosaic Generator using Voronoi Tesellation
This repository implements a method to create image mosaics using Voronoi tessellation proposed by Yoshinori Dobashi and Toshiyuki Haga, Henry Johan, and Tomoyuki Nishita (Eurographics Short Presentations, 2002, DOI: 10.2312/egs.20021036).
You can use it to create mosaics like this:
| Input Image | Voronoi Mosaic |
|---|---|
 |
 |
Installation
To install the package:
pip install .
Or to install it as a standalone command line tool:
uv tool install .
Usage
Once installed, the mosaic can be created with:
voronoi-mosaic example-images/butterfly.jpg --output-path example-images/butterfly-mosaic.jpg
The same command is available as a module entry point:
python -m voronoi_mosaic example-images/butterfly.jpg --output-path example-images/butterfly-mosaic.jpg
The example mosaic shown above was created with the default parameters.
To get help on the parameters:
voronoi-mosaic --help
Parameters
| Option | Default | Description |
|---|---|---|
--init-method |
hex-grid |
How the initial cell centers are placed, either hex-grid or random |
--cellsize |
15 |
Average diameter of a cell in pixels, hex-grid only |
--jitter |
5 |
Width of the random offset applied to the lattice, in pixels, hex-grid only |
--npoints |
1000 |
Number of cells, random only |
--niter |
10 |
Number of optimization steps |
--seed |
0 |
Random seed for reproducibility |
--outline-color |
black |
Any matplotlib color, or none to draw no outlines |
--output-path |
mosaic.png |
Path to save the output image |
--dpi |
300 |
Resolution used to render the mosaic |
The hex-grid method places the cell centers on a hexagonal lattice with a spacing of cellsize, where each center is displaced by up to half the jitter value.
The random method instead samples npoints centers from the image, with a probability proportional to the brightness.
Each optimization step moves every cell center by at most one pixel, so larger cells need more steps to settle.
For cellsize values much above the default, niter should be increased accordingly.
The output image has the same pixel size as the input image, up to rounding, independent of dpi.
Since line widths are given in points, dpi controls how thick the cell outlines appear.
Development
To run the tests:
uv run pytest
Releasing
Publishing a release on GitHub builds the package and uploads it to PyPI.
The release tag has to match the version in pyproject.toml, written as v0.1.0 or 0.1.0, otherwise the workflow stops before the upload.
This requires a one time setup, as the workflow authenticates without a stored token:
- a trusted publisher for this repository on PyPI, with
publish.ymlas the workflow andpypias the environment - an environment named
pypiin the repository settings, which is also the place to require a manual approval before the upload
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file voronoi_mosaic-1.0.0.tar.gz.
File metadata
- Download URL: voronoi_mosaic-1.0.0.tar.gz
- Upload date:
- Size: 925.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4eb83cfd66edd6d8a78cc3f083f5cb2ff91031737280ea1e7a7525fdf533c41a
|
|
| MD5 |
478f293271b55e2437d0faa71a04f4ff
|
|
| BLAKE2b-256 |
8e939e8c762ea54a3e5207079c290d28eb54ecc93a307d12b34c3239a5fe12d3
|
Provenance
The following attestation bundles were made for voronoi_mosaic-1.0.0.tar.gz:
Publisher:
publish.yml on adonath/voronoi-mosaic
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
voronoi_mosaic-1.0.0.tar.gz -
Subject digest:
4eb83cfd66edd6d8a78cc3f083f5cb2ff91031737280ea1e7a7525fdf533c41a - Sigstore transparency entry: 2343475146
- Sigstore integration time:
-
Permalink:
adonath/voronoi-mosaic@772eef47fd3809a9d513f06aa443864928bfa698 -
Branch / Tag:
refs/tags/v1.0.0 - Owner: https://github.com/adonath
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@772eef47fd3809a9d513f06aa443864928bfa698 -
Trigger Event:
release
-
Statement type:
File details
Details for the file voronoi_mosaic-1.0.0-py3-none-any.whl.
File metadata
- Download URL: voronoi_mosaic-1.0.0-py3-none-any.whl
- Upload date:
- Size: 5.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
36516975cd9cb1d94c346772aa9712ba00cbfc290e7079ee2b4768cb4ffc8eef
|
|
| MD5 |
c6764e56e2f919c35f202ecac6256a74
|
|
| BLAKE2b-256 |
c9fc0b2e190799f6b4b2eb82c2125633d8eebe7bbbaa4146462d04676a42741b
|
Provenance
The following attestation bundles were made for voronoi_mosaic-1.0.0-py3-none-any.whl:
Publisher:
publish.yml on adonath/voronoi-mosaic
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
voronoi_mosaic-1.0.0-py3-none-any.whl -
Subject digest:
36516975cd9cb1d94c346772aa9712ba00cbfc290e7079ee2b4768cb4ffc8eef - Sigstore transparency entry: 2343475168
- Sigstore integration time:
-
Permalink:
adonath/voronoi-mosaic@772eef47fd3809a9d513f06aa443864928bfa698 -
Branch / Tag:
refs/tags/v1.0.0 - Owner: https://github.com/adonath
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@772eef47fd3809a9d513f06aa443864928bfa698 -
Trigger Event:
release
-
Statement type:
