best_match_mgT_best_match_mgBestMatchMgBestMatchMgbest_match_mg (Operator)

Name

best_match_mgT_best_match_mgBestMatchMgBestMatchMgbest_match_mg — Searching the best gray value matches in a pyramid.

Warning

best_match_mgbest_match_mgBestMatchMgBestMatchMgBestMatchMgbest_match_mg is obsolete and is only provided for reasons of backward compatibility. New applications should use the shape-based or NCC-based operators instead.

Signature

best_match_mg(Image : : TemplateID, MaxError, SubPixel, NumLevels, WhichLevels : Row, Column, Error)

Herror T_best_match_mg(const Hobject Image, const Htuple TemplateID, const Htuple MaxError, const Htuple SubPixel, const Htuple NumLevels, const Htuple WhichLevels, Htuple* Row, Htuple* Column, Htuple* Error)

void BestMatchMg(const HObject& Image, const HTuple& TemplateID, const HTuple& MaxError, const HTuple& SubPixel, const HTuple& NumLevels, const HTuple& WhichLevels, HTuple* Row, HTuple* Column, HTuple* Error)

void HTemplate::BestMatchMg(const HImage& Image, double MaxError, const HString& SubPixel, Hlong NumLevels, const HTuple& WhichLevels, double* Row, double* Column, double* Error) const

void HTemplate::BestMatchMg(const HImage& Image, double MaxError, const HString& SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const

void HTemplate::BestMatchMg(const HImage& Image, double MaxError, const char* SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const

void HTemplate::BestMatchMg(const HImage& Image, double MaxError, const wchar_t* SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const   (Windows only)

void HImage::BestMatchMg(const HTemplate& TemplateID, double MaxError, const HString& SubPixel, Hlong NumLevels, const HTuple& WhichLevels, double* Row, double* Column, double* Error) const

void HImage::BestMatchMg(const HTemplate& TemplateID, double MaxError, const HString& SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const

void HImage::BestMatchMg(const HTemplate& TemplateID, double MaxError, const char* SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const

void HImage::BestMatchMg(const HTemplate& TemplateID, double MaxError, const wchar_t* SubPixel, Hlong NumLevels, Hlong WhichLevels, double* Row, double* Column, double* Error) const   (Windows only)

static void HOperatorSet.BestMatchMg(HObject image, HTuple templateID, HTuple maxError, HTuple subPixel, HTuple numLevels, HTuple whichLevels, out HTuple row, out HTuple column, out HTuple error)

void HTemplate.BestMatchMg(HImage image, double maxError, string subPixel, int numLevels, HTuple whichLevels, out double row, out double column, out double error)

void HTemplate.BestMatchMg(HImage image, double maxError, string subPixel, int numLevels, int whichLevels, out double row, out double column, out double error)

void HImage.BestMatchMg(HTemplate templateID, double maxError, string subPixel, int numLevels, HTuple whichLevels, out double row, out double column, out double error)

void HImage.BestMatchMg(HTemplate templateID, double maxError, string subPixel, int numLevels, int whichLevels, out double row, out double column, out double error)

def best_match_mg(image: HObject, template_id: HHandle, max_error: float, sub_pixel: str, num_levels: int, which_levels: Union[str, int]) -> Tuple[float, float, float]

Description

best_match_mgbest_match_mgBestMatchMgBestMatchMgBestMatchMgbest_match_mg applies gray value matching using an image pyramid. best_match_mgbest_match_mgBestMatchMgBestMatchMgBestMatchMgbest_match_mg works analogously to best_matchbest_matchBestMatchBestMatchBestMatchbest_match, but it is faster due to the use of a pyramid. Input is an image with an optionally reduced domain. The template is searched within those points of the domain of the image, in which the model lies completely within the image. This means that the model will not be found if it extends beyond the borders of the image. The parameter MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error specifies the maximum error for template matching. Using smaller values results in a reduced runtime but it is possible that the pattern might be missed. The value of MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error has to be chosen larger compared with best_matchbest_matchBestMatchBestMatchBestMatchbest_match, because the error at higher levels of the pyramid is often larger.

SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel specifies if the result is calculated with sub pixel accuracy or not. A value of 1 for NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels results in an operator similar to best_matchbest_matchBestMatchBestMatchBestMatchbest_match, i.e. only the original gray values are used. For values larger than 1, the algorithm starts at the lowest resolution and searches for a position with the lowest matching error. At the next higher resolution this position is refined. This is continued up to the maximum resolution (WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels = 'all'"all""all""all""all""all"). As an alternative Method the mode WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels with value 'original'"original""original""original""original""original" can be used. In this case not only the position with the lowest error but all points below MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error are analyzed further on in the next higher resolution. This method is slower but it is more stable and the possibility to miss the correct position is very low. In this case it is often possible to start with a lower resolution (higher level in Pyramid, i.e. larger value for NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels) which leads to a reduced runtime. Besides the values 'all'"all""all""all""all""all" and 'original'"original""original""original""original""original" for WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels you can specify the pyramid level explicitly where to switch between a “match all” and the ”best match”. Here 0 corresponds to 'original'"original""original""original""original""original" and NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels - 1 is equivalent to 'all'"all""all""all""all""all". A value in-between is in most cases a good compromise between speed and a stable detection. A larger value for WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels results in a reduced runtime, a smaller value results in a more stable detection. The value of NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels has to be equal or smaller than the value used to create the template.

The position of the found matching position is returned in RowRowRowRowrowrow and ColumnColumnColumnColumncolumncolumn. The corresponding error is given in ErrorErrorErrorErrorerrorerror. If no point below MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error is found a value of 255 for ErrorErrorErrorErrorerrorerror and 0 for RowRowRowRowrowrow and ColumnColumnColumnColumncolumncolumn is returned. If the desired object is missed (no object found or wrong position) you have to set MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error higher or WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels lower. Check also if the illumination has changed (see set_offset_templateset_offset_templateSetOffsetTemplateSetOffsetTemplateSetOffsetTemplateset_offset_template).

The maximum error of the position (without noise) is 0.1 pixel. The average error is 0.03 pixel.

Execution Information

Parameters

ImageImageImageImageimageimage (input_object)  singlechannelimage(-array) objectHImageHObjectHImageHobject (byte)

Input image inside of which the pattern has to be found.

TemplateIDTemplateIDTemplateIDTemplateIDtemplateIDtemplate_id (input_control)  template HTemplate, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Template number.

MaxErrorMaxErrorMaxErrorMaxErrormaxErrormax_error (input_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Maximal average difference of the gray values.

Default value: 30.0

Suggested values: 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 9.0, 11.0, 15.0, 17.0, 20.0, 30.0, 40.0, 50.0, 60.0, 70.0

Typical range of values: 0 ≤ MaxError MaxError MaxError MaxError maxError max_error ≤ 255

Minimum increment: 1

Recommended increment: 3

SubPixelSubPixelSubPixelSubPixelsubPixelsub_pixel (input_control)  string HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Exactness in subpixels in case of 'true'"true""true""true""true""true".

Default value: 'false' "false" "false" "false" "false" "false"

List of values: 'false'"false""false""false""false""false", 'true'"true""true""true""true""true"

NumLevelsNumLevelsNumLevelsNumLevelsnumLevelsnum_levels (input_control)  integer HTupleintHTupleHtuple (integer) (int / long) (Hlong) (Hlong)

Number of the used resolution levels.

Default value: 4

Suggested values: 1, 2, 3, 4, 5, 6

WhichLevelsWhichLevelsWhichLevelsWhichLevelswhichLevelswhich_levels (input_control)  integer HTupleUnion[str, int]HTupleHtuple (integer / string) (int / long / string) (Hlong / HString) (Hlong / char*)

Resolution level up to which the method “best match” is used.

Default value: 2

Suggested values: 'all'"all""all""all""all""all", 'original'"original""original""original""original""original", 0, 1, 2, 3, 4, 5, 6

RowRowRowRowrowrow (output_control)  point.y HTuplefloatHTupleHtuple (real) (double) (double) (double)

Row position of the best match.

ColumnColumnColumnColumncolumncolumn (output_control)  point.x HTuplefloatHTupleHtuple (real) (double) (double) (double)

Column position of the best match.

ErrorErrorErrorErrorerrorerror (output_control)  real HTuplefloatHTupleHtuple (real) (double) (double) (double)

Average divergence of the gray values in the best match.

Result

If the parameter values are correct, the operator best_match_mgbest_match_mgBestMatchMgBestMatchMgBestMatchMgbest_match_mg returns the value 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>)SetSystem("no_object_result",<Result>)set_system("no_object_result",<Result>). If necessary, an exception is raised.

Possible Predecessors

create_templatecreate_templateCreateTemplateCreateTemplateCreateTemplatecreate_template, read_templateread_templateReadTemplateReadTemplateReadTemplateread_template, adapt_templateadapt_templateAdaptTemplateAdaptTemplateAdaptTemplateadapt_template, draw_regiondraw_regionDrawRegionDrawRegionDrawRegiondraw_region, draw_rectangle1draw_rectangle1DrawRectangle1DrawRectangle1DrawRectangle1draw_rectangle1, reduce_domainreduce_domainReduceDomainReduceDomainReduceDomainreduce_domain, set_reference_templateset_reference_templateSetReferenceTemplateSetReferenceTemplateSetReferenceTemplateset_reference_template, set_offset_templateset_offset_templateSetOffsetTemplateSetOffsetTemplateSetOffsetTemplateset_offset_template

Alternatives

fast_matchfast_matchFastMatchFastMatchFastMatchfast_match, fast_match_mgfast_match_mgFastMatchMgFastMatchMgFastMatchMgfast_match_mg, best_matchbest_matchBestMatchBestMatchBestMatchbest_match, best_match_pre_mgbest_match_pre_mgBestMatchPreMgBestMatchPreMgBestMatchPreMgbest_match_pre_mg, best_match_rotbest_match_rotBestMatchRotBestMatchRotBestMatchRotbest_match_rot, best_match_rot_mgbest_match_rot_mgBestMatchRotMgBestMatchRotMgBestMatchRotMgbest_match_rot_mg, exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchExhaustiveMatchexhaustive_match, exhaustive_match_mgexhaustive_match_mgExhaustiveMatchMgExhaustiveMatchMgExhaustiveMatchMgexhaustive_match_mg

Module

Matching