sweetcorn 0.2.1 → 0.3.0

package/dist/custom-processors.d.ts

@@ -0,0 +1,6 @@
+import type { ArrayOrBuffer, ImageInfo } from './types.js';
+/**
+ * A collection of pixel mutation processors that deviate from the standardized threshold map and
+ * error diffusion algorithms.
+ */
+export declare const customProcessors: Record<'white-noise' | 'threshold', (pixels: ArrayOrBuffer<number>, info: ImageInfo) => void>;

package/dist/custom-processors.js

@@ -0,0 +1,29 @@
+/**
+ * A collection of pixel mutation processors that deviate from the standardized threshold map and
+ * error diffusion algorithms.
+ */
+export const customProcessors = {
+    /**
+     * White noise dithering (pretty rough and ugly)
+     */
+    'white-noise'(pixels, { channels }) {
+        for (let index = 0; index < pixels.length; index += channels) {
+            const threshold = Math.random();
+            for (let channel = 0; channel < channels; channel++) {
+                if (channel > 2)
+                    continue; // Skip alpha channel
+                pixels[index + channel] = pixels[index + channel] / 255 < threshold ? 0 : 255;
+            }
+        }
+    },
+    /**
+     * Basic quantization. This could be represented as a threshold map of `[[128]]` but defining it
+     * like this allows it to be implemented more efficiently.
+     */
+    threshold(pixels) {
+        for (let index = 0; index < pixels.length; index++) {
+            const pixelValue = pixels[index];
+            pixels[index] = pixelValue < 128 ? 0 : 255;
+        }
+    },
+};

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { Sharp } from 'sharp';
 import type { SweetcornOptions } from './types.js';
 export type { DitheringAlgorithm } from './types.js';
+export type { SweetcornOptions };
 /**
  * Create a dithered image — turn smooth pixels into crunchy kernels! 🌽
  * @param image A Sharp image instance, e.g. created using `sharp('my-file.png')`.

package/dist/index.js

@@ -1,5 +1,6 @@
-import { applyDiffusionKernel, applyThresholdMap } from './processors.js';
+import { customProcessors } from './custom-processors.js';
 import diffusionKernels from './diffusion-kernels.js';
+import { applyDiffusionKernel, applyThresholdMap } from './processors.js';
 import thresholdMaps from './threshold-maps.json' with { type: 'json' };
 let sharp;
 async function loadSharp() {
@@ -21,37 +22,54 @@ async function loadSharp() {
  * @returns A new Sharp image instance.
  */
 export default async function sweetcorn(image, options) {
-    const { algorithm } = options;
-    if (!sharp)
-        sharp = await loadSharp();
-    // Convert image to greyscale before dithering.
+    // Clone the input image to avoid mutating it.
+    // Also, force it to a PNG to ensure we have a valid input. Some inputs such as "raw", can have
+    // issues with channel manipulations like our alpha channel handling below.
+    image = image.clone().toFormat('png');
+    /** Alpha channel extracted before any other manipulations have been applied. */
+    let alphaChannel;
+    if (!options.preserveColour) {
+        if (options.preserveAlpha) {
+            alphaChannel = await image.clone().extractChannel('alpha').toBuffer();
+        }
+        // Alpha channel shouldn’t be dithered, so we remove it (and add it back later if needed.)
+        image.removeAlpha();
+    }
     // We use gamma to linearize the colorspace, and improve the perceptual quality.
-    image.gamma(2.2, 1).greyscale();
+    image.gamma(2.2, 1);
+    // Convert image to greyscale before dithering.
+    if (!options.preserveColour) {
+        image.greyscale();
+    }
     // Get raw pixel data for this image.
-    const rawPixels = await image.raw().toBuffer({ resolveWithObject: true });
-    const thresholdMap = options.thresholdMap || thresholdMaps[algorithm];
-    const diffusionKernel = options.diffusionKernel || diffusionKernels[algorithm];
+    const { data: pixels, info } = await image.raw().toBuffer({ resolveWithObject: true });
+    const thresholdMap = options.thresholdMap || thresholdMaps[options.algorithm];
+    const diffusionKernel = options.diffusionKernel || diffusionKernels[options.algorithm];
+    const customProcessor = customProcessors[options.algorithm];
+    // Dither raw pixel data in place.
     if (thresholdMap) {
-        applyThresholdMap(rawPixels.data, rawPixels.info.width, thresholdMap);
+        applyThresholdMap(pixels, info, thresholdMap);
     }
     else if (diffusionKernel) {
-        applyDiffusionKernel(rawPixels.data, rawPixels.info.width, rawPixels.info.height, diffusionKernel);
+        applyDiffusionKernel(pixels, info, diffusionKernel);
     }
-    else if (algorithm === 'white-noise') {
-        // White noise dithering (pretty rough and ugly)
-        for (let index = 0; index < rawPixels.data.length; index++) {
-            const pixelValue = rawPixels.data[index];
-            rawPixels.data[index] = pixelValue / 255 < Math.random() ? 0 : 255;
-        }
-    }
-    else if (algorithm === 'threshold') {
-        // Basic quantization
-        for (let index = 0; index < rawPixels.data.length; index++) {
-            const pixelValue = rawPixels.data[index];
-            rawPixels.data[index] = pixelValue < 128 ? 0 : 255;
-        }
+    else if (customProcessor) {
+        customProcessor(pixels, info);
     }
     // Convert raw pixel data back into a Sharp image.
-    const outputImage = sharp(rawPixels.data, { raw: rawPixels.info });
+    if (!sharp)
+        sharp = await loadSharp();
+    const outputImage = sharp(pixels, { raw: info });
+    // Enforce black-and-white output when colour hasn’t been requested and there’s no alpha channel.
+    if (!options.preserveColour && !alphaChannel) {
+        outputImage.toColourspace('b-w');
+    }
+    // Ensure alpha channel is included/excluded as required.
+    if (alphaChannel) {
+        outputImage.joinChannel(alphaChannel);
+    }
+    else if (info.channels > 3 && !options.preserveAlpha) {
+        outputImage.removeAlpha();
+    }
     return outputImage;
 }

package/dist/processors.d.ts

@@ -1,10 +1,5 @@
-/** Any array-like structure indexed by numbers and with a `length`, e.g. an `Array` or `Buffer`. */
-interface ArrayOrBuffer<T> {
-    length: number;
-    [n: number]: T;
-}
+import { ArrayOrBuffer, ImageInfo } from './types.js';
 /** Applies a threshold map to raw pixel data for ordered dithering. */
-export declare function applyThresholdMap(pixels: ArrayOrBuffer<number>, width: number, map: number[][]): void;
+export declare function applyThresholdMap(pixels: ArrayOrBuffer<number>, { width, channels }: ImageInfo, map: number[][]): void;
 /** Applies an error diffusion kernel to raw pixel data. */
-export declare function applyDiffusionKernel(pixels: ArrayOrBuffer<number>, width: number, height: number, kernel: number[][]): void;
-export {};
+export declare function applyDiffusionKernel(pixels: ArrayOrBuffer<number>, { width, height, channels }: ImageInfo, kernel: number[][]): void;

package/dist/processors.js

@@ -1,26 +1,36 @@
 /** Applies a threshold map to raw pixel data for ordered dithering. */
-export function applyThresholdMap(pixels, width, map) {
+export function applyThresholdMap(pixels, { width, channels }, map) {
     const mapWidth = map[0].length;
     const mapHeight = map.length;
     for (let index = 0; index < pixels.length; index++) {
+        const channel = index % channels;
+        if (channel == 3)
+            continue; // Skip alpha channel
         const pixelValue = pixels[index];
-        const [x, y] = [index % width, Math.floor(index / width)];
+        const channelIndex = Math.floor(index / channels);
+        const [x, y] = [channelIndex % width, Math.floor(channelIndex / width)];
         const threshold = map[y % mapHeight][x % mapWidth];
         pixels[index] = pixelValue < threshold ? 0 : 255;
     }
 }
 /** Applies an error diffusion kernel to raw pixel data. */
-export function applyDiffusionKernel(pixels, width, height, kernel) {
+export function applyDiffusionKernel(pixels, { width, height, channels }, kernel) {
     const kernelWidth = kernel[0].length;
     const kernelHeight = kernel.length;
     const kernelRadius = Math.floor((kernelWidth - 1) / 2);
     for (let index = 0; index < pixels.length; index++) {
+        const channel = index % channels;
+        if (channel == 3)
+            continue; // Skip alpha channel
         const original = pixels[index];
         const quantized = original < 128 ? 0 : 255;
         pixels[index] = quantized;
         const error = original - quantized;
         // (x, y) co-ordinates of the current pixel in the image.
-        const [x, y] = [index % width, Math.floor(index / width)];
+        const [x, y] = [
+            Math.floor(index / channels) % width,
+            Math.floor(Math.floor(index / channels) / width),
+        ];
         // Distribute the error to neighbouring pixels based on the kernel.
         for (let diffX = 0; diffX < kernelWidth; diffX++) {
             for (let diffY = 0; diffY < kernelHeight; diffY++) {
@@ -31,7 +41,7 @@ export function applyDiffusionKernel(pixels, width, height, kernel) {
                 const neighbourY = y + diffY;
                 // Ensure we don't go out of bounds
                 if (neighbourX >= 0 && neighbourY >= 0 && neighbourX < width && neighbourY < height) {
-                    const neighbourIndex = neighbourY * width + neighbourX;
+                    const neighbourIndex = neighbourY * width * channels + neighbourX * channels + channel;
                     pixels[neighbourIndex] = eightBitClamp(pixels[neighbourIndex] + error * diffusionWeight);
                 }
             }

package/dist/threshold-maps.json

@@ -125,11 +125,6 @@
         [224, 140, 56, 14, 98, 182],
         [238, 154, 70, 28, 112, 196]
     ],
-    "dot-vertical-5x3": [
-        [153, 51, 0, 102, 204],
-        [170, 68, 17, 119, 221],
-        [187, 85, 34, 136, 238]
-    ],
     "dot-horizontal-3x5": [
         [153, 170, 187],
         [51, 68, 85],
@@ -137,6 +132,33 @@
         [102, 119, 136],
         [204, 221, 238]
     ],
+    "dot-vertical-5x3": [
+        [153, 51, 0, 102, 204],
+        [170, 68, 17, 119, 221],
+        [187, 85, 34, 136, 238]
+    ],
+    "horizontal-checkers-6": [
+        [245, 231, 217, 210, 224, 238, 35, 21, 7, 0, 14, 28],
+        [161, 147, 133, 126, 140, 154, 119, 105, 91, 84, 98, 112],
+        [77, 63, 49, 42, 56, 70, 203, 189, 175, 168, 182, 196],
+        [35, 21, 7, 0, 14, 28, 245, 231, 217, 210, 224, 238],
+        [119, 105, 91, 84, 98, 112, 161, 147, 133, 126, 140, 154],
+        [203, 189, 175, 168, 182, 196, 77, 63, 49, 42, 56, 70]
+    ],
+    "vertical-checkers-6": [
+        [245, 161, 77, 35, 119, 203],
+        [231, 147, 63, 21, 105, 189],
+        [217, 133, 49, 7, 91, 175],
+        [210, 126, 42, 0, 84, 168],
+        [224, 140, 56, 14, 98, 182],
+        [238, 154, 70, 28, 112, 196],
+        [35, 119, 203, 245, 161, 77],
+        [21, 105, 189, 231, 147, 63],
+        [7, 91, 175, 217, 133, 49],
+        [0, 84, 168, 210, 126, 42],
+        [14, 98, 182, 224, 140, 56],
+        [28, 112, 196, 238, 154, 70]
+    ],
     "blue-noise": [
         [
             134, 22, 92, 59, 163, 190, 12, 155, 181, 119, 233, 47, 175, 12, 113, 141, 47, 183, 111, 196,

package/dist/types.d.ts

@@ -36,4 +36,23 @@ export interface SweetcornOptions {
      * ]
      */
     diffusionKernel?: number[][] | undefined;
+    /**
+     * Dither as a three-channel RGB image instead of converting to a single-channel black-and-white image.
+     */
+    preserveColour?: boolean | undefined;
+    /**
+     * Preserve the alpha channel of the image, if it has one, instead of removing it.
+     */
+    preserveAlpha?: boolean | undefined;
+}
+/** Any array-like structure indexed by numbers and with a `length`, e.g. an `Array` or `Buffer`. */
+export interface ArrayOrBuffer<T> {
+    length: number;
+    [n: number]: T;
+}
+/** Information about an image’s dimensions and channels. Subset of Sharp’s `OutputInfo`. */
+export interface ImageInfo {
+    width: number;
+    height: number;
+    channels: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweetcorn",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "description": "JavaScript image dithering tools for Sharp",
   "keywords": [
@@ -39,6 +39,7 @@
   "scripts": {
     "build": "tsc",
     "pretest": "pnpm build",
-    "test": "node --test"
+    "test": "node --test",
+    "test:update": "node --test --test-update-snapshots"
   }
 }