CImage:FiltKernel

The FiltKernel method applies a user-defined kernel to an image. The filter is defined as a CMatrix.

Syntax

bSuccess = CImage:FiltKernel( CMatrix, cols, rows )

bSuccess = CImage:FiltKernel( CMatrix, cols, rows, CRect )

where

CMatrix is the filter kernel in a CMatrix.

cols is the column length of the filter kernel.

rows is the row length of the filter kernel.

CRect is the rectangle defining the area to process. If omitted or passed as nil, the entire image is processed.

bSuccess is the returned success code. On success it is true, otherwise false.

This method applies a filter kernel defined as a CMatrix. No normalization is automatically applied, so the calling script is responsible for any normalization. If normalization is needed, use the CMatrix:Normalize method before calling FiltKernel.

Note that the filter CMatrix is defined as row major, that is, row index first and column index second. However, the arguments to FiltKernel are passed with the column dimension first (see Syntax).

The following table defines a 3x3 gradient filter at 45 degree angle:

3x3 Gradient Filter

-1	-1	-1
-1	2	1
-1	1	1

This filter can be created as a CMatrix using the following script:

K = CMatrix:new()	-- create a new CMatrix
K:Init( 3, 3, -1 )	-- initialize 3x3 to all -1.0
K:Set( 2, 3, -1 )
K:Set( 3, 2, -1 )
K:Set( 3, 3, -1 )
K:Set( 2, 2, 2 )	-- central pixel

Example

Suppose an image is displayed in a CImageView named V. The following script creates a filter Kernel K as a 5x5 CMatrix of 0's. Next, the central pixel at index [3][3] is set to 100.0. The filter is then normalized to unit volume. With only the central pixel non-zero, this is a 5x5 identity filter which does a lot of math but simply returns the same image unchanged. The filter is applied to the region [100:300, 400:800]:

K = CMatrix:new()	-- create a new CMatrix
K:Init( 5, 5, 0 )	-- define a 5x5 matrix of 0's
K:Set( 3, 3, 100 )	-- set the central matrix value
K:Normalize()	-- normalize to a volume of 1.0
I = V:GetImage()	-- attach the current displayed image
R = NewRect( 100,300, 400,800 )	-- setup the rectangle to process
I:FiltKernel( K, 5, 5, R )	-- apply the filter
V:Update()	-- update the display after the scale