convol_image

Herror ::convol_image ( Hobject Image, Hobject *ImageResult, const HTuple &FileName, const HTuple &Margin ) HImage HImage::ConvolImage ( const HTuple &FileName, const HTuple &Margin ) const HImageArray HImageArray::ConvolImage ( const HTuple &FileName, const HTuple &Margin ) const

Convolve an image with an arbitrary filter mask.

::convol_image convolves the input image Image with an arbitrary linear filter. The corresponding filter matrix is stored in a file named FileName. Several options for the treatment at the image's borders can be chosen (Margin):

   Margin = 0...255
                      Gray values are assumed constant outside of
			the image (with the given gray value).
            -1
	                The border's gray values are continued.
            -2
	                The border's gray values are continued
			cyclically.
            -3
	                The gray values are mirrored along the image
			borders.

All image points are convolved with the filter mask. If an overflow or underflow occurs, the resulting gray value is clipped (to 0 or 255, respectively). The filter mask is contained in a file with the following structure: <Mask size> <Inverse weight of the mask> <Matrix> The first line contains the size of the filter mask, given as two numbers separated by white space (e.g., 3 3 for 3 x 3). Here, the first number defines the height of the filter mask, while the second number defines its width. The next line contains the inverse weight of the mask, i.e., the number by which the convolution of a particular image point is divided. The remaining lines contain the filter mask as integer numbers (separated by white space), one line of the mask per line in the file. The file must have the extension ``.fil''. This extension must not be passed to the operator.

Parameters

`Image` (input_object)	(multichannel-)image(-array) `->` Hobject: HImage(Array) ( byte )
Image to be convolved.

`ImageResult` (output_object)	multichannel-image(-array) `->` Hobject : HImage(Array)* ( byte )
Convolved result image.

`FileName` (input_control)	string `->` HTuple.char *
Name of the file containing the filter mask.
Default value: 'filter'

`Margin` (input_control)	integer `->` HTuple.long
Border treatment: 0...255 (constant), -1 (continue border's gray value), -2 (continue cyclically), -3 (mirror gray values).
Default value: -3
Typical range of values: `-3 <= Margin <= 255`

Module

Image filters