| MIL 10 Reference
| Customize Help
| Save Settings

MpatInquire


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
MpatGetResult
MpatPreprocModel
Synopsis
Inquire about the pattern matching model or the result buffer parameter setting.
Syntax
MIL_INT MpatInquire(
MIL_ID PatId, //in
MIL_INT64 InquireType, //in
void *UserVarPtr //out
)
Description

This function returns information about the specified model or result buffer. It is useful to determine, for example, the size of a model that has been restored from disk and its position in the model's source image.

The position (M_ORIGINAL_X and M_ORIGINAL_Y) can be directly compared with search results (by MpatFindModel() or MpatFindMultipleModel()), to calculate the displacement of target images relative to the model's source image.

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 or result buffer for which to read the information.

InquireType

Specifies the parameter about which to inquire.

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

UserVarPtr
Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):
  • MIL_DOUBLE
  • MIL_ID
  • MIL_INT
  • MIL_INT32
  • MIL_INT64

Specifies the address in which to write the requested information. Since this function also returns the requested information, you can set this parameter to M_NULL.

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

Parameter associations

The tables below list possible values for the InquireType parameter and possible values returned to the UserVarPtr parameter.

For a model identifier, the InquireType parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a model identifier
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_ACCEPTANCE_THRESHOLD +

Inquires the minimum acceptable match score to be considered as an occurrence of the model. SET

(summarize)
Collapse Value

Specifies the acceptance level.
Collapse M_ALLOC_OFFSET_X +

Inquires the X-offset of model's top-left corner relative to the top-left corner of the model's source image. SET

(summarize)
Collapse Value

Specifies the X-offset.
Collapse M_ALLOC_OFFSET_Y +

Inquires the Y-offset of model's top-left corner relative to the top-left corner of the model's source image. SET

(summarize)
Collapse Value

Specifies the Y-offset.
Collapse M_ALLOC_SIZE_X +

Inquires the model width. SET

(summarize)
Collapse Value

Specifies the width.
Collapse M_ALLOC_SIZE_Y +

Inquires the model height. SET

(summarize)
Collapse Value

Specifies the height.
Collapse M_ALLOC_TYPE +

Inquires the model type. SET

(summarize)
Collapse M_NORMALIZED +

Specifies a model used to search for the position, match score, and angle (if angular search is enabled) of a model occurrence in a target image, using MpatFindModel() and MpatFindMultipleModel().
Collapse M_CENTER_X +

Inquires the X-offset of the model's reference position relative to the top-left corner of model. SET

(summarize)
Collapse Value

Specifies the X-offset of the model's reference position.
Collapse M_CENTER_Y +

Inquires the Y-offset of the model's reference position relative to the top-left corner of model. SET

(summarize)
Collapse Value

Specifies the Y-offset of the model's reference position.
Collapse M_CERTAINTY_THRESHOLD +

Inquires the match score at which an occurrence is assumed, without looking for better matches elsewhere in the image. SET

(summarize)
Collapse Value

Specifies the certainty level.
Collapse M_COARSE_SEARCH_ACCEPTANCE +

Inquires the minimum acceptable match score at all levels except the last level, to be considered as an occurrence of the model. SET

(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. INFO
Collapse M_EXTRA_CANDIDATES +

Inquires the number of extra candidates to consider as possible candidates. SET

(summarize)
Collapse Value

Specifies the number of extra candidates. INFO
Collapse M_FAST_FIND +

Inquires whether forcing or preventing fast peak finding is used. SET

(summarize)
Collapse M_DISABLE

Specifies not to use fast peak finding. INFO
Collapse M_ENABLE

Specifies to use fast peak finding. INFO
Collapse M_FIRST_LEVEL +

Inquires the resolution level for the initial stage of the search.

To determine the maximum possible level, use MpatInquire() with M_MODEL_MAX_LEVEL. Use MpatInquire() with M_PROC_FIRST_LEVEL to inquire about the default value of the lowest resolution level. SET

(summarize)
Collapse 0 <= Value <= MaxLevel

Specifies the first level, where MaxLevel is the maximum possible level. INFO
Collapse M_LAST_LEVEL +

Inquires the resolution level for the final stage of the search.

To determine the maximum possible level, use MpatInquire() with M_MODEL_MAX_LEVEL. SET

(summarize)
Collapse 0 <= Value <= MaxLevel

Specifies the last level, where MaxLevel is the maximum possible level. INFO
Collapse M_MAX_INITIAL_PEAKS +

Inquires the maximum number of peaks returned after a first level search for occurrences of multiple models or M_CIRCULAR_OVERSCAN type models. SET

(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. INFO
Collapse M_MIN_SPACING_X +

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

(summarize)
Collapse 1.0 <= Value <= 100.0

Specifies the minimum spacing.
Collapse M_MIN_SPACING_Y +

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

(summarize)
Collapse 1.0 <= Value <= 100.0

Specifies the minimum spacing.
Collapse M_MODEL_MAX_LEVEL +

Inquires the maximum search level possible for the model.

(summarize)
Collapse Value >= 7

Specifies the maximum search level possible for the model.
Collapse M_MODEL_STEP +

Inquires whether all or every second model pixel is used in the high-resolution stage of the search. SET

(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). INFO
Collapse M_NUMBER_OF_OCCURRENCES +

Inquires the number of model occurrences for which to search in the target image. SET

(summarize)
Collapse M_ALL

Specifies to look for all matches that are greater than or equal to the acceptance level.
Collapse 1 <= Value <= 1000

Specifies the maximum number of occurrences for which to look in the target image.
Collapse M_ORIGINAL_X +

Inquires the X-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting).

(summarize)
Collapse Value

Specifies the X-offset.
Collapse M_ORIGINAL_Y +

Inquires the Y-offset of the model's reference position relative to the top-left corner of the model's source image (takes into account the MpatSetCenter() setting).

(summarize)
Collapse Value

Specifies the Y-offset.
Collapse M_POSITION_ACCURACY +

Inquires the search position accuracy. SET

(summarize)
Collapse M_HIGH

Specifies a high accuracy (typically ± 0.05 pixels).
Collapse M_LOW

Specifies a low accuracy (typically ± 0.20 pixels). INFO
Collapse M_MEDIUM

Specifies a medium accuracy (typically ± 0.10 pixels).
Collapse M_POSITION_START_X +

Inquires the X-coordinate of search region origin within target image. SET

(summarize)
Collapse M_ALL

Specifies the X-coordinate of the top-left corner of the target image to allow a search of the full image.
Collapse Value

Specifies the X-coordinate, relative to the pixel coordinate system.
Collapse M_POSITION_START_Y +

Inquires the Y-coordinate of search region origin within target image. SET

(summarize)
Collapse M_ALL

Specifies the Y-coordinate of the top-left corner of the target image to allow a search of the full image.
Collapse Value

Specifies the Y-coordinate, relative to the pixel coordinate system.
Collapse M_POSITION_UNCERTAINTY_X +

Inquires the search region width. SET

(summarize)
Collapse M_ALL

Specifies the width of the full image.
Collapse Value

Specifies the width, in pixels.
Collapse M_POSITION_UNCERTAINTY_Y +

Inquires the search region height. SET

(summarize)
Collapse M_ALL

Specifies the height of the full image.
Collapse Value

Specifies the height, in pixels.
Collapse M_PREPROCESSED +

Inquires whether the pattern matching model is preprocessed. The model must be preprocessed (using MpatPreprocModel()) before calling MpatFind...(). After some of the search parameters of the pattern matching model are changed with MpatSet...(), this inquire type will indicate that the model is no longer in its preprocessed state.

(summarize)
Collapse 0

Specifies that the model is not preprocessed.
Collapse 1

Specifies that the model is preprocessed.
Collapse M_PROC_FIRST_LEVEL +

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

(summarize)
Collapse 0 <= Value <= MaxLevel

Specifies the lowest resolution level, where MaxLevel is the maximum level. To establish the maximum level, use MpatInquire() with M_MODEL_MAX_LEVEL.

(summarize)
Collapse M_PROC_LAST_LEVEL +

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

(summarize)
Collapse 0 <= Value <= MaxLevel

Specifies the highest resolution level, where MaxLevel is the maximum level. To establish the maximum level, use MpatInquire() with M_MODEL_MAX_LEVEL.

(summarize)
Collapse M_ROTATED_MODEL_MINIMUM_SCORE +

Inquires whether angle refinement mode is used and returns its score. SET

(summarize)
Collapse M_DEFAULT

Same as M_DISABLE.
Collapse M_DISABLE

Specifies to disable the angle refinement mode.
Collapse 0.0 <= Value <= 100.0

Specifies the minimum score.
Collapse M_SEARCH_ANGLE +

Inquires the value of the initial search angle. SET

(summarize)
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse M_SEARCH_ANGLE_ACCURACY +

Inquires the angular accuracy. SET

(summarize)
Collapse M_DISABLE

Specifies that the angular accuracy equals the tolerance.
Collapse 0.1 <= Value <= 180.0

Specifies the angle accuracy, in degrees.
Collapse M_SEARCH_ANGLE_DELTA_NEG +

Inquires the difference that determines the lower limit of the search angle's range. SET

(summarize)
Collapse 0.0 <= Value <= 180.0

Specifies the angle, in degrees.
Collapse M_SEARCH_ANGLE_DELTA_POS +

Inquires the difference that determines the upper limit of the search angle's range. SET

(summarize)
Collapse 0.0 <= Value <= 180.0

Specifies the angle, in degrees.
Collapse M_SEARCH_ANGLE_INTERPOLATION_MODE +

Inquires the interpolation mode. SET

(summarize)
Collapse M_BICUBIC

Specifies that bicubic interpolation is used when rotating the model.
Collapse M_BILINEAR

Specifies that bilinear interpolation is used when rotating the model.
Collapse M_NEAREST_NEIGHBOR

Specifies that nearest neighbor interpolation is used when rotating the model.
Collapse M_SEARCH_ANGLE_MODE +

Inquires the state of the angular search mode. SET

(summarize)
Collapse M_DISABLE

Specifies to disable the angular search mode.
Collapse M_ENABLE

Specifies to enable the angular search mode.
Collapse M_SEARCH_ANGLE_TOLERANCE +

Inquires 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. SET

(summarize)
Collapse M_AUTO

Specifies that the tolerance will be automatically determined based on an analysis of the model.
Collapse 0.1 <= Value <= 180.0

Specifies that the given angle is the 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. INFO
Collapse M_SPEED +

Inquires the model search speed. SET

(summarize)
Collapse M_HIGH

Specifies a high search speed.
Collapse M_LOW

Specifies a low search speed.
Collapse M_MEDIUM

Specifies a medium search speed.
Collapse M_VERY_HIGH

Specifies a very high search speed.
Collapse M_VERY_LOW

Specifies a very low search speed.
Combination constant for M_NORMALIZED (when InquireType=M_ALLOC_TYPE and UserVarPtr=M_NORMALIZED).

The following value might be combined with the above-mentioned value to determine whether circular overscan data was extracted with the model.

function map Returns whether circular overscan data was extracted with the model
CollapseCombination value Description
Collapse M_CIRCULAR_OVERSCAN

Specifies that the model is extracted from the source image with the circular overscan data. INFO

For a result buffer identifier, the InquireType parameter can be set to one of the values below.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For a result buffer identifier
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_NUMBER_OF_ENTRIES +

Inquires the number of entries allocated in the result buffer. SET

(summarize)
Collapse M_DEFAULT

Specifies that the number of entries will be allocated dynamically to match the number of actual occurrences found at runtime.
Collapse Value

Specifies the number of result entries to allocate. INFO
Collapse M_RESULT_OUTPUT_UNITS +

Inquires whether results are returned in pixel or world units. SET

(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. INFO
Collapse M_SAVE_SUMS +

Inquires whether the values of the sums used to compute the normalized correlation function for each model occurrence are saved. SET

(summarize)
Collapse M_DISABLE

Specifies that the sums are not saved.
Collapse M_ENABLE

Specifies that the sums are saved.
Collapse M_TARGET_CACHING +

Inquires whether the pyramidal representation of the buffer is kept in the result buffer. SET

(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. INFO

For inquiring the system on which the model or result buffer is allocated, set this parameter to the following value.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE.

function map For inquiring the system on which the model or result buffer is allocated
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_OWNER_SYSTEM +

Inquires the system on which the model or result buffer is allocated. SET SET

(summarize)
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().

You can add one of the following values to the above-mentioned values to cast the requested information to the required data type.

function map For casting information to the required data type.
CollapseInquireType Description
UserVarPtr
- Possible values returned
Collapse M_TYPE_MIL_DOUBLE

Casts the requested information to a MIL_DOUBLE.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_TYPE_MIL_ID

Casts the requested information to a MIL_ID.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_ID

Collapse M_TYPE_MIL_INT

Casts the requested information to a MIL_INT.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT

Collapse M_TYPE_MIL_INT32

Casts the requested information to a MIL_INT32.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT32

Collapse M_TYPE_MIL_INT64

Casts the requested information to a MIL_INT64.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_INT64

Return value
The returned value is the requested information, cast to a MIL_INT.
Compilation information
Header Include mil.h.
Library Use mil.lib; milpat.lib.
DLL Requires mil.dll; milpat.dll.
ACCEPTANCE THRESHOLD ALLOC OFFSET X ALLOC OFFSET Y ALLOC SIZE X ALLOC SIZE Y ALLOC TYPE NORMALIZED CENTER X CENTER Y CERTAINTY THRESHOLD COARSE SEARCH ACCEPTANCE DEFAULT EXTRA CANDIDATES FAST FIND DISABLE ENABLE FIRST LEVEL LAST LEVEL MAX INITIAL PEAKS DEFAULT ALL MIN SPACING X MIN SPACING Y MODEL MAX LEVEL MODEL STEP DEFAULT NUMBER OF OCCURRENCES ALL ORIGINAL X ORIGINAL Y POSITION ACCURACY HIGH LOW MEDIUM POSITION START X ALL POSITION START Y ALL POSITION UNCERTAINTY X ALL POSITION UNCERTAINTY Y ALL PREPROCESSED PROC FIRST LEVEL PROC LAST LEVEL ROTATED MODEL MINIMUM SCORE DEFAULT DISABLE SEARCH ANGLE SEARCH ANGLE ACCURACY DISABLE SEARCH ANGLE DELTA NEG SEARCH ANGLE DELTA POS SEARCH ANGLE INTERPOLATION MODE BICUBIC BILINEAR NEAREST NEIGHBOR SEARCH ANGLE MODE DISABLE ENABLE SEARCH ANGLE TOLERANCE AUTO SPEED HIGH LOW MEDIUM VERY HIGH VERY LOW CIRCULAR OVERSCAN NUMBER OF ENTRIES DEFAULT RESULT OUTPUT UNITS DEFAULT ACCORDING TO CALIBRATION PIXEL WORLD SAVE SUMS DISABLE ENABLE TARGET CACHING DEFAULT DISABLE ENABLE OWNER SYSTEM DEFAULT HOST TYPE MIL DOUBLE TYPE MIL ID TYPE MIL INT TYPE MIL INT32 TYPE MIL INT64