Usage in Node.js

Prerequisites

You will need to have Node.js >=20.10.0 installed.

Installation

npm

npm i sweetcorn

pnpm

pnpm add sweetcorn

yarn

yarn add sweetcorn

If you don‘t have it installed already, you will also need to install sharp.

Usage

Sweetcorn operates on a Sharp image instance. See the Sharp documentation for details on how to create and manipulate images with Sharp.

In the following example, we load an image from the local filesystem using sharp(), then pass the image to sweetcorn() along with your desired options:

import sharp from 'sharp';
import sweetcorn from 'sweetcorn';

// Load input.png from the local filesystem
const input = await sharp('input.png');
// Dither the image using the Stucki algorithm
const dithered = await sweetcorn(input, { algorithm: 'stucki' });

You can then further process the dithered image sweetcorn() returns using any of Sharp’s methods.

For example, you could save it as a lossless WebP file (an efficient format for dithered images):

dithered.webp({ lossless: true }).toFile('output.webp');

Or return the image as a PNG buffer in response to a server request:

const buffer = await dithered.png().toBuffer();
return new Response(buffer);

See Sharp’s “Output options” docs for more details about supported formats and options.

API

sweetcorn(image, options)

Import: import sweetcorn from 'sweetcorn'
Type: (image: Sharp, options: SweetcornOptions) => Promise<Sharp>

Takes a Sharp image instance and returns a new image dithered using the provided options object.

The options object must include one of the following properties:

• algorithm
  The name of a built-in dithering algorithm to use. See the “Algorithms” page for the full list of supported algorithms.

• thresholdMap
  Type: number[][]
  A custom threshold map to use for dithering. See “Threshold map dithering” for more details.

• diffusionKernel
  Type: number[][]
  A custom diffusion kernel to use for dithering. See “Error diffusion dithering” for details.

The following properties are optional:

• preserveColour
  Type: boolean
  If set to true, Sweetcorn will dither the image in full colour instead of converting it to greyscale first. Colour images will have larger file sizes than black-and-white images.

• preserveAlpha
  Type: boolean
  If set to true, Sweetcorn will preserve the alpha channel of the input image. Transparent areas of the image will remain transparent in the dithered output.