| MIL 10 Reference
| Customize Help
| Save Settings

MmodGetResult


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
MmodFree
MmodInquire
Synopsis
Get the specified type of result(s) from a Model Finder result buffer.
Syntax
void MmodGetResult(
MIL_ID ResultId, //in
MIL_INT ResultIndex, //in
MIL_INT64 ResultType, //in
void *ResultArrayPtr //out
)
Description

This function retrieves the result(s) of the specified type from a Model Finder result buffer. Results are only available after calling MmodFind().

The result entries will be ordered by match score, starting with the highest score (regardless of the result type requested). When searching for multiple models, results are not sorted according to which model occurrence was found; results are still sorted according to score. The M_INDEX result type returns the index of the model associated with the Model Finder result; whereas the M_USER_LABEL result type returns its user label.

If your target image was associated with a calibration context, positional and dimensional results are, by default, returned with respect to the relative coordinate system of the image. Otherwise, these results are returned in pixels, relative to the top-left pixel in the target image.

If your target image was associated with a calibration context but you want to retrieve positional and dimensional results in pixel units, use MmodControl() with the M_RESULT_OUTPUT_UNITS control type set to M_PIXEL. However, note that if you set M_RESULT_OUTPUT_UNITS to M_WORLD without specifying a calibrated image in which to calculate the results, MmodGetResult() will generate an error.

If the target is not calibrated and the nominal search aspect ratio is not set to 1 (MmodControl() with M_ASPECT_RATIO), results are returned for the corrected target coordinate system (whereby the target pixel width is equal to the pixel height).

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
ResultId

Specifies the identifier of the Model Finder result buffer from which to retrieve results.

ResultIndex

Specifies where to get results. This parameter can be set to one of the following:

function map For specifying where to get results
CollapseValue Description
Collapse M_DEFAULT

Same as M_ALL for result types that apply to one or all occurrences. Same as M_GENERAL for general result types.

(summarize)
Collapse M_ALL

Retrieves the results of the specified type for all model occurrences found.
Collapse M_GENERAL

Retrieves a result relating to the entire Model Finder context.
Collapse 0 <= Value < M_NUMBER

Specifies the result index.
ResultType

Specifies the type of result to retrieve.

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

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

Specifies the address in which to write results.

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

Parameter associations

The tables below list possible values for the ResultType parameter and possible values returned to the ResultArrayPtr parameter.

When retrieving a general result, the ResultType parameter can be set to one of the following values.

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

function map For general results
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_CONTEXT_ID +

Retrieves the identifier of the Model Finder context used by MmodFind() to obtain the results in the result buffer. Note that this identifier might not be valid if the Model Finder context has been freed using MmodFree().

(summarize)
Collapse M_MOD_DEFINE_COMPATIBLE +

Retrieves whether the result can be used to define a model.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_FALSE

Specifies that the result cannot be used to define a model.
Collapse M_TRUE

Specifies that the result can be used to define a model.
Collapse M_NUMBER +

Retrieves the number of occurrences found (all models).

(summarize)
Collapse M_TIMEOUT_END +

Retrieves whether the timeout has been reached. You can set the timeout limit using MmodControl() with M_TIMEOUT. By default, there is no limit.

(summarize)
Collapse M_FALSE

Specifies that the timeout has not been reached.
Collapse M_TRUE

Specifies that the timeout has been reached.

When retrieving a general result, a result for an individual occurrence, or a result for all occurrences (M_ALL), the ResultType parameter can be set to the following value.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of a MIL_DOUBLE (when retrieving an individual occurrence or a general result) or the address of an array of type MIL_DOUBLE with a size equal to the number of occurrences found; this number can be obtained using MmodGetResult() with M_NUMBER (when retrieving all results).

function map For an individual occurrence or a general result
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_NUMBER_OF_CHAINED_EDGELS +

Retrieves the total number of chained edgels.

For a general result, M_NUMBER_OF_CHAINED_EDGELS returns the number of chained edgels in the target.

For a specified occurrence, M_NUMBER_OF_CHAINED_EDGELS returns the chained edgels in the occurrence. When used with M_ALL, an array of results is returned, with one result per occurrence.

You can use M_NUMBER_OF_CHAINED_EDGELS to determine the required array size for the M_CHAIN_... result types.

M_NUMBER_OF_CHAINED_EDGELS is not supported for a general result if the Model Finder context uses a controlled geometric search algorithm.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)

When retrieving a general result or result(s) for a single occurrence, the ResultType parameter can be set to one of the following values.

When retrieving a general result, the following values are not supported if the Model Finder context is an M_GEOMETRIC_CONTROLLED type of context.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of an array of type MIL_DOUBLE with a size equal to the number of chained edgels. This number can be obtained using MmodGetResult() with M_NUMBER_OF_CHAINED_EDGELS .

function map For a general result for a single occurrence
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_CHAIN_ANGLE +

Retrieves the angle values of each edgel in all chains in the entire target or in the model occurrence.

The angle is always returned in uncalibrated pixel units and is measured counter-clockwise in the image, from the positive X-axis towards the negative Y-axis of the image.

Possible values range from 0 to 360 degrees and mapped in the range of 0 to 255 (that is, an 8-bit range).

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_CHAIN_INDEX +

Retrieves the chain index of each edgel in all chains in the entire target, or in the model occurrence.

The first chain in the target is identified as index 1, with increasing indices for subsequent chains.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_CHAIN_X +

Retrieves the X-coordinate of each edgel in all chains in the entire target or in the model occurrence.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_CHAIN_Y +

Retrieves the Y-coordinate of each edgel in all chains in the entire target or in the model occurrence.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)

You can add one of the following values to the above-mentioned values to specify the edges for which to retrieve results.

function map For specifying which edges in the occurrence to consider
CollapseCombination value Description
Collapse M_MODEL

Retrieves the edge information of the model transformed at the occurrence position.
Collapse M_TARGET

Retrieves the edge information of the target in the region of the occurrence. When using M_TARGET, you must not set the ResultIndex parameter to M_GENERAL.

(summarize)

When retrieving a result for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of a MIL_DOUBLE (when retrieving an individual occurrence) or the address of an array of type MIL_DOUBLE with a size equal to the number of occurrences found; this number can be obtained using MmodGetResult() with M_NUMBER (when retrieving all results).

function map For a result for a single occurrence or all occurrences
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_ANGLE +

Retrieves the angle of the occurrence's reference axis (specified for the model using MmodControl() with M_REFERENCE_ANGLE), relative to the output coordinate system specified using MmodControl() with M_RESULT_OUTPUT_UNITS.

An angle interpreted with respect to the pixel coordinate system is always measured counter-clockwise. For information on the angle's direction of rotation when interpreting the angle with respect to the relative coordinate system, see the Angle convention in MIL subsection of the Working with real-world units section of Chapter 25: Calibrating your camera setup.

(summarize)
Collapse M_ASPECT_RATIO +

Retrieves the found aspect ratio of all occurrences.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_CENTER_X +

Retrieves the X-coordinate of the center of an occurrence of a circle model.

This result type is only supported for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_CENTER_Y +

Retrieves the Y-coordinate of the center of an occurrence of a circle model.

This result type is only supported for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_FIT_ERROR +

Retrieves the fit error as the average quadratic distance, in pixels or calibrated units, between the edges in the occurrence and the corresponding edges in the model. A perfect fit is represented as 0.0.

(summarize)
Collapse M_INDEX +

Retrieves the index of the model that was found.

(summarize)
Collapse M_MODEL_COVERAGE +

Retrieves the model coverage of the occurrence. The model coverage is the percentage of the total length of the model's active edges found in the occurrence. 100% indicates that for every active edge in the model, a corresponding edge was found in the occurrence.

Note that using a weighted mask with a model affects the calculation of the model coverage. To view the modified equation, refer to the Determining what is a match section of Chapter 7: Geometric Model Finder.

(summarize)
Collapse M_POLARITY +

Retrieves the polarity of the occurrence.

(summarize)
Collapse M_ANY

Specifies that the occurrences are a mixture of polarities. For more information, see MmodControl() with M_POLARITY and M_ANY.

(summarize)
Collapse M_REVERSE

Specifies that the polarity of occurrences is the reverse of that of the model. For more information, see MmodControl() with M_POLARITY and M_REVERSE.

(summarize)
Collapse M_SAME

Specifies that the polarity of occurrences is the same as that of the model. For more information, see MmodControl() with M_POLARITY and M_SAME.

(summarize)
Collapse M_POSITION_X +

Retrieves the X-coordinate of the occurrence. This is the X-position of the model's reference axis transformed at the occurrence (MmodControl() with M_REFERENCE_X).

(summarize)
Collapse M_POSITION_Y +

Retrieves the Y-coordinate of the occurrence. This is the Y-position of the model's reference axis transformed at the occurrence (MmodControl() with M_REFERENCE_Y).

(summarize)
Collapse M_SCALE +

Retrieves the scale of the occurrence.

(summarize)
Collapse M_SCORE +

Retrieves the score of the occurrence (as a percentage). The score is calculated as follows:

Score = Model coverage x (1 - Fit error weighting factor * Normalized fit error).

Note: the normalized fit error is the fit error (M_FIT_ERROR) converted to a number between 0.0-1.0 for an M_GEOMETRIC or M_GEOMETRIC_CONTROLLED type of Model Finder context, while for an M_SHAPE_CIRCLE type of Model Finder context, the normalized fit error is influenced by the value of M_SAGITTA_TOLERANCE and is not limited to being between 0.0 and 1.0. For all Model Finder context types, the terms within the square brackets result in a number between 0.0 and 1.0.

(summarize)
Collapse M_SCORE_TARGET +

Retrieves the target score of the occurrence. The target score is calculated as follows:

Target Score = Target coverage x (1 - Fit error weighting factor * Normalized fit error).

Note that the normalized fit error (M_FIT_ERROR) is the fit error converted to a number between 0.0 and 1.0.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_TARGET_COVERAGE +

Retrieves the target coverage of the model. The target coverage is a percentage of the total length of edges present within the occurrence's bounding box, corresponding to the model's active edges. Lower scores indicate that features or edges found in the target (result occurrence) are not present in the model.

Note that using a weighted mask with a model affects the calculation of the target coverage. To view the modified equation, refer to the Determining what is a match section of Chapter 7: Geometric Model Finder.

This result type is not available for an M_SHAPE_CIRCLE type of Model Finder result buffer.

(summarize)
Collapse M_USER_LABEL +

Retrieves the user label of the model that was found.

(summarize)
Collapse M_NO_LABEL

Specifies that no user label is associated with the model.
Collapse Value

Specifies the user label of the model. INFO

When retrieving a result for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values. The following values are not available for all model types. For one of these values to be available for a result occurrence, the result occurrence must be of the appropriate type. Use M_AVAILABLE to ensure that the value can be used with the occurrence. If the ResultIndex parameter is set to M_ALL, all the occurrences must support the result type, otherwise an error is generated.

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of a MIL_DOUBLE (when retrieving an individual occurrence) or the address of an array of type MIL_DOUBLE with a size equal to the number of occurrences found; this number can be obtained using MmodGetResult() with M_NUMBER (when retrieving all results).

function map For a result for a single occurrence or all occurrences (with constraints)
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_CORNER_RADIUS +

Retrieves the radius used to round the corners of the models. This control type is only valid for models of type M_RECTANGLE, M_SQUARE, M_DIAMOND, M_TRIANGLE, and M_CROSS.

(summarize)
Collapse M_HEIGHT +

Retrieves the height of the shape. This result type is only available for M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE and M_TRIANGLE.

(summarize)
Collapse M_HORIZONTAL_THICKNESS +

Retrieves the horizontal thickness of the cross. This result type is only available for M_CROSS.

(summarize)
Collapse M_INNER_RADIUS +

Retrieves the inner radius of the ring. This result type is only available for M_RING.

(summarize)
Collapse M_OUTER_RADIUS +

Retrieves the outer radius of the ring. This result type is only available for M_RING.

(summarize)
Collapse M_RADIUS +

Retrieves the radius of the circle. This result type is only available for M_CIRCLE.

(summarize)
Collapse M_VERTICAL_THICKNESS +

Retrieves the vertical thickness of the cross. This result type is only available for M_CROSS.

(summarize)
Collapse M_WIDTH +

Retrieves the width of the shape. This result type is only available for M_CROSS, M_DIAMOND, M_ELLIPSE, M_RECTANGLE, M_SQUARE and M_TRIANGLE.

(summarize)

To retrieve a transformation coefficient for a single occurrence or for all occurrences, the ResultType parameter can be set to one of the following values. These coefficients allow you to convert coordinates in the model coordinate system to the corresponding coordinates in the target coordinate system for that occurrence (or vice versa). These coefficients handle variations in scale, translation, and angle. If the model is calibrated, these coefficients are given for the real world.

Use the following equations:

x d = A x s + B y s + C .

y d = -B x s + A y s + D .

where A, B, C, and D are the transformation coefficients (forward or reverse); x s and y s specify the source coordinates (with respect to the origin of the model coordinate system for a forward transformation or target coordinate system for a reverse transformation); and, x d and y d are the destination coordinates (with respect to the origin of the target coordinate system for a forward transformation or model coordinate system for a reverse transformation).

Unless otherwise specified, the following values require that you pass the ResultArrayPtr parameter the address of a MIL_DOUBLE (when retrieving an individual occurrence) or the address of an array of type MIL_DOUBLE with a size equal to the number of occurrences found; this number can be obtained using MmodGetResult() with M_NUMBER (when retrieving all results).

function map For retrieving a transformation coefficient
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_A_FORWARD +

Retrieves the forward transformation coefficient A for the occurrence.

(summarize)
Collapse M_A_REVERSE +

Retrieves the reverse transformation coefficient A for the occurrence.

(summarize)
Collapse M_B_FORWARD +

Retrieves the forward transformation coefficient B for the occurrence.

(summarize)
Collapse M_B_REVERSE +

Retrieves the reverse transformation coefficient B for the occurrence.

(summarize)
Collapse M_C_FORWARD +

Retrieves the forward transformation coefficient C for the occurrence.

(summarize)
Collapse M_C_REVERSE +

Retrieves the reverse transformation coefficient C for the occurrence.

(summarize)
Collapse M_D_FORWARD +

Retrieves the forward transformation coefficient D for the occurrence.

(summarize)
Collapse M_D_REVERSE +

Retrieves the reverse transformation coefficient D for the occurrence.

(summarize)

You can add the following value to the above-mentioned values to specify whether a result is available.

function map For determining whether results are available
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_AVAILABLE

Retrieves whether a result is available to be returned.

(summarize)
Collapse ResultArrayPtr data type info

Data type: MIL_DOUBLE

Collapse M_NULL

Specifies that the result is not available to be retrieved.
Collapse Value != 0

Specifies that the result is available to be retrieved.

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

function map For specifying the data type
CollapseResultType Description
ResultArrayPtr
- Possible values returned
Collapse M_TYPE_MIL_DOUBLE

Casts the requested results to a MIL_DOUBLE.

(summarize)
Collapse ResultArrayPtr data type info

  • Data type: array of type MIL_DOUBLE
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_DOUBLE
    Note: When a single result.
Collapse M_TYPE_MIL_ID

Casts the requested results to a MIL_ID.

(summarize)
Collapse ResultArrayPtr data type info

  • Data type: array of type MIL_ID
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_ID
    Note: When a single result.
Collapse M_TYPE_MIL_INT

Casts the requested results to a MIL_INT.

(summarize)
Collapse ResultArrayPtr data type info

  • Data type: array of type MIL_INT
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_INT
    Note: When a single result.
Collapse M_TYPE_MIL_INT32

Casts the requested results to a MIL_INT32.

(summarize)
Collapse ResultArrayPtr data type info

  • Data type: array of type MIL_INT32
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_INT32
    Note: When a single result.
Collapse M_TYPE_MIL_INT64

Casts the requested results to a MIL_INT64.

(summarize)
Collapse ResultArrayPtr data type info

  • Data type: array of type MIL_INT64
    Array size: Depends on the result type.
    Note: When multiple results.

  • Data type: MIL_INT64
    Note: When a single result.
Compilation information
Header Include mil.h.
Library Use mil.lib; milmod.lib.
DLL Requires mil.dll; milmod.dll.
DEFAULT ALL GENERAL NUMBER CONTEXT ID MOD DEFINE COMPATIBLE FALSE TRUE NUMBER TIMEOUT END FALSE TRUE NUMBER OF CHAINED EDGELS CHAIN ANGLE CHAIN INDEX CHAIN X CHAIN Y MODEL TARGET ANGLE ASPECT RATIO CENTER X CENTER Y FIT ERROR INDEX MODEL COVERAGE POLARITY ANY REVERSE SAME POSITION X POSITION Y SCALE SCORE SCORE TARGET TARGET COVERAGE USER LABEL NO LABEL CORNER RADIUS HEIGHT HORIZONTAL THICKNESS INNER RADIUS OUTER RADIUS RADIUS VERTICAL THICKNESS WIDTH A FORWARD A REVERSE B FORWARD B REVERSE C FORWARD C REVERSE D FORWARD D REVERSE AVAILABLE NULL TYPE MIL DOUBLE TYPE MIL ID TYPE MIL INT TYPE MIL INT32 TYPE MIL INT64 GENERAL DEFAULT GENERAL ALL DEFAULT GENERAL GENERAL DEFAULT ALL