Template Matching
Locate a template in an image
Libraries:
Computer Vision Toolbox /
Analysis & Enhancement
Description
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 block can output an NbyN matrix of the match metric values centered around the best match location.
Examples
Find Location of Object in Image Using Template Matching
Read the reference image and the template image into the MATLAB workspace.
Ports
Input
I — Image
image
Input 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
 int64
 uint8
 uint16
 uint32
 uint64
 Boolean
 fixed point
T — Template
MbyN matrix
Template, 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 interest
fourelement vector
Region 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
Output
Metric — Match metric values
matrix
Matrix 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.
Dependencies
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 locations
twoelement vector
Best 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 match
NbyN matrix
Metric 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 neighborhood
off  on
Enable 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.
Dependencies
This port appears when you enable the Output NxN matrix of metric values around best match parameter.
Data Types: Boolean
ROIValid — Valid region of interest
off  on
Enable 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.
Dependencies
This port appears when you enable the Output flag indicating if ROI is valid parameter.
Data Types: Boolean
Parameters
Main Tab
Match metric — Match metric
Sum 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 metric
Match 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 toBest match location
and you enable the Output NxN matrix of metric values around best match parameter.
Search method — Search method
Exhaustive
(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.
Dependencies
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
on (default)  off
Enable to add the NMetric and NValid ports.
Dependencies
This parameter appears when you set the Output parameter to
Best match location
.
N — Size of output matrix
3
(default)  integer
Size 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.
Dependencies
This parameter appears when you enable the Output NxN matrix of metric values around best match parameter.
Enable ROI processing — Enable ROI processing
on (default)  off
Enable ROI processing.
Dependencies
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 ROI
off (default)  on
Enable to add the ROIValid port.
Dependencies
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 (DSP System Toolbox).
Block Characteristics
Data Types 

Multidimensional Signals 

VariableSize Signals 

Algorithms
Match Metrics
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
.
Sum of Absolute Differences (SAD)
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}$$
Sum of Squared Differences (SSD)
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}}$$
Maximum Absolute Difference (MaxAD)
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}$$
References
[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.
Extended Capabilities
C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.
FixedPoint Conversion
Design and simulate fixedpoint systems using FixedPoint Designer™.
Version History
Introduced in R2009b
MATLAB Command
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.
Select a Web Site
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: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)