Narcissistic, Perfectly Modest

    @thi.ng/pixel-dither
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.23 • Public • Published

    pixel-dither

    npm version npm downloads Twitter Follow

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

    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

    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.13 KB

    Dependencies

    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 { intBufferFromImage, GRAY8 } from "@thi.ng/pixel";
    import { ditherWith, ATKINSON } from "@thi.ng/pixel-dither";
    
    const img = intBufferFromImage("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));
    
    // ...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 });

    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 - 2022 Karsten Schmidt // Apache Software License 2.0

    Keywords

    Install

    npm i @thi.ng/pixel-dither

    DownloadsWeekly Downloads

    234

    Version

    1.1.23

    License

    Apache-2.0

    Unpacked Size

    35.5 kB

    Total Files

    28

    Last publish

    Collaborators

    • thi.ng