STScI Logo

convolve images.imfilter


NAME · USAGE · PARAMETERS · DESCRIPTION · EXAMPLES · TIME_REQUIREMENTS
BUGS · SEE_ALSO

NAME

convolve -- convolve an image with an arbitrary rectangular kernel

USAGE

convolve input output kernel

PARAMETERS

input
List of images to be convolved with the rectangular kernel.
output
List of output images. The number of output images must equal the number of input images. If the input image name equals the output image name the convolved image will replace the input image.
kernel
A text file name or a string listing the 2D kernel elements. The kernel elements are separated by whitespace or commas and the kernel rows are delimited by row_delimiter . In string entry mode the elements are assumed to be in row order. In text file entry mode the last row of the kernel is the first row of the text file. Kernel is requested if bilinear is "no".
xkernel
A text file or string containing the 1D x dimension component of the bilinear convolution kernel. The kernel elements are separated by whitespace or commas. Xkernel is requested if bilinear is "yes".
ykernel
A text file or string containing the 1D y dimension component of the bilinear convolution kernel. The kernel elements are separated by whitespace or commas. Ykernel is requested if bilinear is "yes".
bilinear
Is the convolution kernel bilinear? If bilinear is yes, then the full 2D convolution kernel kernel can be expressed as two independent 1D convolutions xkernel and ykernel , and a more efficient convolution algorithm is used.
radsym = no
Is the convolution kernel radially symmetric? If radsym "yes", a more efficient convolution algorithm is used.
boundary = "nearest"
The algorithm used to compute the values of the out of bounds pixels. The options are:
nearest
Use the value of the nearest boundary pixel.
constant
Use a constant value.
reflect
Generate a value by reflecting around the boundary.
wrap
Generate a value by wrapping around to the opposite side of the image.
constant = 0.
The constant for constant-valued boundary extension.
row_delimiter = ";"
The row delimiter character for multi-row kernels.

DESCRIPTION

CONVOLVE convolves the list of images specified by input with an arbitrary user supplied rectangular kernel kernel (if bilinear is "no") or two equivalent 1D kernels xkernel and ykernel (if bilinear is "yes") and places the convolved images in output . Out of bounds pixels are computed using the algorithm specified by boundary .

Kernel or alternatively xkernel and ykernel is either a text file name or a short string listing the kernel elements. The kernel elements are separated by whitespace or commas and the kernel rows are delimited by the character row_delimiter . In string entry mode the elements are assumed to be in row order. In text file entry mode the last row of the kernel is the the first row of the text file.

The parameters bilinear and radsym can be used to greatly speed up the convolution task for convolution kernels which have the appropriate mathemetical form. Bilinear convolution kernels are those which define a function which is mathematically separable in the x and y dimension. In this case convolving each line of the input image with xkernel and then convolving each column of this intermediate image with ykernel , is operationally equivalent to convolving each point in the entire image with the full 2D kernel kernel . Radially symmetric kernels are those which are symmetric about some central point.

EXAMPLES

Examples 1 and 2 use the following kernel where -1 is element 1 of row 1.

	          1.  1.  1.
	 kernel = 0.  0.  0.
	         -1. -1. -1.

1. Convolve an image with the above kernel using string entry mode and wrap around boundary extension.

    cl> convolve m82 m82.cnv "-1. -1. -1.; 0. 0. 0.; 1. 1. 1." bound=wrap

2. Type the contents of the kernel file fdy on the terminal. Convolve an image with the kernel in fdy using nearest neighbour boundary extension.

    cl> type fdy

        1. 1. 1.;
        0. 0. 0.;
        -1. -1. -1.;

    cl> convolve m74 m74.cnv fdy

Example 3 uses the following bilinear kernel, where x# and y# are elements of xkernel and ykernel respectively.

	xkernel = .2500  .5000  .2500

	ykernel = .2500  .5000  .2500

		  .0625  .1250  .0625      y1*x1  y1*x2  y1*x3
	 kernel = .1250  .2500  .1250   =  y2*x1  y2*x2  y2*x3
	          .0625  .1250  .0625      y3*x1  y3*x2  y3*x3

3. Convolve an image with the full 2D kernel kernel and with the the equivalent 1D kernels xkernel and ykernel and compare the results.

    cl> convolve m92 m92.1 kernel

    cl> convolve m92 m92.2 xkernel ykernel bilinear+

    cl> imarith m92.1 - m92.2 diff

TIME REQUIREMENTS

CONVOLVE requires approximately 30 and 8 cpu seconds to convolve a 512 square real image with 17 by 17 radially symmetric convolution kernel using the full 2D and bilinear kernels (if appropriate) respectively on a Sparc Station 1.

BUGS

SEE ALSO

gauss, laplace, gradient, boxcar


Source Code · Search Form · STSDAS