Add dominant color method

[392781]

Fixes #4634.

Changes proposed in this pull request:

• Adds a method to determine the dominant colors in an image using k-means clustering

I added some very basic tests but seeing as I'm very new at open source contributing I am open to suggestions to improve them.

[392781]

One thing to note about this is that k-means clustering takes a few seconds to compute for larger images which is bothersome. I'm currently working on improving the speed of the algorithm.

One catch-all method of doing this is to rescale the image for faster results. This solution is simple and doesn't require a lot of bloated code on top of the algorithm. The cost is that there is a loss of pixel information through rescaling so the dominant colors will come out different than original image.

Another is to do a bit of math on the color spaces used and throw out some less necessary pixels (kind of how Color-Thief does it on the RGBA space. The benefit is avoiding some more computation. The cost is readability of the method and the need to cover all supported color spaces. One way to sidestep this is to convert to a more familiar color space such as HSV, RGB, or RGBA; however, I'm not that knowledgable about these spaces and the effects of converting between them (however, it seems colorthief does it so I'm not sure.)

I'm hesitant to implement option 2 because I do not want this method to become too bloated or more complicated than it already is... But these are some ideas to think about. For now I'll test out resizing as an option and maybe play around with converting modes.

EDIT: I decided to implement the option to rescale since excluding colors yielded mixed results.

[hugovk]

The Image module is pretty big and I wonder if this would be better suited in another one?

• ImageColor
• ImageOps
• ImageStat

[392781]

The Image module is pretty big and I wonder if this would be better suited in another one?

* [`ImageColor`](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html)

* [`ImageOps`](https://pillow.readthedocs.io/en/stable/reference/ImageOps.html)

* [`ImageStat`](https://pillow.readthedocs.io/en/stable/reference/ImageStat.html)

I've been thinking the same thing. I think if it were placed anywhere else it may be in ImageOps... ImageColor doesn't feel like a great fit for what this does unless maybe it gives an option to return colors in string formats.

[nulano]

I'm not sure ImageOps is the right place. It is a set of functions that return a processed variation of the source image, not properties of an image.

The ImageOps module contains a number of ‘ready-made’ image processing operations.

---

ImageColor doesn't seem right either:

The ImageColor module contains color tables and converters from CSS3-style color specifiers to RGB tuples. This module is used by PIL.Image.new() and the ImageDraw module, among others.

---

ImageStat looks like the closest match, but the PIL.ImageStat.Stat class caches results and the proposed function takes parameters. Maybe make this a module function in ImageStat (e.g. PIL.ImageStat.dominant_colors(im, ...))?

The ImageStat module calculates global statistics for an image, or for a region of an image.