Configuring SVG feConvolveMatrix kernelMatrix

The SVG <feConvolveMatrix> filter primitive applies matrix convolution effects—such as blurring, sharpening, edge detection, and embossing—by combining neighboring pixels based on a mathematical grid. The kernelMatrix attribute defines this grid of transformation values, but its behavior, dimensions, and visual outcome depend on several key companion attributes. This guide details the essential parameters that directly configure and control the kernelMatrix.

Core Attributes that Configure kernelMatrix

1. kernelMatrix

• Type: <list of numbers>
• Description: The actual matrix of numbers applied to the pixel values. The number of values provided must equal the product of the dimensions defined in the order attribute (\(orderX \times orderY\)).

2. order

• Type: <number-optional-number>
• Default: 3 (a \(3 \times 3\) matrix)
• Description: Defines the grid size (columns and rows) of the kernelMatrix.
  • A single value (e.g., order="3") sets a square matrix (\(3 \times 3\), requiring 9 values).
  • Two values (e.g., order="3 5") set the width and height respectively (3 columns by 5 rows, requiring 15 values).

3. targetX and targetY

• Type: <integer>
• Default: \(\lfloor orderX / 2 \rfloor\) and \(\lfloor orderY / 2 \rfloor\) (the center of the matrix)
• Description: Determines the X and Y coordinates (0-indexed) of the target pixel within the kernel matrix. This defines which cell in the kernel corresponds to the current pixel being processed.

4. divisor

• Type: <number>
• Default: The sum of all values in kernelMatrix (or 1 if the sum is 0).
• Description: Divides the sum of the matrix multiplication results before applying the bias. Setting a custom divisor normalizes brightness and prevents the output colors from blowing out or clipping.

5. bias

• Type: <number>
• Default: 0
• Description: Adds a fixed offset value to the final color result after the matrix multiplication and divisor step. This is commonly used in edge detection or embossing effects to shift neutral/gray areas into visible color ranges.

6. edgeMode

• Type: duplicate | wrap | none
• Default: duplicate
• Description: Determines how input image boundaries are sampled when a kernel extends beyond the edges of the image:
  • duplicate: Extends the nearest edge pixel values outward.
  • wrap: Samples pixels from the opposite side of the image.
  • none: Treats pixels outside the boundary as transparent black (zeros).

7. preserveAlpha

• Type: true | false
• Default: false
• Description: Specifies whether the convolution matrix applies only to the color channels (true) while preserving the original alpha channel, or processes both color and alpha channels identically (false).

8. kernelUnitLength

• Type: <number-optional-number>
• Default: Direct 1:1 mapping with the current coordinate system.
• Description: Defines the intended distance between successive columns and rows in the kernel grid, enabling resolution-independent convolution effects.

Example Configuration

<filter id="sharpen">
  <feConvolveMatrix
    order="3 3"
    kernelMatrix="
       0 -1  0
      -1  5 -1
       0 -1  0"
    divisor="1"
    bias="0"
    targetX="1"
    targetY="1"
    edgeMode="duplicate"
    preserveAlpha="true" />
</filter>