MmetSetRegion

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Set the metrology region that delimits the area from which to establish the feature.

Syntax

void MmetSetRegion(
    AIL_ID     ContextId,                   //out
    AIL_INT    FeatureLabelOrIndex,         //in
    AIL_INT    ReferenceFrameLabelOrIndex,  //in
    AIL_INT64  Geometry,                    //in
    AIL_DOUBLE Param1,                      //in
    AIL_DOUBLE Param2,                      //in
    AIL_DOUBLE Param3,                      //in
    AIL_DOUBLE Param4,                      //in
    AIL_DOUBLE Param5,                      //in
    AIL_DOUBLE Param6                       //in
)

Description

This function sets a geometrically-defined ROI, referred to as a metrology region, for a feature within the template of the metrology context. For a physically measured feature, the metrology region delimits the area in the target image from which to establish the edgels of the feature to validate and measure. For a constructed feature, the metrology region delimits the area in the feature itself, which is used as the base feature to build the constructed feature.

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 2D graphics list. This is referred to as a 2D 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 2D graphics list metrology region (M_FROM_GRAPHIC_LIST), the 2D 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 2D 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 geometry and operation of the feature you are adding, with MmetAddFeature. For example, to add a physically measured circle feature that is built using a best fit operation, you can use an M_RING metrology region.

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 Gradient angle.

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

Parameters

`ContextId` (out, AIL_ID)

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` (in, AIL_INT)

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

For specifying a feature

Value	Description
`M_FEATURE_INDEX`	Specifies the index of an existing individual feature.
`M_FEATURE_LABEL`	Specifies the label value of an existing individual feature.

`ReferenceFrameLabelOrIndex` (in, AIL_INT)

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

For specifying the reference frame

Value	Description
`M_DEFAULT`	Same as `M_GLOBAL_FRAME`.
`M_FEATURE_INDEX`	Specifies the index value of an existing reference frame feature.
`M_FEATURE_LABEL`	Specifies the label value of an existing reference frame feature.
`M_GLOBAL_FRAME`	Specifies the global frame as the reference frame.