Technology moves fast! ⚡ Don't get left behind.🚶 Subscribe to our mailing list to keep up with latest and greatest in open source projects! 🏆

Subscribe to our mailing list


Finding dominant colors of an image using k-means clustering

Subscribe to updates I use DominantColor

Statistics on DominantColor

Number of watchers on Github 52
Number of open issues 0
Main language Swift
Open pull requests 0+
Closed pull requests 0+
Last commit almost 4 years ago
Repo Created almost 4 years ago
Repo Last Updated almost 2 years ago
Size 1.77 MB
Organization / Authorobjcio
Page Updated
Do you use DominantColor? Leave a review!
View DominantColor activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating DominantColor for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Finding the dominant colors of an image using the CIE LAB color space and the k-means clustering algorithm.


Color Space

The RGB color space does not take human perception into account, so the CIELAB color space is used instead, which is designed to approximate human vision [1].

Conversion from RGB

The conversion from RGB values to LAB values requires first transforming the RGB values to an absolute color space like sRGB[2]. On iOS, this conversion is not necessary because sRGB is the native device color space[3]. On OS X, the conversion can be performed using -[NSColorSpace sRGBColorSpace].

Once the colors have been converted to sRGB, they are first converted to linear sRGB values and then to CIE XYZ values[4]. Finally, they are converted to the CIE LAB color space[5] using a D65 standard illuminant[6][7].

Color Difference

A color difference algorithm is used to group similar colors. API consumers can choose between the CIE 76[8], CIE 94[9], and CIE 2000[10] algorithms for low, medium, and high color grouping accuracy, respectively. The default algorithm is CIE 94, as it provides results that are close to CIE 2000 with a negligible performance impact in comparison to CIE 76.

Clustering (k-means)

Pixels are grouped into clusters of dominant colors using a standard k-means clustering algorithm[11][12][13].

Choosing K

The k-value was originally chosen based on the rule of thumb k = sqrt(n/2)[14] but this resulted in k-values that were too large to run in a reasonable amount of time for large values of n. Right now, I'm using a magic value of 16 because empirical testing showed that it yielded the best results for many different images but I'm still looking into a number of more data-driven alternate approaches.

Selecting Initial Centroids

The initial centroids are currently selected on a random basis. An alternative approach is to use the k-means++ algorithm, in which after the first centroid is selected randomly, the subsequent centroids are selected with probability proportional to the distance from the randomly selected centroid.


The k-means algorithm has a worst case runtime that is super-polynomial in the input size[15], so sampling large numbers of pixels is a problem. Images are automatically downsampled such that the total number of pixels is less than or equal to a specified maximum number of pixels to sample. The value I've been using is 1000, which is a good balance between accurate results and runtime.


Everything is implemented in Swift except for the functions that convert between color spaces, which use GLKit and thus must be written in C (since Swift doesn't support C unions at this time).


The project includes Mac and iOS apps that can be used to see the results of the algorithm and to run a simple benchmark.

Mac app iOS app



Licensed under the MIT License.



DominantColor list of languages used
Other projects in Swift