Extract a color palette from image pixel samples

Turn a representative list of image pixels into a compact, useful color palette. This capability groups nearby RGB values, ranks the resulting clusters by their weighted presence, and reports each dominant color as both a hexadecimal swatch and RGB channels, together with its pixel count and share of the supplied sample. It is designed for pipelines that have already sampled or counted pixels and need a deterministic summary without uploading or decoding the original image.

Prepare representative pixel samples

Start with pixels sampled from across the whole image rather than from one convenient corner. Each record contains red, green, and blue channel values from 0 through 255. If preprocessing has already counted identical colors, add a count to the record; otherwise omit count and every record represents one pixel.

Weighted records are especially useful for images with large flat regions because they preserve the true frequency without forcing you to repeat the same RGB object thousands of times. Sampling should be spatially balanced. A simple grid, uniform stride, or resized preview usually provides a better picture than taking the first pixels in file order.

Keep transparent pixels out unless you have already composited them onto the background that viewers will see, because an invisible RGB value should not shape a visible palette. The algorithm merges exact duplicates before clustering, so repeated records and an equivalent counted record produce the same result. This makes it safe to choose whichever input representation is easiest for your image-processing pipeline.

Understand deterministic color clustering

Choose n as the maximum number of dominant colors you want. It must be an integer of at least one, and the capability returns fewer colors when the sample contains fewer distinct RGB values. Centers are initialized deterministically from frequent and well-separated samples, then refined through bounded weighted clustering in RGB space.

No random seed, clock, network service, or model is involved, so identical input produces identical output. Nearby shades can join the same cluster, allowing compression artifacts, antialiasing, gradients, and small lighting changes to contribute to a representative swatch instead of fragmenting the answer into nearly identical entries. The representative RGB value is the weighted mean of its cluster, rounded to valid channel integers, and its hexadecimal value is derived from those same channels.

Clusters are ranked by pixel count, with a stable hexadecimal tie-breaker. RGB distance is intentionally straightforward and predictable; it is a practical summary rather than a perceptual color-management system, so color-critical print workflows may prefer to convert samples into a perceptual space before using a specialized quantizer.

Use counts and shares in downstream work

Every item includes hex, an RGB object, count, and share. Use the first swatch for a rough dominant accent, but inspect its share before assuming it represents most of the picture. A leading color with a share near one half is a much stronger visual signal than a leading color in an evenly divided five-color palette.

For automation, store the full ranked list so thresholds can evolve without reprocessing samples. Invalid channel values, malformed records, excessive input, and n below one fail explicitly instead of producing a misleading palette.