Searching the best grayvalue matches in a pyramid.
::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 paramter 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 set larger compared with ::best_match, because the error is at higher levels of the pyramid often increased.
SubPixel specifies if the result is calculated with sub pixel accuracy or not. A value of 1 for SubPixel 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 resultion 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 analysed further on in the next higher resolution. This method is slower but it is more stable and the possibilty 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 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.
|
Image (input_object) |
image(-array) -> Hobject: HImage(Array) ( byte ) |
| Input image inside of which the pattern has to be found. | |
|
TemplateID (input_control) |
template -> HTuple.long |
| Template number. | |
|
MaxError (input_control) |
real -> HTuple.double |
| Maximal average difference of the grayvalues. | |
| Default value: 30 | |
| Suggested values: 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 15, 17, 20, 30, 40, 50, 60, 70 | |
| Typical range of values: 0 <= MaxError <= 255 | |
| Minimum increment: 1 | |
|
Recommended increment: 3 | |
|
SubPixel (input_control) |
string -> HTuple.char * |
| Exactness in subpixels in case of 'true'. | |
| Default value: 'false' | |
| List of values: 'true', 'false' | |
|
NumLevels (input_control) |
integer -> HTuple.long |
| Number of the used resolution levels. | |
| Default value: 4 | |
| List of values: 1, 2, 3, 4, 5, 6 | |
|
WhichLevels (input_control) |
integer -> HTuple.long / char * |
| 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 (output_control) |
point.y -> double * |
| Row position of the best match. | |
|
Column (output_control) |
point.x -> double * |
| Column position of the best match. | |
|
Error (output_control) |
real -> double * |
| Average divergence of the grayvalues in the best match. | |
If the parameter values are correct, the operator ::best_match_mg returns the value 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 handling 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
Gray value template matching
