README

This is a tiny image processing library to convert your images to Voronoi mosaic 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")

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.

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. 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