| MIL 10 Reference
| Customize Help
| Save Settings

MmeasFindMarker


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
MmeasDraw
MmeasFree
Synopsis
Find a marker in a target image and take the specified measurements.
Syntax
void MmeasFindMarker(
MIL_ID ContextId, //in
MIL_ID ImageBufId, //in
MIL_ID MarkerId, //in
MIL_INT64 MeasurementList //in
)
Description

This function finds an edge, stripe, or circle marker in the specified target image and takes the specified measurements. To locate the marker, MIL uses its essential characteristics (MmeasSetMarker()), its score characteristics (MmeasSetScore()), and the measurement context (MmeasControl()).

For edge and stripe markers, it is recommended that the box search region be set to an angle close to that of the required marker (that is, within the marker's particular rotation tolerance) to ensure that the marker is found and that results are accurate. The greater the angle of the marker relative to the search region, the greater the distortion of the marker's actual characteristics, which increases the chance that MmeasFindMarker() might not successfully locate the marker.

MmeasFindMarker() stores its results in the specified measurement marker (not in a result buffer). To obtain results, use MmeasGetResultSingle() or MmeasGetResult(). All positional results are relative to the top-left pixel in the target image, or the origin of the relative coordinate system if the target is a calibrated image.

If you have associated the target image with a calibration context, you can specify that certain input settings be interpreted in world units. To do so, use MmeasSetMarker() with M_MARKER_REFERENCE_INPUT_UNITS, M_INCLUSION_POINT_INPUT_UNITS, and/or M_SEARCH_REGION_INPUT_UNITS set to M_WORLD. By using a calibrated image, you can specify the search region according to the relative coordinate system using MmeasSetMarker(), and then fixture the relative coordinate system to each object. This way, you will only need to place the search region once, and all of the search results will be made from the same reference location. Note that if you set any of these constants to M_WORLD but you don't pass MmeasFindMarker() a calibrated target image, the function will generate an error.

For edge and stripe markers, you can limit the find operation to a region of the target image buffer using a rectangular region of interest (ROI) set with MbufSetRegion(). For circle markers, you can limit the find operation to a region of the target image buffer using a circular region of interest (ROI) set with MbufSetRegion(). The find marker operation will then search inside the ROI instead of inside any previously set search regions. Note that while the region of interest (ROI) affects the marker occurrences, it will not change the settings of any previously set search regions. In these cases, the region must be defined in vector format from a graphics list (M_VECTOR or M_VECTOR_AND_RASTER). An error will be generated if the ROI is only in raster format (M_RASTER).

When finding an edge or stripe marker, the target image buffer can have a rectangular region of interest (ROI), defined using MbufSetRegion() (with or without rotation). When finding a circle marker, the target image buffer can have a circular region of interest (ROI), defined using MbufSetRegion().

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
ContextId

Specifies the identifier of the measurement context.

function map For specifying the measurement context identifier
CollapseValue Description
Collapse M_DEFAULT

Specifies the default measurement context of the current MIL application.
Collapse Measurement context ID

Specifies a valid measurement context, previously allocated using MmeasAllocContext().
ImageBufId

Specifies the identifier of the target image buffer in which to locate the marker. This buffer must be a 1-band, 8-bit or 16-bit unsigned image buffer.

MarkerId

Specifies the identifier of the marker to be located in the image.

MeasurementList

Specifies the measurements to perform.

MIL considers the specified measurements when establishing results (MmeasGetResult() or MmeasGetResultSingle()). If you do not specify M_DEFAULT, which takes all possible measurements applicable to the marker type, you might not be able to retrieve all results for that marker. For the vast majority of applications, M_DEFAULT should be set.

Note that if you did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to perform certain measurements, such as determining the equation of a line (M_LINE_EQUATION). To ensure that MIL does not internally use multiple subregions when you did not specify any, you must not select measurements that require them.

Except for M_DEFAULT, you can add measurement list values together (for example, M_POSITION + M_ANGLE).

The measurements in the following table can be performed with edge, stripe, or circle markers.

function map For specifying the measurements to perform when using edge, stripe, or circle markers
CollapseValue Description
Collapse M_DEFAULT

Performs all measurements that apply to the marker type. For example, if you are using a circle, MIL takes all measurements possible for circle markers.

(summarize)
Collapse M_POLARITY +

Determines whether the edge(s) are rising (positive polarity) or falling (negative polarity).
Collapse M_POSITION +

Determines the position of the marker.

By specifying M_POSITION, all of the following will also be accessible with MmeasGetResult() or MmeasGetResultSingle() (for edge and stripe markers): M_BOX_EDGEVALUES, M_EDGE_END, M_EDGE_STRENGTH M_EDGE_START, M_ORIENTATION, M_EDGEVALUE_PEAK_POS_MAX, M_EDGEVALUE_PEAK_POS_MIN, and M_SPACING.

(summarize)
Combination constants that can be used alone or as combination constants for the values listed in For specifying the measurements to perform when using edge, stripe, or circle markers.

You can use one or more of the following values in combination with each other or with the above-mentioned values, to specify the measurement to perform when using edge or stripe markers.

The measurements in the following table can be performed with edge or stripe markers, unless otherwise specified.

function map For specifying the measurements to perform when using edge or stripe markers
CollapseValue Description
Collapse M_ANGLE

Determines the angle of the mean line of a marker, relative to the output coordinate system specified using MmeasControl() with M_RESULT_OUTPUT_UNITS. The angle can result in a value between 0° and 360°. For a stripe marker, MIL establishes the angle of three lines: the stripe's mean line, the stripe's first outermost edge, and the stripe's second outermost edge.

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

If you did not explicitly specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to establish the lines it requires to determine M_ANGLE.

(summarize)
Collapse M_EDGE_CONTRAST

Determines 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 a stripe marker, MIL establishes this value from the stripe's first and second outermost edges.

(summarize)
Collapse M_EDGE_INSIDE

Determines the number of edges located between the two exterior edges of a stripe. This only applies to stripe markers.

(summarize)
Collapse M_EDGE_WIDTH

Determines the distance between the start (M_EDGE_START) and end (M_EDGE_END) of the intensity transition from which the edge is established. For a stripe marker, MIL establishes this value for the stripe's first and second outermost edges.

(summarize)
Collapse M_EDGEVALUE_PEAK_CONTRAST

Determines the grayscale difference of the intensity transition between the first zero edgevalues on both sides of the edge peak (before M_EDGEVALUE_PEAK_POS_MIN, and after M_EDGEVALUE_PEAK_POS_MAX). For a stripe marker, MIL establishes this value for the stripe's first and second outermost edges.

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

(summarize)
Collapse M_EDGEVALUE_PEAK_WIDTH

Determines the distance between the minimum (M_EDGEVALUE_PEAK_POS_MIN) and maximum (M_EDGEVALUE_PEAK_POS_MAX) positions of the edge peak (that is, the minimum and maximum position of the edgevalue along the first derivative representation of the intensity). For a stripe marker, MIL establishes this value for the stripe's first and second outermost edges.

(summarize)
Collapse M_LENGTH

Determines the length of the side of the marker 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.

(summarize)
Collapse M_LINE_END_POINT_FIRST

Determines the X- and Y-coordinates of the first intersection point between the marker'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 did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to establish the line it requires to determine M_LINE_END_POINT_FIRST.

(summarize)
Collapse M_LINE_END_POINT_SECOND

Determines the X- and Y-coordinates of the second intersection point between the marker'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 did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to establish the line it requires to determine M_LINE_END_POINT_SECOND.

(summarize)
Collapse M_LINE_EQUATION

Determines the equation of the line following an edge. The line equation is of the general form, Ax + By + C = 0. For a stripe marker, MIL establishes the equation of three lines: the stripe's mean line, the stripe's first edge, and the stripe's second edges.

If you did not specify multiple subregions (MmeasSetMarker() with M_SUB_REGIONS_NUMBER), MIL will internally use three to establish the lines it requires to determine M_LINE_EQUATION.

(summarize)
Collapse M_STRIPE_WIDTH

Determines the width of the stripe marker. The stripe's width refers to the distance between the position of the maximum edgevalue of the stripe's two outermost edges. This only applies to stripe markers.

(summarize)
Combination constant that can be used alone or as combination constant for the values listed in For specifying the measurements to perform when using edge, stripe, or circle markers.

You can use the following value on its own, or add it to the above-mentioned values, to specify the measurement to perform when using circle markers.

function map For specifying the measurement to perform when using circle markers
CollapseValue Description
Collapse M_RADIUS

Determines the distance between the circle's circumference and the circle's center.
Compilation information
Header Include mil.h.
Library Use mil.lib; milmeas.lib.
DLL Requires mil.dll; milmeas.dll.
DEFAULT UNSIGNED PROC RASTER DEFAULT POLARITY POSITION ANGLE EDGE CONTRAST EDGE INSIDE EDGE WIDTH EDGEVALUE PEAK CONTRAST EDGEVALUE PEAK WIDTH LENGTH LINE END POINT FIRST LINE END POINT SECOND LINE EQUATION STRIPE WIDTH RADIUS STRIPE CIRCLE