Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

vision.TemplateMatcher System object

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.

Typical use of the template matcher involves finding a small region within a larger image. The region is specified by the template image which can be as large as the input image, but which is typically smaller than the input image.

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 object outputs the location (LOC), of odd and even templates:

Odd number of pixels in templateEven number of pixels in template

Note

Starting in R2016b, instead of using the step method to perform the operation defined by the System object™, you can call the object with arguments, as if it were a function. For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

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

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

stepFinds the best template match within image
Common to All System Objects
clone

Create System object with same property values

getNumInputs

Expected number of inputs to a System object

getNumOutputs

Expected number of outputs of a System object

isLocked

Check locked states of a System object (logical)

release

Allow System object property value changes

Examples

expand all

This example shows how to remove the effect of camera motion from a video stream.

Introduction

In this example we first define the target to track. In this case, it is the back of a car and the license plate. We also establish a dynamic search region, whose position is determined by the last known target location. We then search for the target only within this search region, which reduces the number of computations required to find the target. In each subsequent video frame, we determine how much the target has moved relative to the previous frame. We use this information to remove unwanted translational camera motions and generate a stabilized video.

Initialization

Create a System object™ to read video from a multimedia file. We set the output to be of intensity only video.

% Input video file which needs to be stabilized.
filename = 'shaky_car.avi';

hVideoSource = vision.VideoFileReader(filename, ...
                                      'ImageColorSpace', 'Intensity',...
                                      'VideoOutputDataType', 'double');

Create a template matcher System object to compute the location of the best match of the target in the video frame. We use this location to find translation between successive video frames.

hTM = vision.TemplateMatcher('ROIInputPort', true, ...
                            'BestMatchNeighborhoodOutputPort', true);

Create a System object to display the original video and the stabilized video.

hVideoOut = vision.VideoPlayer('Name', 'Video Stabilization');
hVideoOut.Position(1) = round(0.4*hVideoOut.Position(1));
hVideoOut.Position(2) = round(1.5*(hVideoOut.Position(2)));
hVideoOut.Position(3:4) = [650 350];

Here we initialize some variables used in the processing loop.

pos.template_orig = [109 100]; % [x y] upper left corner
pos.template_size = [22 18];   % [width height]
pos.search_border = [15 10];   % max horizontal and vertical displacement
pos.template_center = floor((pos.template_size-1)/2);
pos.template_center_pos = (pos.template_orig + pos.template_center - 1);
fileInfo = info(hVideoSource);
W = fileInfo.VideoSize(1); % Width in pixels
H = fileInfo.VideoSize(2); % Height in pixels
BorderCols = [1:pos.search_border(1)+4 W-pos.search_border(1)+4:W];
BorderRows = [1:pos.search_border(2)+4 H-pos.search_border(2)+4:H];
sz = fileInfo.VideoSize;
TargetRowIndices = ...
  pos.template_orig(2)-1:pos.template_orig(2)+pos.template_size(2)-2;
TargetColIndices = ...
  pos.template_orig(1)-1:pos.template_orig(1)+pos.template_size(1)-2;
SearchRegion = pos.template_orig - pos.search_border - 1;
Offset = [0 0];
Target = zeros(18,22);
firstTime = true;

Stream Processing Loop

This is the main processing loop which uses the objects we instantiated above to stabilize the input video.

while ~isDone(hVideoSource)
    input = step(hVideoSource);

    % Find location of Target in the input video frame
    if firstTime
      Idx = int32(pos.template_center_pos);
      MotionVector = [0 0];
      firstTime = false;
    else
      IdxPrev = Idx;

      ROI = [SearchRegion, pos.template_size+2*pos.search_border];
      Idx = step(hTM, input, Target, ROI);

      MotionVector = double(Idx-IdxPrev);
    end

    [Offset, SearchRegion] = updatesearch(sz, MotionVector, ...
        SearchRegion, Offset, pos);

    % Translate video frame to offset the camera motion
    Stabilized = imtranslate(input, Offset, 'linear');

    Target = Stabilized(TargetRowIndices, TargetColIndices);

    % Add black border for display
    Stabilized(:, BorderCols) = 0;
    Stabilized(BorderRows, :) = 0;

    TargetRect = [pos.template_orig-Offset, pos.template_size];
    SearchRegionRect = [SearchRegion, pos.template_size + 2*pos.search_border];

    % Draw rectangles on input to show target and search region
    input = insertShape(input, 'Rectangle', [TargetRect; SearchRegionRect],...
                        'Color', 'white');
    % Display the offset (displacement) values on the input image
    txt = sprintf('(%+05.1f,%+05.1f)', Offset);
    input = insertText(input(:,:,1),[191 215],txt,'FontSize',16, ...
                    'TextColor', 'white', 'BoxOpacity', 0);
    % Display video
    step(hVideoOut, [input(:,:,1) Stabilized]);
end

Release

Here you call the release method on the objects to close any open files and devices.

release(hVideoSource);

Conclusion

Using the Computer Vision System Toolbox™ functionality from MATLAB® command line it is easy to implement complex systems like video stabilization.

Appendix

The following helper function is used in this example.

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.

Extended Capabilities

Introduced in R2012a