| MIL 10 Reference
| Customize Help
| Save Settings

MmeasSetScore


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
MmeasSetMarker
MmeasStream
Synopsis
Set a score characteristic of a marker.
Syntax
void MmeasSetScore(
MIL_ID MarkerId, //in
MIL_INT64 Characteristic, //in
MIL_DOUBLE Min, //in
MIL_DOUBLE Low, //in
MIL_DOUBLE High, //in
MIL_DOUBLE Max, //in
MIL_DOUBLE ScoreOffset, //in
MIL_INT64 InputUnits, //in
MIL_INT64 ControlFlag //in
)
Description

This function sets a score characteristic of a marker. MIL uses score characteristics to determine the best edge, stripe, or circle marker. This function only processes markers that have all the essential characteristics specified with MmeasSetMarker().

Unlike essential characteristics, which are either met or not, score characteristics can have a range of acceptable values; based on where the actual characteristic result falls within these specified limits, MIL calculates the characteristic's score. To calculate the final score of the marker itself (MmeasGetResult() with M_SCORE_TOTAL), MIL multiplies the score of all the marker's score characteristics. The marker with the highest final score is the one located by MmeasFindMarker().

To retrieve the characteristic's score, as well as other related information, such as the actual value of the characteristic (for example, the contrast of the marker in the image), you can use MmeasGetScore() with M_RESULT (after calling MmeasFindMarker()). To inquire the specified settings for a score characteristic, use MmeasGetScore() with M_MARKER.

To set the acceptable limits of a score characteristic, use the Min, Low, High, and Max parameters. The values for these parameters must adhere to the following conditions: Min <= Low <= High <= Max . If these conditions are not met, MIL generates an error. Characteristics that are greater than or equal to Low and less than or equal to High receive a score of 100%, while those that are greater than or equal to Min and less than Low, or greater than High and less than or equal to Max, receive a score above 0% and below 100%. Characteristics that are less than Min or greater than Max receive a score of 0% and are discarded.

You can set all limits except Min to M_MAX_POSSIBLE_VALUE, which represents a predetermined maximum established by MIL for that characteristic (the smallest possible value for any characteristic is always 0). Once a limit has been set to M_MAX_POSSIBLE_VALUE, all subsequent limits must also be set to M_MAX_POSSIBLE_VALUE. For example, if you are using M_EDGE_CONTRAST_SCORE, and set the Low parameter to M_MAX_POSSIBLE_VALUE, you must also set the High and Max parameters to M_MAX_POSSIBLE_VALUE.

By default, MIL only calculates the score of the marker's edge strength (M_STRENGTH_SCORE); therefore, the marker with the highest edgevalue (and all the essential characteristics) is found. When using another score characteristic to find the best marker, you might want to ignore the strength characteristic, to avoid its multiplicative influence. To do so, specify M_STRENGTH_SCORE and set Min and Low to 0, and set High and Max to M_MAX_POSSIBLE_VALUE.

You can reduce the influence of a characteristic on the total score by using a score offset. MIL calculates the lowest-possible nonzero score by subtracting the specified score-offset from 100% (100% - ScoreOffset = LowestPossibleScore). Since characteristics can, by default, score above 0%, the default score-offset is equivalent to 100% (calculated as, 100% - 100% = 0%). Unless you are developing an advanced application, the default is typically appropriate. Values below Min and above Max are set to 0, whereas values between Min and Low are mapped to scores between this LowestPossibleScore and 100%, and values between High and Max are mapped to scores between 100% and this LowestPossibleScore.

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
MarkerId

Specifies the identifier of the measurement marker for which to set the score characteristic.

Characteristic

Specifies the score characteristic to set.

The values in the table below are for specifying a score characteristic for an edge, stripe, or circle marker.

function map For specifying a score characteristic for an edge, stripe, or circle marker
CollapseValue Description
Collapse M_EDGE_CONTRAST_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the grayscale difference between the start and end of the intensity transition from which the marker's edge is established. To retrieve the start and end of the intensity transition, use MmeasGetResult() with M_EDGE_START and M_EDGE_END.

The theoretical limit of the greatest possible contrast value (M_MAX_POSSIBLE_VALUE) depends on the target image. For example, for an 8-bit image, the greatest possible contrast is 255.

(summarize)
Collapse M_EDGEVALUE_PEAK_CONTRAST_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the grayscale difference of the intensity transition between the first zero edgevalues on both sides of the established edge peak. To retrieve the minimum and maximum position of the edge peak, use MmeasGetResult() with M_EDGEVALUE_PEAK_POS_MIN and M_EDGEVALUE_PEAK_POS_MAX.

Note that some search regions might never have a zero edgevalue; in which case, you should use M_EDGE_CONTRAST_SCORE for a more meaningful result.

The theoretical limit of the greatest possible contrast value (M_MAX_POSSIBLE_VALUE) depends on the target image. For example, for an 8-bit image, the greatest possible contrast is 255; this corresponds to an edgevalue of 100.

(summarize)
Collapse M_STRENGTH_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the mean edgevalue (strength) of the marker.

The theoretical limit of the greatest possible edgevalue (M_MAX_POSSIBLE_VALUE) is 100.

(summarize)

The values in the table below are for specifying a score characteristic for an edge or stripe marker.

function map For specifying a score characteristic for an edge or stripe marker
CollapseValue Description
Collapse M_DISTANCE_FROM_BOX_ORIGIN_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the distance between the position of the box search region's origin and the position of the marker.

The theoretical limit of the greatest possible position-offset (M_MAX_POSSIBLE_VALUE) depends on the relevant dimension of the box search region (either the box's width or height, depending on the orientation). For a multiple marker, each occurrence must respect the specified limits; otherwise MIL discards the marker.

(summarize)
Collapse M_SPACING_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the typical distance (spacing) between consecutive edge or stripe occurrences of a multiple marker.

The theoretical limit of the greatest possible spacing value (M_MAX_POSSIBLE_VALUE) depends on the relevant dimension of the box search region (either the box's width or height, depending on the orientation).

(summarize)

The values in the table below are for specifying a score characteristic for a stripe marker.

function map For specifying a score characteristic for a stripe marker
CollapseValue Description
Collapse M_EDGE_INSIDE_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the number of edges inside a stripe marker.

The theoretical limit of the greatest possible number of edges (M_MAX_POSSIBLE_VALUE) is equivalent to half the relevant dimension of the box search region (either 0.5 x BoxWidth or 0.5 x BoxHeight, depending on the orientation).

(summarize)
Collapse M_STRIPE_WIDTH_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the distance (width) between the stripe's two outermost edges.

The theoretical limit of the greatest possible width value for the stripe (M_MAX_POSSIBLE_VALUE) depends on the relevant dimension of the box search region (either the box's width or height, depending on the orientation).

(summarize)

The values in the table below are for specifying a score characteristic for a circle marker.

function map For specifying a score characteristic for a circle marker
CollapseValue Description
Collapse M_RADIUS_SCORE

Specifies that MIL must calculate a score, as a percentage, based on the linear distance between the circle's center and its circumference (radius).

The theoretical limit of the greatest possible radius value for the circle (M_MAX_POSSIBLE_VALUE) is the length of the outer radius specified for the ring search region using MmeasSetMarker() with M_RING_RADII.

(summarize)
Min

Specifies the minimum limit, which MIL uses to calculate the characteristic's score. Any value less than the minimum limit receives a score of 0%.

For M_STRENGTH_SCORE, this value is set to 0 by default.

function map For specifying the minimum acceptable limit
CollapseValue Description
Collapse 0 <= Value < Low

Specifies the minimum acceptable limit.

The default value is 0.0.

(summarize)
Low

Specifies the low limit, which MIL uses to calculate the characteristic's score. Any value less than the lowest limit and greater than or equal to the minimum limit receives a score above 0% and below 100%, while any value greater than or equal to the lowest limit and less than or equal to the highest limit receives a score of 100%.

For M_STRENGTH_SCORE, this value is set to M_MAX_POSSIBLE_VALUE by default.

function map For specifying the low acceptable limit
CollapseValue Description
Collapse M_MAX_POSSIBLE_VALUE

Specifies that the low acceptable limit is equivalent to the greatest possible value.
Collapse Min <= Value <= High

Specifies the low acceptable limit.

The default value is 0.0.

(summarize)
High

Specifies the high limit, which MIL uses to calculate the characteristic's score. Any value greater than the highest limit and less than or equal to the maximum limit receives a score above 0% and below 100%.

For M_STRENGTH_SCORE, this value is set to M_MAX_POSSIBLE_VALUE by default.

function map For specifying the high acceptable limit
CollapseValue Description
Collapse M_MAX_POSSIBLE_VALUE

Specifies that the high acceptable limit is equivalent to the greatest possible value.

This is the default value.

(summarize)
Collapse Low <= Value <= Max

Specifies the high acceptable limit.
Max

Specifies the maximum limit, which MIL uses to calculate the characteristic's score. Any value greater than the maximum limit receives a score of 0%.

For M_STRENGTH_SCORE, this value is set to M_MAX_POSSIBLE_VALUE by default.

function map For specifying the maximum acceptable limit
CollapseValue Description
Collapse M_MAX_POSSIBLE_VALUE

Specifies that the maximum acceptable limit is equivalent to the greatest possible value.

This is the default value.

(summarize)
Collapse High <= Value <= M_MAX_POSSIBLE_VALUE

Specifies the maximum acceptable limit.
ScoreOffset

Specifies the characteristic's score-offset. This allows you to indirectly specify the lowest non-zero score that a characteristic can receive. The measurement module subtracts the score-offset from 100% to establish the lowest possible score assigned to values between Min and above Max and values between Min and Low.

function map For specifying the score-offset
CollapseValue Description
Collapse M_DEFAULT

Specifies the default value; the default value is 100.0%. This means that the lowest possible score is 0 (100%-100%=0).

(summarize)
Collapse 0.0 <= Value <= 100.0

Specifies the score-offset, as a percentage.
InputUnits

Specifies the units with which to interpret the Min, Low, High, and Max parameter values, when applicable. This essentially sets the input coordinate system to use.

You must set this parameter to M_DEFAULT for the following score characteristics: M_EDGE_CONTRAST_SCORE, M_EDGEVALUE_PEAK_CONTRAST_SCORE, M_EDGE_INSIDE_SCORE, and M_STRENGTH_SCORE. In these cases, M_DEFAULT indicates that the input unit information is not required.

function map For specifying the input units
CollapseValue Description
Collapse M_DEFAULT

Same as M_PIXEL, if the score characteristic's settings are affected by input units. Otherwise, M_DEFAULT specifies that the input unit information should be ignored.

(summarize)
Collapse M_PIXEL

Specifies that the values will be interpreted in pixel units, with respect to the pixel coordinate system.
Collapse M_WORLD

Specifies that the values will be interpreted in world units, with respect to the relative coordinate system. If world units are specified, calling MmeasFindMarker() generates an error if the operation is not performed on a calibrated image.

(summarize)
ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Compilation information
Header Include mil.h.
Library Use mil.lib; milmeas.lib.
DLL Requires mil.dll; milmeas.dll.
EDGE CONTRAST SCORE EDGEVALUE PEAK CONTRAST SCORE STRENGTH SCORE DISTANCE FROM BOX ORIGIN SCORE SPACING SCORE EDGE INSIDE SCORE STRIPE WIDTH SCORE RADIUS SCORE MAX POSSIBLE VALUE MAX POSSIBLE VALUE MAX POSSIBLE VALUE MAX POSSIBLE VALUE DEFAULT DEFAULT PIXEL WORLD STRIPE EDGE CIRCLE EDGE CONTRAST SCORE EDGEVALUE PEAK CONTRAST SCORE EDGE INSIDE SCORE STRENGTH SCORE