Search results
You can obtain results using MmeasGetResult() (or MmeasGetResultSingle()) or MmeasGetScore(). MIL stores results from MmeasFindMarker() directly within the marker buffer rather than in a result buffer. Results do not overwrite specified marker characteristics. If you have specified a score characteristic with MmeasSetScore(), you can obtain the results using MmeasGetScore(). All positional results are relative to the center of the top-left pixel in the target image or the origin of the relative coordinate system of an calibrated image.
For a multiple occurrence marker, MmeasFindMarker() takes the required measurements for all the found edges or stripes (all marker occurrences). To obtain the number of edges or stripes found, use MmeasGetResult() with M_NUMBER. Global results, such as the maximum, minimum, mean, or standard deviation of any characteristic of the calculated results can be returned.
Finding the marker and taking measurements
Use MmeasFindMarker() to find a marker and take its measurements, such as its strength, position, and contrast. By default, MIL performs all measurements that apply to the marker type, which is typically what you want. Measurements are taken with subpixel accuracy. When you call MmeasFindMarker(), however, you can limit the number of measurements performed using MmeasSetMarker(). Advanced users can modify how MIL calculates the positions of the subpixels using MmeasSetMarker() with M_SUBPIXEL_MODE.
Edge measurements taken by the find operation
When you call MmeasFindMarker(), MIL not only locates the best possible marker, but also takes its measurements, such as the marker's angle and width. If you call this function with M_DEFAULT, MIL performs all possible measurements on the marker, which is typically appropriate for the vast majority of applications. However, you can also call MmeasFindMarker() with a specific set of measurements to calculate. In this case, be aware that certain results might not be available for retrieval. For example, if you use MmeasFindMarker() to calculate just the line equation of an edge marker (M_LINE_EQUATION), you cannot use MmeasGetResult() with M_EDGE_END to retrieve the X- and Y-coordinates of the end of the edge. Except for some very rare cases, there is no reason to restrict the default measurements MmeasFindMarker() performs.
Some of the less evident measurements that MIL takes are discussed below; for a complete list, refer to MmeasFindMarker() in the MIL Reference.
Line equation (mean line)
When you call the find operation, MIL calculates the equation of the line that best follows the edge marker. MIL bases the line equation on the general form, Ax + By + C = 0. Use MmeasGetResult() with M_LINE_A, M_LINE_B, and M_LINE_C to retrieve the coefficients A, B, and C, respectively.
If you did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL internally uses three, since it is the minimum number it requires to calculate the line equation (mean line).
Angle
When you call the find operation, MIL calculates the angle of an edge marker, which you can then retrieve using MmeasGetResult() with M_ANGLE. MIL measures the angle, as a value from 0° to 360°, between the positive X-axis and the edge's mean line.
Length
When you call the find operation, MIL also calculates the length of the side of the search region perpendicular to the search direction, in pixels, which you can then retrieve using MmeasGetResult() with M_LENGTH. 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.
Position and reference position
The edge marker's position refers to the X- and Y-coordinates of its maximum edgevalue (highest edge peak), as found with MmeasFindMarker(). To retrieve the marker's found position, use MmeasGetResult() with M_POSITION. To draw a cross (+) at this position, use MmeasDraw() with M_DRAW_POSITION; if you are using subregions, you can specify M_DRAW_SUB_POSITIONS to draw a cross at the found position of each subedge.
MIL uses the found position of the edge marker (M_DRAW_POSITION) as its default reference position, when calculating measurements between two markers using MmeasCalculate(). To change the default, call MmeasSetMarker() with M_MARKER_REFERENCE and specify X- and Y-offset values relative to the found position. Only MmeasCalculate() makes use of this reference position. For more information, see the Measurements between two markers section later in this chapter.
Intersection point
When you call the find operation, MIL calculates the X- and Y-coordinates of the two intersection points between the marker's mean line and the box search region. To retrieve the intersection points, use MmeasGetResult() with M_LINE_END_POINT_FIRST and M_LINE_END_POINT_SECOND.
For vertical edges, the first intersection point is typically at the top of the box search region, while the second intersection point is typically at the bottom. For horizontal edges, the first intersection point is typically on the right of the box search region, while the second intersection point is typically on the left. However, the intersection point that MIL considers first and second can change depending on certain factors, such as the orientation, the edge's angle, and the rotation of the box search region.
An edge's start, end, and width (based on the intensity profile)
When you call the find operation, MIL calculates the start and end position of the edge, based on the intensity profile of the search region. To retrieve these results, use M_EDGE_START and M_EDGE_END. You can also retrieve the distance between M_EDGE_START and M_EDGE_END, using M_EDGE_WIDTH. For more information, see the Search algorithm section earlier in this chapter.
An edge peak's maximum/minimum position and width (based on the first derivative)
When you call the find operation, MIL calculates the minimum and maximum positions of the edge peak, based on the edge profile (the normalized first derivative of the intensity profile). To retrieve these results, use M_EDGEVALUE_PEAK_POS_MIN and M_EDGEVALUE_PEAK_POS_MAX. You can also retrieve the distance between M_EDGEVALUE_PEAK_POS_MIN and M_EDGEVALUE_PEAK_POS_MAX, using M_EDGEVALUE_PEAK_WIDTH. For more information, see the Search algorithm section earlier in this chapter.
Stripe measurements taken by the find operation
When you call MmeasFindMarker(), MIL not only locates the best possible marker, but also takes its measurements, such as the stripe marker's length and width. As with edge markers, you would typically perform all possible measurements on the stripe (M_DEFAULT).
Line equation (mean line)
When you call the find operation to find stripe markers, MIL calculates the equation of three lines: the stripe's mean line, the line that best represents the stripe's first edge, and the line that best represents the stripe's second edge.
Much like for edge markers, each line equation is based on the general form, Ax + By + C = 0. Use MmeasGetResult() with M_LINE_A, M_LINE_B, and M_LINE_C to retrieve the coefficients A, B, and C, respectively. You can retrieve these coefficients for a specific edge's line equation, using the combination value M_EDGE_FIRST or M_EDGE_SECOND. If you do not specify a specific edge, the function returns the coefficients of the line equation for the stripe's mean line. The mean line follows the center of the marker occurrence, between the lines MIL calculates for the stripe's two outermost edges.
If you did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL internally uses three subregions, since it is the minimum number it requires to calculate a line equation.
Angle
When you call the find operation, MIL calculates the angle of a stripe marker, in much the same manner as it does for an edge based marker (discussed in the the Angle subsection of this section), that is to say by measuring the angle between the positive X-axis and the stripe's mean line. The angle of a stripe marker is independent of the angle of the search region. The angle is measured in the coordinate system specified, and can be changed using M_RESULT_OUTPUT_UNITS.
You can also retrieve the angle of the stripe's first or second edge, using M_ANGLE and the combination value M_EDGE_FIRST or M_EDGE_SECOND, respectively.
Length
As with an edge marker, the length of a stripe marker is the length of the side of the search region perpendicular to the search region. The retrieval of the length of a marker is discussed in the Length subsection of this section.
Position and reference position
The position of a stripe marker is at the center of a theoretical line between the position (maximum edgevalue) of the stripe's two outermost edges, as found with MmeasFindMarker(). The process of retrieving the found position for a stripe marker is much the same as for an edge marker, as discussed in the Position and reference position subsection of this section. Furthermore, all operations in the previously mentioned corresponding section for an edge marker can also be performed for a stripe marker.
Stripe width
To retrieve the actual stripe width, call MmeasGetResult() with M_STRIPE_WIDTH. This result is available even if you do not use M_STRIPE_WIDTH_SCORE. To draw an H-type line (|-|) along the found width of the stripe, use MmeasDraw() with M_DRAW_WIDTH.
Maximum association distance of subedges
To retrieve the distance between the calculated stripe marker and its farthest subedge, use MmeasGetResult() with M_FIT_ERROR_MAX. To retrieve the number of outliers (ignored subedges), use MmeasGetResult() with M_NUMBER_OF_OUTLIERS.
Circle measurements taken by the find operation
When you call MmeasFindMarker(), MIL not only locates the best possible marker, but also takes its measurements, such as the circle marker's position and radius. As with edge markers, you would typically perform all possible measurements on the circle (M_DEFAULT).
Position and reference position
The circle marker's position refers to the X- and Y-coordinates of its center, as found with MmeasFindMarker(). The process of retrieving the found position for a circle marker is much the same as for an edge or stripe marker, as discussed in the Position and reference position subsection of this section. Furthermore, all operations in the previously mentioned corresponding section for an edge marker can also be performed for a circle marker.
Maximum association distance of subedges
The retrieval of the distance between a circle marker and its farthest subedge is done in much the same way as it is done for a stripe marker, as discussed in the Maximum association distance of subedges subsection of this section.
Radius
To retrieve a circle marker's radius, use MmeasGetResult() with M_RADIUS. This result is available even if you do not use M_RADIUS_SCORE.
Drawing
To verify marker specifications or results, you can call MmeasDraw() with M_MARKER or M_RESULT, respectively; that is, you can perform the drawing operation (M_DRAW_...) using the expected marker characteristics (M_MARKER), or using the marker characteristics found in the target image (M_RESULT). For example, you can draw the marker's search region defined using MmeasSetMarker() (M_DRAW_SEARCH_REGION), as well as the found position of a marker (M_DRAW_POSITION). When drawing results, you can use the M_RESULT_PER_SUBREGION() macro to indicate that MIL should perform the drawing operation according to the specified subregions (one or all) of the specified occurrences (one or all). For stripe markers, you can perform certain drawing operations based on the marker's first or second outermost edge, by adding either M_EDGE_FIRST or M_EDGE_SECOND to the operation (for example, M_DRAW_POSITION + M_EDGE_SECOND). A stripe's first edge is the edge located closest to the search region origin.
MIL stores both the specified (expected) marker characteristics, and the characteristics of marker results, in the same measurement marker buffer. You must therefore pass the identifier of this one marker to MmeasDraw(), whether you are using M_MARKER or M_RESULT. MmeasDraw() also accepts the identifier of a measurement result buffer, but only for drawing the resulting line between two markers when using MmeasCalculate(). For more information, see the Measurements between two markers section later in this chapter.
To control the drawing color of MmeasDraw() operations, you can use a previously allocated graphics context or the default graphics context (see the Graphics context section of Chapter 22: Generating graphics). You can draw directly into an image buffer or a graphics list. By drawing into the display's overlay buffer or associating the graphics list with the display, you can also annotate non-destructively. For more information, see the Annotating the displayed image non-destructively section of Chapter 21: Displaying an image.