IPCONVOL Function
Performs 1D, 2D, or 3D convolution on signals, images, and volumes.
Usage
result = IPCONVOL(image, kernel[, scale_factor])
Input Parameters
image—A 1D, 2D, or 3D array of any data type except string or complex that contains a signal; point or signal-interleaved signals; an image; image, row or pixel interleaved images; or a volume.
kernel—The array used to convolve each value in image. This parameter can be of any data type except string. The kernel parameter can also be a spatial filter object. (See the Returned Value description for the IPREAD_FILTER Function for information about the filter spatial object.) The dimensions of kernel must be less than the dimensions of image.
scale_factor—(optional) A scale factor used to reduce the size of the output result by scaling the weighting factors in the filter kernel. This parameter is ignored if kernel is a filter object.
Returned Value
result—An array of the same dimensions and size as image; however, the size of the array may be affected by using the Edge keyword, or the scale_factor parameter.
Keywords
Edge—A scalar string indicating how edge effects are handled. (Default: 'zero') Valid strings are:
'pad'—The input image is padded before the filtering operation with the value specified using the Pad_Value keyword.'zero'—Sets the border of the output image to zero. (Default)'copy'—Copies the border of the input image to the output image.'reduce'—Returns a reduced-size image that is smaller than the input image by the kernel dimensions.Intleave—A scalar string indicating the type of interleaving of 2D input signals and 3D image arrays. Valid strings and the corresponding interleaving methods are:
'point'—The 2D input array arrangement is (p, x) for p point-interleaved signals of length x.'signal'—The 2D input image array arrangement is (x, p) for p signal-interleaved signals of length x.'pixel'—The input array arrangement is (p, x, y) for p pixel-interleaved images of x-by-y.'row'—The 3D image array arrangement is (x, p, y) for p row-interleaved images of x-by-y.'image'—The 3D image array arrangement is (x, y, p) for p image-interleaved images of x-by-y.'volume'—The input image array is treated as a single entity.No_Clip—If set, clipping is avoided by setting the output image type large enough to contain the maximum of the two combined images.
note | The No_Clip keyword prevents underflow or overflow conditions from occurring. |
No_Mirror—If set, the kernel is not mirrored for the convolution operation. (Default: kernel mirrored before convolution)
Pad_Value—The value to use for the image padding. (Default: 0)
note | The Pad_Value keyword is only valid when Edge = 'pad'. |
Spot—This keyword specifies explicit positioning of the element number of the filter window “sweet spot.” The Spot keyword default depends on the setting of the Edge keyword as shown in Table 10-1: Edge and Spot Keywords Relationships.
Zero_Negatives—If set, all negative values in the result image are set to zero.
Discussion
Convolution is a general purpose method used for smoothing and blurring an image, as well as edge detection, shifting, and other filtering functions. Convolution is often performed in conjunction with other image processing functions such as the FILT_NONLIN and FILT_SMOOTH functions.
note | Equations describing the convolution process can be found in the CONVOL function description in the PV‑WAVE Reference. |
The kernel parameter can be either a filter object (see the Returned Value description for the IPREAD_FILTER Function for information about the filter object) or an array. The dimensions of the filter kernel describe the size of the neighborhood surrounding each value in image that is analyzed. The filter kernel also includes weighting values for each point in the array. These weighting values are used to determine the average value returned in the result array.
When kernel is a filter object, the scale_factor parameter is not used; however, there is a scale factor key in the kernel associative array. A typical use of the scale_factor parameter is to set it equal to the sum of the filter kernel values. In this way, the amplitude gain of the filter is normalized to 1.0.
In many image processing applications, the kernel “sweet spot,” that is, the positioning of the filter kernel with respect to the underlying image pixels, is important. The Spot keyword allows exact positioning of the filter kernel as it is convolved with the image pixels, and is typically located at the center of the filter kernel. Other commonly used kernel sweet spots are the first element or the last element of the kernel array.
Controlling edge effects is important in many image processing applications as well, and this can be accomplished by specifying a control method with the Edge keyword. Edge effects occur where the filter kernel array “overhangs” the image. Two methods most commonly used to deal with edge effect behavior are copying the input image edges to the result image, or zeroing the edges of the result image: accomplished with the 'copy' and 'zero' strings, respectively, for the Edge keyword. Padding the input image before convolution and reducing the size of the result image are other methods for edge effects. These methods are accomplished with the 'pad' and 'reduce' strings, respectively, for the Edge keyword.
The filter kernel array is always mirrored before the convolution operation. To disable this behavior, use the No_Mirror keyword.
Example
; Read in an image.
image = IMAGE_READ(!IP_Data + 'dollars.tif')
; Read in a filter kernel for edge detection.
kernel = IPREAD_FILTER(!IP_Data + 'kernel/kirsch_sw3.ker')
; Apply the kernel, with a sweet spot in the upper left
; corner. Reduce the output image, getting rid of edge effects.
edge_image = IPCONVOL(image('pixels'), kernel, $
Spot = 0, Edge = 'reduce'); Display the edge-enhanced image.
TVSCL, edge_image
See Also
