| Customize Help
| Save Settings

McalSetCoordinateSystem



Function Map
Synopsis
Change the position and orientation of a coordinate system.
Syntax
void McalSetCoordinateSystem(
MIL_ID CalibratedMilObjectId, //in
MIL_INT64 TargetCoordinateSystem, //in
MIL_INT64 ReferenceCoordinateSystem, //in
MIL_INT64 TransformType, //in
MIL_ID ArrayBufOrMatrix3dgeoId, //in
MIL_DOUBLE Param1, //in
MIL_DOUBLE Param2, //in
MIL_DOUBLE Param3, //in
MIL_DOUBLE Param4 //in
)
Description

This function moves a specified (target) coordinate system in relation to a specified (reference) coordinate system. For example, you can move the relative coordinate system by (0, 6, 0) in the absolute coordinate system. This will displace the origin of the relative coordinate system by 6 units along the Y-axis of the absolute coordinate system. You can call this function to move the relative coordinate system of a camera calibration context, calibrated image, or 3D reconstruction result buffer of type M_POINT_CLOUD_RESULT. Note that to return the position and orientation of one coordinate system as a transformation of another coordinate system, you can use McalGetCoordinateSystem().

If you are moving the relative coordinate system of an image that has been corrected, the XY-plane of the relative coordinate system should not be moved in the Z-direction and should not be rotated around its X or Y-axis. In other words, the relative coordinate system of a corrected image can only be translated along its X or Y-axis or rotated around its Z-axis. Moving the relative coordinate system of an image is useful for analyzing an object using a temporary local coordinate system. You can also use McalFixture() to move the relative coordinate system with respect to a result. If you move the relative coordinate system, results returned in world units from other modules are returned with respect to the relative coordinate system's new position, and settings which accept input in world units will accept that input with respect to the relative coordinate system's new position.

If you transform the camera or tool coordinate system, MIL assumes that the camera has been moved in your camera setup, so it adjusts the camera calibration mapping between the absolute coordinate system and the pixel coordinate system.

You can also use this function to transform the relative coordinate system of a 3D reconstruction result buffer of type M_POINT_CLOUD_RESULT, which M3dmapGetResult() uses to express world coordinates. To transform the relative coordinate system of a result buffer, TargetCoordinateSystem must be set to M_RELATIVE_COORDINATE_SYSTEM and ReferenceCoordinateSystem must be set to M_RELATIVE_COORDINATE_SYSTEM or M_ABSOLUTE_COORDINATE_SYSTEM.

Note that all angles should be given in degrees. However, unlike most other MIL functions (including McalRelativeOrigin()), angles are interpreted using the right-hand grip rule around the axis of rotation; if you wrap your right hand around the axis of rotation, pointing your thumb in the positive direction of the axis, your fingers wrap in the direction of rotation. For example, a positive rotation around the Z-axis corresponds to a rotation that turns the positive X-axis toward the positive Y-axis.

You can specify whether the transformation of the target coordinate system is applied from the current position (M_COMPOSE_WITH_CURRENT) of the target coordinate system or from the origin of the reference coordinate system (M_ASSIGN).

Note that you cannot move the pixel coordinate system nor the absolute coordinate system.

If you adjust the 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 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
CalibratedMilObjectId

Specifies the identifier of a camera calibration context, 3D reconstruction result buffer of type M_POINT_CLOUD_RESULT, or a calibrated image.

TargetCoordinateSystem

Specifies the coordinate system on which to apply the transformation. This parameter can be set to one of the following.

If CalibratedMilObjectId is set to a 3D reconstruction result buffer (must be of type M_POINT_CLOUD_RESULT) or a calibrated image, TargetCoordinateSystem must be set to M_RELATIVE_COORDINATE_SYSTEM.

function map For specifying the target coordinate system
Click to summarizeValue Description
Click to summarize M_CAMERA_COORDINATE_SYSTEM

Specifies to apply the transformation to the camera coordinate system. The origin of the camera coordinate system corresponds to the effective pinhole of the modeled camera and the Z-axis of the camera coordinate system points in the direction that the camera is facing.

By default, a rigid link exists between the tool and camera coordinate systems such that moving one automatically moves the other accordingly. This can be temporarily broken using McalControl() with M_LINK_TOOL_AND_CAMERA.

This coordinate system can only be moved when CalibratedMilObjectId is set to a 3D-based camera calibration context (McalAlloc() set to M_3D_ROBOTICS or M_TSAI_BASED) that you have successfully calibrated, or after using McalSetCoordinateSystem() with M_ASSIGN.

(summarize)
Click to summarize M_RELATIVE_COORDINATE_SYSTEM

Specifies to apply the transformation to the relative coordinate system. The relative coordinate system defines the world plane in which results are measured. By default, it corresponds to the absolute coordinate system.

(summarize)
Click to summarize M_ROBOT_BASE_COORDINATE_SYSTEM

Specifies to apply the transformation to the robot-base coordinate system. The origin of this coordinate system is positioned at the base of the robot holding the camera. This coordinate system is defined as the origin of the robot encoders. If the encoders of the robot all indicate 0, it means that the tool coordinate system is at the same position and orientation as the robot-base coordinate system.

This coordinate system can only be moved when CalibratedMilObjectId is set to a camera calibration context of type M_3D_ROBOTICS that you have successfully calibrated, or after using McalSetCoordinateSystem() with M_ASSIGN.

The only way to change the position and orientation of this coordinate system is when you reset the encoders on a mobile robot.

(summarize)
Click to summarize M_TOOL_COORDINATE_SYSTEM

Specifies to apply the transformation to the tool coordinate system. The tool coordinate system is used to position the camera. Though this coordinate system can be used to move the camera, it need not be associated with the real camera position. By default, its axes are parallel to the absolute coordinate system, and its origin is the same as that of the absolute coordinate system.

By default, a rigid link exists between the tool and camera coordinate systems such that moving one automatically moves the other accordingly. This can be temporarily broken using McalControl() with M_LINK_TOOL_AND_CAMERA.

This coordinate system can only be moved when CalibratedMilObjectId is set to a 3D-based camera calibration context (McalAlloc() set to M_3D_ROBOTICS or M_TSAI_BASED) that you have successfully calibrated, or after using McalSetCoordinateSystem() with M_ASSIGN.

(summarize)
ReferenceCoordinateSystem

Specifies the reference coordinate system. The reference coordinate system must be defined before calling this function. This parameter can be set to one of the following values.

If your CalibratedMilObjectId is a 3D reconstruction result buffer (must be of type M_POINT_CLOUD_RESULT), ReferenceCoordinateSystem must be set to M_RELATIVE_COORDINATE_SYSTEM or M_ABSOLUTE_COORDINATE_SYSTEM.

function map For specifying the reference coordinate system
Click to summarizeValue Description
Click to summarize M_DEFAULT

Same as M_ABSOLUTE_COORDINATE_SYSTEM.

Click to summarize M_ABSOLUTE_COORDINATE_SYSTEM

Specifies to use the absolute coordinate system as a reference coordinate system for the transformation. The absolute coordinate system is unmovable and is the coordinate system from which all other world coordinate systems are defined. By default, the origin of the absolute coordinate system corresponds to the center of the top-left calibration point when using McalGrid().

(summarize)
Click to summarize M_CAMERA_COORDINATE_SYSTEM

Specifies to use the camera coordinate system as a reference coordinate system for the transformation. The camera coordinate system's origin corresponds to the effective pinhole of the modeled camera and its Z-axis points in the direction that the camera is facing.

(summarize)
Click to summarize M_RELATIVE_COORDINATE_SYSTEM

Specifies to use the relative coordinate system as a reference coordinate system for the transformation. The relative coordinate system defines the world plane in which results are returned. By default, it corresponds to the absolute coordinate system. The relative coordinate system can be recentered and/or re-oriented using either McalSetCoordinateSystem() or McalRelativeOrigin().

(summarize)
Click to summarize M_ROBOT_BASE_COORDINATE_SYSTEM

Specifies to use the robot base coordinate system as a reference coordinate system for the transformation. This coordinate system is defined as the origin of the robot encoders. If the encoders of the robot all indicate 0, it means that the tool coordinate system is at the same position and orientation as the robot base coordinate system.

This coordinate system can only used as a reference when CalibratedMilObjectId is set to a M_3D_ROBOTICS that you have successfully calibrated, or after using McalSetCoordinateSystem() with M_ASSIGN.

The position and orientation of this coordinate system are only changed when resetting the encoders on a mobile robot.

(summarize)
Click to summarize M_TOOL_COORDINATE_SYSTEM

Specifies to use the tool coordinate system as a reference coordinate system for the transformation. The tool coordinate system is used to position the camera. By default, its axes are parallel to the absolute coordinate system, and its origin is the same as that of the absolute coordinate system.

(summarize)
TransformType

Specifies the type of transformation to apply to the target coordinate system.

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

ArrayBufOrMatrix3dgeoId

Specifies the identifier of a MIL array buffer that contains the transformation matrix to use, or specifies the identifier of a transformation matrix object. The expected transformation matrix is dependent on the type of transformation selected.

The MIL array buffer must be a 32-bit floating-point buffer, allocated using MbufAlloc2d() with M_ARRAY. The required buffer size is dependent on the type of transformation selected.

The transformation matrix object must have been previously allocated using M3dgeoAlloc() with M_TRANSFORMATION_MATRIX.

If using a transformation matrix, it must represent a rotation and/or translation, nothing else (for example, it cannot represent a scale); otherwise, an error is reported.

Set this parameter to M_NULL if not used.

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

Param1

Specifies an attribute of the transformation. Its definition is dependent on the type of transformation selected.

Set this parameter to M_DEFAULT if not used.

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

Param2

Specifies an attribute of the transformation. Its definition is dependent on the type of transformation selected.

Set this parameter to M_DEFAULT if not used.

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

Param3

Specifies an attribute of the transformation. Its definition is dependent on the type of transformation selected.

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 transformation. Its definition is dependent on the type of transformation selected.

Set this parameter to M_DEFAULT if not used.

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

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

Note that if Param1, Param2, Param3, or Param4 are not required by the transformation, they should be set to M_DEFAULT.

function map For specifying the transformation type
Click to summarizeTransformType Description
ArrayBufOrMatrix3dgeoId
Param1
Param2
Param3
Param4
Click to summarize M_HOMOGENEOUS_MATRIX +

Specifies to apply a translation, a rotation, or both to the target coordinate system. Specify the transformation using a 4x4 homogenous matrix.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

Specifies the identifier of the MIL array buffer or the transformation matrix object containing the matrix representation of the rotation.

(summarize)
Click to summarize M_IDENTITY +

Specifies to apply the identity transformation to the target coordinate system. When used with the M_ASSIGN combination constant, this operation transforms the target coordinate system so that it has the same position and orientation as the reference coordinate system.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize M_ROTATION_AXIS_ANGLE +

Specifies to apply a rotation operation described by an axis and angle of rotation. The axis of rotation is defined by a vector. The angle of rotation is measured in the counter-clockwise direction around the axis of rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the X-component of the vector that defines the axis of rotation.

Click to summarize Param2

Specifies the Y-component of the vector that defines the axis of rotation.

Click to summarize Param3

Specifies the Z-component of the vector that defines the axis of rotation.

Click to summarize Param4

Specifies the angle of the rotation, in degrees, around the axis of rotation.

(summarize)
Click to summarize M_ROTATION_AXIS_X +

Specifies to apply a rotation operation on the target coordinate system which corresponds to the rotation that aligns the X-axis of the reference coordinate system with the specified vector.


You must specify a combination value from the following table:
(summarize)
Click to summarize Param1

Specifies the X-component of the vector.

Click to summarize Param2

Specifies the Y-component of the vector.

Click to summarize Param3

Specifies the Z-component of the vector.

Click to summarize M_ROTATION_AXIS_Y +

Specifies to apply a rotation operation on the target coordinate system which corresponds to the rotation that aligns the Y-axis of the reference coordinate system with the specified vector.


You must specify a combination value from the following table:
(summarize)
Click to summarize Param1

Specifies the X-component of the vector.

Click to summarize Param2

Specifies the Y-component of the vector.

Click to summarize Param3

Specifies the Z-component of the vector.

Click to summarize M_ROTATION_AXIS_Z +

Specifies to apply a rotation operation on the target coordinate system which corresponds to the rotation that aligns the Z-axis of the reference coordinate system with the specified vector.


You must specify a combination value from the following table:
(summarize)
Click to summarize Param1

Specifies the X-component of the vector.

Click to summarize Param2

Specifies the Y-component of the vector.

Click to summarize Param3

Specifies the Z-component of the vector.

Click to summarize M_ROTATION_MATRIX +

Specifies to apply a rotation operation that is described by a 3x3 rotation matrix.

Note that, if using a transformation matrix, the translation part of the matrix is ignored (no error is reported if it contains a translation).


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

Specifies the identifier of the MIL array buffer or the transformation matrix object containing the matrix representation of the rotation.

(summarize)
Click to summarize M_ROTATION_QUATERNION +

Specifies to apply a rotation operation that is described by a rotation quaternion.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the scalar component of the quaternion.

Click to summarize Param2

Specifies the X-component of the quaternion.

Click to summarize Param3

Specifies the Y-component of the quaternion.

Click to summarize Param4

Specifies the Z-component of the quaternion.

Click to summarize M_ROTATION_X +

Specifies to apply a rotation operation that is described by a rotation around the X-axis.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_XYZ +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the X-axis, a rotation about the Y-axis, and a rotation about Z-axis rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_XZY +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the X-axis, a rotation about the Z-axis, and a rotation about the Y-axis rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_Y +

Specifies to apply a rotation operation that is described by a rotation about the Y-axis.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_YXZ +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the Y-axis, a rotation about the X-axis, and a rotation about Z-axis rotation. This is also known as roll-pitch-yaw rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_YZX +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the Y-axis, a rotation about the Z-axis, and a rotation about the X-axis rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_Z +

Specifies to apply a rotation operation that is described by a rotation about the Z-axis.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_ZXY +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the Z-axis, a rotation about the X-axis, and a rotation about the Y-axis rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize M_ROTATION_ZYX +

Specifies to apply a rotation operation that is described by three distinct rotations about the axes of the reference coordinate system in the following order: a rotation about the Z-axis, a rotation about the Y-axis, and a rotation about the X-axis rotation.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the Z-axis rotation, in degrees.

(summarize)
Click to summarize Param2

Specifies the Y-axis rotation, in degrees.

(summarize)
Click to summarize Param3

Specifies the X-axis rotation, in degrees.

(summarize)
Click to summarize M_TRANSLATION +

Specifies to apply a translation operation along each of the reference coordinate system's axes.


You must specify a combination value from the following table:
(summarize)
Click to summarize ArrayBufOrMatrix3dgeoId

This parameter must be set to M_NULL.

Click to summarize Param1

Specifies the displacement along the X-axis of the reference coordinate system.

Click to summarize Param2

Specifies the displacement along the Y-axis of the reference coordinate system.

Click to summarize Param3

Specifies the displacement along the Z-axis of the reference coordinate system.

Combination values for the values listed in For specifying the transformation type.

You must add one of the following values to the above-mentioned values to specify how to apply the transformation.

function map For specifying how to apply the transformation
Click to summarizeCombination value Description
Click to summarize M_ASSIGN

Specifies to assign the specified transformation to the target coordinate system from the origin and orientation of the reference coordinate system.

This is the default value.

(summarize)
Click to summarize M_COMPOSE_WITH_CURRENT

Specifies to compose the specified transformation with the current position and orientation in the reference coordinate system. This effectively applies the transformation to the current position and orientation of the target coordinate system. Note that this constant cannot be used with an undefined coordinate system.

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
NULL PROC CAMERA COORDINATE SYSTEM RELATIVE COORDINATE SYSTEM ROBOT BASE COORDINATE SYSTEM TOOL COORDINATE SYSTEM DEFAULT ABSOLUTE COORDINATE SYSTEM CAMERA COORDINATE SYSTEM RELATIVE COORDINATE SYSTEM ROBOT BASE COORDINATE SYSTEM TOOL COORDINATE SYSTEM FLOAT HOMOGENEOUS MATRIX FLOAT IDENTITY ROTATION AXIS ANGLE ROTATION AXIS X ROTATION AXIS Y ROTATION AXIS Z ROTATION MATRIX FLOAT ROTATION QUATERNION ROTATION X ROTATION XYZ ROTATION XZY ROTATION Y ROTATION YXZ ROTATION YZX ROTATION Z ROTATION ZXY ROTATION ZYX TRANSLATION ASSIGN COMPOSE WITH CURRENT