Extract a palette from an image

How it works

A picture does not contain a dominant colour waiting to be read off it. It contains a few million pixels, and a palette is the result of a decision about how to group them: how many groups to allow, what counts as near, and which pixels are given a vote. Dominant colour is not a measurement, it is the output of that decision. Two extractors run over the same photograph will disagree, and neither of them has made an error.

Two ways to divide the colours up

k-means places a fixed number of centres in colour space and moves each one to the mean of the pixels nearest it, over and over, until they stop moving. It has to be told how many centres to place, and what it minimises is the total squared distance from every pixel to its own centre, so the centres settle where pixels are dense. A long gradient, a sky or a wall falling into shadow, collapses into a single centre, because that placement is what makes the distance small.

Median cut works the other way round. Every pixel starts in one box; the box is measured on each of its three axes, sorted along the widest one, and cut at the median. Repeat on whichever box holds the most pixels. Heckbert published the method in 1980 for palette quantisation, and cutting at the median rather than the midpoint is the whole character of it: the boxes come out with roughly equal populations instead of roughly equal volumes, so a picture with one huge smooth region gets that region subdivided rather than represented once.

The two do not merely suit different pictures, they disagree about what a colour is. Measured on synthetic images where the right answer is known in advance: three equal flat bands of #e63946, #457b9d and #f4a261 come back from k-means as those exact three values, every swatch sitting zero distance from its own pixels.

Median cut on the same bands recovers #457b9d, gives half the frame to #ef8a59 (an average of the red band and the orange band), and fills its third slot with a dusty rose mixed out of the blue and the red. Its cut lands at the population median rather than at a colour boundary, so a box straddles two bands and hands back a colour that is in neither.

That gap holds on photographic material too. On a five-region synthetic photograph the widest distance between a swatch and a pixel it stands for came to 0.080 under k-means and 0.319 under median cut, and the same figure is reported for your own file.

Median cut earns its option where equal occupancy is the point. Asked for four colours from a black-to-white ramp of one pixel per level, it returns #242424, #616161, #a0a0a0 and #e0e0e0, each standing for exactly a quarter of the pixels; k-means splits the same ramp 28.1, 27.3, 24.2 and 20.3 percent, since it is equalising distance rather than population. Neither division is the correct one. They answer different questions, and a set of swatches meant to carry equal weight wants the first. For recovering the colours a picture actually contains, k-means is the default here.

Averaging stored bytes drags a mixture dark

The number in an 8-bit sRGB channel is not proportional to light. It has been through the sRGB transfer curve from IEC 61966-2-1, which spends more of the 256 codes on dark values than light ones, so adding two bytes and halving is arithmetic performed on the wrong quantity. Black and white averaged as bytes gives 128, and 128 decodes to a linear value of 0.216, a grey reflecting about a fifth of the light rather than half of it. Decode first, average, then re-encode and the answer is 188, or #bcbcbc. In OKLab those two greys sit at lightness 0.600 and 0.795.

The same error runs through every cluster average, more quietly. Take a field at #3f7a2a and a sky at #7ab8e8 in equal measure. Averaged as stored bytes the centre lands on #5d9989; averaged in linear light it lands on #629dac. Both are a muted teal that appears nowhere in the picture, which is the useful signal that one cluster is covering two things. The byte average is darker and pulled towards the green, so it also misreports which of the two the mixture is closer to. Every average on this page is taken after decoding.

Distance in sRGB is not perceived difference

Clustering needs a definition of near, and Euclidean distance across three sRGB channels gives all three the same weight. Light does not. Moving the green channel by 16 of 255, from #00cc00 to #00dc00, is an OKLab difference of 0.045; the same 16 steps on blue, #0000cc to #0000dc, comes to 0.027.

A clusterer measuring in sRGB reads those two moves as identical, so a single threshold is too coarse for green and too fine for blue: it holds together a green range a person sees as two colours, then spends a whole swatch on a blue variation nobody would call a second colour. Median cut inherits the same bias when it picks a box's widest axis. The k-means option runs in OKLab instead, the perceptual space the palette builder page sets out.

The backdrop wins on count

On product photography the most common colour in the frame is the paper sweep behind the product, and on a screenshot it is the page background. Counting pixels answers a question nobody asked. The filter drops any sampled pixel whose OKLab chroma is under 0.04 and whose lightness is above 0.92 or below 0.25, which for a neutral grey means #e5e5e5 and lighter, or #212121 and darker.

The chroma clause is what keeps saturated colours in: pure yellow sits at lightness 0.968, well over the ceiling, and stays in the vote on its chroma of 0.211. The pixel count the filter removed is reported, so the cost of turning it on is visible.

Nothing here is random. Pixels are read on a fixed grid at a stride that brings the long edge to about 200, capping the vote at 40,000 pixels however large the file. k-means is seeded by k-means++ from a fixed constant rather than from Math.random, and stops once no centre has moved further than 0.0001 in OKLab, or after 40 passes.

The same file with the same settings returns the same palette. Two reported figures say whether to believe it: the share each colour holds, and the widest gap between a swatch and the pixels standing behind it. A wide gap means the picture carries more variety than the number of colours you asked for.