Imgix APIsRendering APISizeResize Filter

Resize Filter

resize-filter

Selects the resampling kernel used whenever an image is scaled. Every resize has to decide what color each output pixel takes from the input pixels around it, and the kernel is that decision. The default is lanczos2, which suits photographic content; resize-filter lets you override it when a different trade-off between sharpness, smoothness and edge fidelity is wanted.

The kernel applies to both upscales and downscales.

Accepted values

ValueAliasesBest for
lanczos2—Default. Photographic content. A good balance of sharpness and freedom from artifacts.
lanczos3lanczos, photo, sharpA sharper result than lanczos2, at the cost of more ringing around high-contrast edges.
bicubiccubic, catmull-romSmooth gradients with moderate sharpening.
mitchellgraphic, softSofter output with less ringing. Useful for graphics and flat color.
bilinearlinearFast and smooth, noticeably softer than the cubic and lanczos kernels.
nearestpixelHard edges with no interpolation. The right choice for pixel art, QR codes and screenshots of UI.

Values are matched exactly and are case-sensitive. A value that matches nothing — including a correctly spelled kernel in the wrong case, such as NEAREST — is ignored, and the image renders with the default lanczos2 instead of returning an error.

Preserving hard edges

The clearest difference appears when scaling up. nearest repeats each source pixel as a solid block, keeping edges crisp, while the default interpolates between them and produces a smooth gradient. For pixel art, QR codes, barcodes and UI screenshots, that interpolation is usually unwanted.

Default (lanczos2) — interpolated
sandbox-demo
resize-filter=nearest — blocky
sandbox-demo

Sharpness on a downscale

A downscale throws most of the source pixels away, and the kernel decides how the survivors are weighted. The difference is clearest on fine, high-contrast detail: the photograph below is reduced to a third of its width, which leaves the bridge’s suspender cables about one output pixel wide.

Drag the divider to wipe one render over the other, and use the rows beneath it to put any two values on either side. lanczos2 is the default kernel, and original is the full-resolution source with no reduction applied at all.

The Golden Gate Bridge reduced to 700 pixels wide with different resampling kernelsThe Golden Gate Bridge reduced to 700 pixels wide with different resampling kernels
◂▸
lanczos2nearest
Left
Right

nearest takes a single source pixel per output pixel and ignores the rest, so a cable that falls between samples simply disappears and the ones that survive turn jagged. It is the wrong choice for downscaling a photograph, however well it works on an upscale. bilinear averages only the four nearest pixels, which blurs the cables into the sky. The cubic and lanczos kernels weight a wider neighborhood and hold them.

Comparing any kernel against original shows what the reduction itself costs: the cables and the city on the far shore are carried by a handful of pixels at this size, and a kernel can only decide how gracefully they are given up.

Comparing the smooth kernels

lanczos2, lanczos3, bicubic and mitchell separate by only a pixel or two of edge contrast, which is not visible at normal size. Each demo below downscales the same crop to 100px wide with the named kernel and then magnifies that result 5x with nearest, so the individual output pixels can be compared:

lanczos3 — hard cable edges
sandbox-demo
Default (lanczos2)
sandbox-demo
mitchell — softest, least ringing
sandbox-demo

The sharper kernels keep more contrast at an edge, at the cost of a light and dark fringe beside it — ringing. The softer kernels trade that contrast away for a cleaner transition.

Intent names may be retuned

pixel, graphic, soft, photo and sharp describe what a kernel is for rather than naming it. Which kernel each maps to may be retuned over time, so use the kernel names — nearest, mitchell, lanczos3 and the rest — wherever the output must not change.

Resizing layers

Watermarks and blend layers have their own kernels, and do not inherit this one. A layer resizes with lanczos2 unless you set mark-resize-filter or blend-resize-filter for it, whatever resize-filter says for the base image — including when blend-size=inherit makes a blend layer take the base image’s sizing.

That independence is useful: a pixel-art badge can stay crisp while the photograph behind it resizes normally.

?w=800&mark=badge.png&mark-w=96&mark-resize-filter=nearest

What the kernel does not affect

resize-filter applies to the output resize of the picture you asked for. These keep their own resampling, so the setting cannot change what they see:

  • The analysis behind smart crops — crop=faces, crop=entropy, crop=edges, crop=auto — and object detection.
  • The blurred backdrop of fit=fill with fill=blur.
  • mask and append images.
  • The internals of effects such as shadows and reflections.
  • fm=ico and fm=pdf.

Animated images use the kernel on every frame. Video is not affected.

Notes

resize-filter only takes effect when the image is actually scaled. A request that returns the image at its native size has nothing to resample, so the parameter makes no difference.

To enlarge a photograph rather than preserve hard pixels, consider super-resolution, which reconstructs detail instead of interpolating between existing pixels.