This project is part of the @thi.ng/umbrella monorepo.

• About
  • Status
• Installation
• Dependencies
• Usage examples
• API
  • Custom dither kernels
• Authors
• License

About

Extensible image dithering w/ various algorithm presets. This is a support package for @thi.ng/pixel.

The package provides the following dithering algorithm presets (can also be very easily extended via definition of custom kernels):

• Atkinson
• Bayes (ordered dithering w/ customizable sizes & levels)
• Burkes
• Diffusion (1D row/column, 2D)
• Floyd-Steinberg
• Jarvis-Judice-Ninke
• Sierra 2-row
• Stucki
• Threshold

Status

STABLE - used in production

Search or submit any issues for this package

Installation

yarn add @thi.ng/pixel-dither

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/pixel-dither"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const pixelDither = await import("@thi.ng/pixel-dither");

Package sizes (gzipped, pre-treeshake): ESM: 1.07 KB

Dependencies

• @thi.ng/checks
• @thi.ng/math
• @thi.ng/pixel

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

Screenshot	Description	Live demo	Source
	Showcase of various dithering algorithms	Demo	Source
	Image dithering and remapping using indexed palettes	Demo	Source

API

Generated API docs

import { packedBufferFromImage, GRAY8 } from "@thi.ng/pixel";
import { ditherWith, ATKINSON } from "@thi.ng/pixel-dither";

const img = packedBufferFromImage("foo.jpg");

// apply dithering to all channels in given pixel buffer
ditherWith(ATKINSON, img);

// first convert to 8-bit gray before dithering
ditherWith(ATKINSON, img.as(GRAY8));

// apply dithering to select channels only
// use custom threshold & error spillage/bleed factor
ditherWith(ATKINSON, img, { channels: [1, 2, 3], threshold: 0.66, bleed: 0.75 });

Custom dither kernels

All bundled algorithm presets (apart from orderedDither()) are implemented as DitherKernel configurations for, defining how each dithered pixel's error should be diffused/distributed to neighbors. This approach makes it very easy to define custom dither configs, like so:

const CUSTOM: DitherKernel = {
    // X offsets of neighbor pixels to update
    ox: [1],
    // Y offsets of neighbor pixels to update
    oy: [1],
    // error weights for updated pixels
    weights: [1],
    // bit shift (scale factor)
    shift: 1,
};

ditherWith(CUSTOM, img);

The above config will distribute the error to a single pixel @ offset (1,1). However the error will be bit-shifted by 1 bit to the right (aka division-by-2). In code form:

pixels[i + ox + oy * width] += (err * weight) >> shift;

Important: Ensure the offset positions only refer to still unprocessed pixels, i.e. those to the right and/or below the currently processed pixel (in following rows).

You can see the result of this kernel in the pixel-dither demo.

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-pixel-dither,
  title = "@thi.ng/pixel-dither",
  author = "Karsten Schmidt",
  note = "https://thi.ng/pixel-dither",
  year = 2021
}

License

© 2021 Karsten Schmidt // Apache Software License 2.0