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.
Features
- Greyscale and Gaussian blur
- Threshold, ordered Bayer, Floyd-Steinberg, and Atkinson dithering
- 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:
[]
= "0.1"
Codec features can be selected individually:
[]
= { = "0.1", = false, = ["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 ;
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. Palette::new accepts any non-empty collection of RGB colours.
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:
Additional examples cover each built-in effect in the examples
directory.