Lens Docs

Appearance

EWA Resampling and Filters ​

Once you know where a destination pixel 'hits' the source image, you need to determine the color to make the destination pixel, using the pixels near the 'hit' point in the source image.

Normally the distort() function will use the Area Resampling method EWA (Elliptical Weighted Average) to average out a larger area of the source image to work out the right color for this pixel.

You can change the filter using by EWA resampling using the filter option to use one of built-in presets (FilterName), or even set your own filter object that implements ResampleFilter interface using the same filter option.

ts
import { distort, FilterName } from "@alxcube/lens";

// ...

const result = await distort(image, distortionName, args, {
  filter: FilterName.ROBIDOUX_SHARP,
});

At the moment Lens supports following filter presets:

TIP

If you are interested in deeper understanding of filters, you can find much more detailed info at ImageMagick Resample Filters page, especially in Cylindrical Filters section.

Resampling Failure ​

In some special situations the EWA resampling Ellipse may fail to actually 'hit' any real pixel for it to create a weighted average. Basically the ellipse is so small, or so thin, that it falls completely between every pixel in the image. And without any pixel colors, it can not generate a color for the output image at that point.

This is an extreme situation, and generally is impossible to achieve unless you are playing with Expert Filter Settings. But in the unlikely event that no pixels are hit, or the filter weights add up to zero, the resampling will fail. In that case Lens will fall back to using a simple direct interpolated lookup, just like you would get if you turn of EWA filtering (see next).

If you want to check if this is happening you can use the special interpolation InterpolationMethod.BACKGROUND with a unusual background color so as to highlight any such resampling failures:

ts
import { distort, InterpolationMethod } from "@alxcube/lens";

// ...

const result = await distort(image, distortionName, args, {
  interpolationMethod: InterpolationMethod.BACKGROUND,
  imageBackgroundColor: "#00ff00", // Green
});

Interpolated, or Direct Color Lookup ​

You can set preferredResampler option to "point", to turn off filtering, and hence EWA resampling:

ts
const result = await distort(image, distortionName, args, {
  preferredResampler: "point",
});

When this is done Lens will switch color lookups to use fast and simpler Pixel Interpolation. That is it will look up a color using only a 'single point' reference to the source image without any 'resampling area'. The color of the resulting pixels will use an interpolated color based only on nearest neighbours to point.

Interpolation will generally cause sever aliasing effects when any form of minification or downsampling of the image occurs.

But it does work extremely well for images containing minimal distortions such as rotations, tiling, or for image enlargement (magnification or up-sampling). A supersampling technique can be combined with interpolation, to improve the results in areas of strong compression, minification or downsampling.