Operator Reference

HALCON Operator Reference / Filters / Match
ClassesClasses | | Operators

exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchexhaustive_match (Operator)

exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchexhaustive_match — Matching of a template and an image.

Signature

exhaustive_match(Image, RegionOfInterest, ImageTemplate : ImageMatch : Mode : )

Herror exhaustive_match(const Hobject Image, const Hobject RegionOfInterest, const Hobject ImageTemplate, Hobject* ImageMatch, const char* Mode)

Herror T_exhaustive_match(const Hobject Image, const Hobject RegionOfInterest, const Hobject ImageTemplate, Hobject* ImageMatch, const Htuple Mode)

void ExhaustiveMatch(const HObject& Image, const HObject& RegionOfInterest, const HObject& ImageTemplate, HObject* ImageMatch, const HTuple& Mode)

HImage HImage::ExhaustiveMatch(const HRegion& RegionOfInterest, const HImage& ImageTemplate, const HString& Mode) const

HImage HImage::ExhaustiveMatch(const HRegion& RegionOfInterest, const HImage& ImageTemplate, const char* Mode) const

HImage HImage::ExhaustiveMatch(const HRegion& RegionOfInterest, const HImage& ImageTemplate, const wchar_t* Mode) const   ( Windows only)

def exhaustive_match(image: HObject, region_of_interest: HObject, image_template: HObject, mode: str) -> HObject

Description

The operator exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchexhaustive_match matches ImageTemplateImageTemplateImageTemplateimageTemplateimage_template and ImageImageImageimageimage within the region of interest RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest. Hereby the ImageTemplateImageTemplateImageTemplateimageTemplateimage_template will be moved over all points of ImageImageImageimageimage which lie within the RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest. With regard to the parameter ModeModeModemodemode, a matching criterion will be calculated. The result values will be stored in ImageMatchImageMatchImageMatchimageMatchimage_match.

The following matching criteria (ModeModeModemodemode) are available:

'norm_correlation'

whereby indicates the gray value in the -th column and -th row of the image . is the center of the region of ImageTemplateImageTemplateImageTemplateimageTemplateimage_template. and are chosen so that all points of the template will be reached, run across the RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest. At the image frame only those parts of ImageTemplateImageTemplateImageTemplateimageTemplateimage_template will be considered which lie inside the image (i.e. and will be restricted correspondingly). Higher values returned in ImageMatchImageMatchImageMatchimageMatchimage_match, represent better matches.

Range of values: [0 ... 255 (best fit)].

'dfd'

Calculating the average “displaced frame difference”: The terms are the same as in 'norm_correlation'"norm_correlation""norm_correlation""norm_correlation""norm_correlation". means the area of the region . Lower values returned in ImageMatchImageMatchImageMatchimageMatchimage_match, represent better matches.

Range of values: [0 (best fit) .. 255].

To calculate the normalized correlation as well as the “displaced frame difference” is (with regard to the area of ImageTemplateImageTemplateImageTemplateimageTemplateimage_template) very time consuming. Therefore it is important to restrict the input region (RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest if possible, i.e. to apply the filter only in a very confined “region of interest”.

As far as quality is concerned, both modes return comparable results, whereby the mode 'dfd'"dfd""dfd""dfd""dfd" is faster by a factor of about 3.5.

Execution Information

  • Multithreading type: reentrant (runs in parallel with non-exclusive operators).
  • Multithreading scope: global (may be called from any thread).
  • Automatically parallelized on tuple level.
  • Automatically parallelized on internal data level.

Parameters

ImageImageImageimageimage (input_object)  singlechannelimage(-array) → objectHImageHObjectHObjectHobject (byte)

Input image.

RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest (input_object)  region → objectHRegionHObjectHObjectHobject

Area to be searched in the input image.

ImageTemplateImageTemplateImageTemplateimageTemplateimage_template (input_object)  singlechannelimage → objectHImageHObjectHObjectHobject (byte)

This area will be “matched” by ImageImageImageimageimage within the RegionOfInterestRegionOfInterestRegionOfInterestregionOfInterestregion_of_interest.

ImageMatchImageMatchImageMatchimageMatchimage_match (output_object)  image(-array) → objectHImageHObjectHObjectHobject * (byte)

Result image: values of the matching criterion.

ModeModeModemodemode (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Desired matching criterion.

Default: 'dfd' "dfd" "dfd" "dfd" "dfd"

List of values: 'dfd'"dfd""dfd""dfd""dfd", 'norm_correlation'"norm_correlation""norm_correlation""norm_correlation""norm_correlation"

Example (HDevelop)

read_image(Image,'monkey')
dev_display(Image)
draw_rectangle2(WindowHandle,Row,Column,Phi,Length1,Length2)
gen_rectangle2(Rectangle,Row,Column,Phi,Length1,Length2)
reduce_domain(Image,Rectangle,Template)
exhaustive_match(Image,Image,Template,ImageMatch,'dfd')
invert_image(ImageMatch,ImageInvert)
local_max(Image,Maxima)
union1(Maxima,AllMaxima)
add_channels(AllMaxima,ImageInvert,FitMaxima)
threshold(FitMaxima,BestFit,230.0,255.0)
dev_display(BestFit)

Example (C)

read_image(&Image,"monkey");
disp_image(Image,WindowHandle);
/* mark one eye */
draw_rectangle2(WindowHandle,&Row,&Column,&Phi,&Length1,&Length2);
gen_rectangle2(&Rectangle,Row,Column,Phi,Length1,Length2);
reduce_domain(Image,Rectangle,&Template);
exhaustive_match(Image,Image,Template,&ImageMatch,'dfd');
invert_image(ImageMatch,&ImageInvert);
local_max(ImageInvert,&Maxima);
union1(Maxima,&AllMaxima);
add_channels(AllMaxima,ImageInvert,&FitMaxima);
threshold(FitMaxima,&BestFit,230.0,255.0);
disp_region(BestFit,WindowHandle);

Example (HDevelop)

read_image(Image,'monkey')
dev_display(Image)
draw_rectangle2(WindowHandle,Row,Column,Phi,Length1,Length2)
gen_rectangle2(Rectangle,Row,Column,Phi,Length1,Length2)
reduce_domain(Image,Rectangle,Template)
exhaustive_match(Image,Image,Template,ImageMatch,'dfd')
invert_image(ImageMatch,ImageInvert)
local_max(Image,Maxima)
union1(Maxima,AllMaxima)
add_channels(AllMaxima,ImageInvert,FitMaxima)
threshold(FitMaxima,BestFit,230.0,255.0)
dev_display(BestFit)

Example (HDevelop)

read_image(Image,'monkey')
dev_display(Image)
draw_rectangle2(WindowHandle,Row,Column,Phi,Length1,Length2)
gen_rectangle2(Rectangle,Row,Column,Phi,Length1,Length2)
reduce_domain(Image,Rectangle,Template)
exhaustive_match(Image,Image,Template,ImageMatch,'dfd')
invert_image(ImageMatch,ImageInvert)
local_max(Image,Maxima)
union1(Maxima,AllMaxima)
add_channels(AllMaxima,ImageInvert,FitMaxima)
threshold(FitMaxima,BestFit,230.0,255.0)
dev_display(BestFit)

Result

If the parameter values are correct, the operator exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchexhaustive_match returns the value 2 ( H_MSG_TRUE) . If the input is empty (no input images are available) the behavior can be set via set_system('no_object_result',<Result>)set_system("no_object_result",<Result>)SetSystem("no_object_result",<Result>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>). If necessary, an exception is raised.

Possible Predecessors

draw_regiondraw_regionDrawRegionDrawRegiondraw_region, draw_rectangle1draw_rectangle1DrawRectangle1DrawRectangle1draw_rectangle1

Possible Successors

local_maxlocal_maxLocalMaxLocalMaxlocal_max, thresholdthresholdThresholdThresholdthreshold

Alternatives

exhaustive_match_mgexhaustive_match_mgExhaustiveMatchMgExhaustiveMatchMgexhaustive_match_mg

Module

Foundation

ClassesClasses | | Operators