Document resize kernels with a side-by-side comparison

docs/scripts/generate-kernel-comparison.mjs

@@ -0,0 +1,47 @@
+/*!
+  Copyright 2013 Lovell Fuller and others.
+  SPDX-License-Identifier: Apache-2.0
+*/
+
+// Rebuild docs/public/api-resize-kernels.png from a high-contrast diagonal.
+// Rasterise the SVG at 1280x960 first, then downsize the same PNG to 160x120.
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import sharp from '../../lib/index.mjs';
+
+const root = path.resolve(fileURLToPath(new URL('../..', import.meta.url)));
+const input = Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="960" viewBox="0 0 1280 960">
+  <rect width="1280" height="960" fill="white"/>
+  <path d="M0 760 L1000 0 H1280 L0 960Z" fill="#111"/>
+  <path d="M0 250 L1280 900" fill="none" stroke="#111" stroke-width="24"/>
+  <path d="M150 0 L1280 570" fill="none" stroke="#e84428" stroke-width="8"/>
+</svg>`);
+// Resizing SVG input directly rasterises at the output size and ignores the kernel.
+const raster = await sharp(input).png().toBuffer();
+const output = path.join(root, 'docs/public/api-resize-kernels.png');
+const kernels = [
+  'nearest', 'linear', 'cubic', 'mitchell',
+  'lanczos2', 'lanczos3', 'mks2013', 'mks2021'
+];
+const width = 176;
+const height = 154;
+const imageWidth = 160;
+const imageHeight = 120;
+const panels = await Promise.all(kernels.map(async (kernel, index) => {
+  const image = await sharp(raster)
+    .resize(imageWidth, imageHeight, { kernel, fastShrinkOnLoad: false })
+    .png()
+    .toBuffer();
+  const label = Buffer.from(`<svg width="${width}" height="28" xmlns="http://www.w3.org/2000/svg"><text x="8" y="21" font-size="17" font-family="sans-serif" fill="#16181d">${kernel}</text></svg>`);
+  const x = (index % 4) * width;
+  const y = Math.floor(index / 4) * height;
+  return [
+    { input: image, left: x + 8, top: y + 28 },
+    { input: label, left: x, top: y }
+  ];
+}));
+await sharp({ create: { width: width * 4, height: height * 2, channels: 4, background: '#fff' } })
+  .composite(panels.flat())
+  .png()
+  .toFile(output);
+console.log(output);

docs/src/content/docs/api-resize.md

@@ -41,6 +41,16 @@ Possible downsizing kernels are:
 - `mks2013`: Use a [Magic Kernel Sharp](https://johncostella.com/magic/mks.pdf) 2013 kernel, as adopted by Facebook.
 - `mks2021`: Use a Magic Kernel Sharp 2021 kernel, with more accurate (reduced) sharpening than the 2013 version.
 
+The comparison below downsizes the same 1280x960 high-contrast diagonal graphic to 160x120 with each kernel.
+Use `nearest` to keep hard pixel edges; `linear` softens them. For photographs,
+start with the default `lanczos3`, then compare other kernels if fine edges
+look too soft or show halos. The best choice depends on the image and output size.
+
+<img alt="Side-by-side 160x120 downsizes of one diagonal graphic using nearest, linear, cubic, mitchell, lanczos2, lanczos3, mks2013 and mks2021 kernels" width="704" height="308" src="/api-resize-kernels.png">
+
+Rebuild this image with `node docs/scripts/generate-kernel-comparison.mjs`.
+The comparison disables shrink-on-load so the kernel's effect is easier to see.
+
 When upsampling, these kernels map to `nearest`, `linear` and `cubic` interpolators.
 Downsampling kernels without a matching upsampling interpolator map to `cubic`.
 

lib/resize.mjs

@@ -153,6 +153,16 @@ function isResizeExpected (options) {
  * - `mks2013`: Use a [Magic Kernel Sharp](https://johncostella.com/magic/mks.pdf) 2013 kernel, as adopted by Facebook.
  * - `mks2021`: Use a Magic Kernel Sharp 2021 kernel, with more accurate (reduced) sharpening than the 2013 version.
  *
+ * The comparison below downsizes the same 1280x960 high-contrast diagonal graphic to 160x120 with each kernel.
+ * Use `nearest` to keep hard pixel edges; `linear` softens them. For photographs,
+ * start with the default `lanczos3`, then compare other kernels if fine edges
+ * look too soft or show halos. The best choice depends on the image and output size.
+ *
+ * <img alt="Side-by-side 160x120 downsizes of one diagonal graphic using nearest, linear, cubic, mitchell, lanczos2, lanczos3, mks2013 and mks2021 kernels" width="704" height="308" src="/api-resize-kernels.png">
+ *
+ * Rebuild this image with `node docs/scripts/generate-kernel-comparison.mjs`.
+ * The comparison disables shrink-on-load so the kernel's effect is easier to see.
+ *
  * When upsampling, these kernels map to `nearest`, `linear` and `cubic` interpolators.
  * Downsampling kernels without a matching upsampling interpolator map to `cubic`.
  *