Understanding SVG feConvolveMatrix for Matrix Kernels

The feConvolveMatrix filter primitive in SVG is a powerful image processing tool designed to apply custom matrix convolutions to graphics and text. By using mathematical matrix kernels, it recalculates pixel values based on neighboring pixels to produce a wide range of visual effects, including sharpening, blurring, edge detection, embossing, and beveling. This article explains how feConvolveMatrix works, its core attributes, and its role in building tailored visual filters directly within SVG.

How feConvolveMatrix Works

Convolution is a mathematical operation used in digital signal and image processing. In the context of SVG, feConvolveMatrix overlays a grid of numbers—known as a kernel matrix—over each pixel in an image. It multiplies the color values of the current pixel and its surrounding neighbors by the corresponding numbers in the kernel, sums the results, and applies the new calculated color value to the target pixel.

Key Attributes for Custom Kernels

To create custom matrix effects, feConvolveMatrix relies on several fundamental attributes:

• order: Defines the dimensions of the convolution grid, typically represented as two numbers (e.g., order="3 3" for a 3x3 matrix) or a single number for square matrices.
• kernelMatrix: The list of numbers defining the weights used in the convolution computation. For a 3x3 matrix, you provide nine numbers in row-major order.
• divisor: The number by which the sum of the matrix multiplication is divided. If omitted, the browser defaults to the sum of the kernel values, or 1 if the sum is zero. Proper division prevents the image from blowing out to pure white or collapsing to pure black.
• bias: An offset added to the final result of the convolution calculation, useful for shifting color ranges in effects like embossing.
• targetX and targetY: Define the center pixel coordinate of the kernel relative to the current pixel being processed.
• edgeMode: Determines how pixels on the outer edges of the graphic are calculated when neighbor pixels do not exist, using values like duplicate, wrap, or none.
• preserveAlpha: A boolean value (true or false) indicating whether the convolution applies solely to color channels or includes the alpha channel. Setting it to true maintains the original opacity shape while modifying internal colors.

Practical Applications

By altering the values within the kernelMatrix, feConvolveMatrix enables diverse visual results:

• Edge Detection: Setting positive values on one side of the kernel and negative values on the opposite side extracts outlines and high-contrast boundaries.
• Sharpening: Placing a high positive weight in the center cell and negative weights in adjacent cells increases contrast between adjacent pixels, crisping soft details.
• Embossing: Combining directional positive and negative weights with a mid-tone bias generates a pseudo-3D stamped or engraved appearance.
• Custom Blurs and Glows: Distributing equal positive weights across the kernel softens sharp lines and averages color transitions.

Integration in SVG Pipelines

Because feConvolveMatrix operates natively within the SVG filter graph, it can be combined with other primitives such as feOffset, feBlend, and feColorMatrix. This integration allows developers and designers to build complex, resolution-independent raster operations entirely in code without relying on external image editing software.