Parasol Framework Manual

Applies a matrix convolution filter effect.

Convolve applies a matrix convolution filter effect to an input source. A convolution combines pixels in the input image with neighbouring 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 neighbouring 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 neighbouring pixels. The basic convolution formula which is applied to each colour value for a given pixel is:

COLOURX,Y = (
     SUM I=0 to [MatrixRows-1] {
       SUM J=0 to [MatrixColumns-1] {
         SOURCE X - TargetX + J, Y - TargetY + I * Matrix * MatrixColumns - J - 1,  MatrixRows - I - 1
       }
     }
   ) / Divisor + Bias * ALPHAX,Y

Note in the above formula that the values in the kernel matrix are applied such that the kernel matrix is rotated 180 degrees relative to the source and destination images in order to match convolution theory as described in many computer graphics textbooks.

Because they operate on pixels, matrix convolutions are inherently resolution-dependent. To make resolution-independent results, an explicit value should be provided for either the ResX and ResY attributes on the parent VectorFilter and/or UnitX and UnitY.

Structure

The ConvolveFX class consists of the following fields:

Access	Name	Type	Comment
	Bias	DOUBLE	Used to adjust the final result of each computed RGB value.
After applying the Matrix to the input image to yield a number and applying the Divisor, the Bias value is added to each component. One application of Bias is when it is desirable to have .5 gray value be the zero response of the filter. The Bias value shifts the range of the filter. This allows representation of values that would otherwise be clamped to 0 or 1. The default is 0.
	Divisor	DOUBLE	Defines the divisor value in the convolution algorithm.
After applying the Matrix to the input image to yield a number, that number is divided by Divisor to yield the final destination color value. A divisor that is the sum of all the matrix values tends to have an evening effect on the overall color intensity of the result. The default value is the sum of all values in Matrix, with the exception that if the sum is zero, then the divisor is set to `1`.
	EdgeMode	INT	Defines the behaviour of the convolve algorithm around the edges of the input image.
The EdgeMode determines how to extend the input image with color values so that the matrix operations can be applied when the Matrix is positioned at or near the edge of the input image.
	Matrix	DOUBLE []	A list of numbers that make up the kernel matrix for the convolution.
A list of numbers that make up the kernel matrix for the convolution. The number of entries in the list must equal `MatrixColumns * MatrixRows`.
	MatrixColumns	INT	The number of columns in the Matrix.
Indicates the number of columns represented in Matrix. A typical value is `3`. It is recommended that only small values are used; higher values may result in very high CPU overhead and usually do not produce results that justify the impact on performance. The default value is `3`.
	MatrixRows	INT	The number of rows in the Matrix.
Indicates the number of rows represented in Matrix. A typical value is `3`. It is recommended that only small values are used; higher values may result in very high CPU overhead and usually do not produce results that justify the impact on performance. The default value is 3.
	PreserveAlpha	INT	If TRUE, the alpha channel is protected from the effects of the convolve algorithm.
	TargetX	INT	The X position of the matrix in relation to the input image.
Determines the positioning in X of the convolution matrix relative to a given target pixel in the input image. The left-most column of the matrix is column number zero. The value must be such that `0 <= TargetX < MatrixColumns`. By default, the convolution matrix is centered in X over each pixel of the input image, i.e. `TargetX = floor(MatrixColumns / 2)`.
	TargetY	INT	The Y position of the matrix in relation to the input image.
Determines the positioning in Y of the convolution matrix relative to a given target pixel in the input image. The left-most column of the matrix is column number zero. The value must be such that `0 <= TargetY < MatrixRows`. By default, the convolution matrix is centered in Y over each pixel of the input image, i.e. `TargetY = floor(MatrixRows / 2)`.
	UnitX	DOUBLE	The distance in filter units between rows in the Matrix.
Indicates the intended distance in current filter units (i.e. as determined by the value of PrimitiveUnits) between successive columns and rows, respectively, in the Matrix. By specifying value(s) for UnitX, the kernel becomes defined in a scalable, abstract coordinate system. If UnitX is not specified, the default value is one pixel in the offscreen bitmap, which is a pixel-based coordinate system, and thus potentially not scalable. For some level of consistency across display media and user agents, it is necessary that a value be provided for at least one of ResX and UnitX. The most consistent results and the fastest performance will be achieved if the pixel grid of the offscreen bitmap aligns with the pixel grid of the kernel.
	UnitY	DOUBLE	The distance in filter units between columns in the Matrix.
Indicates the intended distance in current filter units (i.e. as determined by the value of PrimitiveUnits) between successive columns and rows, respectively, in the Matrix. By specifying value(s) for UnitY, the kernel becomes defined in a scalable, abstract coordinate system. If UnitY is not specified, the default value is one pixel in the offscreen bitmap, which is a pixel-based coordinate system, and thus potentially not scalable. For some level of consistency across display media and user agents, it is necessary that a value be provided for at least one of ResY and UnitY. The most consistent results and the fastest performance will be achieved if the pixel grid of the offscreen bitmap aligns with the pixel grid of the kernel.
	XMLDef	STRING	Returns an SVG compliant XML string that describes the effect.

Actions

The following actions are currently supported:

Name

Comment

Draw

Draws object graphics to drawable areas.

ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)

Input	Description
X	The X position of the region to be drawn.
Y	The Y position of the region to be drawn.
Width	The width of the region to be drawn.
Height	The height of the region to be drawn.

Class Info
ID	ID_CONVOLVEFX
Category	Graphics
Include	modules/convolvefx.h
Version	1

ConvolveFX Class

Structure

Actions

Class Info

Class List