sweetcorn 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import type { Sharp } from 'sharp';
-import type { DitheringAlgorithm } from './types';
-export type { DitheringAlgorithm };
-interface SweetcornOptions {
-    algorithm: DitheringAlgorithm;
-}
-export default function sweetcorn(image: Sharp, { algorithm }: SweetcornOptions): Promise<Sharp>;
+import type { SweetcornOptions } from './types.js';
+export type { DitheringAlgorithm } from './types.js';
+/**
+ * Create a dithered image — turn smooth pixels into crunchy kernels! 🌽
+ * @param image A Sharp image instance, e.g. created using `sharp('my-file.png')`.
+ * @param options Options configuring Sweetcorn.
+ * @returns A new Sharp image instance.
+ */
+export default function sweetcorn(image: Sharp, options: SweetcornOptions): Promise<Sharp>;

package/dist/index.js

@@ -1,5 +1,6 @@
+import { applyDiffusionKernel, applyThresholdMap } from './processors.js';
+import diffusionKernels from './diffusion-kernels.js';
 import thresholdMaps from './threshold-maps.json' with { type: 'json' };
-import diffusionKernels from './diffusion-kernels';
 let sharp;
 async function loadSharp() {
     let sharpImport;
@@ -13,7 +14,14 @@ async function loadSharp() {
     sharpImport.cache(false);
     return sharpImport;
 }
-export default async function sweetcorn(image, { algorithm }) {
+/**
+ * Create a dithered image — turn smooth pixels into crunchy kernels! 🌽
+ * @param image A Sharp image instance, e.g. created using `sharp('my-file.png')`.
+ * @param options Options configuring Sweetcorn.
+ * @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.
@@ -21,13 +29,13 @@ export default async function sweetcorn(image, { algorithm }) {
     image.gamma(2.2, 1).greyscale();
     // Get raw pixel data for this image.
     const rawPixels = await image.raw().toBuffer({ resolveWithObject: true });
-    const thresholdMap = thresholdMaps[algorithm];
-    const diffusionKernel = diffusionKernels[algorithm];
+    const thresholdMap = options.thresholdMap || thresholdMaps[algorithm];
+    const diffusionKernel = options.diffusionKernel || diffusionKernels[algorithm];
     if (thresholdMap) {
-        applyThresholdMap(rawPixels, thresholdMap);
+        applyThresholdMap(rawPixels.data, rawPixels.info.width, thresholdMap);
     }
     else if (diffusionKernel) {
-        applyDiffusionKernel(rawPixels, diffusionKernel);
+        applyDiffusionKernel(rawPixels.data, rawPixels.info.width, rawPixels.info.height, diffusionKernel);
     }
     else if (algorithm === 'white-noise') {
         // White noise dithering (pretty rough and ugly)
@@ -43,54 +51,7 @@ export default async function sweetcorn(image, { algorithm }) {
             rawPixels.data[index] = pixelValue < 128 ? 0 : 255;
         }
     }
-    // Astro supports outputting different formats, but dithered images like this respond quite
-    // predictably to different compression methods. PNG and lossless WebP outperform lossy
-    // formats for this type of image, with lossless WebP producing slightly smaller images, so we
-    // use that here.
+    // Convert raw pixel data back into a Sharp image.
     const outputImage = sharp(rawPixels.data, { raw: rawPixels.info });
     return outputImage;
 }
-function applyDiffusionKernel(rawPixels, kernel) {
-    const kernelWidth = kernel[0].length;
-    const kernelHeight = kernel.length;
-    const kernelRadius = Math.floor((kernelWidth - 1) / 2);
-    for (let index = 0; index < rawPixels.data.length; index++) {
-        const original = rawPixels.data[index];
-        const quantized = original < 128 ? 0 : 255;
-        rawPixels.data[index] = quantized;
-        const error = original - quantized;
-        const [x, y] = [index % rawPixels.info.width, Math.floor(index / rawPixels.info.width)];
-        const width = rawPixels.info.width;
-        const height = rawPixels.info.height;
-        for (let diffX = 0; diffX < kernelWidth; diffX++) {
-            for (let diffY = 0; diffY < kernelHeight; diffY++) {
-                const diffusionWeight = kernel[diffY][diffX];
-                if (diffusionWeight === 0)
-                    continue;
-                const offsetX = diffX - kernelRadius;
-                const offsetY = diffY;
-                const neighborX = x + offsetX;
-                const neighborY = y + offsetY;
-                // Ensure we don't go out of bounds
-                if (neighborX >= 0 && neighborY >= 0 && neighborX < width && neighborY < height) {
-                    const neighborIndex = neighborY * width + neighborX;
-                    rawPixels.data[neighborIndex] = clamp(rawPixels.data[neighborIndex] + error * diffusionWeight);
-                }
-            }
-        }
-    }
-}
-function clamp(value, min = 0, max = 255) {
-    return Math.min(Math.max(value, min), max);
-}
-/** Applies a threshold map to the raw pixel data for ordered dithering. */
-function applyThresholdMap(rawPixels, thresholdMap) {
-    const mapWidth = thresholdMap[0].length;
-    const mapHeight = thresholdMap.length;
-    for (let index = 0; index < rawPixels.data.length; index++) {
-        const pixelValue = rawPixels.data[index];
-        const [x, y] = [index % rawPixels.info.width, Math.floor(index / rawPixels.info.width)];
-        const threshold = thresholdMap[y % mapHeight][x % mapWidth];
-        rawPixels.data[index] = pixelValue < threshold ? 0 : 255;
-    }
-}

package/dist/processors.d.ts

@@ -0,0 +1,10 @@
+/** 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;
+}
+/** Applies a threshold map to raw pixel data for ordered dithering. */
+export declare function applyThresholdMap(pixels: ArrayOrBuffer<number>, width: number, 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 {};

package/dist/processors.js

@@ -0,0 +1,44 @@
+/** Applies a threshold map to raw pixel data for ordered dithering. */
+export function applyThresholdMap(pixels, width, map) {
+    const mapWidth = map[0].length;
+    const mapHeight = map.length;
+    for (let index = 0; index < pixels.length; index++) {
+        const pixelValue = pixels[index];
+        const [x, y] = [index % width, Math.floor(index / 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) {
+    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 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)];
+        // Distribute the error to neighbouring pixels based on the kernel.
+        for (let diffX = 0; diffX < kernelWidth; diffX++) {
+            for (let diffY = 0; diffY < kernelHeight; diffY++) {
+                const diffusionWeight = kernel[diffY][diffX];
+                if (diffusionWeight === 0)
+                    continue;
+                const neighbourX = x + diffX - kernelRadius;
+                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;
+                    pixels[neighbourIndex] = eightBitClamp(pixels[neighbourIndex] + error * diffusionWeight);
+                }
+            }
+        }
+    }
+}
+/** Clamps a number between `0` and `255`. */
+function eightBitClamp(value) {
+    return Math.min(Math.max(value, 0), 255);
+}

package/dist/threshold-maps.json

@@ -37,6 +37,106 @@
         [63, 191, 31, 159, 55, 183, 23, 151, 61, 189, 29, 157, 53, 181, 21, 149],
         [255, 127, 223, 95, 247, 119, 215, 87, 253, 125, 221, 93, 245, 117, 213, 85]
     ],
+    "dot-4": [
+        [192, 80, 96, 208],
+        [64, 0, 16, 112],
+        [176, 48, 32, 128],
+        [240, 160, 144, 224]
+    ],
+    "dot-6": [
+        [238, 203, 119, 147, 210, 245],
+        [196, 98, 63, 112, 140, 217],
+        [91, 56, 28, 35, 105, 133],
+        [84, 21, 0, 7, 70, 126],
+        [189, 49, 14, 42, 161, 168],
+        [231, 182, 77, 154, 175, 224]
+    ],
+    "dot-diagonal-6": [
+        [112, 84, 98, 126, 154, 140],
+        [70, 0, 14, 168, 238, 224],
+        [56, 42, 28, 182, 196, 210],
+        [126, 154, 140, 112, 84, 112],
+        [168, 238, 224, 70, 0, 14],
+        [182, 196, 210, 56, 42, 28]
+    ],
+    "dot-8": [
+        [12, 36, 68, 108, 100, 60, 28, 4],
+        [44, 116, 152, 184, 176, 144, 92, 20],
+        [76, 160, 208, 232, 224, 200, 136, 52],
+        [124, 192, 240, 252, 248, 216, 168, 84],
+        [120, 188, 236, 252, 244, 212, 164, 80],
+        [72, 156, 204, 228, 220, 196, 132, 48],
+        [40, 112, 148, 180, 172, 140, 88, 16],
+        [8, 32, 64, 104, 96, 56, 24, 0]
+    ],
+    "dot-diagonal-8": [
+        [96, 40, 48, 104, 140, 188, 196, 148],
+        [32, 0, 8, 56, 180, 236, 244, 204],
+        [88, 24, 16, 64, 172, 228, 252, 212],
+        [120, 80, 72, 112, 132, 164, 220, 156],
+        [136, 184, 192, 144, 100, 44, 52, 108],
+        [176, 232, 240, 200, 36, 4, 12, 60],
+        [168, 224, 248, 208, 92, 28, 20, 68],
+        [128, 160, 216, 152, 124, 84, 76, 116]
+    ],
+    "dot-diagonal-10": [
+        [46, 79, 138, 198, 242, 245, 206, 145, 85, 49],
+        [69, 99, 160, 209, 202, 200, 210, 167, 104, 70],
+        [138, 161, 195, 171, 136, 134, 165, 196, 165, 139],
+        [198, 209, 171, 109, 74, 71, 104, 165, 209, 200],
+        [243, 202, 136, 73, 5, 2, 66, 130, 197, 241],
+        [245, 201, 135, 70, 2, 0, 65, 128, 194, 242],
+        [204, 211, 167, 104, 65, 66, 99, 160, 208, 206],
+        [144, 166, 196, 166, 130, 128, 160, 195, 171, 145],
+        [75, 104, 165, 209, 196, 193, 208, 171, 109, 76],
+        [50, 81, 139, 200, 241, 243, 206, 145, 87, 53]
+    ],
+    "dot-diagonal-16": [
+        [126, 116, 100, 80, 82, 102, 118, 120, 128, 138, 154, 174, 172, 152, 136, 134],
+        [114, 66, 54, 36, 38, 56, 68, 104, 140, 188, 200, 218, 216, 198, 186, 150],
+        [98, 52, 26, 22, 24, 30, 58, 88, 156, 202, 228, 232, 230, 224, 196, 166],
+        [78, 34, 8, 6, 4, 18, 40, 84, 174, 220, 246, 248, 250, 236, 214, 170],
+        [76, 32, 10, 0, 2, 20, 42, 86, 178, 222, 244, 254, 252, 234, 212, 168],
+        [96, 50, 16, 12, 14, 28, 60, 90, 158, 204, 238, 242, 240, 226, 194, 164],
+        [112, 64, 48, 46, 44, 62, 70, 106, 142, 190, 206, 208, 210, 192, 184, 148],
+        [124, 110, 94, 74, 72, 92, 108, 122, 130, 144, 160, 180, 182, 162, 146, 132],
+        [128, 138, 154, 174, 172, 152, 136, 134, 126, 116, 100, 80, 82, 102, 118, 120],
+        [140, 188, 200, 218, 216, 198, 186, 150, 114, 66, 54, 36, 38, 56, 68, 104],
+        [156, 202, 228, 232, 230, 224, 196, 166, 98, 52, 26, 22, 24, 30, 58, 88],
+        [174, 220, 246, 248, 250, 236, 214, 170, 78, 34, 8, 6, 4, 18, 40, 84],
+        [178, 222, 244, 254, 252, 234, 212, 168, 76, 32, 10, 0, 2, 20, 42, 86],
+        [158, 204, 238, 242, 240, 226, 194, 164, 96, 50, 16, 12, 14, 28, 60, 90],
+        [142, 190, 206, 208, 210, 192, 184, 148, 112, 64, 48, 46, 44, 62, 70, 106],
+        [130, 144, 160, 180, 182, 162, 146, 132, 124, 110, 94, 74, 72, 92, 108, 122]
+    ],
+    "dot-horizontal-6": [
+        [245, 231, 217, 210, 224, 238],
+        [161, 147, 133, 126, 140, 154],
+        [77, 63, 49, 42, 56, 70],
+        [35, 21, 7, 0, 14, 28],
+        [119, 105, 91, 84, 98, 112],
+        [203, 189, 175, 168, 182, 196]
+    ],
+    "dot-vertical-6x6": [
+        [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]
+    ],
+    "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],
+        [0, 17, 34],
+        [102, 119, 136],
+        [204, 221, 238]
+    ],
     "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

@@ -1,3 +1,39 @@
-import type diffusionKernels from './diffusion-kernels';
+import type diffusionKernels from './diffusion-kernels.js';
 import type thresholdMaps from './threshold-maps.json';
 export type DitheringAlgorithm = keyof typeof thresholdMaps | keyof typeof diffusionKernels | 'white-noise' | 'threshold';
+export interface SweetcornOptions {
+    /**
+     * The name of one of Sweetcorn’s built-in dithering algorithms to use.
+     *
+     * @see https://delucis.github.io/sweetcorn/algorithms/
+     *
+     * @example
+     * algorithm: 'floyd-steinberg'
+     */
+    algorithm?: DitheringAlgorithm | undefined;
+    /**
+     * A custom threshold map to use for ordered dithering.
+     *
+     * @see https://delucis.github.io/sweetcorn/guides/byo-algorithm/#defining-a-custom-threshold-map-for-sweetcorn
+     *
+     * @example
+     * thresholdMap: [
+     *   [0, 0.5],
+     *   [0.75, 0.25],
+     * ]
+     */
+    thresholdMap?: number[][] | undefined;
+    /**
+     * A custom diffusion kernel to use for error diffusion dithering.
+     *
+     * @see https://delucis.github.io/sweetcorn/guides/byo-algorithm/#defining-a-custom-diffusion-kernel-for-sweetcorn
+     *
+     * @example
+     * diffusionKernel: [
+     *   [0, 0, 0.2],
+     *   [0.1, 0.4, 0.1],
+     *   [0, 0.2, 0],
+     * ]
+     */
+    diffusionKernel?: number[][] | undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweetcorn",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "JavaScript image dithering tools for Sharp",
   "keywords": [
@@ -29,7 +29,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "homepage": "https://github.com/delucis/sweetcorn",
+  "homepage": "https://delucis.github.io/sweetcorn/",
   "repository": {
     "type": "git",
     "url": "https://github.com/delucis/sweetcorn.git",
@@ -37,6 +37,8 @@
   },
   "bugs": "https://github.com/delucis/sweetcorn/issues",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "pretest": "pnpm build",
+    "test": "node --test"
   }
 }