README

This is a tiny image processing library to convert your images to Voronoi mosaic, Voronoi relief, or Warhol effect images. We used k-means clustering algorithms to determine the position of Voronoi sites and pixel groups of Warhol effect.

How to use

pip install imgrit

The library depends on Pillow, NumPy, and SciPy.

If you have scikit-learn, the library uses the faster k-means. You can install it together with pip install "imgrit[sklearn]".

The following is the input image.

from PIL import Image
import imgrit

my_image = Image.open("../images/original.jpg")
voronoi_mosaic = imgrit.voronoi_mosaic(my_image, 250)
voronoi_mosaic.save("voronoi-mosaic.png")

warhol_effect = imgrit.warhol_effect(my_image, 10)
warhol_effect.save("warhol-effect.png")

Voronoi relief

voronoi_relief renders each Voronoi region as smooth, slightly raised paint. The regions are separated by recessed gray lines, and the whole image is lit from the upper left.

voronoi_relief = imgrit.voronoi_relief(my_image, 250)
voronoi_relief.save("voronoi-relief.jpg")

You can adjust the look with the following arguments. Sizes are relative to the typical region size, which is the square root of the number of pixels divided by the number of regions. So the look stays similar for any number of regions.

For example, the following makes darker lines and flatter regions.

imgrit.voronoi_relief(my_image, 250, line_color=40, height=0.02)

The relief is computed as a height map. For each pixel, the library computes the exact distance to the boundary of its Voronoi region. The height rises from the boundary and becomes flat inside the region, and the lines sit in U-shaped grooves. The image is then shaded with diffuse and specular lighting based on the slope of the height map.

Performance

Rough execution times by image size. voronoi_mosaic fits k-means on a random subsample of pixels (200 pixels per region, at least 10,000 pixels), so the number of regions has little effect on the time up to a few hundred regions. For large images, most of the time is spent on pixel-wise processing, which grows with the number of pixels.

With scikit-learn (pip install "imgrit[sklearn]"):

Without scikit-learn (SciPy's k-means is used):

SciPy's k-means becomes very slow with many regions, so installing scikit-learn is recommended if you use more than a few hundred regions. Peak memory usage was about 4 GB for a 12 MP image.

voronoi_relief places the regions in the same way as voronoi_mosaic:

Peak memory usage was also about 4 GB for a 12 MP image.

Measurement environment: Mac mini (Apple M4, 10 cores, 24 GB memory), macOS 15.7, Python 3.14.7, NumPy 2.5.3, SciPy 1.18.1, Pillow 12.3.0, scikit-learn 1.9.1. voronoi_relief was measured later on the same machine with NumPy 2.5.4 and Pillow 13.0.0. Each value is a single run on images/original.jpg resized to the given size. Times vary with your machine and the input image, so please use them as a rough guide.

OpenSea

If you'd like to see more images, please visit Asakura Gallery Digital at OpenSea.

Citations

A novel method for Voronoi mosaic effect using k-means clustering