Struct Pipeline 

pub struct Pipeline { /* private fields */ }

A builder struct to specify image quantization options.

Note that the Oklab color space is used in all cases to provide reasonable results.

Examples

First, specify any options you want:

use quantette::{Pipeline, QuantizeMethod};

let pipeline = Pipeline::new()
    .palette_size(32u16.try_into()?)
    .ditherer(None)
    .quantize_method(QuantizeMethod::kmeans())
    .parallel(true);

Note that some of the options and functions above require certain cargo features to be enabled.

Then, specify the input image or color slice as well as the desired output:

use quantette::{ImageBuf, Pipeline, QuantizeMethod};

// let img = image::open("some image")?.into_rgb8();
let img = image::RgbImage::new(256, 256);
let img = ImageBuf::try_from(img)?;

let quantized = pipeline
    .clone()
    .input_image(img.as_ref())
    .output_srgb8_image();

assert_eq!(img.dimensions(), quantized.dimensions());

let palette = pipeline
    .input_image(img.as_ref())
    .output_srgb8_palette()
    .map(|palette| palette.into_vec())
    .unwrap_or_default();

assert_eq!(palette.len(), 1);

Implementations

impl Pipeline

pub fn new() -> Self

Create a new Pipeline with default options.

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

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

See the docs for PaletteSize for more information.

The default palette size is PaletteSize::MAX.

Examples

let pipeline = Pipeline::new()
    .palette_size(24u16.try_into()?)
    .palette_size(PaletteSize::from_u8_clamped(24))
    .palette_size(PaletteSize::MAX);

pub fn quantize_method(self, quantize_method: impl Into<QuantizeMethod>) -> Self

Sets the color quantization method to use.

See the docs for QuantizeMethod for more details.

The default quantization method is QuantizeMethod::Wu.

Examples

use quantette::{kmeans::KmeansOptions, PaletteBuf, Pipeline, QuantizeMethod};
use palette::Srgb;

let colors = vec![Srgb::new(0, 0, 0), Srgb::new(255, 255, 255)];
let custom_palette = PaletteBuf::try_from(colors.clone())?;
let pipeline = Pipeline::new()
    .quantize_method(QuantizeMethod::Wu)
    .quantize_method(QuantizeMethod::try_from(colors)?)
    .quantize_method(custom_palette)
    .quantize_method(QuantizeMethod::kmeans())
    .quantize_method(KmeansOptions::new().sampling_factor(0.5));

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

Sets whether or not to run the pipeline in parallel across multiple threads.

Use a rayon::ThreadPool to specify the number of threads if necessary.

The default value is false.

pub fn ditherer(self, ditherer: impl Into<Option<FloydSteinberg>>) -> Self

Sets whether or not to apply dithering to the image.

The current implementation only supports Floyd–Steinberg dithering. See the docs for FloydSteinberg for more details. To disable dithering, provide None as a value to this function.

The default value is Some(FloydSteinberg::new()).

Examples

use quantette::{dither::FloydSteinberg, Pipeline};

let ditherer = FloydSteinberg::with_error_diffusion(0.75).unwrap();
let pipeline = Pipeline::new()
    .ditherer(None)
    .ditherer(FloydSteinberg::new())
    .ditherer(ditherer);

pub fn dedup(self, dedup: impl Into<Option<bool>>) -> Self

Sets whether or not to deduplicate pixels in the image as an optimization.

If dithering is enabled (see ditherer), it is recommended to keep this option as default or set to false.

Otherwise, with dithering disabled:

• For large images it is recommended to deduplicate pixels for overall faster quantization.
• For smaller images, not performing deduplication can be faster.

The optimal cutoff between a “large” and “small” image depends on:

• the ratio between the number of unique pixels in the image and the total number of pixels in the image
• the chosen quantization method
• hardware

Some experimentation may be needed based on your workflow and hardware.

The default value is None (automatically choose whether or not to dedup).

Examples

Pipeline::new()
    .dedup(None) // automatically choose whether or not to dedup
    .dedup(true) // always dedup (not recommended if dithering is enabled)
    .dedup(false); // never dedup

pub fn input_slice( self, colors: &[Srgb<u8>], ) -> Result<PipelineWithSliceInput<'_>, LengthOutOfRange>

Specify a slice of Srgb<u8> colors as input.

Note that only palettes can be outputted when a slice is used as input. To get an image as an output, provide an image as input using input_image.

Errors

Returns an error if colors is empty or has a length greater than MAX_PIXELS.

pub fn input_image( self, image: ImageRef<'_, Srgb<u8>>, ) -> PipelineWithImageRefInput<'_>

Specify a sRGB image reference as input.

See the ImageRef docs for more information as well as how to create one.

Trait Implementations

impl Clone for Pipeline

fn clone(&self) -> Pipeline

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Pipeline

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

Formats the value using the given formatter.

impl Default for Pipeline

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for Pipeline

fn eq(&self, other: &Pipeline) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Pipeline