Tolerance Documentation is Incorrect

[SturgeonInc]

There are two issues:

Group colors to limit the output and give a better visual representation.

While technically accurate "group" is technically accurate, but misleading. The program scans pixel by pixel. When a pixel is scanned, its color is compared to that of every other unique color on record. If the color of the pixel is deemed unique enough (something determined by the tolerance parameter), it is saved as a unique color. If not, it is ignored. There is no averaging or blending.
For example, if the program is run on the image of a rectangle for whose left half is solid red and the right half is solid blue, given a high enough tolerance, the image will group the whole image's color as pure red.

Similarly, it would be blue if blue were on the left. It depends on what pixels are scanned first, so colors that are further up and further left are the ones that are counted as unique.
I guess not technically an issue, but I feel like this should be noted in the documentation.

[Tolerance is] based on a scale from 0 to 100. Where 0 won't group any color and 100 will group all colors into one.

This is outright false. The "tolerance" parameter is just the minimum distance in the CIELAB (Lab*) color space (as determined by the CIE76 algorithm: math.sqrt((l * l) + (a * a) + (b * b))) for two colors to be grouped together. As a result, although tolerance = 0 works as stated, tolerance = 100 does not. For example, the minimum integer value for the program to group the red and blue rectangle from before into one color is tolerance = 177. Thankfully, you can enter tolerance values greater than 100 without raising an error because of the other issue I opened: ArgumentTypeErrors aren't raised if the module isn't run using the command line.

[Sahil028]

Hi @SturgeonInc Thanks for this explanation, as I had some doubts along the same lines. As I am working on a piece where generally the variety of colors in an image ranges from 10 to 20. I have used different types of modules either it's based on some kind of clustering ( where we input the clusters generally but I would prefer it in an automated way) or some version of distance formula. Also tried automatic k finding but that takes a lot of time. Did you find any better color extraction technique ?

[SturgeonInc]

I don’t fully understand what your application is. What I ended up using was:
https://github.com/zygisS22/color-palette-extraction

It is in Javascript, but served my purposes. It has a nice demo app to play around with, as well as a useful article explaining how it works (median cut algorithm, in short).

If you’re looking for something much more in-depth, there’s TinEye’s multicolor engine API.

Both automatically cluster colors together to a desired degree, although the former is a little more complicated to alter.

I hope this helps.