| MIL 10 Reference
| Customize Help
| Save Settings

MpatSetSearchParameter


See also
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
Available on Matrox Supersight
function map Function map
Examples
MpatSetPosition
MpatSetSpeed
Synopsis
Set the internal search parameters of a model.
Syntax
void MpatSetSearchParameter(
MIL_ID PatId, //in
MIL_INT64 Parameter, //in
MIL_DOUBLE Value //in
)
Description

This function is for advanced users of the pattern matching module. It need not be used under most circumstances because the default settings usually provide the best results for search operations. However, if the default values do not satisfy the requirements of your application, this function can be used to set the model's internal search parameters. These internal search parameters are normally derived from the speed and accuracy settings (see MpatSetSpeed() and MpatSetAccuracy()), but this function gives the experienced user precise control over them. To gain a clearer understanding of how the search algorithm works, see Chapter 6: Pattern matching.

Note that if some of the model's search parameters are changed after a call to MpatPreprocModel(), the model must be preprocessed again. To inquire if your model is in a preprocessed state, use the MpatInquire() function with M_PREPROCESSED.

Note that all of the model's internal parameters, except M_COARSE_SEARCH_ACCEPTANCE, are saved and restored with the model, just like the other parameters such as search region, speed, and accuracy.

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
PatId

Specifies the identifier of the model whose search parameter to change, or of the result buffer.

Parameter

Specifies the search parameter to set.

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

Value

Specifies the value to which to set the specified parameter.

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

Parameter associations

The tables below list possible values for the Parameter and Value parameters.

The values below are for a model identifier.

function map For a model identifier
CollapseParameter Description
Value
Collapse M_ALL

Sets all search parameters automatically from the current speed and accuracy settings.

(summarize)
Collapse M_DEFAULT

Specifies all search parameters.
Collapse M_ALLOC_OFFSET_X

Sets the model's allocation X-offset.

(summarize)
Collapse Value

Specifies the X-offset.

This might be useful when the original value is lost after rotating a model. You can use MpatInquire() to inquire about the current X-offset. This value can be any integer.

The default value is 0.

(summarize)
Collapse M_ALLOC_OFFSET_Y

Sets the model's allocation Y-offset.

(summarize)
Collapse Value

Specifies the Y-offset.

This might be useful when the original value is lost after rotating the model. You can use MpatInquire() to inquire about the current Y-offset. This value can be any integer.

The default value is 0.

(summarize)
Collapse M_COARSE_SEARCH_ACCEPTANCE

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

(summarize)
Collapse M_DEFAULT

Specifies to determine the coarse search acceptance threshold level automatically.
Collapse 1.0 <= Value <= 100.0

Specifies the coarse search acceptance threshold level.

This can speed up the search when some of the matches you request do not reach the certainty threshold, 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 model. So, if you always want to use your own coarse search acceptance level, you should set it each time after restoring your model and before calling MpatFindModel(). Otherwise, the default coarse search acceptance level is used.

(summarize)
Collapse M_EXTRA_CANDIDATES

Sets the number of extra candidates to consider. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.
Collapse Value

Specifies the number of extra candidates. This value can be any integer.

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 parameter allows you to add robustness to the algorithm, by considering more candidates, without compromising too heavily on search speed.

(summarize)
Collapse M_FAST_FIND

Sets whether to use fast peak finding. INQ

(summarize)
Collapse M_DEFAULT

Specifies to use preprocessing to decide if fast peak finding is appropriate.
Collapse 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)
Collapse 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)
Collapse 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. Use MpatInquire() with M_PROC_FIRST_LEVEL to inquire about the default value of the lowest resolution level. INQ

(summarize)
Collapse M_DEFAULT

Same as M_AUTO_SIZE_BASED.
Collapse M_AUTO_CONTENT_BASED

Specifies the first level based on an analysis of the model contents.
Collapse M_AUTO_SIZE_BASED

Specifies the first level based on the model size.
Collapse 0 <= Value <= MaxLevel

Specifies the first level, where MaxLevel is the maximum possible level. Use MpatInquire() with M_MODEL_MAX_LEVEL to establish the maximum possible level.

(summarize)
Collapse 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. Use MpatInquire() with M_PROC_LAST_LEVEL to inquire about the default value of the highest resolution level. INQ

(summarize)
Collapse M_DEFAULT

Specifies the last level automatically.
Collapse 0 <= Value <= MaxLevel

Specifies the last level, where MaxLevel is the maximum possible level. Use MpatInquire() with M_MODEL_MAX_LEVEL to establish the maximum possible level.

(summarize)
Collapse 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 M_CIRCULAR_OVERSCAN type models.

This control only has an effect when searching for occurrences of an M_CIRCULAR_OVERSCAN type model or for multiple models.

(summarize)
Collapse M_DEFAULT

Specifies to limit the returned number of peaks for optimal performance.
Collapse 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)
Collapse M_MIN_SPACING_X

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

(summarize)
Collapse M_DEFAULT

Sets the minimum spacing to 75% of the model width (SizeX of MpatAlloc...()).
Collapse 1.0 <= Value <= 100.0

Specifies the minimum spacing.
Collapse M_MIN_SPACING_Y

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

(summarize)
Collapse M_DEFAULT

Sets the minimum spacing to 75% of the model height (SizeY of MpatAlloc...()).
Collapse 1.0 <= Value <= 100.0

Specifies the minimum spacing.
Collapse 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)
Collapse M_DEFAULT

Specifies the model step automatically.
Collapse 1

Specifies all model pixels.
Collapse 2

Specifies 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)

The values below are for a result buffer identifier.

function map For a result buffer identifier
CollapseParameter Description
Value
Collapse 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)
Collapse M_DEFAULT

Same as M_ACCORDING_TO_CALIBRATION.
Collapse M_ACCORDING_TO_CALIBRATION

Specifies that results are returned in world units if the result was calculated on an image associated with a calibration context; otherwise, specifies that results are returned in pixel units.
Collapse M_PIXEL

Specifies that results are returned in pixel units, with respect to the pixel coordinate system.
Collapse M_WORLD

Specifies that results are returned in world units, with respect to the relative coordinate system. If world units are specifed, calling MpatGetResult() generates an error if the result was not calculated on a calibrated image.

(summarize)
Collapse M_SAVE_SUMS

Sets whether to save the values of the sums used to compute the normalized correlation function for each model occurrence. INQ

(summarize)
Collapse M_DISABLE

Specifies that the sums are not saved.

This is the default value.

(summarize)
Collapse M_ENABLE

Specifies that the sums are saved.
Collapse M_TARGET_CACHING

Sets whether the pyramidal representation of the buffer is called or kept in the result buffer. INQ

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.
Collapse M_DISABLE

Specifies that the pyramidal representation of the buffer is generated each time MpatFindModel() or MpatFindMultipleModel() is called.
Collapse M_ENABLE

Specifies that the pyramidal representation of the buffer (generated when MpatFindModel() or MpatFindMultipleModel() is called) is kept in the result buffer.

This pyramidal representation is re-used by consecutive calls to MpatFindModel() and MpatFindMultipleModel() as long as the same result buffer is used and the image, search region, and model size are not modified.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milpat.lib.
DLL Requires mil.dll; milpat.dll.
ALL DEFAULT ALLOC OFFSET X ALLOC OFFSET Y COARSE SEARCH ACCEPTANCE DEFAULT EXTRA CANDIDATES DEFAULT FAST FIND DEFAULT DISABLE ENABLE FIRST LEVEL DEFAULT AUTO CONTENT BASED AUTO SIZE BASED LAST LEVEL DEFAULT MAX INITIAL PEAKS DEFAULT ALL MIN SPACING X DEFAULT MIN SPACING Y DEFAULT MODEL STEP DEFAULT RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD SAVE SUMS DISABLE ENABLE TARGET CACHING DEFAULT DISABLE ENABLE