Image Color Palette Extractor (local)

How image color palette extraction works

Pulling a palette from a photo is one of the oldest tricks in design tools — Pinterest's Lens, Adobe's Color Theme tool, Procreate's Color Discovery, Lightroom presets and countless brand guides all use some flavor of the same algorithm: take an image, reduce its millions of pixels to a handful of representative hues, sort them by frequency or perceived importance, and present them as a swatch list. The two classics are k-means clustering (used in this tool) and median cut (the original GIF quantizer); modern variants include octree quantization and the Material Design Palette algorithm that weights vibrancy on top of frequency.

The k-means workflow in detail

• Pick a target number of colors K (5 is the sweet spot for moodboards).
• Initialize K centroids randomly in color space — better seeds (k-means++) converge faster.
• Assign every pixel to the nearest centroid using a distance metric (usually Euclidean in RGB).
• Recompute each centroid as the mean of the pixels assigned to it.
• Repeat until the centroids stop moving (or a max iteration cap is reached).
• Return the centroids, optionally sorted by cluster size for "dominance" ordering.

Why the color space matters

RGB is convenient but perceptually non-uniform: equal numeric distances do not look equally different to the human eye. Clustering in CIE Lab or modern OKLab yields palettes that look "cleaner" because the algorithm respects how we actually perceive color difference. Premium tools convert to Lab before clustering and back to sRGB for display. For pure speed you can stay in RGB and downsample the image first — a 100×100 thumbnail produces nearly identical palettes to the full-resolution input.

Vibrancy filtering and the Material approach

Pure frequency analysis often returns muddy beiges and greys — the "average" of a photo. The Material Design Palette library solves this by tagging each cluster with vibrancy categories (Vibrant, Muted, LightVibrant, DarkMuted, etc.) and skipping clusters with extreme luminance or low chroma. This is why Android extracts a usable accent color from any album art automatically.

Libraries and tools in the wild

• ColorThief — the popular JS library, median-cut based, runs in the browser.
• Vibrant.js — Material Palette port to JavaScript.
• Pillow (Python) — Image.quantize() with median cut.
• Colormind, Coolors.co, Adobe Color, Canva Color Picker — hosted UIs that wrap the same ideas.
• Web Workers — offload k-means off the main thread to keep the UI responsive on big images.

Use cases

• Brand identity — pull the dominant hues from a logo or hero photo to seed a design system.
• Data viz — generate categorical scales that feel native to the chart's background image.
• Moodboards — combine palettes from multiple references into a unified swatch sheet.
• Accessibility audits — check the extracted colors against WCAG contrast for overlay text.
• Photo editing — match Lightroom presets to a reference image's tonal palette.

FAQ

Which algorithm is best? k-means produces the most perceptually accurate palettes; median cut is faster and was the GIF standard for decades.

How many colors should I extract? 5 to 8 covers most design needs; more than 12 starts to feel noisy.

Why do gradients give weird results? A smooth gradient has no clusters — the algorithm has to pick arbitrary cut points, so accuracy drops.

Is my image uploaded anywhere? No. Everything happens client-side in the browser — pixels never leave your machine.