Crate okolors

Expand description

Create a color palette from an image using k-means clustering in the Oklab color space.

This library is a simple wrapper around the quantette crate but only exposes functionality for generating color palettes. Additionally, this crate adds a few additional options not present in quantette.

§Features

This crate has two features that are enabled by default:

threads: adds a few methods to the Okolors builder (parallel and batch_size).
image: enables integration with the image crate.

§Examples

To start, create an Okolors from a RgbImage (note that the image feature is needed):

let img = image::open("some image")?.into_rgb8();
let palette_builder = Okolors::try_from(&img)?;

Instead of an RgbImage, a slice of Srgb<u8> colors can be used instead:

let srgb = vec![Srgb::new(0, 0, 0)];
let palette_builder = Okolors::try_from(srgb.as_slice())?;

If the default options aren’t to your liking, you can tweak them:

let palette_builder = Okolors::try_from(&img)?
    .palette_size(16)
    .lightness_weight(0.5)
    .sampling_factor(0.25)
    .parallel(true) // this option requires the `threads` feature
    .sort_by_frequency(true);

To finally generate the palette, use:

Okolors::srgb8_palette for a Srgb<u8> palette
Okolors::srgb_palette for a Srgb palette (components are f32 instead of u8)
Okolors::oklab_palette for an Oklab palette

For example:

let palette = palette_builder.srgb8_palette();

To clarify, the Oklab colorspace is used to quantize the colors in all cases. The methods above just determine what colorspace you want the final colors converted into.

All of the color types present in the public API for this crate (like Srgb or Oklab are from the palette crate. You can check it out for more information. For example, its documentation should provide you everything you need to know to cast a Vec<Srgb<u8>> into a Vec<[u8; 3]>.

Re-exports§

pub use image;
pub use palette;

Structs§

AboveMaxLen
An error type for when the length of an input (e.g., Vec or slice) is above the maximum supported value.
ColorSlice
A simple new type wrapper around &'a [Color] with the invariant that the length of the inner slice must not be greater than MAX_PIXELS.
Okolors
A builder struct to specify options for palette generation.
PaletteSize
This type is used to specify the (maximum) number of colors to include in a palette.

Constants§