Gaussian blur, LAB sharpen parameters, and custom convolution kernels

While Image enhancement, local contrast, and edge detection previews blur and sharpen outputs side by side, tuning thumbnail crispness or denoising scans in production requires understanding gaussblur amplitude truncation, the six CIE LAB sharpen parameters, and the boundary between median rank filters (Rank / median) and custom convolution matrices (conv / convolve).

1. Gaussian blur (GaussianBlur / gaussblur): sigma and min_ampl

vips_gaussblur runs a separable 1D Gaussian kernel:

• sigma: standard deviation of the Gaussian bell curve (blur radius). Values of 1.0–5.0 soften thumbnails or feather masks; 15.0–40.0 produces frosted-glass backdrops. Note that sharp.blur(sigma) requires sigma between 0.3 and 1000.
• min_ampl (minimum amplitude cutoff): determines where the Gaussian tails are truncated (default 0.2). For smoother wide-radius gradients without subtle banding, lower min_ampl by passing the optional second argument image.GaussianBlur(sigma, 0.05) in govips or minAmplitude: 0.05 in sharp.

Gaussian blur (Sigma 4.0) · WebP1938 × 1292, 95,724 bytes, 3 bands

Generated with govips v2.20.0 / libvips 8.17.3.

govips

// Optional second parameter minAmpl defaults to 0.2; smaller values widen the kernel for smoother tails
if err := image.GaussianBlur(4.0, 0.2); err != nil {
    return err
}

sharp

import sharp from 'sharp';

await sharp('input.jpg')
  .blur({ sigma: 4.0, minAmplitude: 0.2, precision: 'integer' })
  .webp({ quality: 82 })
  .toFile('blur.webp');

pyvips

import pyvips

image = pyvips.Image.new_from_file("input.jpg")
blurred = image.gaussblur(4.0, min_ampl=0.2, precision="integer")
blurred.write_to_file("blur.webp", Q=82)

vips CLI

vips gaussblur input.jpg 'blur.webp[Q=82]' 4.0 --min-ampl 0.2 --precision integer

2. Unsharp masking in CIE LAB lightness space (Sharpen)

Unlike naive RGB Laplacian sharpening, vips_sharpen converts the image to CIE LAB and sharpens only the L (lightness) channel*, preventing colour fringes and hue shifts along high-contrast edges.

Its piecewise-linear transfer curve is controlled by six parameters:

Parameter	Default	Meaning	Tuning guidance
sigma	0.5	Gaussian low-pass radius	0.5–1.2 for web thumbnails; 1.5–2.5 for high-DPI print
x1 (flat/jagged threshold)	2.0	High-frequency difference threshold separating flat areas from edges	Raise to 3.0–5.0 on noisy low-light photos to avoid amplifying grain
m1 (flat slope)	1.0	Sharpening multiplier applied to differences below x1	Set to 0 to leave flat areas (skin, night sky) untouched
m2 (jagged slope)	2.0	Sharpening multiplier applied to edges above x1	1.0–2.0 for crisp thumbnails; excessive values cause bright halos
y2 / y3 (brightening / darkening cap)	10.0 / 20.0	Maximum allowed L* increase (y2) or decrease (y3)	Caps overshoot on extreme black-to-white edges

Note: govips exposes image.Sharpen(sigma, x1, m2) with three arguments, whereas sharp, pyvips, and vips CLI expose all six parameters.

LAB lightness sharpen · WebP1938 × 1292, 621,814 bytes, 3 bands

Generated with govips v2.20.0 / libvips 8.17.3.

govips

// Sharpen(sigma, x1, m2)
if err := image.Sharpen(1.2, 2.0, 1.5); err != nil {
    return err
}

sharp

import sharp from 'sharp';

await sharp('input.jpg')
  .sharpen({
    sigma: 1.2,
    m1: 1.0,
    m2: 1.5,
    x1: 2.0,
    y2: 10.0,
    y3: 20.0,
  })
  .webp({ quality: 82 })
  .toFile('sharpen.webp');

pyvips

import pyvips

image = pyvips.Image.new_from_file("input.jpg")
sharpened = image.sharpen(sigma=1.2, x1=2.0, y2=10.0, y3=20.0, m1=1.0, m2=1.5)
sharpened.write_to_file("sharpen.webp", Q=82)

vips CLI

vips sharpen input.jpg 'sharpen.webp[Q=82]' --sigma 1.2 --x1 2.0 --m1 1.0 --m2 1.5

3. Median rank filtering (Rank / median) and custom convolution kernels (convolve / conv)

• Median / rank filtering: sorts pixels inside a w × h window and picks the value at index = (w*h)/2, removing salt-and-pepper noise without blurring sharp step edges. Supported across all four interfaces: image.Rank(3, 3, 4) in govips, .median(3) in sharp, .median(3) / .rank(3, 3, 4) in pyvips, and vips rank in out 3 3 4 in vips CLI.
• Custom 2D convolution kernels: sharp (.convolve()), pyvips (Image.new_from_array + .conv()), and vips CLI (vips conv) accept arbitrary M × N kernels with scale and offset. govips v2.19.0 exposes fixed operators such as Sobel() rather than a public arbitrary-matrix Conv wrapper.

govips

// 3×3 median filter (index 4 selects the median of 9 sorted pixels)
if err := image.Rank(3, 3, 4); err != nil {
    return err
}

// Edge detection: govips exposes built-in Sobel(), not an arbitrary-matrix Conv()
if err := image.Sobel(); err != nil {
    return err
}

sharp

import sharp from 'sharp';

// 1. 3×3 median filter
await sharp('input.jpg').median(3).webp({ quality: 82 }).toFile('median.webp');

// 2. Custom 3×3 emboss convolution kernel with scale=1 and offset=128
await sharp('input.jpg')
  .convolve({
    width: 3,
    height: 3,
    kernel: [-2, -1, 0, -1, 1, 1, 0, 1, 2],
    scale: 1,
    offset: 128,
  })
  .webp({ quality: 82 })
  .toFile('emboss.webp');

pyvips

import pyvips

image = pyvips.Image.new_from_file("input.jpg")

# 1. 3×3 median filter
median = image.median(3)

# 2. Custom 3×3 convolution kernel (attach scale and offset to the kernel image)
kernel = pyvips.Image.new_from_array(
    [[-2, -1, 0], [-1, 1, 1], [0, 1, 2]],
    scale=1.0,
    offset=128.0,
)
emboss = image.conv(kernel, precision="integer")
emboss.write_to_file("emboss.webp", Q=82)

vips CLI

# 3×3 median filter
vips rank input.jpg 'median.webp[Q=82]' 3 3 4

When to choose Gaussian blur vs median filtering

Gaussian blur (gaussblur) is a separable linear filter that runs in (O(R)) per pixel and is suited for visual softening and pre-filtering. Median filtering (rank) sorts pixels inside each 2D window and is specifically designed to remove isolated impulse/salt-and-pepper noise while keeping document text and line edges sharp.

Sources

• libvips gaussblur documentation
• libvips sharpen documentation
• libvips rank and conv documentation
• sharp blur, sharpen, median, and convolve