This page is In Progress

Notice: The WebPlatform project, supported by various stewards between 2012 and 2015, has been discontinued. This site is now available on github.

feConvolveMatrix

Overview Table

DOM Interface
SVGElement

Notes

Remarks

feConvolveMatrix applies a matrix convolution filter effect. A convolution combines pixels in the input image with neighboring pixels to produce a resulting image. A wide variety of imaging operations can be achieved through convolutions, including blurring, edge detection, sharpening, embossing, and beveling.

A matrix convolution is based on an n-by-m matrix (the convolution kernel) which describes how a given pixel value in the input image is combined with its neighboring pixel values to produce a resulting pixel value. Each result pixel is determined by applying the kernel matrix to the corresponding source pixel and its neighboring pixels.

Because they operate on pixels, matrix convolutions are inherently resolution-dependent. To make feConvolveMatrix produce resolution-independent results, an explicit value should be provided for either the filterRes attribute on the filter element and/or attribute kernelUnitLength.

kernelUnitLength, in combination with the other attributes, defines an implicit pixel grid in the filter effects coordinate system (that is, the coordinate system established by the primitiveUnits attribute). If the pixel grid established by kernelUnitLength is not scaled to match the pixel grid established by attribute filterRes (implicitly or explicitly), then the input image will be temporarily rescaled to match its pixels with kernelUnitLength. The convolution happens on the resampled image. After applying the convolution, the image is resampled back to the original resolution.

Syntax

Standards information

Members

The SVGFEConvolveMatrixElement object has these properties:

  • bias: Shifts the range of the filter. This allows representation of values that would otherwise be clamped to 0 or 1.
  • divisor: Affects the final destination color value of the filter.
  • edgeMode: Determines how to extend the input image as necessary with color values so that the matrix operations can be applied when the kernel is positioned at or near the edge of the input image.
  • height: Gets or sets the height of an element.
  • in1: Identifies input for the given filter primitive.
  • kernelMatrix: The list of numbers that make up the kernel matrix for the convolution.
  • kernelUnitLengthX: kernelUnitLength indicates the intended distance in current filter units for dx and dy in the surface normal calculation formulas.
  • kernelUnitLengthY: kernelUnitLength indicates the intended distance in current filter units for dx and dy in the surface normal calculation formulas.
  • orderX: Indicates the number of cells in each dimension for kernelMatrix.
  • orderY: Indicates the number of cells in each dimension for kernelMatrix.
  • preserveAlpha: Indicates that the convolution will apply to all channels or just the color channels.
  • result: Provides a reference for the output result of a filter.
  • targetX: Determines the positioning in X of the convolution matrix relative to a given target pixel in the input image.
  • targetY: Determines the positioning in Y of the convolution matrix relative to a given target pixel in the input image.
  • width: Defines the width of an element.
  • x: Gets or sets the x-coordinate value.
  • y: Gets or sets the y-coordinate value.

See also

Related articles

Filters

Attributions