MmeasFindMarker

See also

User Guide:

Circle markers: basic and advanced characteristics that should or can be specified Marker characteristics Measurements between two markers Score characteristics Search region Search results

Reference:

MbufInquire MbufSetRegion MmeasAllocContext MmeasControl MmeasGetResult MmeasGetResultSingle MmeasInquire MmeasSetMarker MmeasSetScore

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
calibratedruler.cpp
circlemeasurement.cpp
foodinspectioncereal.cpp
gumpackinspection.cpp
mcal.cpp
mcal.cs
mcal.vb
meas2stepoverview.cpp
measoverviewexample.cpp
measurementinspectiontask.cpp
mmeas.cpp
mmeas.cs
mmeas.vb
multiviewannotations.cpp
tirestringread.cpp

Function Map

- ContextId

Table:

For specifying the measurement context identifier

- ImageBufId

- MarkerId

- MeasurementList

Table:	For specifying the measurements to perform when using edge, stripe, or circle markers
+ combination:	For specifying the measurements to perform when using edge or stripe markers
+ combination:	For specifying the measurement to perform when using circle markers

Compilation information

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 camera 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 2D 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 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

ContextId

Specifies the identifier of the measurement context.

For specifying the measurement context identifier
Value	Description
M_DEFAULT	Specifies the default measurement context of the current MIL application.
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 + M_LENGTH).

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

For specifying the measurements to perform when using edge, stripe, or circle markers
Value	Description
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) Performs all measurements that apply to the marker type. (more details...)
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) Determines the position of the marker. (more details...)

Combination values that can be used alone or as combination values for M_POSITION.

You can use one or more of the following values in combination with each other or with the above-mentioned value, 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.

For specifying the measurements to perform when using edge or stripe markers
Value	Description
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 26: 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) Determines the angle of the mean line of a marker, relative to the output coordinate system specified using MmeasControl() with M_RESULT_OUTPUT_UNITS. (more details...)
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) 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. (more details...)
M_EDGE_INSIDE	Determines the number of edges located between the two exterior edges of a stripe. This only applies to stripe markers. (summarize) Determines the number of edges located between the two exterior edges of a stripe. (more details...)
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) Determines the distance between the start (M_EDGE_START) and end (M_EDGE_END) of the intensity transition from which the edge is established. (more details...)
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) 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). (more details...)
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) 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). (more details...)
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) Determines the length of the side of the marker perpendicular to the search direction. (more details...)
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) Determines the X- and Y-coordinates of the first intersection point between the marker's mean line and the box search region. (more details...)
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) Determines the X- and Y-coordinates of the second intersection point between the marker's mean line and the box search region. (more details...)
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) Determines the equation of the line following an edge. (more details...)
M_POLARITY	Determines whether the edge(s) are rising (positive polarity) or falling (negative polarity).
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) Determines the width of the stripe marker. (more details...)

Combination value that can be used alone or as combination value for M_POSITION.

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

For specifying the measurement to perform when using circle markers
Value	Description
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.