Main Content

vision.TemplateMatcher

Locate template in image

expand all in page

Description

To locate a template in an image.

  1. Create thevision.TemplateMatcherobject and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, seeWhat Are System Objects?

Creation

Syntax

tMatcher = vision.TemplateMatcher
tMatcher = vision.TemplateMatcher(名称、值)

Description

example

tMatcher=愿景。TemplateMatcherreturns a template matcher object,tMatcher. This object performs template matching by shifting a template in single-pixel increments throughout the interior of an image.

tMatcher=愿景。TemplateMatcher(Name,Value)sets properties using one or more name-value pairs. Enclose each property name in quotes. For example,tMatcher = vision.TemplateMatcher('Metric','Sum of absolute differences')

道具erties

expand all

Unless otherwise indicated, properties arenontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and thereleasefunction unlocks them.

If a property istunable, you can change its value at any time.

For more information on changing property values, seeSystem Design in MATLAB Using System Objects.

Metric used for template matching, specified as'Sum of absolute differences','Sum of squared differences', or'Maximum absolute difference'.

Type of output, specified as'Metric matrix'or'Best match location'.

Specify search criteria to find minimum difference between two inputs, specified 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'方法在计算上更便宜的比'Exhaustive'method, but sometimes does not find the optimal solution. This property applies when you set theOutputValueproperty to'Best match location'.

Enable metric values output, specified astrueorfalse. This property applies when you set theOutputValueproperty to'Best match location'.

Size of the metric values, specified as an odd number. The sizeN, of theN-by-Nmatrix of metric values as an odd number. For example, if the matrix size is 3-by-3 set this property to3. This property applies when you set theOutputValueproperty to'Best match location'and theBestMatchNeighborhoodOutputPortproperty totrue.

Enable ROI specification through input, specified astrueorfalse. Set this property totrueto define the Region of Interest (ROI) over which to perform the template matching. If you set this property totrue, the ROI must be specified. Otherwise the entire input image is used.

Enable output of a flag indicating if any part of ROI is outside input image, specified astrueorfalse. When you set this property totrue, the object returns an ROI flag. The flag, when set tofalse, indicates a part of the ROI is outside of the input image. This property applies when you set theROIInputPortproperty totrue

Fixed-Point Properties

Rounding method for fixed-point operations, specified as'Floor','Ceiling','Convergent','Nearest','Round','Simplest', or'Zero'.

Action to take when integer input is out-of-range, specified as'Wrap'or'Saturate'.

Product data type, specified as'Same as input'or'Custom'.

Product word and fraction lengths, specified as a scalednumerictype(Fixed-Point Designer)object. This property applies only when you set theAccumulatorDataTypeproperty to'Custom'.

Data type of accumulator, specified as'Same as product','Same as input', or'Custom'.

Accumulator word and fraction lengths, specified as a scalednumerictype(Fixed-Point Designer)object. This property applies only when you set theAccumulatorDataTypeproperty to'Custom'.

Usage

Syntax

location = tMatcher(I,T)
[location,numberOfValues,numValid] = tMatcher(I,T,ROI)
[location,numberOfValues,numValid,ROIvalid] = tMatcher(I,T,ROI)
[location,ROIvalid] = tMatcher(I,T,ROI)

Description

example

location= tMatcher(I,T)returns the [xy] location coordinates of the best template match relative to the top left corner of the image between the image matrix,I, and the template matrix,T. The object computes the location by shifting the template in single-pixel increments throughout the interior of the image.

[location,numberOfValues,numValid] = tMatcher(I,T,ROI)returns the location of the best template matchlocation, the metric values around the best matchnumberOfValues, and a logical flagnumValid. This applies when you set theOutputValueproperty to'Best match location'and theBestMatchNeighborhoodOutputPortproperty totrue.

[location,numberOfValues,numValid,ROIvalid] = tMatcher(I,T,ROI)also returns a logical flag,ROIvalidto indicate whether theROIis outside the bounds of the input imageI. This applies when you set theOutputValueproperty to'Best match location', and theBestMatchNeighborhoodOutputPort,ROIInputPort, andROIValidityOutputPortproperties totrue.

[location,ROIvalid] = tMatcher(I,T,ROI)also returns a logical flagROIvalidindicating if the specifiedROIis outside the bounds of the input imageI. This applies when you set theOutputValueproperty to'Best match location', and both theROIInputPortandROIValidityOutputPortproperties totrue.

Input Arguments

expand all

Input image, specified as either a 2-D grayscale or truecolor image.

Input template, specified as 2-D grayscale or truecolor image.

Input ROI, specified as a four-element vector, [xywidthheight], where the first two elements represent the coordinates of the upper-left corner of the rectangular ROI.

Output Arguments

expand all

Location of best template match, returned as a vector in the format (x,y). The coordinates indicate the center of the template relative to the top-left corner of the image. For more details, seeAlgorithms

Metric value matrix , returned as a matrix. Afalsevalue fornumValidindicates that the neighborhood around the best match extended outside the borders of the metric value matrixnumberOfValues.

Valid neighborhood, returned astrueorfalse. Afalsevalue fornumValidindicates that the neighborhood around the best match extended outside the borders of the metric value matrixnumberOfValues.

Valid ROI neighborhood, returned astrueorfalse. Afalsevalue forROIvalidindicates that the ROI is outside the bounds of the input image.

Object Functions

To use an object function, specify the System object™ as the first input argument. For example, to release system resources of a System object namedobj, use this syntax:

release(obj)

expand all

step RunSystem objectalgorithm
release Release resources and allow changes toSystem objectproperty values and input characteristics
reset Reset internal states ofSystem object

Examples

collapse all

Open Script

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.文件名='shaky_car.avi'; hVideoSource = VideoReader(filename);

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 cornerpos.template_size = [22 18];% [width height]pos.search_border = [15 10];% max horizontal and vertical displacementpos.template_center = floor((pos.template_size-1)/2); pos.template_center_pos = (pos.template_orig + pos.template_center - 1); W = hVideoSource.Width;% Width in pixelsH = hVideoSource.Height;% Height in pixelsBorderCols = [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 = [W, H]; 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.

whilehasFrame(hVideoSource) input = rgb2gray(im2double(readFrame(hVideoSource)));% Find location of Target in the input video frameiffirstTime Idx = int32(pos.template_center_pos); MotionVector = [0 0]; firstTime = false;elseIdxPrev = Idx; ROI = [SearchRegion, pos.template_size+2*pos.search_border]; Idx = hTM(input,Target,ROI); MotionVector = double(Idx-IdxPrev);end[Offset, SearchRegion] = updatesearch(sz, MotionVector,...SearchRegion, Offset, pos);% Translate video frame to offset the camera motionStabilized = imtranslate(input, Offset,'linear'); Target = Stabilized(TargetRowIndices, TargetColIndices);% Add black border for displayStabilized(:, 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 regioninput = insertShape(input,'Rectangle', [TargetRect; SearchRegionRect],...'Color','white');% Display the offset (displacement) values on the input imagetxt = sprintf('(%+05.1f,%+05.1f)', Offset); input = insertText(input(:,:,1),[191 215],txt,'FontSize',16,...'TextColor','white','BoxOpacity', 0);% Display videohVideoOut([input(:,:,1) Stabilized]);end

Conclusion

Using the Computer Vision 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

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 [xy] 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 template Even number of pixels in template

Extended Capabilities

Version History

Introduced in R2012a

See Also

||||