How to use`kmeans` parameter in Pillow Image.quantize?

Question

Doc page for PIL.Image.quantize gives:

Image.quantize(colors=256, method=None, kmeans=0, palette=None, dither=1)
    colors – The desired number of colors, <= 256
    kmeans – Integer

https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.quantize

How to use this kmeans parameter?

If kmeans is "number of clusters to use", isn't that going to be the same value as colors? Or is the idea to specify say 10 clusters but only 3 colors, and have the other clusters pick up the not-of-interest colors?

Answer 1

I don't see in the documentation the definition you report of kmeans as the number of "clusters", but from my understanding the number of clusters in some cases might be larger than the number of obtained colors.

Suppose you want to reduce a greyscale image with, say, 100 unique colors (out of 256 a greyscale image can have) to 8 colors. In the case of uniform quantization method (which, however, is not implemented by Pillow), if those 100 colors are uniformly distributed in the (0,255) range, specifiyng 8 clusters you will probably get 8 colors, but if those 100 colors are badly distributed, so that there are no pixels with colors in one (or more) of the clusters, you will get a resulting image with 7 (or less) colors.

Other quantization methods make sure that clusters are not empty and so the number of colors is always the same as the number of clusters.

An overview of quantization topic can be found here.

However, I made some tests specifyng only kmeans parameter and I couldn't see any decrease of colors, so I guess the parameter kmeans isn't the number of clusters, it might be a parameter controlling clustering algorithm convergence as reported in the comment by Mark Setchell.