Locate a template in an image
Computer Vision Toolbox / Analysis & Enhancement
The Template Matching block finds the best match of a template within an input image. The block computes match metric values by shifting a template over a region of interest or the entire image, and then finds the best match location.
The block outputs either the match metric values or the onebased (x,y) coordinates of the best template match. Optionally the lbock can output an NbyN matrix of the match metric values centered around the best match location.
I
— ImageInput image to use with the template. The block does not pad the input data. Therefore, it can only compute values for the match metrics between the input image and the template, where the template is positioned such that it falls entirely on the input image. A set of all such positions of the template is termed as the valid region of the input image. The size of the valid region is the difference between the sizes of the input and template images plus one.
size_{valid}=size_{input} – size_{template}+1  (1) 
Data Types: single
 double
 int8
 int16
 int32
 uint8
 uint16
 uint32
 Boolean
 fixed point
T
— TemplateTemplate, specified as an MbyN matrix
The Template Matching block does not pad the input data. Therefore, it can only compute values for the match metrics between the input image and the template, where the template is positioned such that it falls entirely on the input image. A set of all such positions of the template is termed as the valid region of the input image. The size of the valid region is the difference between the sizes of the input and template images plus one.
size_{valid}=size_{input} – size_{template}+1  (2) 
Data Types: single
 double
 uint8
 Boolean
 fixed point
ROI
— Region of interestRegion of interest vector in the format (x,y,width,height), where (x,y) are onebased coordinates for the upperleft corner of the region. The block outputs the best match location index relative to the top left corner of the input image.
Data Types: single
 double
 uint8
 Boolean
 fixed point
Metric
— Match metric valuesMatrix of match metric values. The matrix of the match metrics always implements singlestep exhaustive window iteration. Therefore, the block computes the metric values at every pixel.
When you set the Output parameter to Metric
matrix
, the block outputs the valid image size.
Data Types: single
 double
 uint8
 Boolean
 fixed point
Loc
— Best match locationsBest template match located at the onebased (x,y) coordinates. When in the ROI processing mode, the block treats the image around the ROI as an extension of the ROI subregion. Therefore, it computes the best match locations true to the actual boundaries of the ROI. The block outputs the best match coordinates, relative to the topleft corner of the image. The onebased [x y] coordinates of the location correspond to the center of the template. The following table shows how the block outputs the center coordinates for odd and even templates:
Odd number of pixels in template  Even number of pixels in template 

Data Types: uint32
NMetric
— Metric values in neighborhood of best matchMetric values in the neighborhood of the best match, returned as an NbyN matrix. N, specified in the mask, must be an odd number. When you select Best match location to return the matrix of metrics in a neighborhood around the best match, an exhaustive loop computes all the metric values for the NbyN neighborhood. This output is particularly useful for performing template matching with subpixel accuracy.
Data Types: single
 double
 uint8
 Boolean
 fixed point
NValid
— Valid neighborhoodEnable to track the valid neighborhood region. The neighborhood matrix of metric values is valid inside of the ROI. The block sets the NValid output as follows:
1
— The neighborhood containing the best match is
completely inside the region of interest.
0
— The neighborhood containing the best match is
completely or partially outside of the region of interest.
This port appears when you enable the Output NxN matrix of metric values around best match parameter.
Data Types: Boolean
ROIValid
— Valid region of interestEnable to track the valid region of interest. If the ROI lies partially outside the valid image, the block only processes the intersection of the ROI and the valid image. The block sets the ROIValid output as follows:
1
— The ROI lies completely inside the valid part of the
input image.
0
— The ROI lies completely or partially outside of the
valid part of the input image.
This port appears when you enable the Output flag indicating if ROI is valid parameter.
Data Types: Boolean
Main Tab
Match metric
— Match metricSum of absolute differences
(default)  Sum of squared differences
 Maximum absolute difference
Select match metric as one of:
Sum of absolute differences
(SAD)
Sum of squared differences
(SSD)
Maximum absolute difference
(MaxAD)
The block computes the match metric at each step of the iteration. Choose the match metric that best suits your application. The block calculates the global optimum for the best metric value. It uses the valid subregion of the input image intersected by the ROI, if provided.
Output
— Match metricMatch metric
(default)  Best match location
Select the type of output as one of:
Match metric
— Output the match metric matrix. This
option adds the Metric output port to the block.
Best match location
— Output the
[x,y] coordinates for the location of the
best match. This option adds the Loc output port to the
block. It also makes the Search method, Output NxN
matrix of metric values around best match, and Enable ROI
processing parameters available.
The Output parameter on the Data Types pane appears when
you set the Output parameter on the Main
tab to Metric matrix
or if you set it to
Best match location
and you enable the
Output NxN matrix of metric values around best match
parameter.
Search method
— Search methodExhaustive
(default)  Threestep
Specify the search method as either Exhaustive
or
Threestep
. The Exhaustive
search method is computationally intensive because it searches at every pixel location
of the image. However, this method provides a more precise result.
The Threestep
search method is a fast search that uses a
neighborhood approach versus a search at every pixel. The search starts with a step size
equal to or slightly greater than half of the maximum search range and then employs the
following steps:
The block compares nine search points in each step. There is a central point and eight search points located on the search area boundary.
The block decrements the step size by one, after each step, ending the search with a step size of one pixel.
At each new step, the block moves the search center to the best matching point resulting from the previous step. The number one blue circles in the figure below represent a search with a starting step size of three. The number two green circles represent the next search, with step size of two, centered around the best match found from the previous search. Finally, the number three orange circles represent the final search, with step size of one, centered around the previous best match.
This parameter appears when you set the Output parameter to
Best match location
.
Output NxN matrix of metric values around best match
— Output NbyN matrix Enable to add the NMetric and NValid ports.
This parameter appears when you set the Output parameter to
Best match location
.
N
— Size of output matrix3
(default)  integerSize of output matrix. This value determines the size of the NbyN output matrix centered around the best match location index. N must be an odd number.
This parameter appears when you enable the Output NxN matrix of metric values around best match parameter.
Enable ROI processing
— Enable ROI processingEnable ROI processing.
This parameter appears when you set the Output parameter
to Best match location
.
When you enable this parameter, the block adds the ROI input port, and the Output flag indicating if ROI is valid parameter appears.
Output flag indicating if ROI is valid
— Valid ROIEnable to add the ROIValid port.
This parameter appears when you enable the Enable ROI processing parameter.
Data Types Tab
For details on the fixedpoint block parameters, see Specify FixedPoint Attributes for Blocks .
Data Types 

Multidimensional Signals 

VariableSize Signals 

The match metrics use a difference equation with general form:
$${d}_{p}(x,y)=({\displaystyle \sum _{i=1}^{n}{\left{x}_{i}{y}_{i}\right}^{p}{)}^{\raisebox{1ex}{$1$}\!\left/ \!\raisebox{1ex}{$p$}\right.}}$$
$${l}_{n}^{p}$$ denotes the metric space $$({R}^{n},{d}_{p})$$ for $${R}^{n}$$
n > 1
.
The SAD metric is also known as the Taxicab or Manhattan Distance metric. It sums the absolute values of the differences between pixels in the original image and the corresponding pixels in the template image. This metric is the $${l}^{1}$$ norm of the difference image. The lowest SAD score estimates the best position of template within the search image. The general SAD distance metric becomes:
$${d}_{1}({I}_{j},T)={\displaystyle \sum _{i=1}^{n}\left{I}_{i,j}{T}_{i}\right}$$
The SSD metric is also known as the Euclidean Distance metric. It sums the square of the absolute differences between pixels in the original image and the corresponding pixels in the template image. This metric is the square of the $${l}^{2}$$ norm of the difference image. The general SSD distance metric becomes:
$${d}_{2}({I}_{j},T)={\displaystyle \sum _{i=1}^{n}{\left{I}_{i,j}{T}_{i}\right}^{2}}$$
The MaxAD metric is also known as the Uniform Distance metric. It sums the maximum of absolute values of the differences between pixels in the original image and the corresponding pixels in the template image. This distance metric provides the $${l}^{\infty}$$ norm of the difference image. The general MaxAD distance metric becomes:
$${d}_{\infty}({I}_{j},T)=\underset{x\to \infty}{\mathrm{lim}}{\displaystyle \sum _{i=1}^{n}{\left{I}_{i,j}{T}_{i}\right}^{p}}$$
which simplifies to:
$${d}_{\infty}({I}_{j},T)=\underset{i}{\overset{n}{\mathrm{max}}}{\left{I}_{i,j}{T}_{i}\right}^{p}$$
[1] Koga T., et. Al. Motioncompensated interframe coding for video conferencing. In National Telecommunications Conference. Nov. 1981, G5.3.1–5, New Orleans, LA.
[2] Zakai M., “General distance criteria” IEEE Transaction on Information Theory, pp. 94–95, January 1964.
[3] Yu, J., J. Amores, N. Sebe, Q. Tian, "A New Study on Distance Metrics as Similarity Measurement" IEEE International Conference on Multimedia and Expo, 2006 .
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
Select web siteYou can also select a web site from the following list:
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.