IPCORRELATE Function
Performs direct (spatial domain) or indirect (spatial frequency domain) correlation between an array and a template.
Usage
result = IPCORRELATE(image, template)
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.
template—A 1D, 2D, or 3D array of any data type except string containing the template used for correlation. The template parameter can also be a filter object. (See the IPREAD_FILTER Function for information about the filter objects.)
Returned Value
result—An array of the same dimensions and size as image, unless otherwise affected by use of the Edge keyword.
Keywords
Direct—If set, direct method correlation is performed in the spatial domain using convolution. For the direct method, the template parameter may be either an array or a spatial filter object (see the IPREAD_FILTER Function for more information on the spatial filter object associative array format).
Edge—A scalar string indicating how edge effects are handled. (Default: 'zero')
note | The Edge keyword is only valid when using the direct method. |
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. The No_Clip keyword is only valid when using the direct method. |
Pad_Value—The value to use for the image padding. (Default: 0)
note | The Pad_Value keyword is only valid when Edge = 'pad', and when using the direct method. |
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.
note | The Spot keyword is only valid when using the direct method. |
Zero_Negatives—If set, all negative values in the result image are set to zero.
Discussion
Correlation is often used for template matching in conjunction with other Image Processing Toolkit functions such as THRESHOLD to locate maxima in the correlation output. Correlation is computed in either the spatial or the frequency domain. The frequency domain computation is the default method for IPCORRELATE. This method is used most often, and performs correlation by first multiplying the FFT of the image with the conjugate of the FFT of the correlation template, and then taking the inverse of the result. The spatial domain computation, also called the direct method, performs correlation as the convolution operation without mirroring the filter kernel. The spatial domain computation is accomplished by using the Direct keyword in the calling sequence.
note | For equations describing the direct method correlation process, see CONVOL in the PV‑WAVE Reference. |
Example
image = IMAGE_READ(!IP_Data + 'vnitext.tif')
; Create a template for object recognition.
template = IMAGE_READ(!IP_Data + 'letter_n.tif')
; Correlate the image with the template.
corr_image = IPCORRELATE(image('pixels')/MAX(image('pixels'), $
template('pixels')/ MAX(image('pixels')))TVSCL, corr_image
; The maximum value in the correlation image corresponds
; to the location of the template in the image.
max_value = MAX(corr_image, object_loc)
PRINT, object_loc
See Also
In the PV‑WAVE Reference: CONVOL
