Documentation Center

  • Trial Software
  • Product Updates

vision.TemplateMatcher System object

Package: vision

Locate template in image

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 templateEven 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.

Code Generation Support
Supports MATLAB® Function block: Yes
System Objects in MATLAB Code Generation.
Code Generation Support, Usage Notes, and Limitations.

Properties

Metric

Metric used for template matching

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.

The default isfalse.

 Fixed-Point Properties

Methods

cloneCreate template matcher object with same property values
getNumInputsNumber of expected inputs to step method
getNumOutputsNumber of outputs from step method
isLockedLocked status for input attributes and nontunable properties
release Allow property value and input characteristics changes
stepFinds the best template match within image

Examples

Find the location of a particular chip on an image of an electronic board:

 htm=vision.TemplateMatcher;
 hmi = vision.MarkerInserter('Size', 10, ...
    'Fill', true, 'FillColor', 'White', 'Opacity', 0.75); I = imread('board.tif');

% Input image
  I = I(1:200,1:200,:); 

% Use grayscale data for the search
  Igray = rgb2gray(I);     

% Use a second similar chip as the template
  T = Igray(20:75,90:135) 

% Find the [x y] coordinates of the chip's center
  Loc=step(htm,Igray,T);  

% Mark the location on the image using white disc
  J = step(hmi, I, Loc);

imshow(T); title('Template');
figure; imshow(J); title('Marked target');

Algorithms

This object implements the algorithm, inputs, and outputs described on the Template Matching block reference page. The object properties correspond to the block parameters.

See Also

|

Was this topic helpful?