Operator Reference

HALCON Operator Reference / Legacy / Matching
ClassesClasses | | Operators

best_matchT_best_matchBestMatchBestMatchbest_match (Operator)

best_matchT_best_matchBestMatchBestMatchbest_match — Searching the best matching of a template and an image.

Warning

best_matchbest_matchBestMatchBestMatchbest_match is obsolete and is only provided for reasons of backward compatibility. The operator will be removed with HALCON 25.11. New applications should use the shape-based or NCC-based operators instead.

Signature

best_match(Image : : TemplateID, MaxError, SubPixel : Row, Column, Error)

Herror T_best_match(const Hobject Image, const Htuple TemplateID, const Htuple MaxError, const Htuple SubPixel, Htuple* Row, Htuple* Column, Htuple* Error)

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

void HTemplate::BestMatch(const HImage& Image, double MaxError, const HString& SubPixel, HTuple* Row, HTuple* Column, HTuple* Error) const

void HTemplate::BestMatch(const HImage& Image, double MaxError, const HString& SubPixel, double* Row, double* Column, double* Error) const

void HTemplate::BestMatch(const HImage& Image, double MaxError, const char* SubPixel, double* Row, double* Column, double* Error) const

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

void HImage::BestMatch(const HTemplate& TemplateID, double MaxError, const HString& SubPixel, HTuple* Row, HTuple* Column, HTuple* Error) const

void HImage::BestMatch(const HTemplate& TemplateID, double MaxError, const HString& SubPixel, double* Row, double* Column, double* Error) const

void HImage::BestMatch(const HTemplate& TemplateID, double MaxError, const char* SubPixel, double* Row, double* Column, double* Error) const

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

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

void HTemplate.BestMatch(HImage image, double maxError, string subPixel, out HTuple row, out HTuple column, out HTuple error)

void HTemplate.BestMatch(HImage image, double maxError, string subPixel, out double row, out double column, out double error)

void HImage.BestMatch(HTemplate templateID, double maxError, string subPixel, out HTuple row, out HTuple column, out HTuple error)

void HImage.BestMatch(HTemplate templateID, double maxError, string subPixel, out double row, out double column, out double error)

def best_match(image: HObject, template_id: HHandle, max_error: float, sub_pixel: str) -> Tuple[Sequence[float], Sequence[float], Sequence[float]]

def best_match_s(image: HObject, template_id: HHandle, max_error: float, sub_pixel: str) -> Tuple[float, float, float]

Description

The operator best_matchbest_matchBestMatchBestMatchbest_match performs a matching of the template of TemplateIDTemplateIDTemplateIDtemplateIDtemplate_id and ImageImageImageimageimage. Hereby the template will be moved over the points of ImageImageImageimageimage so that the template will lie always inside ImageImageImageimageimage. best_matchbest_matchBestMatchBestMatchbest_match works similar to fast_matchfast_matchFastMatchFastMatchfast_match, with the exception, that each time a better match is found the value of MaxErrorMaxErrorMaxErrormaxErrormax_error is internally updated to a lower value to reduce runtime.

With regard to the parameter SubPixelSubPixelSubPixelsubPixelsub_pixel, the position will be indicated by subpixel accuracy. The matching criterion (“displaced frame difference”) is defined as follows: The runtime of the operator depends on the size of the domain of ImageImageImageimageimage. Therefore it is important to restrict the domain as far as possible, i.e. to apply the operator only in a very confined “region of interest”. The parameter MaxErrorMaxErrorMaxErrormaxErrormax_error determines the maximal error which the searched position is allowed to have at most. The lower this value is, the faster the operator runs.

RowRowRowrowrow and ColumnColumnColumncolumncolumn return the position of the best match, whereby ErrorErrorErrorerrorerror indicates the average difference of the gray values. If no position with an error below MaxErrorMaxErrorMaxErrormaxErrormax_error was found the position (0,0) and a matching result of 255 for ErrorErrorErrorerrorerror are returned. In this case MaxErrorMaxErrorMaxErrormaxErrormax_error has to be set larger.

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

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.

Parameters

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

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

TemplateIDTemplateIDTemplateIDtemplateIDtemplate_id (input_control)  template → HTemplate, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Template number.

MaxErrorMaxErrorMaxErrormaxErrormax_error (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

Maximum average difference of the gray values.

Default: 20.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

Value range: 0 ≤ MaxError MaxError MaxError maxError max_error ≤ 255

Minimum increment: 1

Recommended increment: 3

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

Subpixel accuracy in case of 'true'"true""true""true""true".

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

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

RowRowRowrowrow (output_control)  point.y(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Row position of the best match.

ColumnColumnColumncolumncolumn (output_control)  point.x(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Column position of the best match.

ErrorErrorErrorerrorerror (output_control)  real(-array) → HTupleSequence[float]HTupleHtuple (real) (double) (double) (double)

Average divergence of the gray values of the best match.

Result

If the parameter values are correct, the operator best_matchbest_matchBestMatchBestMatchbest_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

create_templatecreate_templateCreateTemplateCreateTemplatecreate_template, read_templateread_templateReadTemplateReadTemplateread_template, set_offset_templateset_offset_templateSetOffsetTemplateSetOffsetTemplateset_offset_template, set_reference_templateset_reference_templateSetReferenceTemplateSetReferenceTemplateset_reference_template, adapt_templateadapt_templateAdaptTemplateAdaptTemplateadapt_template, draw_regiondraw_regionDrawRegionDrawRegiondraw_region, draw_rectangle1draw_rectangle1DrawRectangle1DrawRectangle1draw_rectangle1, reduce_domainreduce_domainReduceDomainReduceDomainreduce_domain

Alternatives

fast_matchfast_matchFastMatchFastMatchfast_match, fast_match_mgfast_match_mgFastMatchMgFastMatchMgfast_match_mg, best_match_mgbest_match_mgBestMatchMgBestMatchMgbest_match_mg, best_match_pre_mgbest_match_pre_mgBestMatchPreMgBestMatchPreMgbest_match_pre_mg, best_match_rotbest_match_rotBestMatchRotBestMatchRotbest_match_rot, best_match_rot_mgbest_match_rot_mgBestMatchRotMgBestMatchRotMgbest_match_rot_mg, exhaustive_matchexhaustive_matchExhaustiveMatchExhaustiveMatchexhaustive_match, exhaustive_match_mgexhaustive_match_mgExhaustiveMatchMgExhaustiveMatchMgexhaustive_match_mg

Module

Matching

ClassesClasses | | Operators