Document resize kernels with a side-by-side comparison

[sivashankarav]

Fixes #3354.

Add brief kernel selection guidance and a side-by-side image of all eight downsampling kernels applied to the same high-contrast diagonal graphic. The image can be regenerated with node docs/scripts/generate-kernel-comparison.mjs; the source is built in the script, so it does not rely on a third-party image.

Update both the resize JSDoc and the generated docs page. The examples disable shrink-on-load so the kernel differences are visible.

Tested: npm run lint-js, cd docs && npm run build. The full npm test stops during type lint in this fresh checkout because generated dist/index.d.mts is missing.

[lovell]

An SVG input used with resize will be rasterised at the specified dimensions and kernel will be ignored, which is why the 8 parts of the image in the PR all look the same. (I should probably add something to the docs about this short-cut.)

I think you'll need to render the SVG as PNG using the full 1280x960 dimensions then use a second pipeline to resize down using the various kernels.

[sivashankarav]

Thanks for catching this. I've changed the generator to rasterise the SVG at 1280x960 first, then resize that PNG in a separate pipeline for each kernel. The regenerated image now has eight distinct pixel outputs. JavaScript lint and the docs build pass.

[lovell]

Thanks for the update. Although it does contain diagonal lines, I'm unsure this is the best source image to fully demonstrate how the various kernels behave as many of the outputs are still very similar. The sort of thing that really tests these are slightly-curved diagonals, concentric circles and checkerboard patterns.

There are some sample images at libvips/libvips#2200 we might be able to use.

Perhaps a nice slider or onion-skin comparison tool might be better? We could embed it as an iframe rather than have all the HTML in the JSDocs.