MpatControl

Filters
See also

User Guide:

Defining and adding models to your Pattern Matching context Finding models when they are at an angle Fixturing offset Pattern matching examples Search constraints Speeding up the search Steps to performing a pattern search The pattern matching algorithm (for advanced users)

Reference:

MmodInquire MpatAlloc MpatAllocResult MpatDefine MpatFind MpatGetResult MpatInquire MpatPreprocess

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

binarybasedcircledetection.cpp
dmilobjecttrackingslave.cpp
fixturedcoderead.cpp
mmodeltracking.cpp
mmodeltracking.cs
mmodeltracking.vb
mpat.cpp
mpat.cs
mpat.vb
mpatfindmultiplemodels.cpp
pcbmodelmatching.cpp

Function Map

- ContextOrResultPatId

- Index

Table:

For specifying a context, or a model index

- ControlType

- ControlValue

Parameter Associations

Table:	For the general settings of the Pattern Matching context
Table:	For an individual model or all models in a Pattern Matching context
Table:	For controlling advanced settings
Table:	For the result buffer identifier

Type specific versions of the function when using a C compiler under 64-bit

Compilation information

Synopsis

Control a setting of a Pattern Matching context, one or all models, or Pattern Matching result buffer.

Syntax

void MpatControl(

MIL_ID ContextOrResultPatId,	//in
MIL_INT Index,	//in
MIL_INT64 ControlType,	//in
MIL_DOUBLE ControlValue	//in

)

Description

This function allows you to control a setting of a Pattern Matching context, at least one (or all) of the models contained therein, or a Pattern Matching result buffer. These settings control the execution of MpatFind() operations. Most of the control type settings can be inquired using MpatInquire().

Changing certain control type settings might require preprocessing of the Pattern Matching context again, using MpatPreprocess(). To know if the Pattern Matching context needs to be preprocessed, call MpatInquire() with M_PREPROCESSED, after adjusting all required control types.

Any value that you provide to the MIL Pattern Matching module (for example, position and width) must be specified in the pixel coordinate system, even if the target image is calibrated.

You can change the search region at any time without preprocesing the Pattern Matching context again (for example, when tracking an object, the search region could be changed before each call to MpatFind()).

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, MpatControl() internally calls the MIL_DOUBLE version of this function (MpatControlDouble()). If you need to pass integer values, call the MIL_INT64 version of this function (MpatControlInt64()).

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.

Parameters

This function is not supported on the selected boards.

Parameters

ContextOrResultPatId

Specifies the Pattern Matching context or Pattern Matching result buffer whose settings you want to modify. The Pattern Matching context or result buffer must have been previously allocated on the system using MpatAlloc() or MpatAllocResult(), respectively.

Index

Specifies to control a Pattern Matching context, an individual model, or a Pattern Matching result buffer. Set this parameter to one of the following values:

For specifying a context, or a model index
Value	Description
M_DEFAULT	Specifies the default. If a Pattern Matching context is specified, same as M_ALL. If a Pattern Matching result buffer is specified, same as M_GENERAL. (summarize) Specifies the default. (more details...)
M_ALL	Applies the specified control setting to all models, if a Pattern Matching context is specified.
M_CONTEXT	Controls a general setting of a specified Pattern Matching context, if one is specified.
M_GENERAL	Controls a general setting of a Pattern Matching result buffer when ContextOrResultPatId is a result buffer.
Value >= 0	Specifies the index of the individual model to control, if a Pattern Matching context is specified.

ControlType

Specifies the setting to change.

See the Parameter associations section for possible values that can be specified.

ControlValue

Specifies the setting's new value.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The tables below list possible values for the ControlType and ControlValue parameters.

For the general settings of the Pattern Matching context
For an individual model or all models in a Pattern Matching context
For controlling advanced settings
For the result buffer identifier

The following control type and control value allows you specify general settings for a Pattern Matching context. For controlling general context settings, the Index parameter must be set to M_CONTEXT.

For the general settings of the Pattern Matching context
ControlType		Description
	ControlValue	Description
M_SEARCH_MODE		Sets the search mode to use when performing an MpatFind() operation. INQ (summarize) Sets the search mode to use when performing an MpatFind() operation. INQ (more details...)
	M_DEFAULT	Same as M_FIND_ALL_MODELS.
	M_FIND_ALL_MODELS	Specifies to search for all the specified models in the target image using their own search settings. Note that, all models must be of the same size and use the same search region. Each model's search settings also determine the maximum number of occurrences of that model to search for in the target image (M_NUMBER). (summarize) Specifies to search for all the specified models in the target image using their own search settings. (more details...)
	M_FIND_BEST_MODELS	Specifies to search for the best occurrences of any model in the target image, using the search settings from the first model in the Pattern Matching context. Consequently, the search settings of the other models are ignored. Note that, all models must be of the same size. The number of different matches that are found depends on M_NUMBER, M_CERTAINTY, and M_ACCEPTANCE, but cannot exceed 100 occurrences, unless M_MAX_INITIAL_PEAKS is set to M_ALL. You cannot use M_FIND_BEST_MODELS to perform an angular search (M_SEARCH_ANGLE). Note that, if the first model in the Pattern Matching context is to be ignored (that is, the number of occurrences for that model is set to 0), the settings of the first model whose number of occurrences is not set to 0 will be used instead. (summarize) Specifies to search for the best occurrences of any model in the target image, using the search settings from the first model in the Pattern Matching context. (more details...)

The following control types and control values allow you to control the settings for an individual model or all models in a Pattern Matching context. For controlling the settings of one or all models, the Index parameter must be set to the model index of a specific model in the Pattern Matching context or to M_ALL, respectively.

For an individual model or all models in a Pattern Matching context
ControlType		Description
	ControlValue	Description
M_ACCEPTANCE		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 (summarize) Specifies the acceptance level. INQ (more details...)
	0.0 <= Value <= 100.0	Specifies the acceptance level, as a percentage. The default value is 70 percent. (summarize) Specifies the acceptance level, as a percentage. (more details...)
M_ACCURACY		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 (summarize) Specifies the required positional accuracy. INQ (more details...)
	M_HIGH	Specifies a high accuracy (typically ± 0.05 pixels).
	M_LOW	Specifies a low accuracy (typically ± 0.20 pixels). Note that when using this setting, the match scores can be slightly lower than usual. If a precise match score is important to you, use at least medium accuracy. (summarize) Specifies a low accuracy (typically ± 0.20 pixels). (more details...)
	M_MEDIUM	Specifies a medium accuracy (typically ± 0.10 pixels). This is the default value. (summarize) Specifies a medium accuracy (typically ± 0.10 pixels). (more details...)
M_CERTAINTY		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 (summarize) Specifies the certainty level. INQ (more details...)
	0.0 <= Value <= 100.0	Specifies the certainty level, as a percentage. The default value is 80. (summarize) Specifies the certainty level, as a percentage. (more details...)
M_NUMBER		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 (summarize) Specifies the maximum expected number of occurrences of a model in a target image. INQ (more details...)
	M_ALL	Specifies to look for all matches that are greater than or equal to the acceptance level.
	Value >= 0	Specifies the maximum number of occurrences for which to look in the target image. Only integer values are accepted. The default value is 1. (summarize) Specifies the maximum number of occurrences for which to look in the target image. (more details...)
M_REFERENCE_X		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 (summarize) Sets the X-offset of the model's reference position, relative to the model origin. INQ (more details...)
	Value	Sets the X-offset of the model's reference position relative to the model origin, in pixels. The default value is M_SEARCH_SIZE_X/2. (summarize) Sets the X-offset of the model's reference position relative to the model origin, in pixels. (more details...)
M_REFERENCE_Y		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 (summarize) Sets the Y-offset of the model's reference position, relative to the model origin. INQ (more details...)
	Value	Sets the Y-offset of the model's reference position relative to the model origin, in pixels. The default value is M_SEARCH_SIZE_Y/2. (summarize) Sets the Y-offset of the model's reference position relative to the model origin, in pixels. (more details...)
M_ROTATED_MODEL_MINIMUM_SCORE		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 (summarize) Sets whether to use angle refinement mode, as well as sets the score to use for this mode. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies to disable the angle refinement mode.
	0.0 <= Value <= 100.0	Specifies the minimum score.
M_SEARCH_ANGLE		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 (summarize) Sets the nominal search angle at which to search for occurrences of the model. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.0.
	0.0 <= Value <= 360.0	Specifies the nominal search angle, in degrees.
M_SEARCH_ANGLE_ACCURACY		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 (summarize) Sets the required precision with which to find the angle of the occurrence. INQ (more details...)
	M_DEFAULT	Same as M_DISABLE.
	M_DISABLE	Specifies that the angle accuracy equals the tolerance.
	0 < Value <= 180.0	Specifies the angle accuracy, in degrees.
M_SEARCH_ANGLE_DELTA_NEG		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 (summarize) Sets the lower limit for the angular range, relative to the nominal search angle (set using M_SEARCH_ANGLE). INQ (more details...)
	M_DEFAULT	Specifies the default value. The default value is 180.0 when the model is of type M_CIRCULAR_OVERSCAN, and 0.0 otherwise. (summarize) Specifies the default value. (more details...)
	0.0 <= Value <= 180.0	Specifies the angle in a clockwise rotation, in degrees.
M_SEARCH_ANGLE_DELTA_POS		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 (summarize) Sets the upper limit for the angular range, relative to the nominal search angle (set using M_SEARCH_ANGLE). INQ (more details...)
	M_DEFAULT	Specifies the default value. The default value is 180.0 when the model is of type M_CIRCULAR_OVERSCAN, and 0.0 otherwise. (summarize) Specifies the default value. (more details...)
	0.0 <= Value <= 180.0	Specifies the angle in a counter-clockwise rotation, in degrees.
M_SEARCH_ANGLE_INTERPOLATION_MODE		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 (summarize) Sets the type of interpolation to use when rotating the model to perform the search at an angle. INQ (more details...)
	M_DEFAULT	Same as M_NEAREST_NEIGHBOR.
	M_BICUBIC	Specifies that bicubic interpolation is used when rotating the model.
	M_BILINEAR	Specifies that bilinear interpolation is used when rotating the model.
	M_NEAREST_NEIGHBOR	Specifies that nearest-neighbor interpolation is used when rotating the model.
M_SEARCH_ANGLE_MODE		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 (summarize) Sets whether to perform calculations specific to angular-range search strategies. INQ (more details...)
	M_DISABLE	Specifies to disable the angular search mode. This is the default value. (summarize) Specifies to disable the angular search mode. (more details...)
	M_ENABLE	Specifies to enable the angular search mode.
M_SEARCH_ANGLE_TOLERANCE		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 (summarize) 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. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 5.0 degrees.
	M_AUTO	Specifies that the tolerance will be automatically determined based on an analysis of the model.
	0 < Value <= 180.0	Specifies the step angle, in degrees.
M_SEARCH_OFFSET_X		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 (summarize) Specifies the X-offset of the specified model's search region. INQ (more details...)
	M_DEFAULT	Specifies the X-coordinate of the top-left corner of the target image. By default, the entire target image is searched. (summarize) Specifies the X-coordinate of the top-left corner of the target image. (more details...)
	Value	Specifies the X-coordinate, relative to the pixel coordinate system, of where to start the search. Only integer values are accepted. (summarize) Specifies the X-coordinate, relative to the pixel coordinate system, of where to start the search. (more details...)
M_SEARCH_OFFSET_Y		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 (summarize) Specifies the Y-offset of the specified model's search region. INQ (more details...)
	M_DEFAULT	Specifies the Y-coordinate of the top-left corner of the target image. By default, the entire target image is searched. (summarize) Specifies the Y-coordinate of the top-left corner of the target image. (more details...)
	Value	Specifies the Y-coordinate, relative to the pixel coordinate system, of where to start the search. Only integer values are accepted. (summarize) Specifies the Y-coordinate, relative to the pixel coordinate system, of where to start the search. (more details...)
M_SEARCH_SIZE_X		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 (summarize) Specifies the width of the search region. INQ (more details...)
	M_DEFAULT	Same as M_ALL.
	M_ALL	Specifies to use the width of the full image.
	Value	Specifies the width, in pixels. Only integer values are accepted. (summarize) Specifies the width, in pixels. (more details...)
M_SEARCH_SIZE_Y		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 (summarize) Specifies the height of the search region. INQ (more details...)
	M_DEFAULT	Same as M_ALL.
	M_ALL	Specifies to use the height of the full image.
	Value	Specifies the height, in pixels. Only integer values are accepted. (summarize) Specifies the height, in pixels. (more details...)
M_SPEED		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 (summarize) Specifies the required search speed when using MpatFind(). INQ (more details...)
	M_HIGH	Specifies a high search speed.
	M_LOW	Specifies a low search speed.
	M_MEDIUM	Specifies a medium search speed. This is the default value. (summarize) Specifies a medium search speed. (more details...)
	M_VERY_HIGH	Specifies a very high search speed.
	M_VERY_LOW	Specifies a very low search speed.

The following control types and control values are for advanced users of the Pattern Matching module. If the default settings do not satisfy the requirements of your application, these control types and control values can be used to fine tune the model's search settings. The default settings typically provide the best results for most search operations. To gain a clearer understanding of how the search algorithm works, see the The pattern matching algorithm (for advanced users) section of Chapter 7: Pattern matching.

For these control types, the Index parameter must be set to the model index of a specific model in the Pattern Matching context or M_ALL.

For controlling advanced settings
ControlType		Description
	ControlValue	Description
M_COARSE_SEARCH_ACCEPTANCE		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 (summarize) Sets the coarse search acceptance threshold level to use for rejecting candidate model peaks at low resolution levels. INQ (more details...)
	M_DEFAULT	Specifies to determine the coarse search acceptance threshold level automatically.
	1.0 <= Value <= 100.0	Specifies the coarse search acceptance threshold level.
M_EXTRA_CANDIDATES		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 (summarize) Sets the number of extra candidates to consider. INQ (more details...)
	M_DEFAULT	Specifies the default value; the default value is 0.
	Value >= 0	Specifies the number of extra candidates. Only integer values are accepted. (summarize) Specifies the number of extra candidates. (more details...)
M_FAST_FIND		Sets whether to use fast peak finding. INQ (summarize) Sets whether to use fast peak finding. INQ (more details...)
	M_DEFAULT	Specifies to use preprocessing to decide if fast peak finding is appropriate.
	M_DISABLE	Specifies not to use fast peak finding. The initial search (at the resolution level determined by M_FIRST_LEVEL) computes the correlation at every position in the search region. This guarantees that the biggest match peak will be found, and that it will be investigated first. (summarize) Specifies not to use fast peak finding. (more details...)
	M_ENABLE	Specifies to use fast peak finding. The search algorithm attempts to find the peaks without checking every point. This is safe in most cases, but can cause matches to be missed for models that produce very narrow peaks. (summarize) Specifies to use fast peak finding. (more details...)
M_FIRST_LEVEL		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 (summarize) Sets the resolution level for the initial stage (lowest resolution) of the search. INQ (more details...)
	M_DEFAULT	Same as M_AUTO_SIZE_BASED.
	M_AUTO_CONTENT_BASED	Specifies to automatically determine the first level based on an analysis of the model contents.
	M_AUTO_SIZE_BASED	Specifies to automatically determine the first level based on the model size.
	0 <= Value <= MaxLevel	Specifies the first level, where MaxLevel is the maximum possible level. After preprocessing your Pattern Matching context, use MpatInquire() with M_MODEL_MAX_LEVEL to establish the maximum possible level. Only integer values are accepted. (summarize) Specifies the first level, where MaxLevel is the maximum possible level. (more details...)
M_LAST_LEVEL		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 (summarize) Sets the resolution level for the final stage (highest resolution) of the search. INQ (more details...)
	M_DEFAULT	Specifies the last level automatically.
	0 <= Value <= MaxLevel	Specifies the last level, where MaxLevel is the maximum possible level. After preprocessing your Pattern Matching context, use MpatInquire() with M_MODEL_MAX_LEVEL to establish the maximum possible level. Only integer values are accepted. (summarize) Specifies the last level, where MaxLevel is the maximum possible level. (more details...)
M_MAX_INITIAL_PEAKS		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 (summarize) 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 (more details...)
	M_DEFAULT	Specifies to limit the returned number of peaks for optimal performance.
	M_ALL	Specifies all occurrences that pass the model acceptance threshold should be returned. Performance might be reduced. It is recommended to use this setting when looking for a large number of occurrences or when the target image has many potential false positive occurrences. (summarize) Specifies all occurrences that pass the model acceptance threshold should be returned. (more details...)
M_MIN_SEPARATION_X		Sets the minimum separation (in X) between two models in order for them to be considered distinct. INQ (summarize) Sets the minimum separation (in X) between two models in order for them to be considered distinct. INQ (more details...)
	M_DEFAULT	Sets the minimum separation to 75% of the model width (Param3 of MpatDefine()) when creating a M_REGULAR_MODEL.
	1.0 <= Value <= 100.0	Specifies the minimum separation.
M_MIN_SEPARATION_Y		Sets the minimum separation (in Y) between two models in order for them to be considered distinct. INQ (summarize) Sets the minimum separation (in Y) between two models in order for them to be considered distinct. INQ (more details...)
	M_DEFAULT	Sets the minimum separation to 75% of the model height ( Param4 of MpatDefine()) when creating a M_REGULAR_MODEL).
	1.0 <= Value <= 100.0	Specifies the minimum separation.
M_MODEL_STEP		Sets whether all or every second pixel in the model is used in the correlation during the high resolution stage of the search. INQ (summarize) Sets whether all or every second pixel in the model is used in the correlation during the high resolution stage of the search. INQ (more details...)
	M_DEFAULT	Specifies to automatically establish the model step.
	1	Specifies to use all model pixels.
	2	Specifies to use every second model pixel (in both the X and Y directions). This speeds up the last (high resolution) stage of the search, particularly for large models. The match score can be affected if the model has many fine features, but will tend not to be affected if the model has mainly coarse features. (summarize) Specifies to use every second model pixel (in both the X and Y directions). (more details...)

The following control types and control values settings can be specified for a Pattern Matching result buffer. For controlling the settings of a Pattern Matching result buffer, the Index parameter must be set to M_GENERAL.

For the result buffer identifier
ControlType		Description
	ControlValue	Description
M_RESULT_OUTPUT_UNITS		Sets whether to return results in pixels or world units. This essentially sets the output coordinate system to use. The setting of this control type will only affect functions within this module which return positional results. This control type can be changed at any time to return results in the required output units. INQ (summarize) Sets whether to return results in pixels or world units. INQ (more details...)
	M_DEFAULT	Same as M_ACCORDING_TO_CALIBRATION.
	M_ACCORDING_TO_CALIBRATION	Specifies that results are returned in world units if the result was calculated on an image associated with a camera calibration context; otherwise, it specifies that results are returned in pixel units.
	M_PIXEL	Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
	M_WORLD	Specifies that results are returned in world units, with respect to the relative coordinate system. If world units are specified, calling MpatGetResult() generates an error if the result was not calculated on a calibrated image. (summarize) Specifies that results are returned in world units, with respect to the relative coordinate system. (more details...)
M_SAVE_SUMS		Sets whether to save the values of the sums used to compute the normalized correlation result for each model occurrence. INQ (summarize) Sets whether to save the values of the sums used to compute the normalized correlation result for each model occurrence. INQ (more details...)
	M_DISABLE	Specifies that the sums are not saved. This is the default value. (summarize) Specifies that the sums are not saved. (more details...)
	M_ENABLE	Specifies that the sums are saved.
M_TARGET_CACHING		Sets whether the pyramidal representation of the target buffer is kept in the result buffer or generated each time MpatFind() is called. INQ (summarize) Sets whether the pyramidal representation of the target buffer is kept in the result buffer or generated each time MpatFind() is called. INQ (more details...)
	M_DEFAULT	Same as M_ENABLE.
	M_DISABLE	Specifies that the pyramidal representation of the target buffer is generated each time MpatFind() is called.
	M_ENABLE	Specifies that the pyramidal representation of the target buffer is kept in the result buffer. Note that the pyramidal representation is generated upon the first call to MpatFind(). This pyramidal representation is re-used by consecutive calls to MpatFind() as long as the same result buffer is used and the image, search region, and model size are not modified. (summarize) Specifies that the pyramidal representation of the target buffer is kept in the result buffer. (more details...)

Type specific versions of the function when using a C compiler under 64-bit

void MpatControlInt64 (MIL_ID ContextOrResultPatId, MIL_INT Index, MIL_INT64 ControlType, MIL_INT64 ControlValue)

Details

Parameters

ContextOrResultPatId

See ContextOrResultPatId of the main function for a description.

Index

See Index of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

void MpatControlDouble (MIL_ID ContextOrResultPatId, MIL_INT Index, MIL_INT64 ControlType, MIL_DOUBLE ControlValue)

Details

Parameters

ContextOrResultPatId

See ContextOrResultPatId of the main function for a description.

Index

See Index of the main function for a description.

ControlType

See ControlType of the main function for a description.

ControlValue

See ControlValue of the main function for a description.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; milpat.lib.
DLL	Requires mil.dll; milpat.dll.