ditherlib 0.4.2

Non-destructive image effects and dithering for whole images and polygon selections
Documentation

Ditherlib

Ditherlib is a Rust library for non-destructive image effects and dithering. Effects can target an entire image or anti-aliased polygon selections, and an ordered pipeline can combine several selected effects into one render.

Source pixels remain immutable after loading. Each render starts from the source and produces a separately owned image, so callers can freely edit and re-render pipelines.

samurai

Features

  • Greyscale and Gaussian blur
  • Threshold and ordered Bayer dithering
  • Floyd-Steinberg, Atkinson, Jarvis-Judice-Ninke, Stucki, Burkes, Sierra, Two-Row Sierra, and Sierra Lite error diffusion
  • Custom diffusion kernels, strength, clamping, and scan direction
  • Custom RGB palettes, black-and-white palettes, and monochrome palettes
  • Configurable logical pixel sizes for every dithering method
  • Whole-image and polygon selections with anti-aliased edges
  • Ordered multi-effect pipelines with reusable rendering buffers
  • Crate-owned image, result, and error types

Installation

JPEG and PNG support are enabled by default:

[dependencies]
ditherlib = "0.4"

Codec features can be selected individually:

[dependencies]
ditherlib = { version = "0.4", default-features = false, features = ["png", "webp"] }

Available codec features are avif, bmp, dds, exr, ff, gif, hdr, ico, jpeg, png, pnm, qoi, tga, tiff, and webp. The processing algorithms compile without any codec features.

Usage

This example converts the full image to greyscale, then applies a red monochrome ordered dither inside a polygon:

use ditherlib::{
    Greyscale, OrderedDither, Palette, Pipeline, Point, Polygon, Renderer,
    Selection, read, write,
};

fn main() -> ditherlib::Result<()> {
    let source = read("input.jpg")?;
    let (width, height) = source.dimensions();
    let area = Polygon::new([
        Point::new(width as f32 * 0.20, height as f32 * 0.20),
        Point::new(width as f32 * 0.80, height as f32 * 0.20),
        Point::new(width as f32 * 0.80, height as f32 * 0.80),
        Point::new(width as f32 * 0.20, height as f32 * 0.80),
    ])?;

    let mut pipeline = Pipeline::new();
    pipeline.add(Greyscale, Selection::All);
    pipeline.add(
        OrderedDither::new(Palette::monochrome([220, 20, 60]), 4)?
            .with_pixel_size(4)?,
        Selection::Polygon(area),
    );

    let rendered = Renderer::new().render_pipeline(&source, &pipeline)?;
    write("output.png", &rendered)
}

Pipeline order matters. Each step receives the result of the previous step, including where polygon selections overlap. Rendering the same pipeline again always begins from the unchanged SourceImage.

Palettes

Palette::black_and_white() provides the familiar two-colour palette. Palette::monochrome(colour) combines black, the supplied RGB colour, and white. Eight-level greyscale, Game Boy, CGA, and PICO-8 palettes are also available through Palette::greyscale(), Palette::game_boy(), Palette::cga(), and Palette::pico_8().

Colour represents an RGB value with named channels, common colour constants, and conversions to and from [u8; 3]. Color is an alias for callers using American spelling. Palette::new accepts either representation:

use ditherlib::{Colour, Palette};

fn main() -> ditherlib::Result<()> {
    let palette = Palette::new([
        Colour::BLACK,
        Colour::new(220, 20, 60),
        Colour::WHITE,
    ])?;
    assert_eq!(palette.colours().len(), 3);
    Ok(())
}

Error diffusion

ErrorDiffusion accepts a built-in algorithm or a validated custom kernel. It supports raster or serpentine scanning, diffusion strength from 0.0 through 2.0, and optional per-channel error clamping.

use ditherlib::{
    DiffusionAlgorithm, DiffusionScan, ErrorDiffusion, Palette, Renderer,
    Selection, read, write,
};

fn main() -> ditherlib::Result<()> {
    let source = read("input.png")?;
    let effect = ErrorDiffusion::new(Palette::black_and_white(), DiffusionAlgorithm::Stucki)
        .with_scan(DiffusionScan::Serpentine)
        .with_pixel_size(2)?;
    let rendered = Renderer::new().render(&source, &effect, &Selection::All)?;
    write("output.png", &rendered)
}

Custom kernels contain forward-pointing weighted taps and a divisor:

use ditherlib::{DiffusionKernel, DiffusionTap, ErrorDiffusion, Palette};

fn main() -> ditherlib::Result<()> {
    let kernel = DiffusionKernel::new(
        [
            DiffusionTap::new(1, 0, 7),
            DiffusionTap::new(-1, 1, 3),
            DiffusionTap::new(0, 1, 5),
            DiffusionTap::new(1, 1, 1),
        ],
        16,
    )?;
    let effect = ErrorDiffusion::new(Palette::black_and_white(), kernel)
        .with_strength(0.75)?
        .with_error_clamp(48);
    assert_eq!(effect.strength(), 0.75);
    Ok(())
}

Errors

Fallible operations return ditherlib::Result<T>. Use DitherError::kind() to handle stable ErrorKind categories covering file access, unsupported formats, decoding, encoding, invalid geometry, dimension mismatches, invalid parameters, and effect failures. Dependency errors may remain available through the standard Error::source() method for diagnostics.

JPEG output discards alpha because the format does not support transparency.

Examples

Every example accepts an input path and output path:

cargo run --release --example pipeline -- input.jpg output.png
cargo run --release --example polygon_pipeline -- input.jpg output.png
cargo run --release --example diffusion_comparison -- input.jpg first.png second.png
cargo run --release --example diffusion_controls -- input.jpg strengths.png clamps.png
cargo run --release --example palette_comparison -- input.jpg palettes.png

The diffusion comparison requires an image with even dimensions. first.png uses Floyd-Steinberg, Atkinson, Jarvis-Judice-Ninke, and Stucki from top-left to bottom-right. second.png uses Burkes, Sierra, Two-Row Sierra, and Sierra Lite in the same order.

The diffusion controls example creates two quadrant comparisons. strengths.png uses strengths 0.0, 0.5, 1.0, and 1.5 from top-left to bottom-right. clamps.png uses error limits of 0, 24, 64, and unlimited in the same order.

The palette comparison uses greyscale, Game Boy, CGA, and PICO-8 from top-left to bottom-right. It applies Floyd-Steinberg diffusion with serpentine scanning to every quadrant so the palette is the only variable.

Additional examples cover each built-in effect in the examples directory.