Okolors

Okolors takes an image and produces a color palette consisting of the image's average colors. It does this by converting the image's pixels to the Oklab color space and then performing k-means clustering. By using a proper color space for color difference and a more accurate clustering algorithm, this helps to ensure that the generated palette is truly representative of the input image.

One of the main intended use cases for Okolors is to generate colors for a theme based off a wallpaper. In line with this goal, the Okolors binary also supports printing the final average colors in multiple Okhsl lightness levels. For example, you can specify a low lightness level for background colors and a high lightness for foreground text in order to achieve a certain contrast ratio. The Okhsl color space is ideal for this, because as the lightness is changed, Okhsl preserves the hue and saturation of the color (better than other color spaces like HSL).

The Okolors binary supports jpeg, png, gif, and qoi images by default. See the features section for more info. Precompiled binaries are available on Github.

For more specific information regarding the okolors library see the docs.rs page as well.

Examples

Let's use the following photo for the examples below.

Running Okolors for this image with the default options gives the following sRGB hex values.

> okolors 'img/Jewel Changi.jpg'
020606 08373E E2E4E7 4F8091 4E2F26 CA835A 926F97 BB7B7B

If your terminal supports true color, then you can use -o swatch to see blocks of the output colors.

> okolors 'img/Jewel Changi.jpg' -o swatch

We can increase the color accuracy by increasing the number of trials, -n, and lowering the convergence threshold, -e.

> okolors 'img/Jewel Changi.jpg' -n 3 -e 0.01 -o swatch

Let's get these colors in additional lightness levels using -l.

> okolors 'img/Jewel Changi.jpg' -l 10,30,50,70 -n 3 -e 0.01 -o swatch

If we're providing our own lightness levels, maybe we want to cluster the colors by hue and saturation only. Let's set the lightness weight to 0.01 using -w.

> okolors 'img/Jewel Changi.jpg' -w 0.01 -l 10,30,50,70 -n 3 -e 0.01 -o swatch

That ended up bringing out an additional pinkish color but also merged white and black into a gray. So, use this at your own discretion!

If some of the colors still seem quite similar, then you can reduce/set the number of colors through -k.

> okolors 'img/Jewel Changi.jpg' -k 7 -w 0.01 -l 10,30,50,70 -n 3 -e 0.01 -o swatch

To see all the other command line options, pass -h for a summary or --help for detailed explanations. Note that the CLI flags translate one-to-one with the library parameters, if there is an equivalent.

Performance

Despite using k-means which is more accurate but slower than something like median cut quantization, Okolors still seems to be pretty fast. Excluding the time to read and decode the image from disk, below are Okolors's running times for each image as reported by criteron. The parameters used were k = 8, convergence_threshold = 0.05, trials = 1, max_iter = 1024, and lightness_weight = 1.0. The benchmarks were run on a 4-core CPU, so YMMV on different hardware (especially with more or less cores).

Note that these are high resolution images, so the running time can be much faster for lower resolution images. The binary also has a CLI flag to create a thumbnail for images over a certain size.

The above times could be reduced by properly leveraging SIMD, possibly once portable-simd becomes stable.

Features

Library

• threads: enabled by default and toggles parallelism via rayon.

Binary

• threads: enabled by default and toggles the corresponding library feature.

• jpeg, png, gif, and qoi: support for these image formats is enabled by default.

• jpeg_rayon: enabled by default, allows multiple threads for decoding jpeg images.

• webp: WebP support is not enabled by default, as it seems that the image crate still has lingering bugs for WebP in certain cases: 1, 2, 3, 4. Panics and bugs resulting from this should be directed upstream.

• avif: similarly, due an issue with AVIF support in the image crate, this feature is not enabled by default and instead uses the libavif-image crate. Compiling with this feature requires cmake and nasm on the system.

• bmp and tiff: support for these image formats is not enabled by default.

References

• kmeans-colors served as the basis for Okolors. If you want to perform other k-means related operations on images or prefer the CIELAB colorspace, then check it out!
• The work by Dr. Greg Hamerly and others was a very helpful resource for the k-means implementation in Okolors.
• The awesome palette library is used for all color conversions.