How to Use This Tool
Drop in an image. You get the colours that are actually in it, how much of the image each one covers, and a contrast reading so you know which ones you can put text on.
Why not just average the pixels
Because an average assumes there is one thing to be average of. A photograph of a red flower on green leaves has two populations of pixels, and the mean of the two lands between them — a brown that appears in neither the flower nor the leaves. It is a correct calculation of a quantity nobody wanted.
Clustering asks a different question: what groups do the pixels fall into? Each returned colour is then the centre of a real group, which is why every swatch you get can be found somewhere in the image.
Median cut, and why the colours have a share
The method is median cut. Put every pixel in one box in colour space, find the axis along which the box is widest, split it at the median, and repeat on whichever box is now largest until you have as many boxes as you asked for. Each box becomes one palette entry.
Because the split is at the median rather than the midpoint, the boxes end up holding comparable numbers of pixels rather than comparable volumes of colour space. That is what makes the percentages meaningful — a colour covering 40% of the image is genuinely 40% of the pixels.
Linear light, and the reason blends look dark
The bytes in an image file are gamma-encoded: the value 128 is not half the light of 255, it is about 22% of it. Averaging those bytes directly is averaging the wrong numbers, and the result comes out noticeably too dark. This is the same bug behind the familiar complaint that a 50% blend between two colours looks muddy in most software.
So every average here is taken in linear light and converted back afterwards. It is two extra lines and it is the difference between a colour you would use and one you would reject.
The near-white and near-black option
Most photographs contain a lot of very light and very dark pixels — sky, shadow, paper, a product shot's background. They are real, and they will dominate the palette, and they are almost never what you were looking for. The filter drops pixels above 96% and below 6% lightness. Turn it off when the image is genuinely monochrome, or when the background colour is the thing you want.
What the contrast numbers mean
Each swatch shows its best contrast ratio against black or white. 4.5:1 is the WCAG AA threshold for normal text and 3:1 for large text. A colour that clears neither is a background for images, not for words.
