Dither

Dither is a high-performance Elixir library for image processing and dithering, powered by a Rust NIF using Rustler. It wraps the excellent dither crate to provide fast, high-quality dithering algorithms.

Features

• Format Support: Load/save and encode/decode common image formats (PNG, JPEG, etc.).
• Transformations: Resize, flip, and grayscale conversion.
• Dithering: Support for 6 high-quality dithering algorithms.
• Native Efficiency: Heavy lifting is performed in Rust, while providing a clean, idiomatic Elixir interface.

Installation

Add dither to your list of dependencies in mix.exs:

def deps do
  [
    {:dither, "~> 0.2.0"}
  ]
end

Building from Source

By default, Dither uses RustlerPrecompiled to provide binaries for common platforms. If you need to build the NIF from source (e.g., for an unsupported architecture or for development), you must have Rust installed and set the DITHER_BUILD environment variable:

DITHER_BUILD=true mix compile

Usage

All public functions in the Dither module return or accept a %Dither{} struct, which tracks the internal NIF reference along with image metadata.

Basic Example

# Load an image
image = Dither.load!("input.png")

# Inspect metadata
IO.inspect(image.size)      # {width, height}
IO.inspect(image.channels)  # 1 (grayscale) or 3 (RGB)

# Dither and save
image
|> Dither.grayscale!()
|> Dither.dither!(algorithm: :atkinson)
|> Dither.save!("output.png")

Dithering Options

The dither/2 function supports the following options:

• :algorithm: The dithering algorithm to use (default: :sierra).
• :bit_depth: The target color depth (default: 1 for black and white).

Supported Algorithms

• :floyd_steinberg
• :atkinson
• :stucki
• :burkes
• :jarvis
• :sierra (default)

Bit Depth

The :bit_depth option controls the quantization level. For example:

• bit_depth: 1 (default): 2 colors (Black & White).
• bit_depth: 2: 4 colors ($2^2$).
• bit_depth: 4: 16 colors ($2^4$).

The Dither Struct

%Dither{
  ref: reference(),      # The NIF resource reference
  size: {u32, u32},      # {width, height} tuple
  channels: 1 | 3        # Number of color channels
}

License

This project is licensed under the MIT License - see the LICENSE file for details.