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