best_match_mg — Searching the best grayvalue matches in a pyramid.
best_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.
best_match_mg applies gray value matching using an image pyramid. best_match_mg works analogously to best_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 MaxError 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 MaxError has to be chosen larger compared with best_match, because the error at higher levels of the pyramid is often larger.
SubPixel specifies if the result is calculated with sub pixel accuracy or not. A value of 1 for NumLevels results in an operator similar to best_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 (WhichLevels = 'all'). As an alternative Method the mode WhichLevels with value 'original' can be used. In this case not only the position with the lowest error but all points below MaxError 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 NumLevels) which leads to a reduced runtime. Besides the values 'all' and 'original' for WhichLevels you can specify the pyramid level explicitly where to switch between a “match all” and the ”best match”. Here 0 corresponds to 'original' and NumLevels - 1 is equivalent to 'all'. A value in-between is in most cases a good compromise between speed and a stable detection. A larger value for WhichLevels results in a reduced runtime, a smaller value results in a more stable detection. The value of NumLevels has to be equal or smaller than the value used to create the template.
The position of the found matching position is returned in Row and Column. The corresponding error is given in Error. If no point below MaxError is found a value of 255 for Error and 0 for Row and Column is returned. If the desired object is missed (no object found or wrong position) you have to set MaxError higher or WhichLevels lower. Check also if the illumination has changed (see set_offset_template).
The maximum error of the position (without noise) is 0.1 pixel. The average error is 0.03 pixel.
Input image inside of which the pattern has to be found.
Maximal average difference of the grayvalues.
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 ≤ 255
Minimum increment: 1
Recommended increment: 3
Exactness in subpixels in case of 'true'.
Default value: 'false'
List of values: 'false', 'true'
Number of the used resolution levels.
Default value: 4
Suggested values: 1, 2, 3, 4, 5, 6
Resolution level up to which the method “best match” is used.
Default value: 2
Suggested values: 'all', 'original', 0, 1, 2, 3, 4, 5, 6
Row position of the best match.
Column position of the best match.
Average divergence of the grayvalues in the best match.
If the parameter values are correct, the operator best_match_mg returns the value 2 (H_MSG_TRUE). If the input is empty (no input images are available) the behaviour can be set via set_system('no_object_result',<Result>). If necessary, an exception is raised.
create_template, read_template, adapt_template, draw_region, draw_rectangle1, reduce_domain, set_reference_template, set_offset_template
fast_match, fast_match_mg, best_match, best_match_pre_mg, best_match_rot, best_match_rot_mg, exhaustive_match, exhaustive_match_mg