| MIL 10 Reference
| Customize Help
| Save Settings

MmetSetPosition


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
MmetSave
MmetSetRegion
Synopsis
Set the position of a feature.
Syntax
void MmetSetPosition(
MIL_ID ContextId, //in
MIL_INT FeatureLabelOrIndex, //in
MIL_INT64 TransformationType, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4, //in
MIL_INT64 ControlFlag //in
)
Description

This function moves the specified feature's position in the metrology template of a metrology context.

This function is valid for all measured (MmetAddFeature() with M_MEASURED) and parametrically constructed (MmetAddFeature() with M_CONSTRUCTED and M_PARAMETRIC) features, unless otherwise specified. Typically this function is used to move the position of the global frame or a parametrically constructed local frame (each of which is considered a feature). When specifying a frame, all features and metrology regions that use that frame as their reference frame are moved accordingly. Note that you can also position features using MmetControl() with M_POSITION_X and M_POSITION_Y. However, in this case you must enter exact values; you cannot, for example, position features based on the results of another module, as you can using MmetSetPosition() with M_RESULT.

MIL moves the specified feature relative to its reference frame, except for the global frame, which MIL moves relative to its default origin (0,0). If the target image is not calibrated, the global frame's default origin 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.

If a calibration context is associated with the target image, set positional and dimensional values in real-world units. Otherwise, use pixel units.

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. The metrology context must have been previously allocated on the required system using MmetAlloc().

FeatureLabelOrIndex

Specifies the label or index of the feature you want to position. Set this parameter to one of the following values.

function map For specifying a feature
CollapseValue Description
Collapse M_DEFAULT

Specifies the global frame.
Collapse

Specifies the index value of an existing individual feature.

(summarize)
Parameters

This parameter specifies the index of the feature to position. You can set this parameter to the following:
Value >= 0

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

Specifies the label value of an existing individual feature.

(summarize)
Parameters

This parameter specifies the label of the feature to position. You can set this parameter to the following:
Value > 0

Specifies the label.
TransformationType

Specifies the type of transformation that will be used to set the new position of the feature.

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

Param1

Specifies an attribute of the position to set. Its definition is dependent on the type of position chosen.

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

Param2

Specifies an attribute of the position to set. Its definition is dependent on the type of position chosen.

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

Param3

Specifies an attribute of the position to set. Its definition is dependent on the type of position chosen.

Set this parameter to M_DEFAULT if not used.

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

Param4

Specifies an attribute of the position to set. Its definition is dependent on the type of position chosen.

Set this parameter to M_DEFAULT if not used.

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

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Parameter associations

The table below lists possible values for the TransformationType, Param1, Param2, Param3, and Param4 parameters.

Note that any unused parameters should be set to M_DEFAULT.

function map For selecting the operation that will be used to position the feature
CollapseTransformationType Description
Param1
Param2
Param3
Param4
Collapse M_FORWARD_COEFFICIENTS

Specifies to position the feature using an operation based on forward transformation coefficients, using the equations that follow.

x d = A x s + B y s + C .

y d = -B x s + A y s + D .

(summarize)
Collapse Param1

Sets the forward transformation coefficient A.

(summarize)
Collapse M_DEFAULT

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

Specifies the coefficient.
Collapse Param2

Sets the forward transformation coefficient B.

(summarize)
Collapse M_DEFAULT

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

Specifies the coefficient.
Collapse Param3

Sets the forward transformation coefficient C.

(summarize)
Collapse M_DEFAULT

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

Specifies the coefficient.
Collapse Param4

Sets the forward transformation coefficient D.

(summarize)
Collapse M_DEFAULT

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

Specifies the coefficient.
Collapse M_GEOMETRIC

Specifies to position the feature using an operation based on a translation and rotation.

(summarize)
Collapse Param1

Sets the translation value for the feature, in the X-direction.

(summarize)
Collapse M_DEFAULT

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

Specifies the distance to move the feature, in pixel or world units.
Collapse Param2

Sets the translation value for the feature, in the Y-direction.

(summarize)
Collapse M_DEFAULT

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

Specifies the distance to move the feature, in pixel or world units.
Collapse Param3

Sets the angle of rotation for the feature.

(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_POSITION

Specifies to position the feature at a specific position and angle. This should be used only for a parametrically constructed local frame.

(summarize)
Collapse Param1

Sets the X-coordinate of the origin of the local frame.

(summarize)
Collapse M_DEFAULT

Specifies the default value. The default value is 0.0 pixels.

(summarize)
Collapse Value

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

Sets the Y-coordinate of the origin of the local frame.

(summarize)
Collapse M_DEFAULT

Specifies the default value. The default value is 0.0 pixels.

(summarize)
Collapse Value

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

Sets the angle of the local frame.

(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_RESULT

Specifies to position the feature at the position calculated by another MIL module. Supported modules are Code, Geometric Model Finder, Pattern Matching, and String Reader. If you are using a Model Finder result, you can combine M_RESULT with M_FORWARD_COEFFICIENTS. In this case, the transformation uses the forward coefficients of Model Finder's result occurrence.

(summarize)
Collapse Param1

Sets a MIL result buffer identifier from the MIL module to use to specify the feature's position.

(summarize)
Collapse Param2

Sets the index value of the result occurrence to use to set the feature's position. This value must be a valid index that is contained within the result buffer you provided with Param1.

(summarize)
Type-specific versions of the function
void MmetSetPositionInt64 (MIL_ID ContextId, MIL_INT FeatureLabelOrIndex, MIL_INT64 TransformationType, MIL_INT64 Param1, MIL_DOUBLE Param2, MIL_DOUBLE Param3, MIL_DOUBLE Param4, MIL_INT64 ControlFlag)
Details
Parameters

ContextId

See ContextId of the main function for a description.

FeatureLabelOrIndex

See FeatureLabelOrIndex of the main function for a description.

TransformationType

See TransformationType 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.

ControlFlag

See ControlFlag 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 FORWARD COEFFICIENTS DEFAULT DEFAULT DEFAULT DEFAULT GEOMETRIC DEFAULT DEFAULT DEFAULT POSITION DEFAULT DEFAULT DEFAULT RESULT