MpatControl

Specifies the acceptance level. If the correlation (match score) between the target image and the model is less than this level, it is not considered a match (an occurrence).

A perfect match is 100%, whereas no correlation is 0%. The match score depends on the image quality. You should experiment to decide what is a typical match score for your application.

Note that the acceptance level must be less than or equal to the certainty level (M_CERTAINTY). INQ

Specifies the required positional accuracy. You can enhance speed performance by selecting a lower positional accuracy.

Note that the search speed slightly affects the positional accuracy. To change the search speed, use M_SPEED. INQ

Specifies the certainty level. If the correlation (match score) between the target image and the model is greater than or equal to the certainty level, a match is assumed without looking elsewhere in the image for a better match.

If you set the certainty level too high (close to 100%), you slow down the search because you force the search algorithm to check the whole search region for the best match. A good certainty level is slightly lower than the expected score, so that the search can finish as soon as the match is found. However, if you set the certainty level too low, false matches might be found. Note that the certainty level must be greater than or equal to the acceptance level (M_ACCEPTANCE). INQ

Specifies the maximum expected number of occurrences of a model in a target image. This number is used when searching, using MpatFind().

Occurrences with match scores that are greater than or equal to the certainty level (set with M_CERTAINTY)) are returned, up to the number specified by M_NUMBER. If such occurrences are fewer than the specified number, the remaining occurrences returned are the best of those that are greater than or equal to the acceptance level (set with M_ACCEPTANCE).

Note that, if a model in the Pattern Matching context is to be ignored, set the number of occurrences for that model (M_NUMBER) to 0. INQ

Sets the X-offset of the model's reference position, relative to the model origin. Position results return the X-coordinate of the model's reference position transformed at the model occurrence. Position results are relative to the target origin.

If you redefine the model's reference position (with M_REFERENCE_...), make sure that the search region (defined by M_SEARCH_OFFSET_... and M_SEARCH_SIZE_... or the target image's ROI) covers this new reference position and takes into account the angular search range of the model (specified using M_SEARCH_ANGLE...).

Note that although the reference position need not be in the model, it should be inside the search region. If, in the target image, the reference position falls outside target image, MIL returns a negative position. INQ

Sets the Y-offset of the model's reference position, relative to the model origin. Position results return the Y-coordinate of the model's reference position transformed at the model occurrence. Position results are relative to the target origin.

If you redefine the model's reference position (with M_REFERENCE_...), make sure that the search region (defined by the M_SEARCH_OFFSET_... and M_SEARCH_SIZE_... or the target image's ROI) covers this new reference position and takes into account the angular search range of the model (specified using M_SEARCH_ANGLE...).

Note that although the reference position need not be in the model, it should be inside the search region. If, in the target image, the reference position falls outside target image, MIL returns a negative position. INQ

Sets whether to use angle refinement mode, as well as sets the score to use for this mode. During preprocessing, this control type helps establish the full range of degrees within which a rotated version of the model can be rotated from the model at a specific angle and still match with at least the score specified by this control type (the angle refinement score). The higher the angle refinement score is set, the smaller the angle refinement step will be.

The lowest value between the determined angle refinement step and the specified angle accuracy (set using M_SEARCH_ANGLE_ACCURACY) is the angle refinement step used when searching for the pattern in the target image. INQ

Sets the nominal search angle at which to search for occurrences of the model.

For best results, if there is a region of interest (ROI) in your target image, set this control's value to 0.0. Note that there will be an increase in processing time if the model is at an angle.

Angles are interpreted with respect to the pixel coordinate system, so they are always measured counter-clockwise.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Sets the required precision with which to find the angle of the occurrence. The precision defines an angular range in which to fine-tune the search after the approximate location of the occurrence of the model is found. To be effective, you must set the degree of accuracy to a value smaller than that of the rotation tolerance (M_SEARCH_ANGLE_TOLERANCE). This angular range is further restricted by M_ROTATED_MODEL_MINIMUM_SCORE. For more information, refer to the Search constraints section of Chapter 7: Pattern matching.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Sets the lower limit for the angular range, relative to the nominal search angle (set using M_SEARCH_ANGLE). The angular range should be used to cover the expected variance in angle. Occurrences with angles outside the angular-range cannot be returned as results.

Note that the greater the range of angles to be searched, the slower the search.

To set the upper limit for the angular range, use M_SEARCH_ANGLE_DELTA_POS.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Sets the upper limit for the angular range, relative to the nominal search angle (set using M_SEARCH_ANGLE). The angular range should be used to cover the expected variance in angle. Occurrences with angles outside the angular-range cannot be returned as results.

Note that the greater the range of angles to be searched, the slower the search.

To set the lower limit for the angular range, use M_SEARCH_ANGLE_DELTA_NEG.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Sets the type of interpolation to use when rotating the model to perform the search at an angle.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Sets whether to perform calculations specific to angular-range search strategies.

To search for models at an angle (within their specified angular range M_SEARCH_ANGLE- M_SEARCH_ANGLE_DELTA_NEG to M_SEARCH_ANGLE + M_SEARCH_ANGLE_DELTA_POS in the target) this control type must be enabled. In addition, you can limit the number of angles searched using M_SEARCH_ANGLE_ACCURACY and M_SEARCH_ANGLE_TOLERANCE.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS. INQ

Sets the full range of degrees within which the pattern in the target image can be rotated from a model at a specific angle and still meet the acceptance level. For example, if a model can tolerate the target image being offset from its search angle by ±2.5°, specify 5°. The specified tolerance determines the step angle. Note that very small tolerance values should only be used within small angular ranges; otherwise, application performance can be adversely affected. For more information, refer to the Finding models when they are at an angle section of Chapter 7: Pattern matching.

MpatFind() does not support angular searches when M_SEARCH_MODE is set to M_FIND_BEST_MODELS.

When M_SEARCH_ANGLE_MODE is disabled, this setting has no effect. INQ

Specifies the X-offset of the specified model's search region. It limits the area in the target image in which to find the reference position of the model (set with M_REFERENCE_...), and consequently increases the search speed.

Note that, if searching for multiple models and your M_SEARCH_MODE is set to M_FIND_ALL_MODELS, the offset of the search region must be the same for all the models.

The search region can fall outside the target area, specified when calling MpatFind().

When dealing with a target image with an ROI, this value is ignored. INQ

Specifies the Y-offset of the specified model's search region. It limits the area in the target image in which to find the reference position of the model (set with M_REFERENCE_...), and consequently increases the search speed.

Note that, if searching for multiple models and your M_SEARCH_MODE is set to M_FIND_ALL_MODELS, the offset of the search region must be the same for all the models.

The search region can fall outside the target area, specified when calling MpatFind().

When dealing with a target image with an ROI, this value is ignored. INQ

Specifies the width of the search region. Note that the size of the search region can be smaller than the size of the model because the search region only defines where to find the reference position.

Note that, if searching for multiple models and your M_SEARCH_MODE is set to M_FIND_ALL_MODELS, the width of the search region must be the same for all the models.

The search region can fall outside the target image, specified when calling MpatFind().

When dealing with a target image with an ROI, this value is ignored. INQ

Specifies the height of the search region. Note that the size of the search region can be smaller than the size of the model because the search region only defines where to find the reference position.

Note that, if searching for multiple models and your M_SEARCH_MODE is set to M_FIND_ALL_MODELS, the height of the search region must be the same for all the models.

The search region can fall outside the target image, specified when calling MpatFind().

When dealing with a target image with an ROI, this value is ignored. INQ

Specifies the required search speed when using MpatFind(). At a higher speed, the search takes all reasonable short cuts; therefore, the search should be performed faster than at lower settings. Generally, the high speed setting should be used for better quality images or when using a simple model. Note, the high speed setting reduces positional accuracy very slightly. Try the low speed settings only if your image quality is particularly poor and you have encountered problems at higher speeds. INQ

Sets the coarse search acceptance threshold level to use for rejecting candidate model peaks at low resolution levels.

Note that this value is not saved with the Pattern Matching context. Instead, this value must be set each time the Pattern Matching context is restored.

Changing the coarse search acceptance to a specified value might increase the search time when some of the matches you request do not reach the certainty level, or when you request more matches than are really present in the image. The coarse search acceptance level should usually be set much lower than the search acceptance level. For example, a good level to set it to is about 20% to 30%. Note that if it is too low, you will not see any increase in speed. However, if it is too high, you risk rejecting real match peaks. Note that the coarse search acceptance threshold level is not saved and restored with the Pattern Matching context. So, if you always want to use your own coarse search acceptance level, you should set it each time after restoring your Pattern Matching context and before calling MpatFind(). Otherwise, the default coarse search acceptance level is used. INQ

Sets the number of extra candidates to consider.

Normally, the search algorithm considers only a limited number of (best) scores as possible candidates to match when proceeding at the most subsampled stage. This setting allows you to add robustness to the algorithm, by considering more candidates, without overly compromising the search speed. INQ

Sets whether to use fast peak finding. INQ

Sets the resolution level for the initial stage (lowest resolution) of the search.

Note that level 0 is the original target image and each higher level is half the size (and resolution) of the previous one. If the specified level is not supported by the search algorithm, the highest possible level will be used. A higher first level speeds up the initial search but makes it less reliable, because the model might not retain enough distinctive features at such a low resolution. After preprocessing your Pattern Matching context, use MpatInquire() with M_PROC_FIRST_LEVEL to inquire about the default value of the lowest resolution level. INQ

Sets the resolution level for the final stage (highest resolution) of the search.

Note that if the specified level is not supported by the search algorithm, the highest acceptable level will be used. Search score can also be less reliable for levels above 0, depending on the characteristics of the model. After preprocessing your Pattern Matching context, use MpatInquire() with M_PROC_LAST_LEVEL to inquire about the default value of the highest resolution level. INQ

Sets the maximum number of returned peaks after an initial search at the first level for occurrences of multiple models, or a single model with circular overscan data (that is, M_AUTO_MODEL or M_REGULAR_MODEL with M_CIRCULAR_OVERSCAN). INQ

Sets the minimum separation (in X) between two models in order for them to be considered distinct. INQ

Sets the minimum separation (in Y) between two models in order for them to be considered distinct. INQ

Sets whether all or every second pixel in the model is used in the correlation during the high resolution stage of the search. INQ