| MIL 10 Reference
| Customize Help
| Save Settings

MbeadGetResult



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
Synopsis
Get results from a bead result buffer.
Syntax
void MbeadGetResult(
MIL_ID ResultBeadId, //in
MIL_INT LabelOrIndex, //in
MIL_INT ResultIndex, //in
MIL_INT64 ResultType, //in
void *UserVarPtr //out
)
Description

This function retrieves results of the specified type from a bead result buffer. Results are only available after calling MbeadVerify().

Results for the specified bead template or trained point are based on how they compare with their corresponding measured bead or measured point in the verification's target image. The returned results are ordered by the label value of their template.

If your target image was associated with a calibration context, positional and dimensional results are returned with respect to the relative coordinate system of the target image. Otherwise, these results are returned in pixels, relative to the top-left pixel in the target 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
ResultBeadId

Specifies the identifier of the bead result buffer from which to get results.

LabelOrIndex

Specifies the label or index of the template for which to get results, or specifies that you are getting general results related to all templates. This parameter must be set to one of the following values:

function map For specifying where you are getting results
CollapseValue Description
Collapse

Specifies the index of the template for which to get results.

(summarize)
Parameters

Specifies the index. Valid indices range from 0 (the first template) to the number of defined templates minus 1.

Collapse

Specifies the label of the template for which to get results.

(summarize)
Parameters

Specifies the label. The label must be greater than 0.

Collapse M_GENERAL

Specifies to get general results related to all templates.

ResultIndex

Specifies the trained points (one or all) for which to get results or specifies that you are getting general results. This parameter must be set to one of the following values:

function map For specifying the trained points for which to get results or for specifying general results
CollapseValue Description
Collapse M_DEFAULT

Same as M_GENERAL.

Collapse M_ALL

Specifies to get results for each trained point in the template.

In this case, the LabelOrIndex parameter must be set to M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL().

(summarize)
Collapse M_GENERAL

Specifies to get general results.

To get general results related to all templates, the LabelOrIndex parameter must be set to M_GENERAL.

To get general results related to a specific template, the LabelOrIndex parameter must be set to M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL().

(summarize)
Collapse Value

Specifies the index of the trained point for which to get results. Valid indices range from 0 (the first point) to the total number of trained points in the template minus 1. To get the number of trained points in the template, use MbeadGetResult() with M_NUMBER.

When specifying the index of the trained point, the LabelOrIndex parameter must be set to M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL().

(summarize)
ResultType

Specifies the result to get.

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):
  • 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 the requested information.

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

To get the status of results, the ResultType parameter can be set to the following value.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE (when retrieving the status of results related to all templates, a single template, or a single trained point) or the address of an array of type MIL_DOUBLE with a size equal to M_NUMBER (when retrieving the status of results related to each trained point in a template).

function map For retrieving the status of results
CollapseResultType Description
UserVarPtr
- Possible values returned
Collapse M_STATUS +

Retrieves whether results have passed or failed verification.

To retrieve the status of results related to all templates, you must set the LabelOrIndex and the ResultIndex parameter to M_GENERAL. In this case, you will get a passing status only if all status results (M_STATUS_...) of all templates have passed verification.

To retrieve the status of results related to a specific template, you must set the LabelOrIndex parameter to the label or index of the template and the ResultIndex parameter to M_GENERAL. In this case, you will get a passing status only if the template's corresponding measured bead has passed all of the following: M_STATUS_GAP_TOLERANCE, M_STATUS_GAP_MAX, and M_STATUS_SCORE.

To retrieve the status of results related to one or all trained points, you must set the LabelOrIndex parameter to the label or index of a template and the ResultIndex parameter to a specific value or M_ALL. In this case, you will get a passing status only if the trained point's corresponding measured point has passed all of the following: M_STATUS_SEARCH, M_STATUS_FOUND, M_STATUS_OFFSET, M_STATUS_WIDTH_MAX, M_STATUS_WIDTH_MIN, and M_STATUS_GAP_MAX.

(summarize)
Collapse M_FAIL

Specifies that the results have not passed verification.

Collapse M_PASS

Specifies that the results have passed verification.

To retrieve the number of templates or the number of trained points in a template, the ResultType parameter can be set 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 retrieving the number of templates or the number of trained points in a template
CollapseResultType Description
UserVarPtr
- Possible values returned
Collapse M_NUMBER +

Retrieves the number of templates or the number of trained points in a template. To retrieve the number of templates, you must set the LabelOrIndex and the ResultIndex parameters to M_GENERAL. To retrieve the number of trained points in a template, you must set the LabelOrIndex parameter to the index or label of the template and the ResultIndex parameter to M_GENERAL.

(summarize)

To retrieve results related to a template's corresponding measured bead, the ResultType parameter should be set to one of the following values. In this case, you must set the LabelOrIndex parameter to the index or label of the template for which to get results (M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL()) and the ResultIndex parameter to M_GENERAL.

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

function map For retrieving results related to a template (measured bead)
CollapseResultType Description
UserVarPtr
- Possible values returned
Collapse M_CLOSURE +

Retrieves whether the measured bead is closed.

(summarize)
Collapse M_FALSE

Specifies that the measured bead is not closed.

Collapse M_TRUE

Specifies that the measured bead is closed.

Collapse M_GAP_COVERAGE +

Retrieves the percentage of the total gap in the measured bead, relative to the length of the expected measured bead.

(summarize)
Collapse M_GAP_MAX_LENGTH +

Retrieves the length of the longest uninterrupted chain of trained points that were not found in the bead.

(summarize)
Collapse M_INTENSITY_MAX +

Retrieves the maximum pixel intensity of the measured bead.

(summarize)
Collapse M_INTENSITY_MAX_INDEX +

Retrieves the index of the trained point that corresponds to the maximum intensity of the measured bead.

(summarize)
Collapse M_INVALID

Specifies that MIL could not establish a maximum pixel intensity. This can occur if, for example, no bead was found in the target image.

(summarize)
Collapse Value

Specifies the index of the trained point that corresponds to the maximum intensity.

Collapse M_INTENSITY_MIN +

Retrieves the minimum pixel intensity of the measured bead.

(summarize)
Collapse M_INTENSITY_MIN_INDEX +

Retrieves the index of the trained point that corresponds to the minimum intensity of the measured bead.

(summarize)
Collapse M_INVALID

Specifies that MIL could not establish a minimum pixel intensity. This can occur if, for example, no bead was found in the target image.

(summarize)
Collapse Value

Specifies the index of the trained point that corresponds to the minimum intensity.

Collapse M_LABEL_VALUE +

Retrieves the label of the template corresponding to the index specified with M_TEMPLATE_INDEX().

(summarize)
Collapse M_NUMBER_FOUND +

Retrieves the number of trained points that have a corresponding measured point in the bead.

(summarize)
Collapse M_OFFSET_MAX +

Retrieves the maximum linear distance between the position of a trained point and the position of its corresponding measured point.

(summarize)
Collapse M_OFFSET_MAX_INDEX +

Retrieves the index of the trained point that represents the maximum offset of the measured bead.

(summarize)
Collapse M_INVALID

Specifies that MIL could not establish a maximum offset. This can occur if, for example, no bead was found in the target image.

(summarize)
Collapse Value > 0

Specifies the index of the trained point that corresponds to the maximum offset.

Collapse M_SCORE +

Retrieves the percentage of trained points that have a corresponding measured point with a passing status, relative to the total number of trained points in the template.

(summarize)
Collapse M_STATUS_GAP_TOLERANCE +

Retrieves whether the M_GAP_COVERAGE result has passed or failed the gap tolerance criterion, as specified using MbeadControl() with M_GAP_TOLERANCE.

(summarize)
Collapse M_FAIL

Specifies that the result is greater than the gap tolerance criterion.

Collapse M_PASS

Specifies that the result is less than or equal to the gap tolerance criterion.

Collapse M_STATUS_SCORE +

Retrieves whether the M_SCORE result has passed or failed the acceptance criterion, as specified using MbeadControl() with M_ACCEPTANCE.

(summarize)
Collapse M_FAIL

Specifies that the result is greater than the acceptance criterion.

Collapse M_PASS

Specifies that the result is less than or equal to the acceptance criterion.

Collapse M_WIDTH_AVERAGE +

Retrieves the average width of the measured bead.

(summarize)
Collapse M_WIDTH_MAX +

Retrieves the maximum width of the measured bead.

(summarize)
Collapse M_WIDTH_MAX_INDEX +

Retrieves the index of the trained point that corresponds to the maximum width of the measured bead.

(summarize)
Collapse M_INVALID

Specifies that MIL could not establish a maximum width. This can occur if, for example, no bead was found in the target image.

(summarize)
Collapse Value

Specifies the index of the trained point that corresponds to the maximum width.

Collapse M_WIDTH_MIN +

Retrieves the minimum width of the measured bead.

(summarize)
Collapse M_WIDTH_MIN_INDEX +

Retrieves the index of the trained point that corresponds to the minimum width of the measured bead.

(summarize)
Collapse M_INVALID

Specifies that MIL could not establish a minimum width. This can occur if, for example, no bead was found in the target image.

(summarize)
Collapse Value

Specifies the index of the trained point that corresponds to the minimum width.

To retrieve results related to a trained point's (one or all) corresponding measured point, the ResultType parameter should be set to one of the following values. In this case, you must set the LabelOrIndex parameter to the index or label of the template for which to get results (M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL()) and the ResultIndex parameter to a specific value or M_ALL.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE (when retrieving results related to a single trained point) or the address of an array of type MIL_DOUBLE with a size equal to M_NUMBER (when retrieving results related to all trained points).

function map For retrieving results related to trained points (measured points)
CollapseResultType Description
UserVarPtr
- Possible values returned
Collapse M_ANGLE +

Retrieves the angle of the measured bead at the position of the measured point.

(summarize)
Collapse M_INTENSITY +

Retrieves the intensity of the measured bead at the position of the measured point. This value is only supported for stripe-beads.

(summarize)
Collapse M_OFFSET +

Retrieves the linear distance between the trained point and its corresponding measured point.

(summarize)
Collapse M_POSITION_X +

Retrieves the X-coordinate of the measured point. The position is taken at the center of the bead width, at that point.

(summarize)
Collapse M_POSITION_Y +

Retrieves the Y-coordinate of the measured point. The position is taken at the center of the bead width, at that point.

(summarize)
Collapse M_STATUS_SEARCH +

Retrieves whether MIL considers it possible to establish the measured point, given the current settings. For example, if the search box corresponding to a measured point falls outside the target image, MIL returns M_FAIL since you can never establish a measured point that is beyond the boundaries of the image.

(summarize)
Collapse M_FAIL

Specifies that MIL considers it impossible to establish the measured point.

Collapse M_PASS

Specifies that MIL considers it possible to establish the measured point.

Collapse M_TRAINED_INDEX +

Retrieves the index of the trained point that corresponds to the measured point. This can be useful to get the indices of all trained points (M_ALL).

(summarize)
Collapse M_TRAINED_POSITION_X +

Retrieves the X-position of the trained point.

(summarize)
Collapse M_TRAINED_POSITION_Y +

Retrieves the Y-position of the trained point.

(summarize)
Collapse M_WIDTH_VALUE +

Retrieves the width of the measured bead at the position of the measured point. This value is only supported for stripe-beads.

(summarize)

To retrieve results related to a template's corresponding measured bead, or to a trained point's (one or all) corresponding measured point, the ResultType parameter can be set to one of the following values. In this case, you must set the LabelOrIndex parameter to the index or label of the template for which to get results (M_TEMPLATE_INDEX() or M_TEMPLATE_LABEL()). When retrieving results related to a template, you must set the ResultIndex parameter to M_GENERAL. When retrieving results related to the trained points, you must set the ResultIndex parameter to a specific value or M_ALL.

Unless otherwise specified, the following values require that you pass the UserVarPtr parameter the address of a MIL_DOUBLE (when retrieving results related to a template or a trained point) or the address of an array of type MIL_DOUBLE with a size equal to M_NUMBER (when retrieving results related to all trained points).

function map For retrieving results related to a template (measured bead) or to trained points (measured points)
CollapseResultType Description
UserVarPtr
- Possible values returned
Collapse M_STATUS_FOUND +

Retrieves the found status of the related template or trained point.

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all trained points have a corresponding measured point (all were found). Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether the corresponding measured point was found. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_GAP_MAX +

Retrieves whether the M_GAP_MAX_LENGTH result has passed or failed the maximum gap criterion, as specified using MbeadControl() with M_GAP_MAX_LENGTH.

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if the longest uninterrupted chain of trained points that were not found in the measured bead is less than M_GAP_MAX_LENGTH. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its associated measured point was not found, and is part of a gap that has failed the maximum gap criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_INTENSITY_MAX +

Retrieves whether the M_INTENSITY result has passed or failed the criterion for the highest pixel intensity allowed, as specified using MbeadControl() with NominalIntensity + M_INTENSITY_DELTA_POS. This value is only supported for stripe-beads. The nominal intensity can either be established by the training phase (M_AUTO) or with an explicit value (M_INTENSITY_NOMINAL).

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all measured points have an intensity that is lower than the highest intensity allowed. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its corresponding measured point has failed or passed the maximum color criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_INTENSITY_MIN +

Retrieves whether the M_INTENSITY result has passed or failed the criterion for the lowest intensity allowed, as specified using MbeadControl() with NominalIntensity - M_INTENSITY_DELTA_NEG. This value is only supported for stripe-beads. The nominal intensity can either be established by the training phase (M_AUTO) or with an explicit value (M_INTENSITY_NOMINAL).

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all measured points have an intensity that is higher than the lowest intensity allowed. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its measured point has failed or passed the minimum color criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_OFFSET +

Retrieves whether the M_OFFSET result has passed or failed the maximum offset criterion, as specified using MbeadControl() with M_OFFSET_MAX.

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all measured points pass the maximum offset criterion. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its measured point has failed or passed the maximum offset criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_WIDTH_MAX +

Retrieves whether the M_WIDTH_VALUE result has passed or failed the maximum width criterion, as specified using MbeadControl() with M_TRAINING_WIDTH_NOMINAL + M_WIDTH_DELTA_POS.

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all measured points pass the maximum width criterion. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its measured point has failed or passed the maximum width criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

Collapse M_STATUS_WIDTH_MIN +

Retrieves whether the M_WIDTH_VALUE result has passed or failed the minimum width criterion, as specified using MbeadControl() with M_TRAINING_WIDTH_NOMINAL - M_WIDTH_DELTA_NEG.

If you set the ResultIndex parameter to M_GENERAL, M_PASS is returned if all measured points pass the minimum width criterion. Otherwise, M_FAIL is returned.

If you set the ResultIndex parameter to M_ALL, M_FAIL or M_PASS is returned for each trained point, depending on whether its measured point has failed or passed the minimum width criterion. If you set the ResultIndex parameter to a specific trained point, only the status of that point is returned.

(summarize)
Collapse M_FAIL

Specifies a failing status.

Collapse M_PASS

Specifies a passing status.

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
UserVarPtr
- Possible values returned
Collapse M_AVAILABLE

Retrieves whether a result is available to be returned.

(summarize)
Collapse UserVarPtr data type info

Data type: MIL_DOUBLE

Collapse M_NULL

Specifies that the result is not available to be returned.

Collapse Value != 0

Specifies that the result is available to be returned.

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
UserVarPtr
- Possible values returned
Collapse M_TYPE_MIL_DOUBLE

Casts the requested results to a MIL_DOUBLE.

(summarize)
Collapse UserVarPtr 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 UserVarPtr 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 UserVarPtr 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 UserVarPtr 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 UserVarPtr 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; milbead.lib.
DLL Requires mil.dll; milbead.dll.
NUMBER OF TEMPLATES GENERAL DEFAULT ALL GENERAL STATUS FAIL PASS NUMBER CLOSURE FALSE TRUE GAP COVERAGE GAP MAX LENGTH INTENSITY MAX INTENSITY MAX INDEX INVALID INTENSITY MIN INTENSITY MIN INDEX INVALID LABEL VALUE NUMBER FOUND OFFSET MAX OFFSET MAX INDEX INVALID SCORE STATUS GAP TOLERANCE FAIL PASS STATUS SCORE FAIL PASS WIDTH AVERAGE WIDTH MAX WIDTH MAX INDEX INVALID WIDTH MIN WIDTH MIN INDEX INVALID ANGLE INTENSITY OFFSET POSITION X POSITION Y STATUS SEARCH FAIL PASS TRAINED INDEX TRAINED POSITION X TRAINED POSITION Y WIDTH VALUE STATUS FOUND FAIL PASS STATUS GAP MAX FAIL PASS STATUS INTENSITY MAX FAIL PASS STATUS INTENSITY MIN FAIL PASS STATUS OFFSET FAIL PASS STATUS WIDTH MAX FAIL PASS STATUS WIDTH MIN FAIL PASS AVAILABLE NULL TYPE MIL DOUBLE TYPE MIL ID TYPE MIL INT TYPE MIL INT32 TYPE MIL INT64 GENERAL GENERAL DEFAULT GENERAL GENERAL DEFAULT ALL ALL