MmeasGetResult

Retrieves the number of points, edges, stripes, or circles measured. Note that edges, stripes, and circles are searched for, but points are placed manually. For circle markers, M_NUMBER will never return a value greater than one, since circles cannot be defined as a multiple-occurrence marker.

If you are getting results from a measurement result buffer, and you are using two multiple-occurrence markers that have a different number of occurrences, MIL uses the fewest number of occurrences to calculate results (MmeasCalculate()).

After a call to the MmeasFindMarker() function, this number is equal to the number of occurrences of a marker found in the search region.

After a call to the MmeasCalculate() function, this number is equal to the smallest number of occurrences held in either marker involved in the calculation.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the angle for each marker occurrence, in degrees. The angle is relative to the output coordinate system specified using M_RESULT_OUTPUT_UNITS with either MmeasSetMarker() (for a measurement marker buffer) or MmeasControl() (for a measurement result buffer).

If retrieved from a measurement marker buffer, M_ANGLE returns the angle of the line measured for the edge. For a stripe marker, this line follows the center of the stripe and is calculated as the mean of the lines following its edges. If the result is requested for a specific edge of the stripe, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, the angle of the first or second edge is returned, respectively.

If retrieved from a measurement result buffer, M_ANGLE returns the angle of the lines joining each of the occurrences of the two markers, relative to the positive X-axis.

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 26: Calibrating your camera setup.

Retrieves the coefficient A of the line equation, for each marker occurrence. The line equation is of the general form, Ax + By + C = 0.

If retrieved from an edge marker, M_LINE_A returns the coefficient A of the line measured for the edge. For a stripe marker, this line follows the center of the stripe, and is calculated as the mean of the lines following its edges. If the result is requested for a specific edge of the stripe, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, the coefficient A of the line equation of the first or second edge, respectively, is returned.

If retrieved from a measurement result buffer, M_LINE_A returns the coefficient A of the line joining each occurrence of the two markers.

Retrieves the coefficient B of the line equation, for each marker occurrence. The line equation is of the general form, Ax + By + C = 0.

If retrieved from an edge marker, M_LINE_B returns the coefficient B of the line measured for the edge. For a stripe marker, this line follows the center of the stripe, and is calculated as the mean of the lines following its edges. If the result is requested for a specific edge of the stripe, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, the coefficient B of the line equation of the first or second edge, respectively, is returned.

If retrieved from a measurement result buffer, M_LINE_B returns the coefficient B of the line joining each occurrence of the two markers.

Retrieves the coefficient C of the line equation, for each marker occurrence. The line equation is of the general form, Ax + By + C = 0.

If retrieved from an edge marker, M_LINE_C returns the coefficient C of the line measured for the edge. For a stripe marker, this line follows the center of the stripe, and is calculated as the mean of the lines following its edges. If the result is requested for a specific edge of the stripe, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, the coefficient C of the line equation of the first or second edge, respectively, is returned.

If retrieved from a measurement result buffer, M_LINE_C returns the coefficient C of the lines joining each occurrence of the two markers.

Retrieves the X- and Y-coordinates of the position, for each marker occurrence.

For point markers, the position refers to the X- and Y-coordinates specified using MmeasSetMarker() with M_POSITION.

For edge markers, the position refers to the X- and Y-coordinates of the edge's maximum edgevalue (highest edge peak).

For stripe markers, the position refers to the X- and Y-coordinates at the center of a theoretical line between the position (maximum edgevalue) of the stripe's two outermost edges. If you use M_EDGE_FIRST or M_EDGE_SECOND, you will get the X- and Y-coordinates of that edge's maximum edgevalue (highest edge peak).

For circle markers, the position refers to the X- and Y-coordinates at the circle's center.

Retrieves whether the marker was found, or that the coordinates of a point marker (MmeasAllocMarker() with M_POINT) are set to a valid position.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the maximum distance from a subedge to the fitted line equation (for edge or stripe markers) or to the fitted circle (for circle markers), for each marker occurrence. This distance is called the maximum fit error. If you did not specify subregions (for edges or stripes), M_FIT_ERROR_MAX returns 0. Note that circles always have subregions.

Retrieves the number of subedges considered outliers, for each marker occurrence. Outliers are subedges within the search region that do not contribute to marker's fit operation since they are considered to be too far away from the general distribution of subedges. The number of outliers corresponds to the number of fitted subedges subtracted from the number of subregions.

Use M_SUB_EDGES_MARKER_INDEX to establish the occurrence to which the subedge belongs.

Retrieves whether the marker's search region was clipped. This value is only useful if you enabled clipping (MmeasSetMarker() with M_SEARCH_REGION_CLIPPING).

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the index of the occurrence on which each subedge is located, for each marker occurrence. If a subedge is not found in a subregion, an arbitrary number is returned. Use M_SUB_EDGES_WEIGHT to determine if a subedge was actually found.

This result is useful when retrieving subedge-type of results for a multiple-occurrence marker. For example, you can use the index to separate, by marker, the values obtained with M_SUB_EDGES_POSITION and M_SUB_EDGES_WEIGHT.

Retrieves the X- and Y-coordinates of the subedges, for each marker occurrence.

If a subedge is not found in a subregion, the X- and Y- positions will be arbitrary numbers. Use M_SUB_EDGES_WEIGHT to determine whether a subedge was found.

Use M_SUB_EDGES_MARKER_INDEX to establish the occurrence to which the subedge belongs.

Retrieves the weight of the subedges, for each marker occurrence. The weight indicates whether a subedge was found in the subregion. Found subedges are used to calculate the fit, angle, and line equation values.

Use M_SUB_EDGES_MARKER_INDEX to establish the occurrence to which the subedge belongs.

Retrieves the number of subregions used.

Note that if you did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to perform certain measurements.

Retrieves the angle found for the box search region when the angle is internally determined by MIL. In this case, you must have specified M_ANY as the angle of the box search region (MmeasSetMarker() with M_BOX_ANGLE) or enabled an angular search (M_BOX_ANGLE_MODE set to M_ENABLE).

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 26: Calibrating your camera setup.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the coordinates of the bottom-left corner of the marker's box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the result will take that rotation into account.

Note that this result type always returns one set of values (X- and Y-positions), even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the coordinates of the bottom-right corner of the marker's box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the result will take that rotation into account.

Note that this result type always returns one set of values (X- and Y-positions), even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the coordinates of the top-left corner of the marker's box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the result will take that rotation into account.

Note that this result type always returns one set of values (X- and Y-positions), even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the coordinates of the top-right corner of the marker's box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the result will take that rotation into account.

Note that this result type always returns one set of values (X- and Y-positions), even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the edgevalues of the marker's box search region.

MIL establishes edgevalues by applying a first derivative filter to the search region's intensity profile and normalizing the output according to the number of pixels and the maximum pixel value possible. To establish the intensity profile, MIL projects the pixels bounded by the two-dimensional search region (or each subregion) into a one-dimensional pixel intensity summation, which is performed vertically or horizontally, depending on the search region's origin and search direction.

Retrieves the number of edgevalues that M_BOX_EDGEVALUES returns. This value corresponds to the number of pixels along the width or height of the marker's box search region, depending on the search region's origin and search direction.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the position, as a distance value relative to the origin of the box search region, for each marker occurrence.

Retrieves the scale and offset used to draw a profile.

Retrieves the grayscale difference between the start (M_EDGE_START) and end (M_EDGE_END) of the intensity transition from which the edge is established, for each marker occurrence.

Retrieves the X- and Y-coordinates of the end of the edge (that is, the end of the intensity transition from which the edge is established), for each marker occurrence. For a stripe marker, the coordinates representing the average value of end positions is returned unless otherwise specified by the combination value M_EDGE_FIRST or M_EDGE_SECOND.

In the intensity profile calculated for a search region, M_EDGE_START represents the first significant slope used to establish the edge, while M_EDGE_END represents the first significant slope in the opposite direction used to establish the edge. Depending on the search region's origin and search direction, the edge's start and end can be on either side of the edge.

To retrieve the minimum and maximum position of the edge peak of the marker, use M_EDGEVALUE_PEAK_POS_MIN and M_EDGEVALUE_PEAK_POS_MAX.

Retrieves the number of edges located between the two exterior edges of a stripe, for each marker occurrence. This result only applies to stripes.

Retrieves the X- and Y-coordinates of the start of the edge (that is, the start of the intensity transition from which the edge is established), for each marker occurrence. For a stripe marker, the coordinates representing the average value of start positions is returned unless otherwise specified by the combination value M_EDGE_FIRST or M_EDGE_SECOND.

In the intensity profile calculated for a search region, M_EDGE_START represents the first significant slope used to establish the edge, while M_EDGE_END represents the first significant slope in the opposite direction used to establish the edge. Depending on the search region's origin and search direction, the edge's start and end can be on either side of the edge.

To retrieve the minimum and maximum position of the edge peak of the marker, use M_EDGEVALUE_PEAK_POS_MIN and M_EDGEVALUE_PEAK_POS_MAX.

Retrieves the greatest edgevalue of the edge, for each marker occurrence. The greatest edgevalue of an edge is considered to be its edge strength.

Retrieves the distance between the start (M_EDGE_START) and end (M_EDGE_END) of the intensity transition from which the edge is established, for each marker occurrence.

To retrieve the width of the edge established by the edge peak of the marker, use M_EDGEVALUE_PEAK_WIDTH.

Retrieves the grayscale difference of the intensity transition between the first zero edgevalues on both sides of the established edge peak (before M_EDGEVALUE_PEAK_POS_MIN, and after M_EDGEVALUE_PEAK_POS_MAX), for each marker occurrence.

Note that some images might never have a zero edgevalue, in which case you should use M_EDGE_CONTRAST for a more meaningful result.

Retrieves the X- and Y-coordinates of the maximum value of the edge peak (that is, the maximum edgevalue along the first derivative representation of the intensity profile), known as the summit, for each marker occurrence. For a stripe marker, the coordinates representing the average value of maximum positions is returned unless otherwise specified by the combination value M_EDGE_FIRST or M_EDGE_SECOND.

To establish the maximum and minimum positions of the edge peak, MIL considers the portion of the peak that contains the maximum edgevalue, and that satisfies the M_EDGEVALUE_MIN and M_EDGEVALUE_VAR_MIN constraints set using MmeasSetMarker(). That is, the peak must dip, on both sides, below either the minimum edgevalue threshold (M_EDGEVALUE_MIN) or the local edgevalue threshold established by subtracting M_EDGEVALUE_VAR_MIN from the peak's summit, whichever is highest.

Depending on the search region's origin and search direction, the maximum and minimum position can be on either side of the edge peak. Note that you can also retrieve different start and end positions of the edge using M_EDGE_START and M_EDGE_END.

Retrieves the X- and Y-coordinates of the minimum position of the edge peak (that is, the minimum edgevalue along the first derivative representation of the intensity profile), for each marker occurrence. For a stripe marker, the coordinates representing the average value of minimum positions is returned unless otherwise specified by the combination value M_EDGE_FIRST or M_EDGE_SECOND.

To establish the minimum and maximum positions of the edge peak, MIL considers the portion of the peak that contains the maximum edgevalue, and that satisfies the M_EDGEVALUE_MIN and M_EDGEVALUE_VAR_MIN constraints set using MmeasSetMarker(). That is, the peak must dip, on both sides, below either the minimum edgevalue threshold (M_EDGEVALUE_MIN)or the local edgevalue threshold established by subtracting M_EDGEVALUE_VAR_MIN from the peak's summit, whichever is highest.

Depending on the search region's origin and search direction, the maximum and minimum position can be on either side of the edge peak's summit. Note that you can also retrieve different start and end positions of the edge using M_EDGE_START and M_EDGE_END.

Retrieves the distance between the minimum (M_EDGEVALUE_PEAK_POS_MIN) and maximum (M_EDGEVALUE_PEAK_POS_MAX) position of the edge peak (that is, the minimum and maximum positions of the edgevalue along the first derivative representation of the intensity profile), for each marker occurrence.

To retrieve the width of the edge instead of the width of the edge peak, use M_EDGE_WIDTH.

Retrieves the length of the side of the search region perpendicular to the search direction. This is useful to retrieve the number of pixels that were projected into a single value of the intensity profile without having to find M_ORIENTATION first.

Retrieves the X- and Y-coordinates of the first intersection point, for each marker occurrence, between the edge's mean line and the box search region. For a stripe marker, the mean line is the mean of the lines following its two edges.

If you request this result for a specific edge of a stripe, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, M_LINE_END_POINT_FIRST will return the first intersection point of the line following the specified edge and the box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the intersection will take that rotation into account.

For vertical edges, the first intersection point is typically at the top of the box search region, while for horizontal edges the first intersection point is typically on the right of the box search region. Note that the intersection point that is considered to be the first or second (M_LINE_END_POINT_SECOND) can change depending on the edge's angle and whether the box search region is rotated.

Retrieves the X- and Y-coordinates of the second intersection point, for each marker occurrence, between the edge's mean line and the box search region. For a stripe marker, the mean line is the mean of the lines following its two edges.

If you request results for a specific edge of a stripe marker occurrence, using the combination value M_EDGE_FIRST or M_EDGE_SECOND, M_LINE_END_POINT_SECOND returns the second intersection point of the line following the specified edge and the box search region.

If the box search region was rotated using MmeasSetMarker() with M_BOX_ANGLE or from an angular search, the intersection will take that rotation into account.

For vertical edges, the second intersection point is typically at the bottom of the box search region, while for horizontal edges the second intersection point is typically on the left of the box search region. Note that the intersection point that is considered to be the first (M_LINE_END_POINT_FIRST) or second can change depending on the edge's angle and whether the box search region is rotated.

Retrieves the orientation of the marker.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Retrieves the polarity, for each marker occurrence.

Retrieves the score, for each marker occurrence. This score represents how confident you should be that MIL found what you expected. For an edge marker, the score is the product of all score characteristics set for the edge. For a stripe marker, the score is the product of the global score of both edges, and of all the characteristics for the stripe.

Retrieves the average score of all marker occurrences. This score represents how confident you should be that MIL found what you expected.

Note that this result type always returns one value, even when using a multiple-occurrence marker, and there are multiple occurrences.

Use M_SCORE to get the score of a single occurrence.

Retrieves the distance between each marker occurrence and the next.

Retrieves the width of the stripe, for each marker occurrence. The stripe's width refers to the distance between the position of the maximum edgevalue of the stripe's two outermost edges. This result is only available for stripe markers.

Retrieves the circle's radius.

Retrieves the distance between each occurrence of the two markers.

Retrieves the distance on the X-axis between each occurrence of the two markers.

Retrieves the distance on the Y-axis between each occurrence of the two markers.