!@thi.ng/pixel-dither

!npm downloads

> [!NOTE]
> This is one of 214 standalone projects, maintained as part
> of the @thi.ng/umbrella monorepo
> and anti-framework.
>
> 🚀 Please help me to work full-time on these projects by sponsoring me on
> GitHub. Thank you! ❤️

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

About

!screenshot

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

``bash
yarn add @thi.ng/pixel-dither
`

ESM import:

`ts
import * as pd from "@thi.ng/pixel-dither";
`

Browser ESM import:

`html

`

JSDelivr documentation

For Node.js REPL:

`js
const pd = await import("@thi.ng/pixel-dither");
`

Package sizes (brotli'd, pre-treeshake): ESM: 1.06 KB

Dependencies

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

Usage examples

Three projects in this repo's
/examples
directory are using this package:

| Screenshot | Description | Live demo | Source |
|:---------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------|:----------------------------------------------------|:---------------------------------------------------------------------------------|
| | Showcase of various dithering algorithms | Demo | Source |
| | Image dithering and remapping using indexed palettes | Demo | Source |
| | Multi-layer vectorization & dithering of bitmap images | Demo | Source |

API

Generated API docs

`ts
import { imageFromURL, intBufferFromImage, GRAY8 } from "@thi.ng/pixel";
import { ditherWith, ATKINSON } from "@thi.ng/pixel-dither";

// create pixel buffer from HTML image element
const img = intBufferFromImage(await imageFromURL("test.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));

// ...or 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 });
`

$3

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:

`ts
import { ditherWith, type DitherKernel } from "@thi.ng/pixel-dither";

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:

`ts
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:

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

License

© 2021 - 2026 Karsten Schmidt // Apache License 2.0