Struct quantette::ImagePipeline

pub struct ImagePipeline<'a> { /* private fields */ }

A builder struct to specify options to create a quantized image or an indexed palette from an image.

Examples

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

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

Then, you can change different options like the number of colors in the palette:

let pipeline = pipeline
    .palette_size(192.into())
    .colorspace(ColorSpace::Oklab)
    .quantize_method(QuantizeMethod::kmeans());

ImagePipeline has all options that PalettePipeline does, so you can check its documentation example for more information. In addition, ImagePipeline has options to control the dither behavior:

let pipeline = pipeline
    .palette_size(192.into())
    .colorspace(ColorSpace::Oklab)
    .quantize_method(QuantizeMethod::kmeans())
    .dither_error_diffusion(0.8);

Finally, run the pipeline:

let image = pipeline.quantized_rgbimage();

Or, in parallel across multiple threads (needs the threads feature):

let image = pipeline.quantized_rgbimage_par();

Implementations

impl<'a> ImagePipeline<'a>

pub fn new( colors: ColorSlice<'a, Srgb<u8>>, width: u32, height: u32 ) -> Option<Self>

Creates a new ImagePipeline with default options. Returns None if the length of colors is not equal to width * height.

pub fn palette_size(self, size: PaletteSize) -> Self

Sets the palette size which determines the (maximum) number of colors to have in the palette.

The default palette size is PaletteSize::MAX.

pub fn colorspace(self, colorspace: ColorSpace) -> Self

Sets the color space to perform color quantization in.

See ColorSpace for more details.

The default color space is ColorSpace::Srgb.

pub fn quantize_method(self, quantize_method: QuantizeMethod<Srgb<u8>>) -> Self

Sets the color quantization method to use.

See QuantizeMethod for more details.

The default quantization method is QuantizeMethod::Wu.

pub fn dedup_pixels(self, dedup_pixels: bool) -> Self

Sets whether or not to deduplicate pixels in the image.

It is recommended to keep this option as default, unless the image is very small or you have reason to believe that the image contains very little redundancy (i.e., most pixels are their own unique color). quantette will only deduplicate pixels if it is worth doing so (i.e., the k-means quantization method is chosen or a color space converision is needed).

The default value is true.

pub fn dither(self, dither: bool) -> Self

Sets whether or not to apply dithering to the image.

The current implementation uses Floyd–Steinberg dithering. The dithering strength/aggresiveness can be controlled via ImagePipeline::dither_error_diffusion.

The default value is true.

pub fn dither_error_diffusion(self, diffusion: f32) -> Self

Sets the error diffusion factor for the dither.

A value of 1.0 diffuses all error to the neighboring pixels and may result in color bleed. Values less than 1.0 only diffuse part of the error for a more tamed dither. The given diffusion should be in the range 0.0..=1.0, otherwise the default error diffusion will be used as a fallback.

The default value is FloydSteinberg::DEFAULT_ERROR_DIFFUSION.

impl<'a> ImagePipeline<'a>

pub fn palette(self) -> Vec<Srgb<u8>>

Runs the pipeline and returns the computed color palette.

pub fn indexed_palette(self) -> (Vec<Srgb<u8>>, Vec<u8>)

Runs the pipeline and returns the quantized image as an indexed palette.

impl<'a> ImagePipeline<'a>

pub fn quantized_rgbimage(self) -> RgbImage

Runs the pipeline and returns the quantized image.

impl<'a> ImagePipeline<'a>

pub fn palette_par(self) -> Vec<Srgb<u8>>

Runs the pipeline in parallel and returns the computed color palette.

pub fn indexed_palette_par(self) -> (Vec<Srgb<u8>>, Vec<u8>)

Runs the pipeline in parallel and returns the quantized image as an indexed palette.

impl<'a> ImagePipeline<'a>

pub fn quantized_rgbimage_par(self) -> RgbImage

Runs the pipeline in parallel and returns the quantized image.

Trait Implementations

impl<'a> Clone for ImagePipeline<'a>

fn clone(&self) -> ImagePipeline<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for ImagePipeline<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<ImagePipeline<'a>> for PalettePipeline<'a>

fn from(value: ImagePipeline<'a>) -> Self

Converts to this type from the input type.

impl<'a> TryFrom<&'a ImageBuffer<Rgb<u8>, Vec<u8>>> for ImagePipeline<'a>

type Error = AboveMaxLen<u32>

The type returned in the event of a conversion error.

fn try_from(image: &'a RgbImage) -> Result<Self, Self::Error>

Performs the conversion.