| MIL 10 Reference
| Customize Help
| Save Settings

MmetSetRegion


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
MmetSetPosition
MmetStream
Synopsis
Set the metrology region that delimits the area in the target image from which to establish the edgels of the feature to validate and measure.
Syntax
void MmetSetRegion(
MIL_ID ContextId, //in
MIL_INT FeatureLabelOrIndex, //in
MIL_INT ReferenceFrameLabelOrIndex, //in
MIL_INT64 Geometry, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4, //in
MIL_DOUBLE Param5, //in
MIL_DOUBLE Param6 //in
)
Description

This function allows you to set a geometrically-defined ROI, referred to as a metrology region, for a physically measured feature within the template of the metrology context. The metrology region delimits the area in the target image from which to establish the edgels of the feature to validate and measure. When you call this function, you can define the metrology region in one of the following ways.

  • Explicitly specify the shape and size of the region. This is referred to as an explicitly-defined metrology region.

  • Set the region's shape and size using a graphic in a graphics list. This is referred to as a graphics list metrology region.

  • Define the metrology region based on other features by passing a derived metrology region object to this function. This is referred to as a derived metrology region.

When using a graphics list metrology region (M_FROM_GRAPHIC_LIST), the graphics list must contain only one graphic and it must have the same geometric-shape as specified with the Geometry parameter of this function. The advantage of defining a graphics list metrology region is that you can set it with respect to the relative coordinate system as well as set it interactively.

When using a derived metrology region (M_FROM_DERIVED_GEOMETRY_REGION), you must allocate a derived metrology region object using MmetAlloc() with M_DERIVED_GEOMETRY_REGION, and then set it up using MmetControl() with M_REGION_.... Once you specify the geometry of the derived metrology region using the M_REGION_GEOMETRY control type, you can set most of the geometry's attributes either explicitly or derive them based on a feature. Use the corresponding M_REGION_..._TYPE control type to specify which. For example, instead of specifying explicit X- and Y-coordinates to set the position of a rectangular metrology region, you can derive its position according to the position of a point feature.

The metrology region that you choose must be compatible with the type of feature you are adding (MmetAddFeature() with M_MEASURED). For example, when adding a physically measured circle feature, you can use an M_RING metrology.

The metrology region is set according to its feature's reference frame (ReferenceFrameLabelOrIndex). The global frame is the default. If the target image is not calibrated, the global frame's default origin (0,0) is aligned with the center of the top-left corner pixel of the target image. If the target image is calibrated, the global frame's default origin is aligned with the origin of the relative (world) coordinate system. To change the reference frame to a local frame, use MmetControl() with M_REFERENCE_FRAME. Local frames are coordinate systems located anywhere within the metrology template and defined as metrology features.

A valid feature must not only fall within the metrology region, but its edgels' gradient angle must also fall along the region's orientation. Various control types can be used to set a valid relationship between the metrology region's orientation, and the edgels' gradient angle. For more information, see the Gradient angle subsection of the Degrees of freedom section of Chapter 15: Metrology.

Note that you cannot specify a geometrically-defined region for a physically measured feature with a region of interest (ROI) set using MbufSetRegion(); you can only use metrology regions established with this function.

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 metrology context containing the template in which to set the metrology region. The metrology context must have been previously allocated on the required system using MmetAlloc().

FeatureLabelOrIndex

Specifies the label or index of the measured feature that will be established from the area delimited by the metrology region. Set this parameter to one of the following values.

function map For specifying a feature
CollapseValue Description
Collapse

Specifies the index of an existing individual feature.

(summarize)
Parameters

This parameter specifies the index of the measured feature to establish from the metrology region. You can set this parameter to the following:
Index >= 0

Specifies the index.
Collapse

Specifies the label value of an existing individual feature.

(summarize)
Parameters

This parameter specifies the label of the measured feature to establish from the metrology region. You can set this parameter to the following:
Label > 0

Specifies the label.
ReferenceFrameLabelOrIndex

Specifies the label or index of the reference frame feature of the physically measured feature for which you are specifying a metrology region. To change the reference frame, use MmetControl() with M_REFERENCE_FRAME.

function map For specifying the reference frame
CollapseValue Description
Collapse M_DEFAULT

Same as M_GLOBAL_FRAME.
Collapse

Specifies the index value of an existing reference frame feature.

(summarize)
Parameters

This parameter specifies the index of the reference frame feature. You can set this parameter to the following:
Index >= 0

Specifies the index. Note that the index of the global frame is 0.
Collapse

Specifies the label value of an existing reference frame feature.

(summarize)
Parameters

This parameter specifies the label of the reference frame feature. You can set this parameter to the following:
Label > 0

Specifies the label.
Collapse M_GLOBAL_FRAME

Specifies the global frame as the reference frame.
Geometry INQ

Specifies the geometric shape of the metrology region.

See the Parameter associations section for possible values that can be specified.

Param1

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

See the Parameter associations section for possible values that can be specified.

Param2

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Param3

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Param4

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Param5

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Param6

Specifies an attribute of the metrology region to set. Its definition is dependent on the geometry chosen.

Set this parameter to M_NULL if not used.

See the Parameter associations section for possible values that can be specified.

Parameter associations

The tables below list possible values for the Geometry, Param1, Param2, Param3, Param4, Param5, and Param6 parameters.

The following can be specified for setting an explicitly-defined metrology region. To specify a graphics list metrology region, you must add M_FROM_GRAPHIC_LIST to the supported geometry (M_ARC, M_RECTANGLE, and M_SEGMENT).

Unused parameters should be set to M_NULL.

function map For setting an explicitly-defined or graphics list metrology region
CollapseGeometry Description
Param1
Param2
Param3
Param4
Param5
Param6
Collapse M_DEFAULT

Same as M_INFINITE.

(summarize)
Collapse M_ARC +

Specifies that the feature will be established from an arc metrology region.

M_ARC can be used to establish point (M_POINT) features.

(summarize)
Collapse Param1

Sets the X-coordinate of the origin of the arc metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the origin of the arc metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the radius of the arc metrology region. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the radius, in pixel or world units.
Collapse Param4

Sets the start angle of the arc metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0°.
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse Param5

Sets the end angle of the arc metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 360.0°.
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse M_INFINITE

Specifies that the feature will be established from an infinite metrology region. An infinite metrology region is an X- Y-plane with no boundaries. Use Param3 to specify the angle that defines the orientation of this region. Note that M_INFINITE is similar to M_RECTANGLE, however a rectangular metrology region has a width and a height, which are used to bind the metrology region.

M_INFINITE can be used to establish any feature and is the default metrology region.

(summarize)
Collapse Param1

Sets the X-coordinate of the origin of the infinite metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the origin of the infinite metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the angle (orientation) of the infinite metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0°. This indicates that the orientation of the infinite metrology region is the same as the orientation of the reference frame.

(summarize)
Collapse M_RADIAL

Specifies that the infinite metrology region has a radial orientation, from 0.0° to 360.0°, based on the specified origin.

In such a metrology region, edgels can only be considered part of the physically measured feature if their gradient angle conforms to the direction of a radii pointing out from the region's origin. M_RADIAL is usually used to define a metrology region for a physically measured circular feature whose radius is unknown. Typically the origin of the metrology region is placed at the feature's center, resulting in valid edgels only being possible if they encircle the origin.

(summarize)
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees, relative to the reference frame. This angle represents the infinite region's orientation.

(summarize)
Collapse M_RECTANGLE +

Specifies that the feature will be established from a rectangular metrology region.

Note that M_RECTANGLE is similar to M_INFINITE, however an infinite metrology region does not have a width and a height (boundaries).

M_RECTANGLE can be used to establish segment (M_SEGMENT) or edgel (M_EDGEL) features.

(summarize)
Collapse Param1

Sets the X-coordinate of the origin of the rectangular metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the origin of the rectangular metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the width of the rectangle. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the rectangle's width, in pixel or world units.
Collapse Param4

Sets the height of the rectangle. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the rectangle's height, in pixel or world units.
Collapse Param5

Sets the angle (orientation) of the rectangular metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0°.
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse M_RING

Specifies that the feature will be established from a ring-shaped metrology region.

M_RING can be used to establish circle (M_CIRCLE) or edgel (M_EDGEL) features.

(summarize)
Collapse Param1

Sets the X-coordinate of the center of the ring-shaped metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the center of the ring-shaped metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the start radius of the ring-shaped metrology region. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the start radius, in pixel or world units.
Collapse Param4

Sets the end radius of the ring-shaped metrology region. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the end radius, in pixel or world units.
Collapse M_RING_SECTOR

Specifies that the feature will be established from a ring-sector metrology region.

M_RING_SECTOR can be used to establish radial segments (M_SEGMENT), arcs (M_ARC), or edgel (M_EDGEL) features.

(summarize)
Collapse Param1

Sets the X-coordinate of the origin of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the origin of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the origin's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the start radius of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the start radius, in pixel or world units.
Collapse Param4

Sets the end radius of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0 pixels.
Collapse Value

Specifies the end radius, in pixel or world units.
Collapse Param5

Sets the start angle of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0°.
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse Param6

Sets the end angle of the ring-sector metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 360.0°.
Collapse 0.0 <= Value <= 360.0

Specifies the angle, in degrees.
Collapse M_SEGMENT +

Specifies that the feature will be established from a linear segment metrology region.

M_SEGMENT can be used to establish point (M_POINT) features.

(summarize)
Collapse Param1

Sets the X-coordinate of the start point of the segment metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the start point's X-coordinate, in pixel or world units.
Collapse Param2

Sets the Y-coordinate of the start point of the segment metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the start point's Y-coordinate, in pixel or world units.
Collapse Param3

Sets the X-coordinate of the end point of the segment metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the end point's X-coordinate, in pixel or world units.
Collapse Param4

Sets the Y-coordinate of the end point of the segment metrology region, relative to the reference frame. INQ

(summarize)
Collapse M_DEFAULT

Specifies the default value; the default value is 0.0.
Collapse Value

Specifies the end point's Y-coordinate, in pixel or world units.
Combination constant for M_ARC; M_RECTANGLE; M_SEGMENT.

You can add the following value to the above-mentioned values to set a graphics list metrology region.

Unused parameters should be set to M_NULL.

function map For setting a graphics list metrology region
CollapseGeometry Description
Param1
Param2
Param3
Param4
Param5
Param6
Collapse M_FROM_GRAPHIC_LIST

Specifies a graphics list metrology region. Interactive graphics are allowed. Metrology ignores a graphic's fill color, if specified.

When using M_FROM_GRAPHIC_LIST with M_ARC, the graphics list must contain only one arc, created using MgraArc(), MgraArcAngle(), or MgraArcFill(). The arc must be circular; that is, its X- and Y-radius must be the same.

When using M_FROM_GRAPHIC_LIST with M_RECTANGLE, the graphics list must contain only one rectangle, created using MgraRect(), MgraRectAngle(), or MgraRectFill().

When using M_FROM_GRAPHIC_LIST with M_SEGMENT, the graphics list must contain only one line, created using MgraLine().

(summarize)
Collapse Param1

Sets the identifier of the graphics list with which to delimit the metrology region. The graphics list must have been previously allocated on the required system using MgraAllocList().

The graphic's data (not the graphic itself) is taken as-is and is considered part of the metrology context with which it is used. For example, the graphic's metrology region information is now relative to the feature's reference frame (ReferenceFrameLabelOrIndex), is saved with the metrology context (MmetSave()), and is not affected by subsequent graphics list modifications unless you re-call M_FROM_GRAPHIC_LIST.

When using a graphics list metrology region, you can first call McalFixture() with M_MOVE_RELATIVE and M_RESULT_MET, and specify the feature's reference frame. You can then ensure that positions are set and returned according to the specified reference frame. For more information, see the Moving using a metrology reference frame subsection of the Moving the relative coordinate system section of Chapter 26: Fixturing in MIL.

(summarize)

The following can be specified for setting a derived metrology region.

Unused parameters should be set to M_NULL.

function map For setting a derived metrology region
CollapseGeometry Description
Param1
Param2
Param3
Param4
Param5
Param6
Collapse M_FROM_DERIVED_GEOMETRY_REGION

Specifies a derived metrology region. To set up this metrology region, use MmetControl() with M_REGION_....

It is only recommended to use a derived metrology region when you need at least one other feature to set the metrology region. However, you can use a derived metrology region to set the metrology region using features, explicit values, or a combination of the two. Once you define this type of metrology region, the region information (not the derived metrology region object itself) is considered part of the metrology context with which it is used; for example, that information will be saved along with the context if you call MmetSave().

You can use M_FROM_DERIVED_GEOMETRY_REGION with any geometry.

(summarize)
Collapse Param1

Sets the identifier of the derived metrology region object. The derived metrology region object must have been previously allocated on the required system using MmetAlloc() with M_DERIVED_GEOMETRY_REGION.

(summarize)
Type-specific versions of the function
void MmetSetRegionInt64 (MIL_ID ContextId, MIL_INT FeatureLabelOrIndex, MIL_INT ReferenceFrameLabelOrIndex, MIL_INT64 Geometry, MIL_INT64 Param1, MIL_DOUBLE Param2, MIL_DOUBLE Param3, MIL_DOUBLE Param4, MIL_DOUBLE Param5, MIL_DOUBLE Param6)
Details
Parameters

ContextId

See ContextId of the main function for a description.

FeatureLabelOrIndex

See FeatureLabelOrIndex of the main function for a description.

ReferenceFrameLabelOrIndex

See ReferenceFrameLabelOrIndex of the main function for a description.

Geometry

See Geometry of the main function for a description.

Param1

See Param1 of the main function for a description.

Param2

See Param2 of the main function for a description.

Param3

See Param3 of the main function for a description.

Param4

See Param4 of the main function for a description.

Param5

See Param5 of the main function for a description.

Param6

See Param6 of the main function for a description.
Compilation information
Header Include mil.h.
Library Use mil.lib; milmetrol.lib.
DLL Requires mil.dll; milmetrol.dll.
DEFAULT GLOBAL FRAME DEFAULT ARC DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT INFINITE DEFAULT DEFAULT DEFAULT RADIAL RECTANGLE DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT RING DEFAULT DEFAULT DEFAULT DEFAULT RING SECTOR DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT DEFAULT SEGMENT DEFAULT DEFAULT DEFAULT DEFAULT FROM GRAPHIC LIST FROM DERIVED GEOMETRY REGION