Color Palette Extractor

Extracting a palette from an image is one of those tasks that sounds trivial and turns out to need real thought. The naive approach — count every unique RGB value, take the top N — fails badly because real photographs have millions of slightly-different RGB values, none of which appear more than a few times. The right approach is **clustering**: group similar pixels into N buckets, then return the average color of each bucket. This is what every palette extractor in production (Pinterest's color search, Spotify's album-cover palettes, Material You's wallpaper theming) does under the hood. The algorithm is **k-means**, and a competent implementation runs in a couple of hundred lines of code with no dependencies.

The implementation here samples pixels off a downscaled canvas (max 200px on the longest side) and runs k-means with **k-means++ initialization** — a heuristic that picks initial cluster centers far from each other, which produces better-than-random convergence. The number of iterations is capped at 30; on real images the algorithm usually converges in 5–10. The downscale step is the key speed optimization: clustering 40,000 sampled pixels takes ~50 milliseconds, while clustering the full 8 million pixels of a 4K photo takes ~5 seconds for results that are indistinguishable. Dominant colors are by definition the most common, so they survive any reasonable downsample.

A subtle but important detail: **alpha-near-zero pixels are skipped**. PNGs with transparent backgrounds (logos, icons, sprites with cutouts) have huge areas of fully-transparent pixels. Browsers report those pixels as having undefined RGB (effectively black or whatever fill color the canvas defaults to). Including them in the cluster pool produces a palette dominated by "transparent = black" which is wrong. The extractor skips pixels with alpha below 16/255 (about 6% opacity) — well below visible threshold but above the rounding noise some PNG encoders produce. The result is a palette that reflects only what the eye actually sees.

The output for each cluster includes its **pixel-count percentage**. This is more useful than it sounds. The largest cluster by pixel count is the image's background or dominant fill — usually less interesting visually than the smaller clusters that contain the subject. The 30%-of-pixels cluster from a photo of a red car on grass is the grass; the 8% cluster is the car. Knowing the cluster size lets you tell "background tint" from "accent color" at a glance, which matters when you're picking colors for a design that should feature, not just match, the image.

**Palette size (k)** is the single tuning knob. The right value depends on what you'll use the palette for:

- **k=2 or 3** is "what's the brand color of this logo?" — finds the most-saturated dominant colors and an off-color (usually white/black background). - **k=4-6** is the design-system sweet spot — enough variety to build a theme, not so many that adjacent entries look identical. - **k=8-12** is for reference work — building a moodboard, matching a photograph's color story. - **k=16+** approaches indexed-color GIF territory; the clusters get small and noisy, with several near-duplicate entries.

The result is **non-deterministic between runs** because k-means++ uses randomness for initialization. For typical images the difference between runs is a few RGB values, well within visible threshold. For images with sharp color discontinuities (logos with pure brand colors, posters), the result is stable. If you need deterministic output across runs, the right tool is a fixed-seed clustering library at the command line, not a browser-based extractor.

**Use cases worth highlighting:**

- **Branding from a logo**: drop in a competitor's logo, get their brand color in 1 click. - **Theme generation from a photograph**: drop in a mood-board image, get a 6-color palette for the rest of the design. - **Image-to-CSS-variables**: copy the extracted HEX values straight into your design tokens. - **Quick "what color is this?"**: drop in a screenshot, pick the swatch you want.

Everything runs in your browser. The k-means implementation is a small pure function (under 200 lines, with vitest coverage including the k-means++ initialization, cluster-ordering, and empty-input edge cases). The image is decoded by the browser's native image pipeline and never transmitted. EXIF GPS data, undecoded color profiles, embedded metadata — all stay on your machine. You can verify in DevTools: zero outgoing image bytes during extraction.