MmeasSetScore

See also

User Guide:

Circle markers: basic and advanced characteristics that should or can be specified Edge markers: advanced characteristics that can be specified Marker characteristics Measurement examples Multiple-occurrence marker characteristics Score characteristics Search algorithm Search results Stripe markers: advanced characteristics that can be specified

Reference:

MmeasFindMarker MmeasGetResult MmeasGetScore MmeasInquire MmeasSetMarker

Availability

Not available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer

Available on Matrox 4Sight-X

Available on Matrox 4Sight GP/GPm

Available on Matrox Supersight

Function map

Examples

advancedmeasurement.cpp
circlemeasurement.cpp
foodinspectioncereal.cpp
gumpackinspection.cpp
mcal.cpp
mcal.cs
mcal.vb
measadvancedoverview.cpp
meascircleoverview.cpp
measstripeoverview.cpp
mmeas.cpp
mmeas.cs
mmeas.vb

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 which MIL system’s documentation you should use in its place and any possible differences.

Parameters

This function is not supported on the selected boards.

This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

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.

For specifying a score characteristic for an edge, stripe, or circle marker
Value	Description
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) 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. (more details...)
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) 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. (more details...)
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) Specifies that MIL must calculate a score, as a percentage, based on the mean edgevalue (strength) of the marker. (more details...)

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

For specifying a score characteristic for an edge or stripe marker
Value	Description
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-occurrence marker, each occurrence must respect the specified limits; otherwise MIL discards the marker. (summarize) 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. (more details...)
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-occurrence 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) 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-occurrence marker. (more details...)

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

For specifying a score characteristic for a stripe marker
Value	Description
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) Specifies that MIL must calculate a score, as a percentage, based on the number of edges inside a stripe marker. (more details...)
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) Specifies that MIL must calculate a score, as a percentage, based on the distance (width) between the stripe's two outermost edges. (more details...)

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

For specifying a score characteristic for a circle marker
Value	Description
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) Specifies that MIL must calculate a score, as a percentage, based on the linear distance between the circle's center and its circumference (radius). (more details...)

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.

For specifying the minimum acceptable limit
Value	Description
0 <= Value < Low	Specifies the minimum acceptable limit. The default value is 0.0. (summarize) Specifies the minimum acceptable limit. (more details...)

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.

For specifying the low acceptable limit
Value	Description
M_MAX_POSSIBLE_VALUE	Specifies that the low acceptable limit is equivalent to the greatest possible value.
Min <= Value <= High	Specifies the low acceptable limit. The default value is 0.0. (summarize) Specifies the low acceptable limit. (more details...)

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.

For specifying the high acceptable limit
Value	Description
M_MAX_POSSIBLE_VALUE	Specifies that the high acceptable limit is equivalent to the greatest possible value. This is the default value. (summarize) Specifies that the high acceptable limit is equivalent to the greatest possible value. (more details...)
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.

For specifying the maximum acceptable limit
Value	Description
M_MAX_POSSIBLE_VALUE	Specifies that the maximum acceptable limit is equivalent to the greatest possible value. This is the default value. (summarize) Specifies that the maximum acceptable limit is equivalent to the greatest possible value. (more details...)
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.

For specifying the score-offset
Value	Description
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) Specifies the default value; the default value is 100.0%. (more details...)
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.

For specifying the input units
Value	Description
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) Same as M_PIXEL, if the score characteristic's settings are affected by input units. (more details...)
M_PIXEL	Specifies that the values will be interpreted in pixel units, with respect to the pixel coordinate system.
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) Specifies that the values will be interpreted in world units, with respect to the relative coordinate system. (more details...)

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.

Table:	For specifying a score characteristic for an edge, stripe, or circle marker
Table:	For specifying a score characteristic for an edge or stripe marker
Table:	For specifying a score characteristic for a stripe marker
Table:	For specifying a score characteristic for a circle marker