| MIL 10 Reference
| Customize Help
| Save Settings

McalGetCoordinateSystem


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
McalFree
McalGrid
Synopsis
Return the position and orientation of a coordinate system.
Syntax
void McalGetCoordinateSystem(
MIL_ID CalibratedMilObjectId, //in
MIL_INT64 TargetCoordinateSystem, //in
MIL_INT64 ReferenceCoordinateSystem, //in
MIL_INT64 InquireType, //in
MIL_ID MatrixId, //in
MIL_DOUBLE *Param1Ptr, //out
MIL_DOUBLE *Param2Ptr, //out
MIL_DOUBLE *Param3Ptr, //out
MIL_DOUBLE *Param4Ptr //out
)
Description

This function returns the position and orientation of one coordinate system as a transformation of another coordinate system. For example, you can use this function to inquire about the position of your camera in the absolute coordinate system; essentially, you can inquire about the origin and orientation of the camera coordinate system with respect to the absolute coordinate system. Note that to move a specified (target) coordinate system relative to a reference coordinate system, you can use McalSetCoordinateSystem().

Note that McalGetCoordinateSystem() returns angles in degrees. However, unlike most other MIL functions, this function returns angles following 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.

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
CalibratedMilObjectId

Specifies the identifier of the calibration context, a 3D reconstruction context, a 3D reconstruction result buffer of type M_POINT_CLOUD_CONTAINER, or any object which has calibration information, such as an image or a result buffer.

TargetCoordinateSystem

Specifies which coordinate system to inquire. This parameter must be set to one of the following values:

Note that when CalibratedMilObjectId is set to a 3D reconstruction context, the context must be of type M_CALIBRATED_CAMERA_LINEAR_MOTION and must have already been calibrated using M3dmapCalibrate() or M3dmapCalibrateMultiple(). In this case, TargetCoordinateSystem can only be set to either M_ABSOLUTE_COORDINATE_SYSTEM or M_LASER_LINE_COORDINATE_SYSTEM.

Note that when CalibratedMilObjectId is set to a 3D reconstruction result buffer, the result buffer must be of type M_POINT_CLOUD_CONTAINER. In this case, TargetCoordinateSystem can only be set to either M_ABSOLUTE_COORDINATE_SYSTEM or M_RELATIVE_COORDINATE_SYSTEM.

function map For specifying the target coordinate system
CollapseValue Description
Collapse M_ABSOLUTE_COORDINATE_SYSTEM

Specifies an implicit and unmovable coordinate system from which all other coordinate systems are defined. By default, it corresponds to the center of the top-left calibration point of the calibration grid if calibrated using McalGrid().

(summarize)
Collapse M_CAMERA_COORDINATE_SYSTEM

Specifies the coordinate system whose origin corresponds to the effective pinhole of the camera and whose Z-axis points in the direction that the camera is facing. This coordinate system is only defined after a successful calibration in M_TSAI_BASED or M_3D_ROBOTICS mode. Alternatively, you can define this coordinate system using McalSetCoordinateSystem() with M_ASSIGN.

(summarize)
Collapse M_LASER_LINE_COORDINATE_SYSTEM

Specifies the coordinate system whose origin is on the first laser line at the point closest to the origin of the absolute coordinate system.

This value is only supported when CalibratedMilObjectId is set to a valid calibrated 3D reconstruction context.

(summarize)
Collapse M_RELATIVE_COORDINATE_SYSTEM

Specifies the coordinate system which determines the world plane used when working with world units which can be recentered and/or reoriented using McalSetCoordinateSystem() or McalRelativeOrigin(). By default, it corresponds to the absolute coordinate system.

(summarize)
Collapse M_ROBOT_BASE_COORDINATE_SYSTEM

Specifies the coordinate system whose origin is positioned at the base of the robot holding the camera. This coordinate system is only supported for M_3D_ROBOTICS calibration mode. It is defined using McalSetCoordinateSystem() with M_ASSIGN, or after a successful calibration with McalGrid() or McalList().

(summarize)
Collapse M_TOOL_COORDINATE_SYSTEM

Specifies the coordinate system used to change the position of the camera coordinate system. Although you can use this coordinate system to move the camera coordinate system, 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.

(summarize)
ReferenceCoordinateSystem

Specifies the coordinate system that will be used as a reference for calculations. All returned coordinates or angles will be calculated relative to this coordinate system. This parameter must be set to one of the following values:

Note that when CalibratedMilObjectId is set to a 3D reconstruction context of type M_CALIBRATED_CAMERA_LINEAR_MOTION, the context must be of type M_CALIBRATED_CAMERA_LINEAR_MOTION and must have already been calibrated using M3dmapCalibrate() or M3dmapCalibrateMultiple(). In this case, ReferenceCoordinateSystem can only be set to either M_ABSOLUTE_COORDINATE_SYSTEM or M_LASER_LINE_COORDINATE_SYSTEM.

Note that when CalibratedMilObjectId is set to a 3D reconstruction result buffer, the result buffer must be of type M_POINT_CLOUD_CONTAINER. In this case, ReferenceCoordinateSystem can only be set to either M_ABSOLUTE_COORDINATE_SYSTEM or M_RELATIVE_COORDINATE_SYSTEM.

function map For specifying the reference coordinate system
CollapseValue Description
Collapse M_DEFAULT

Same as M_ABSOLUTE_COORDINATE_SYSTEM.
Collapse M_ABSOLUTE_COORDINATE_SYSTEM

Specifies an implicit and unmovable coordinate system from which all other world coordinate systems are defined. By default, the origin lies at the center of the top-left calibration point when using McalGrid().

(summarize)
Collapse M_CAMERA_COORDINATE_SYSTEM

Specifies the coordinate system whose origin corresponds to the effective pinhole of the camera and whose Z-axis points in the direction that the camera is facing. This coordinate system can only be used as a reference coordinate system after it has been defined, either by a successful calibration in M_TSAI_BASED or M_3D_ROBOTICS mode. Alternatively, you can define this coordinate system using McalSetCoordinateSystem() with M_ASSIGN.

(summarize)
Collapse M_LASER_LINE_COORDINATE_SYSTEM

Specifies the coordinate system whose origin is on the first laser line at the point closest to the origin of the absolute coordinate system.

This value is only supported when CalibratedMilObjectId is set to a valid calibrated 3D reconstruction context.

(summarize)
Collapse M_RELATIVE_COORDINATE_SYSTEM

Specifies the coordinate system used when working in world units, which can be recentered and/or reoriented using McalSetCoordinateSystem() or McalRelativeOrigin(). By default, it is equivalent to the absolute coordinate system.

(summarize)
Collapse M_ROBOT_BASE_COORDINATE_SYSTEM

Specifies the coordinate system whose origin is positioned at the base of the robot holding the camera. This coordinate system is only supported for M_3D_ROBOTICS calibration mode. It is defined using McalSetCoordinateSystem() with M_ASSIGN, or after a successful calibration with McalGrid() or McalList().

(summarize)
Collapse M_TOOL_COORDINATE_SYSTEM

Specifies the coordinate system used to change the position of the camera coordinate system. Although this is the coordinate system used to move the camera coordinate system, 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.

(summarize)
InquireType

Specifies the type of transformation to use to return the location of the target coordinate system with respect to the reference coordinate system.

Any parameters for which a value is not returned (MatrixId, and Param1Ptr to Param4Ptr) must be set to M_NULL.

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

MatrixId

Specifies the matrix representation of a transformation, in an array buffer. The buffer must be a 32-bit float buffer, allocated using MbufAlloc2d() with M_ARRAY. The required buffer size will depend on the results being returned.

If this parameter is not used, it must be set to M_NULL.

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

Param1Ptr

Specifies the address in which to return information about the transformation required to cause the reference coordinate system to overlap or align with the target coordinate system, depending on which is requested.

If this parameter is not used, it must be set to M_NULL.

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

Param2Ptr

Specifies the address in which to return information about the transformation required to cause the reference coordinate system to overlap or align with the target coordinate system, depending on which is requested.

If this parameter is not used, it must be set to M_NULL.

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

Param3Ptr

Specifies the address in which to return information about the transformation required to cause the reference coordinate system to overlap or align with the target coordinate system, depending on which is requested.

If this parameter is not used, it must be set to M_NULL.

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

Param4Ptr

Specifies the address in which to return information about the transformation required to cause the reference coordinate system to overlap or align with the target coordinate system, depending on which is requested.

If this parameter is not used, it must be set to M_NULL.

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

Parameter associations

The table below lists possible values for the InquireType and MatrixId parameters and possible values returned to the Param1Ptr, Param2Ptr, Param3Ptr, and Param4Ptr parameters.

function map For inquiring about the transformation parameters
CollapseInquireType Description
MatrixId
Param1Ptr
- Possible values returned
Param2Ptr
- Possible values returned
Param3Ptr
- Possible values returned
Param4Ptr
- Possible values returned
Collapse M_HOMOGENEOUS_MATRIX

Retrieves the transformation which makes the axes of the reference coordinate system parallel to those of the target coordinate system, and makes the origin of the reference coordinate system coincide with that of the target coordinate system. The transformation is returned as a 4x4 homogenous matrix. You can use this result to convert a coordinate in the target coordinate system to the reference coordinate system.

(summarize)
Collapse MatrixId

Returns the matrix representation of the transformation which causes the reference coordinate system to overlap with the target coordinate system.

(summarize)
Collapse M_ROTATION_AXIS_ANGLE

Retrieves the axis and angle of rotation which makes the axes of the reference coordinate system parallel to those of the target coordinate system. The axis of rotation is defined by the origin of reference coordinate system and one other point. The rotation angle is measured in the counter-clockwise direction around the axis of rotation, as per the right-hand rule.

The axis of rotation is always normalized.

When the axes of the coordinate systems are already parallel, Param1Ptr to Param4Ptr will be set to (0, 0, 0, 0).

(summarize)
Collapse Param1Ptr

Returns the X-coordinate of one of the points which defines the axis of rotation.
Collapse Param2Ptr

Returns the Y-coordinate of one of the points which defines the axis of rotation.
Collapse Param3Ptr

Returns the Z-coordinate of one of the points which defines the axis of rotation.
Collapse Param4Ptr

Returns the angle of the rotation around the axis of rotation.

(summarize)
Collapse 0 <= Value < 360

Specifies the rotation angle, in degrees.
Collapse M_ROTATION_MATRIX

Retrieves the rotation matrix that makes the axes of the reference coordinate system parallel to those of the target coordinate system. The transformation is returned as a 3x3 matrix.

(summarize)
Collapse MatrixId

Returns the matrix representation of the rotation which brings the axes of the reference coordinate system parallel to those of the target coordinate system.

(summarize)
Collapse M_ROTATION_QUATERNION

Retrieves the components of the quaternion that defines the rotation which makes the axes of the reference coordinate system parallel to those of the target coordinate system.

The quaternion is always normalized.

When the axes of the coordinate systems are already parallel, Param1Ptr to Param4Ptr will be set to (1, 0, 0, 0).

(summarize)
Collapse Param1Ptr

Returns the scalar component of the quaternion.
Collapse Param2Ptr

Returns the X-component of the quaternion.
Collapse Param3Ptr

Returns the Y-component of the quaternion.
Collapse Param4Ptr

Returns the Z-component of the quaternion.
Collapse M_ROTATION_XYZ

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: the X-axis, Y-axis, and Z-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees.
Collapse Param2Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the positive X-axis.
Collapse 270.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the negative X-axis.
Collapse Param3Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees.
Collapse M_ROTATION_XZY

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: the X-axis, Z-axis, and Y-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees.
Collapse Param2Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the positive Y-axis.
Collapse 270.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the negative Y-axis.
Collapse Param3Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees.
Collapse M_ROTATION_YXZ

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: the Y-axis, X-axis, and Z-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees.
Collapse Param2Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the positive Z-axis.
Collapse 270.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the negative Z-axis.
Collapse Param3Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees.
Collapse M_ROTATION_YZX

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: the Y-axis, Z-axis, and X-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees.
Collapse Param2Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the positive Y-axis.
Collapse 270.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the negative Y-axis.
Collapse Param3Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees.
Collapse M_ROTATION_ZXY

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: the Z-axis, X-axis, and Y-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees.
Collapse Param2Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the positive Z-axis.
Collapse 270.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the negative Z-axis.
Collapse Param3Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees.
Collapse M_ROTATION_ZYX

Retrieves the angles of the three rotations that make the axes of the reference coordinate system parallel to those of the target coordinate system. The rotation is described by three distinct rotations about the axes of the reference coordinate system in the following order: Z-axis, Y-axis, and X-axis rotation.

(summarize)
Collapse Param1Ptr

Returns the Z-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the Z-axis rotation, in degrees.
Collapse Param2Ptr

Returns the Y-axis rotation.

(summarize)
Collapse 0.0 <= Value <= 90.0

Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the positive X-axis.
Collapse 270.0 <= Value < 360.0

Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the negative X-axis.
Collapse Param3Ptr

Returns the X-axis rotation.

(summarize)
Collapse 0.0 <= Value < 360.0

Specifies the X-axis rotation, in degrees.
Collapse M_TRANSLATION

Retrieves the components of the translation vector that makes the origin of the reference coordinate system coincide with the origin of the target coordinate system.

(summarize)
Collapse Param1Ptr

Returns the displacement along the X-axis of the reference coordinate system.
Collapse Param2Ptr

Returns the displacement along the Y-axis of the reference coordinate system.
Collapse Param3Ptr

Returns the displacement along the Z-axis of the reference coordinate system.
Compilation information
Header Include mil.h.
Library Use mil.lib; milcal.lib.
DLL Requires mil.dll; milcal.dll.
NULL ABSOLUTE COORDINATE SYSTEM CAMERA COORDINATE SYSTEM LASER LINE COORDINATE SYSTEM RELATIVE COORDINATE SYSTEM ROBOT BASE COORDINATE SYSTEM TOOL COORDINATE SYSTEM DEFAULT ABSOLUTE COORDINATE SYSTEM CAMERA COORDINATE SYSTEM LASER LINE COORDINATE SYSTEM RELATIVE COORDINATE SYSTEM ROBOT BASE COORDINATE SYSTEM TOOL COORDINATE SYSTEM FLOAT HOMOGENEOUS MATRIX FLOAT ROTATION AXIS ANGLE ROTATION MATRIX FLOAT ROTATION QUATERNION ROTATION XYZ ROTATION XZY ROTATION YXZ ROTATION YZX ROTATION ZXY ROTATION ZYX TRANSLATION