vision.TemplateMatcher System object

Description

The template matcher object locates a template in an image.
Use the step syntax below with input image I,
template T, template matcher object, H,
and any optional properties.

LOC = step(H,I,T) computes
the [x y] location coordinates, LOC, of the best
template match between the image matrix, I,
and the template matrix, T. The step method
outputs the coordinates relative to the top left corner of the image.
The LOC [x y] coordinates correspond to the center
of the template. The object centers the location slightly different
for templates with an odd or even number of pixels, (see the table
below for details). The object computes the location by shifting the
template in single-pixel increments throughout the interior of the
image.

METRIC = step(H,I,T) computes
the match metric values for input image, I,
with T as the template. This applies when you
set the OutputValue property to Metric matrix.

LOC = step(H,I,T,ROI) computes
the location of the best template match, LOC, in
the specified region of interest, ROI. This
applies when you set the OutputValue property to Best
match location and the ROIInputPort property
to true. The input ROI must
be a four element vector, [x y width height], where the first two
elements represent the [x y] coordinates of the upper-left corner
of the rectangular ROI.

[LOC,ROIVALID] = step(H,I,T,ROI) computes
the location of the best template match, LOC, in
the specified region of interest, ROI. The
step method also returns a logical flag ROIVALID indicating
if the specified ROI is outside the bounds
of the input image I. This applies when you
set the OutputValue property to Best match
location, and both the ROIInputPort and ROIValidityOutputPort properties
to true.

[LOC,NVALS,NVALID] = step(H,I,T) returns
the location of the best template match LOC, the
metric values around the best match NVALS,
and a logical flag NVALID. A false value
for NVALID indicates that the neighborhood
around the best match extended outside the borders of the metric value
matrix NVALS. This applies when you set the OutputValue property
to Best match location and the BestMatchNeighborhoodOutputPort property
to true.

[LOC,NVALS,NVALID,ROIVALID] = step(H,I,T,ROI) returns
the location of the best template match LOC, the
metric values around the best match NVALS,
and two logical flags, NVALID and ROIVALID.
A false value for NVALID indicates
that the neighborhood around the best match extended outside the borders
of the metric value matrix NVALS. A false value
for ROIVALID indicates that the specified ROI is
outside the bounds of the input image I. This
applies when you set the OutputValue property to Best
match location, and the BestMatchNeighborhoodOutputPort, ROIInputPort,
and ROIValidityOutputPort properties to true.

The object outputs the best match coordinates, relative to the
top-left corner of the image. The [x y] coordinates of the location
correspond to the center of the template. When you use a template
with an odd number of pixels, the object uses the center of the template.
When you use a template with an even number of pixels, the object
uses the centered upper-left pixel for the location. The following
table shows how the block outputs the location (LOC),
of odd and even templates:

Odd number of pixels in template

Even number of pixels in template

Construction

H = vision.TemplateMatcher returns
a template matcher System object, H. This object
performs template matching by shifting a template in single-pixel
increments throughout the interior of an image.

H = vision.TemplateMatcher(Name,Value) returns
a template matcher object, H, with each specified
property set to the specified value.

Properties

Specify the metric to use for template matching as one of Sum of absolute differences | Sum of squared differences | Maximum absolute difference. The default
is Sum of absolute differences.

OutputValue

Type of output

Specify the output you want the object to return as one of Metric matrix | Best
match location. The default is Best
match location.

SearchMethod

Specify search criteria to find minimum difference between two
inputs

Specify how the object searches for the minimum difference between
the two input matrices as Exhaustive or Three-step. If you set this property to Exhaustive, the object searches for the
minimum difference pixel by pixel. If you set this property to Three-step, the object searches for the
minimum difference using a steadily decreasing step size. The Three-step method is computationally less
expensive than the Exhaustive method,
but sometimes does not find the optimal solution. This property applies
when you set the OutputValue property to Best match location.

The default is Exhaustive.

BestMatchNeighborhoodOutputPort

Enable metric values output

Set this property to true to return two outputs, NMETRIC and NVALID.
The output NMETRIC denotes an N-by-N matrix
of metric values around the best match, where N is
the value of the NeighborhoodSize property.
The output NVALID is a logical indicating whether
the object went beyond the metric matrix to construct output NMETRIC.
This property applies when you set the OutputValue property
to Best match location.

The default is false.

NeighborhoodSize

Size of the metric values

Specify the size, N, of the N-by-N matrix
of metric values as an odd number. For example, if the matrix size
is 3-by-3 set this property to 3. This property
applies when you set the OutputValue property
to Best match location and the BestMatchNeighborhoodOutputPort property
to true.

The default is 3.

ROIInputPort

Enable ROI specification through input

Set this property to true to define the Region
of Interest (ROI) over which to perform the template matching. If
you set this property to true, the ROI is specified
using an input to the step method. Otherwise the
entire input image is used.

The default is false.

ROIValidityOutputPort

Enable output of a flag indicating if any part of ROI is outside
input image

When you set this property to true, the object
returns an ROI flag. The flag, when set to false,
indicates a part of the ROI is outside of the input image. This property
applies when you set the ROIInputPort property
to true.

Specify the overflow action as one of Wrap |
Saturate. The default is Wrap.

ProductDataType

Product word and fraction lengths

Specify the product fixed-point data type as Same as first input, Custom. This property applies when you set
the Metric property
to Sum of squared differences.

The default is Custom.

CustomProductDataType

Product word and fraction lengths

Specify the product fixed-point type as a scaled numerictype object with a Signedness of Auto.
This property applies when you set the Metric property
to Sum of squared differences,
and the ProductDataType property
to Custom.

The default is numerictype([],32,30).

AccumulatorDataType

Accumulator word and fraction lengths

Specify the accumulator fixed-point data type as one of Same
as first input | Custom.
The default is Custom.

CustomAccumulatorDataType

Accumulator word and fraction lengths

Specify the accumulator fixed-point type as a scaled numerictype object with a Signedness of Auto.
This property applies when you set the AccumulatorDataType property
to Custom.

The default is numerictype([],32,0).

OutputDataType

Output word and fraction lengths

Specify the output fixed-point data type as one of Same as first input | Custom.
The default is Same as first input.This property
applies when you set the OutputValue property
to Metric matrix. This property
applies when you set the OutputValue property
to Best match location, and the BestMatchNeighborhoodOutputPort property
to true.

CustomOutputDataType

Output word and fraction lengths

Specify the output fixed-point type as a scaled numerictype object with a Signedness of Auto.
This property applies when you set the OutputDataType property
to Custom.