| MIL 10 Reference
| Customize Help
| Save Settings

McalFixture


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
McalDraw
McalFree
Synopsis
Move the relative coordinate system or learn the fixturing offset.
Syntax
void McalFixture(
MIL_ID DstCalibratedMilObjectId, //in
MIL_ID FixturingOffsetCalId, //in
MIL_INT64 Operation, //in
MIL_INT64 LocationType, //in
MIL_ID CalOrLocSourceId, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4 //in
)
Description

This function allows you to move the relative coordinate system to a location (position and angle) that is at a fixed offset from an object that you want to analyze. To specify the location, you must pass the calculated reference location for the object and optionally, a preestablished offset to apply to this reference location. To pass the preestablished offset, you must pass a fixturing offset object that contains the information. Use a separate call to this function to set up the fixturing offset object.

When moving the relative coordinate system (M_MOVE_RELATIVE), you can specify the reference location of the object in one of two ways, based upon some previous analysis. You can have McalFixture() use the position and angle of a model occurrence from a specified MIL Pattern Matching or Model Finder result buffer. Alternatively, you can explicitly specify a location with respect to a specified relative coordinate system; internally, McalFixture() converts this location so that it is with respect to the absolute coordinate system, and then uses the calculated location to place the new relative coordinate system.

Note that if you know the new position and angle for the relative coordinate system in the absolute coordinate system, use McalSetCoordinateSystem() or McalRelativeOrigin() to move it explicitly. Alternatively, you can specify the default uniform calibration context (M_DEFAULT_UNIFORM_CALIBRATION) as the coordinate system in which the location is expressed (CalOrLocSourceId). This calibration context's relative coordinate system is always aligned with its absolute coordinate system (no angle, no offset, no scale). Therefore, the specified location is consequently interpreted as being relative to the absolute coordinate system.

When setting up the fixturing offset object (M_LEARN_OFFSET), McalFixture() learns the offset between a specified location and the relative coordinate system. You can specify the location using the same techniques as those available when moving the relative coordinate system. In addition, you can set it to the reference location of a specified model in its original model source image. The function then saves the offset between the location and its relative coordinate system, in the specified fixturing offset object. Typically, you have obtained the location from a training image, whereby the location is a typical reference location and the relative coordinate system is at a required offset from this location.

McalFixture() assumes that the reference location and preestablished offset use the same absolute coordinate system as the image/calibrated context in which to save the new relative coordinate system, even if their mapping to the pixel coordinate system is different.

For more information on fixturing, see Chapter 26: Fixturing in MIL.

If you adjust the relative coordinate system of a calibrated image associated with an M_VECTOR_AND_RASTER ROI, the raster information will be discarded, causing the ROI to become an M_VECTOR ROI. See MbufSetRegion() for more information.

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
DstCalibratedMilObjectId

Specifies the identifier of the destination calibration context, the 3D reconstruction result buffer, or the calibrated image for which to displace the relative coordinate system. If the Operation parameter is set to M_LEARN_OFFSET, this parameter should be set to M_NULL.

Note that if an image is passed but is not associated with a calibration context, it is automatically considered to be associated with a uniform calibration context where there is no scaling, rotation, or offset present. Therefore, each pixel in the image is considered to represent the same area in real world units and the image is assumed to have no non-linear distortions.

FixturingOffsetCalId

Specifies the identifier of the fixturing offset object to set up (M_LEARN_OFFSET) or to apply to the reference location when moving the relative coordinate system (M_MOVE_RELATIVE). The fixturing offset object must have been previously allocated using McalAlloc(). If you don't need to apply a fixturing offset when moving the relative coordinate system, set this parameter to M_NULL.

Operation

Specifies the operation to perform.

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

LocationType

Specifies how the location used for the operation is specified.

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

CalOrLocSourceId

Specifies the identifier of the MIL object containing the location for the operation, or containing the coordinate system in which the location is expressed.

When this parameter is not used, it should be set to M_DEFAULT.

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

Param1

Specifies information about the location used for the operation. Its definition is dependent on the specified operation and the location type.

When this parameter is not used, it should be set to M_DEFAULT.

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

Param2

Specifies information about the location used for the operation. Its definition is dependent on the specified operation and the location type.

When this parameter is not used, it should be set to M_DEFAULT.

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

Param3

Specifies information about the location used for the operation. Its definition is dependent on the specified operation and the location type.

When this parameter is not used, it should be set to M_DEFAULT.

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

Param4

Specifies information about the location used for the operation. Its definition is dependent on the specified operation and the location type.

When this parameter is not used, it should be set to M_DEFAULT.

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

Parameter associations

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

Any parameter that is not used should be set to M_DEFAULT.

function map For specifying the location used for the operation
CollapseOperation Description
LocationType
CalOrLocSourceId
Param1
Param2
Param3
Param4
Collapse M_LEARN_OFFSET

Learns the offset between the specified location and the coordinate system in which it is expressed, and saves this offset in the specified fixturing offset object. INQ

(summarize)
Collapse M_MODEL_MOD

Specifies to use the location of a Model Finder model's reference axis (that is, the model's reference location) in the model source image. Note that this location is with respect to the model source image's top left corner (the top left corner of the original image from which the model was defined), and not the model image itself.

To set the reference location of the model, use MmodControl() with M_REFERENCE_X, M_REFERENCE_Y, and M_REFERENCE_ANGLE.

(summarize)
Collapse CalOrLocSourceId

Specifies the Model Finder context identifier.

(summarize)
Collapse Param1

Specifies the index of the model within the context.

(summarize)
Collapse M_MODEL_PAT

Specifies to use the reference location of a Pattern Matching model in its source image.

To set the reference location of the model, use MpatSetCenter().

(summarize)
Collapse CalOrLocSourceId

Specifies the Pattern Matching model identifier.

(summarize)
Collapse Param1

Specifies a calibration context or calibrated image that defines the pixel-to-world mapping of the Pattern Matching model's source image.

This is needed because this association is not stored with the model.

(summarize)
Collapse M_POINT_AND_ANGLE

Specifies to use the specified point and angle as the location.

(summarize)
Collapse CalOrLocSourceId

Specifies the relative coordinate system in which the point and angle are expressed.

(summarize)
Collapse M_DEFAULT_UNIFORM_CALIBRATION

Specifies to use the relative coordinate system of a uniform calibration where the absolute and relative coordinate systems are equal to the pixel coordinate system.
Collapse Calibrated image ID

Specifies the identifier of the calibrated image.

If an image is passed but is not associated with a calibration context, it will be treated as if associated with a uniform calibration context where there is no scaling, rotation, or offset present. Therefore, each pixel in the image will be considered to represent the same area in real world units and it will be assumed that no non-linear distortions are present within the image.

(summarize)
Collapse Calibration context ID

Specifies the identifier of the calibration context which defines the relative coordinate system in which the point and angle are expressed.
Collapse Param1

Specifies the X-coordinate of the point, expressed in the specified relative coordinate system.
Collapse Param2

Specifies the Y-coordinate of the point, expressed in the specified relative coordinate system.
Collapse Param3

Specifies the angle, in degrees. The angle is measured from the positive X-axis towards the negative Y-axis of the specified relative coordinate system, as described in the Angle convention in MIL subsection of the Working with real-world units section of Chapter 25: Calibrating your camera setup.

(summarize)
Collapse M_POINT_AND_DIRECTION_POINT

Specifies to use two points to define the location. The first point defines the position, and the angle of the vector going from the first point to the second point defines the angle.

(summarize)
Collapse CalOrLocSourceId

Specifies the relative coordinate system in which the two points are expressed.

(summarize)
Collapse M_DEFAULT_UNIFORM_CALIBRATION

Specifies to use the relative coordinate system of a uniform calibration where the absolute and relative coordinate systems are equal to the pixel coordinate system.
Collapse Calibrated image ID

Specifies the identifier of the calibrated image.

If an image is passed but is not associated with a calibration context, it will be treated as if associated with a uniform calibration context where there is no scaling, rotation, or offset present. Therefore, each pixel in the image will be considered to represent the same area in real world units and it will be assumed that no non-linear distortions are present within the image.

(summarize)
Collapse Calibration context ID

Specifies the identifier of the calibration context which defines the relative coordinate system in which the point and angle are expressed.
Collapse Param1

Specifies the X-coordinate of the first point, expressed in the specified relative coordinate system.
Collapse Param2

Specifies the Y-coordinate of the first point, expressed in the specified relative coordinate system.
Collapse Param3

Specifies the X-coordinate of the second point, expressed in the specified relative coordinate system.
Collapse Param4

Specifies the Y-coordinate of the second point, expressed in the specified relative coordinate system.
Collapse M_RESULT_MET

Specifies to use the resulting position and angle of a metrology reference frame.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of a Metrology result buffer.

(summarize)
Collapse Param1

Specifies the index of the reference frame feature to use. An index value of 0 represents the global frame. Note that the only metrology features supported are local or global frame results.

(summarize)
Collapse M_RESULT_MOD

Specifies to use the position and angle of a Model Finder model occurrence.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of the Model Finder result buffer.

(summarize)
Collapse Param1

Specifies the index of the result occurrence.

(summarize)
Collapse M_RESULT_PAT

Specifies to use the position and angle of a Pattern Matching model occurrence.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of the Pattern Matching result buffer.

(summarize)
Collapse Param1

Specifies the index of the result occurrence.

(summarize)
Collapse M_MOVE_RELATIVE

Moves the relative coordinate system to a location that is at a specified offset from the specified reference location. If no fixturing offset object is specified, the relative coordinate system is placed at the specified reference location.

(summarize)
Collapse M_LASER_3DMAP

Specifies to use the laser line coordinate system, defined by the 3D reconstruction context, to define the location. Note that the context must have been allocated using M_CALIBRATED_CAMERA_LINEAR_MOTION and have been calibrated using M3dmapCalibrate() or M3dmapCalibrateMultiple().

(summarize)
Collapse CalOrLocSourceId

Specifies the laser line coordinate system.

(summarize)
Collapse 3D reconstruction context ID

Specifies the identifier of the 3D reconstruction context which defines the laser line coordinate system.
Collapse M_POINT_AND_ANGLE

Specifies to use the specified point and angle as the reference location.

(summarize)
Collapse CalOrLocSourceId

Specifies the relative coordinate system in which the point and angle are expressed.

(summarize)
Collapse M_DEFAULT

Specifies to use the current relative coordinate system of the target calibrated image or target calibration context (DstCalibratedMilObjectId).
Collapse Calibrated image ID

Specifies the identifier of the calibrated image.

If an image is passed but is not associated with a calibration context, it will be treated as if associated with a uniform calibration context where there is no scaling, rotation, or offset present. Therefore, each pixel in the image will be considered to represent the same area in real world units and it will be assumed that no non-linear distortions are present within the image.

(summarize)
Collapse Calibration context ID

Specifies the identifier of the calibration context which defines the relative coordinate system in which the point and angle are expressed.
Collapse Param1

Specifies the X-coordinate of the point, expressed in the specified relative coordinate system.
Collapse Param2

Specifies the Y-coordinate of the point, expressed in the specified relative coordinate system.
Collapse Param3

Specifies the angle, in degrees. The angle is measured from the positive X-axis towards the negative Y-axis of the specified relative coordinate system, as described in the Angle convention in MIL subsection of the Working with real-world units section of Chapter 25: Calibrating your camera setup.

(summarize)
Collapse M_POINT_AND_DIRECTION_POINT

Specifies to use two points to define the location. The first point defines the position, and the angle of the vector going from the first point to the second point defines the angle.

(summarize)
Collapse CalOrLocSourceId

Specifies the relative coordinate system in which the two points are expressed.

(summarize)
Collapse M_DEFAULT

Specifies to use the current relative coordinate system of the target calibrated image or target calibration context (DstCalibratedMilObjectId).
Collapse Calibrated image ID

Specifies the identifier of the calibrated image.

If an image is passed but is not associated with a calibration context, it will be treated as if associated with a uniform calibration context where there is no scaling, rotation, or offset present. Therefore, each pixel in the image will be considered to represent the same area in real world units and it will be assumed that no non-linear distortions are present within the image.

(summarize)
Collapse Calibration context ID

Specifies the identifier of the calibration context which defines the relative coordinate system in which the point and angle are expressed.
Collapse Param1

Specifies the X-coordinate of the first point, expressed in the specified relative coordinate system.
Collapse Param2

Specifies the Y-coordinate of the first point, expressed in the specified relative coordinate system.
Collapse Param3

Specifies the X-coordinate of the second point, expressed in the specified relative coordinate system.
Collapse Param4

Specifies the Y-coordinate of the second point, expressed in the specified relative coordinate system.
Collapse M_POINT_CLOUD_CONTAINER_3DMAP

Specifies to use the relative coordinate system of the 3D reconstruction result buffer to define the location.

(summarize)
Collapse CalOrLocSourceId

Specifies the relative coordinate system.

(summarize)
Collapse 3D reconstruction result ID

Specifies the identifier of the 3D reconstruction result buffer, which defines the relative coordinate system of the result buffer.
Collapse M_RESULT_ALIGNMENT_3DMAP

Specifies to use the transformation matrix in a 3D alignment result buffer as the reference location.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of a 3D alignment result buffer.

(summarize)
Collapse Param1

Specifies to use the transformation matrix of a specific interim iteration in the pairwise 3D alignment process. This can be useful for debugging the pairwise 3D alignment process.

Note that iteration 0 is the prealignment, regardless of whether a prealignment matrix was provided. Specifying 0 will use the transformation matrix of that iteration.

The maximum value must be smaller than the total number of iterations performed in the pairwise 3D alignment process (M3dmapGetResult() set to M_NB_ITERATIONS).

(summarize)
Collapse M_DEFAULT

Specifies to use the final iteration in the pairwise 3D alignment process.
Collapse 0 <= Value < number of iterations

Specifies the iteration to use.
Collapse M_RESULT_MET

Specifies to use the resulting position and angle of a metrology reference frame as the reference location.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of a Metrology result buffer.

(summarize)
Collapse Param1

Specifies the index of the frame feature to use. An index value of 0 represents the global frame. Note that the only metrology features supported are local or global frame results.

(summarize)
Collapse M_RESULT_MOD

Specifies to use the position and angle of a Model Finder model occurrence as the reference location.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of the Model Finder result buffer.

(summarize)
Collapse Param1

Specifies the index of the result occurrence.

(summarize)
Collapse M_RESULT_PAT

Specifies to use the position and angle of a Pattern Matching model occurrence as the reference location.

(summarize)
Collapse CalOrLocSourceId

Specifies the identifier of the Pattern Matching result buffer.

(summarize)
Collapse Param1

Specifies the index of the result occurrence.

(summarize)
Collapse M_SAME_AS_SOURCE

Specifies that the relative coordinate system of CalOrLocSourceId is copied into DstCalibratedMilObjectId and takes the fixturing offset into account (if any).

(summarize)
Collapse CalOrLocSourceId

Specifies the calibration context to be copied. This can be any calibrated object.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
NULL PROC LEARN OFFSET MODEL MOD MODEL PAT NULL PROC POINT AND ANGLE DEFAULT UNIFORM CALIBRATION NULL PROC POINT AND DIRECTION POINT DEFAULT UNIFORM CALIBRATION NULL PROC RESULT MET RESULT MOD RESULT PAT MOVE RELATIVE LASER 3DMAP POINT AND ANGLE DEFAULT NULL PROC POINT AND DIRECTION POINT DEFAULT NULL PROC POINT CLOUD CONTAINER 3DMAP RESULT ALIGNMENT 3DMAP DEFAULT RESULT MET RESULT MOD RESULT PAT SAME AS SOURCE NULL