Crate palettize 

Palettize

A library for applying ordered Bayer dithering to images with custom color palettes.

Ordered dithering is a technique that reduces the number of colors in an image while maintaining visual quality through the use of spatial patterns. This library provides tools to:

• Generate Bayer matrices of various sizes
• Parse color palettes from hex strings
• Apply dithering with customizable parameters

Quick Start

The simplest way to dither an image is with the dither() function:

use palettize::{dither, grayscale};

// Load an image
let img = image::open("input.png").unwrap();

// Generate a grayscale palette (black & white)
let palette = grayscale(2);

// Apply dithering with default settings
let output = dither(&img, &palette);

// Save the result
output.save("output.png").unwrap();

For more control over dithering parameters, use dither_with_options():

use palettize::{dither_with_options, grayscale};

let img = image::open("input.png").unwrap();
let palette = grayscale(6); // 6-level grayscale

// Bayer level 3 = 16×16 matrix, noise 0.5 = subtle dithering
let output = dither_with_options(&img, &palette, 3, 0.5);
output.save("output.png").unwrap();

Custom Palettes

You can create palettes from custom colors in several ways:

use palettize::{Color, Palette, parse_hex_color};

// From Color structs
let palette = Palette::new(vec![
    Color::new(0, 0, 0),
    Color::new(255, 255, 255),
]);

// From tuples using Into
let palette: Palette = vec![
    (0, 0, 0),
    (255, 255, 255),
].into();

// From hex color strings
let palette = Palette::new(vec![
    parse_hex_color("#1a1c2c").unwrap(),
    parse_hex_color("#5d275d").unwrap(),
    parse_hex_color("#b13e53").unwrap(),
]);

Grayscale Palettes

Use grayscale() to generate evenly-spaced grayscale palettes:

• grayscale(2) - Black and white
• grayscale(6) - 6-level grayscale
• grayscale(256) - Full 8-bit grayscale

Palette Remapping

By default, dithering picks the palette color nearest to each pixel. That is a colorimetric match. remap_to_palette() is the perceptual-intent alternative: it first matches the image’s lightness and chroma distribution to the palette’s distribution in Oklab, then you dither the result.

Use it when an image is washed out or its colors sit far from the palette. The remap spreads the image across the whole palette instead of collapsing it onto the few nearest entries.

use palettize::{dither, remap_to_palette, Palette};

let img = image::open("input.png").unwrap();
let palette: Palette = vec![
    (26, 28, 76),   // Dark blue
    (240, 208, 96), // Light yellow
].into();

// Match the distribution, then dither the full-color result
let remapped = remap_to_palette(&img, &palette, 1.0);
let output = dither(&image::DynamicImage::ImageRgb8(remapped), &palette);
output.save("output.png").unwrap();

Bayer Matrix Levels

The Bayer matrix level controls the size of the dithering pattern:

Level	Matrix Size	Threshold Count
0	2×2	4
1	4×4	16
2	8×8	64 (default)
3	16×16	256
4	32×32	1024
5	64×64	4096

Higher levels produce smoother gradients but larger repeating patterns. Level 2 (8×8) is a good default for most images.

Re-exports

pub use bayer::generate_bayer_matrix;

pub use dither::apply_dithering;

pub use dither::color_distance_sq;

pub use dither::find_two_nearest;

pub use extract::extract_palette_kmeans;

pub use extract::extract_palette_median_cut;

pub use palette::Color;

pub use palette::Palette;

pub use palette::ParseColorError;

pub use palette::grayscale;

pub use palette::parse_hex_color;

pub use remap::remap_to_palette;

Modules

bayer

Bayer matrix generation for ordered dithering.

dither

Core dithering algorithm implementation.

extract

Palette extraction algorithms.

palette

Palette parsing and color palettes.

remap

Palette distribution remapping.

Constants

DEFAULT_BAYER_LEVEL

Default Bayer matrix level used by dither().

DEFAULT_NOISE

Default noise intensity used by dither().

Functions

dither

Dithers an image using the given palette with default settings.

dither_with_options

Dithers an image using the given palette with custom settings.