| Customize Help

Measurements between two markers


Once you have found the position of your markers, you can use MmeasCalculate() to take measurements between two markers. MmeasCalculate() performs measurements according to the line joining the reference position of any two markers. By default, MmeasCalculate() performs all possible measurements (angle, distance, and line equation). This allows you to quickly determine some fundamental information about the relationship between the specified markers, such as how far apart they are from each other.

By default, a marker's reference position is the same as its actual position (MmeasGetResult() with M_POSITION), which depends on the marker's type.

Marker type

Default reference position

Point

X- and Y-coordinates specified using MmeasSetMarker() with M_POSITION.

Edge

X- and Y-coordinates of the edge's maximum edgevalue.

Stripe

X- and Y-coordinates at the center of a theoretical line between the position (maximum edgevalue) of the stripe's two outermost edges.

Circle

X- and Y-coordinates at the circle's center.

To change the marker's reference position, use MmeasSetMarker() with M_MARKER_REFERENCE. Modifying the reference position only affects calculations between two markers (MmeasCalculate()); it does not, for example, affect how MIL finds markers.

Steps to taking measurements between two markers

The following steps provide a basic methodology for taking measurements between two markers:

  1. Allocate a context, using MmeasAllocContext(). This is to allow the user to control the behavior of measurement operations (using MmeasControl()).

  2. Allocate a result buffer, using MmeasAllocResult(). This is to store the results obtained of the MmeasCalculate() operation.

  3. Allocate and define your markers, and find each marker (for more information, see the Steps to finding and obtaining measurements of markers section earlier in this chapter). Note that you cannot find point markers; you must set their position with M_POSITION.

  4. Call MmeasCalculate() and specify the two markers and the measurements to take.

  5. Read the results, using MmeasGetResult().

    To draw the resulting line that MIL used to take measurements between the two markers, call MmeasDraw() with M_DRAW_LINE, M_RESULT, and the identifier of the buffer that contains the results of the MmeasCalculate() operation.

Specifying the measurement context and control settings

While you would normally be required to explicitly specify a measurement context using MmeasAllocContext(), this is not required to perform basic measurements operations for the MmeasFindMarker(), MmeasCalculate(), and MmeasInquire() functions. This is because within those functions, it is possible to specify M_DEFAULT as the context's identifier, and in so doing, allocating the default measurement context.

In order to modify a measurement context using MmeasControl(), you need to explicitly allocate the measurement context using MmeasAllocContext(). This will then allow you to change various context settings, such as the pixel aspect ratio to correct measurement inputs (M_PIXEL_ASPECT_RATIO). However it is to be noted that these settings are typically reserved for more advanced applications. When you no longer require a measurement context allocated with MmeasAllocContext(), free it using MmeasFree().

Calculating with multiple-occurrence markers

If you specify two multiple-occurance markers, calculations are made using the occurrences of the first marker and the corresponding occurrences of the second marker. The number of calculations is limited to the smallest number of occurrences held in either marker. For example, in the following illustration, Marker 1 is a simple edge marker, while Marker 2 is a multiple-occurrence marker with four edge occurrences. In this case, MIL performs the calculations between Marker 1 and the first occurrence of Marker 2.

When retrieving results for a multiple-occurrence marker, you must pass an array to MmeasGetResult() that is large enough to hold the results of all occurrences. If necessary, you can use MmeasGetResultSingle() to retrieve a single result.

Angle

To calculate the angle of the line joining the two markers, use M_ANGLE.

The angle is measured counter-clockwise, from the positive X-axis, and can be a value from 0 to 360°. The angle is returned in the output units specified using MmeasControl() (for a measurement result buffer) with M_RESULT_OUTPUT_UNITS.

Line equation and distance

To calculate the equation of the line joining the two markers, use M_LINE_EQUATION. To calculate the distance between the two markers, use M_DISTANCE.

The following illustration shows two stripe markers, each of which is a multiple-occurrence marker; the first has two occurrences, and the second has three. In this example, MIL calculates the line equation and distance between each corresponding occurrence (relative to each marker's reference position). Since each multiple-occurrence marker has a different number of occurrences, MIL uses the smaller number and ignores the extra occurrence.

Note that you can also retrieve the horizontal or vertical distance between two markers using MmeasGetResult() with M_DISTANCE_X or M_DISTANCE_Y.