Image Mosaic Generator using Voronoi Tesellation

CI

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
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
--background-color white Any matplotlib color, shown in the gaps between the cells
--pad 0.0 Distance in pixels each cell is shrunk by, which opens up a gap between neighboring cells
--radius 0.0 Corner radius in pixels used to round the cells
--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 pad and radius options turn the sharp cells into rounded pebbles. Each cell is first shrunk by pad towards its own center, which opens up a gap that shows the background-color, and its corners are then rounded with radius. Both are given in pixels and are best chosen relative to cellsize, for example a pad of 1.5 and a radius of 4 for the default cellsize of 15. The rounding is limited to half an edge length, so a large radius turns small cells into ellipses rather than distorting them.

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.yml as the workflow and pypi as the environment
  • an environment named pypi in the repository settings, which is also the place to require a manual approval before the upload

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for adonath from gravatar.com adonath

Requires

Python >=3.9

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

voronoi_mosaic-1.1.0.tar.gz (928.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

voronoi_mosaic-1.1.0-py3-none-any.whl (7.3 kB view details)

Uploaded Python 3

File details

Details for the file voronoi_mosaic-1.1.0.tar.gz.

File metadata

  • Download URL: voronoi_mosaic-1.1.0.tar.gz
  • Upload date:
  • Size: 928.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for voronoi_mosaic-1.1.0.tar.gz
Algorithm Hash digest
SHA256 1959842e0130ab070b25d0bf109d78c416669d998014c3df4d63d9152e84acfd
MD5 0a0e93914c45197326a88a6754abefd5
BLAKE2b-256 75cffbc8aebaedf4bf1fa9da0b5af6fc4142b2eeb77e27116db6056d25986aaa

See more details on using hashes here.

Provenance

The following attestation bundles were made for voronoi_mosaic-1.1.0.tar.gz:

Publisher: publish.yml on adonath/voronoi-mosaic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file voronoi_mosaic-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: voronoi_mosaic-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 7.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for voronoi_mosaic-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 6f7fd9bb794a33dc39384295f02fd47f846f792d0d7479fe0489c1e2a2d7324a
MD5 86751f5390831050e6e605926531b70e
BLAKE2b-256 11ed1da513366a5a1053da93a5932b0e2b4a217c609e8cc65c03f80d0fece7a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for voronoi_mosaic-1.1.0-py3-none-any.whl:

Publisher: publish.yml on adonath/voronoi-mosaic

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.1.0 This release

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page