Apps Part of Lumina

Image Palette Extractor (k-means, median cut)

Pull a 2–32 color palette from a photo with k-means in OKLab, median cut or a histogram.

Try an example:

More about this tool

How it works

Upload a PNG, JPEG, WebP or GIF image and get its main colors with the share of the image each one covers, plus how well the palette represents the image. Download the palette as HEX, GIMP GPL, JASC-PAL, JSON, CSS variables or Adobe Swatch Exchange (ASE).

  • The image is decoded to 8-bit sRGB and scaled so its longer side is at most 512 pixels; pixels with alpha below 128 are ignored. Up to 65,536 pixels are sampled on a fixed stride.
  • Median cut (Heckbert 1982) splits the colour box with the largest count-weighted error at the weighted median of its widest channel, then refines with four k-means passes in RGB — the same function Flipline Pixel Studio uses. Histogram groups colours into 32 levels per channel and keeps frequent bins that differ by at least about 42 RGB units — the same function as Lumina Palette Studio.
  • k-means starts from the median-cut colours and runs Lloyd iterations in OKLab, where distances follow perceived differences, until nothing changes (at most 24 passes). Centres outside sRGB are mapped back with the CSS Color 4 method.
  • Share = fraction of opaque sampled pixels whose nearest palette color (OKLab) is that color. Mean error = average OKLab distance × 100 from each pixel to its nearest palette color; lower is a better fit. Results are deterministic.

Sources

Part of Lumina

  • Lumina Photo editor & image toolkit

    Bring out what you saw. A free photo studio, right in your browser.

    Open Lumina

Related tools

How to use the Image Palette Extractor

Pull 2–32 main colours from a photo with k-means in OKLab, median cut or a histogram, see how much of the image each covers, and download GPL, JSON, CSS or ASE.

What it is for

A good palette often starts with a photo: a beach, a poster, a product shot. Eyedropping colours by hand picks whatever pixel you hit, including noise and shadows. A palette extractor groups all pixels into a few representative colours and tells you how much of the picture each one covers.

Upload a PNG, JPEG, WebP or GIF image, choose 2–32 colours and one of three methods:

  • k-means in OKLab groups colours by how different they look, so it usually gives the closest match.
  • Median cut is the method Flipline's Pixel Studio uses for sprites.
  • Histogram is what Lumina's Palette Studio uses; it favours frequent, clearly different colours.

The palette comes back with shares, a fit score and downloads in HEX, GIMP GPL, JASC-PAL, JSON, CSS variables and Adobe Swatch Exchange (ASE). Every text download is read back before it is offered. The image is scaled to at most 512 pixels on the longer side for the analysis; it is not stored.

Worked example

The built-in example is a generated 96 × 64 picture with four vertical fields — deep teal, sea green, cream and sand — each shaded slightly darker towards the bottom. With k-means and 4 colours the result is:

4 colors by kmeans; mean error 1.642 (OKLab × 100).

The colours are #15495D, #6B9B96, #DDB576 and #DEE2D1, each with a 25 % share. They are a little darker than the original top rows because the shading pulls every average down.

Ask for 3 colours and the two light fields merge into #DECCA5 with a 50 % share; the mean error rises to 4.012, a sign that three colours are not enough for this picture. Median cut gives practically the same answer here (4.013). The histogram method gives 2.163 for four colours — its colours come from the most frequent bins, not from averages, so they fit slightly less closely.

How to read the result

  • Colors by share of the image is a bar where each colour's width is its share.
  • Palette lists each colour with its share in percent. Shares count opaque pixels whose nearest palette colour is that one.
  • The summary carries the mean error: the average OKLab distance × 100 between each pixel and its nearest palette colour. Lower means the palette describes the image better; compare it between methods and colour counts.
  • Downloads give the same palette in six formats. The ASE file holds one named group of RGB swatches.

Tips and common mistakes

  • Start with 5–8 colours for photos. If the error drops a lot when you add one more, the extra colour matters.
  • Crop first. A big sky or white border dominates the shares.
  • Transparent pixels (alpha below 128) are ignored, so logos on transparent backgrounds work well.
  • For pixel art, use median cut so the palette matches what Flipline produces.
  • Flat images with few colours return exactly those colours, and a shorter palette if there are fewer than you asked for.
  • Check text colours from the palette with the Contrast Fixer before using them on top of each other.

FAQ

Is the result always the same?

Yes. All three methods are deterministic: the same image and settings always give the same palette.

Why k-means in OKLab and not RGB?

Distances in OKLab follow perceived differences, so two blues that look alike are grouped even when their RGB numbers differ a lot.

Can I open the ASE file in design software?

ASE is the swatch exchange format of Adobe apps, and other editors read it too. The file holds RGB swatches; there is no colour profile.

How big can the image be?

Up to 25 MB and 50 megapixels. It is scaled down to 512 pixels on the longer side for the analysis.

Guide last updated:

For scripts and AI agents

  • JSON API: POST https://luminapaletteextractor.usefulweb.app/api/v1/calculate (same calculation as this page)
  • Interface description: OpenAPI 3.1 · AI guide: llms.txt
  • MCP server (Streamable HTTP): https://luminapaletteextractor.usefulweb.app/mcp · tool name lumina_palette_extractor
Example request
curl -s -X POST https://luminapaletteextractor.usefulweb.app/api/v1/calculate \
  -H 'content-type: application/json' \
  -d '{…see OpenAPI examples…}'
Feedback · ideas & bug reports welcome