sweetcorn 0.2.2 → 0.3.0

package/dist/custom-processors.d.ts

@@ -1,6 +1,6 @@
-import { ArrayOrBuffer } from './types.js';
+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>) => void>;
+export declare const customProcessors: Record<'white-noise' | 'threshold', (pixels: ArrayOrBuffer<number>, info: ImageInfo) => void>;

package/dist/custom-processors.js

@@ -6,10 +6,14 @@ export const customProcessors = {
     /**
      * White noise dithering (pretty rough and ugly)
      */
-    'white-noise'(pixels) {
-        for (let index = 0; index < pixels.length; index++) {
-            const pixelValue = pixels[index];
-            pixels[index] = pixelValue / 255 < Math.random() ? 0 : 255;
+    '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;
+            }
         }
     },
     /**

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

@@ -23,28 +23,53 @@ async function loadSharp() {
  */
 export default async function sweetcorn(image, options) {
     // Clone the input image to avoid mutating it.
-    image = image.clone();
-    const { algorithm } = options;
-    if (!sharp)
-        sharp = await loadSharp();
-    // Convert image to greyscale before dithering.
+    // 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 { data: pixels, info } = await image.raw().toBuffer({ resolveWithObject: true });
-    const thresholdMap = options.thresholdMap || thresholdMaps[algorithm];
-    const diffusionKernel = options.diffusionKernel || diffusionKernels[algorithm];
-    const customProcessor = customProcessors[algorithm];
+    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(pixels, info.width, thresholdMap);
+        applyThresholdMap(pixels, info, thresholdMap);
     }
     else if (diffusionKernel) {
-        applyDiffusionKernel(pixels, info.width, info.height, diffusionKernel);
+        applyDiffusionKernel(pixels, info, diffusionKernel);
     }
     else if (customProcessor) {
-        customProcessor(pixels);
+        customProcessor(pixels, info);
     }
     // Convert raw pixel data back into a Sharp image.
+    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,5 +1,5 @@
-import { ArrayOrBuffer } from './types.js';
+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 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/types.d.ts

@@ -36,9 +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.2",
+  "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"
   }
 }