M3dgeoMatrixGetTransform

See also

Reference:

M3dgeoAlloc M3dgeoInquire M3dgeoMatrixSetTransform

Availability

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/GPm

Available on Matrox Supersight

Function map

Examples

simple3dbinpicking.cpp

Function Map

Table:

For specifying the transformation matrix object identifier

Parameter Associations

Table:

For specifying the transformation type

Compilation information

Synopsis

Get the translation, rotation, or scale defined by a given transformation matrix object.

Syntax

void M3dgeoMatrixGetTransform(

MIL_ID Matrix3dgeoId,	//in
MIL_INT64 InquireType,	//in
MIL_DOUBLE *Param1Ptr,	//out
MIL_DOUBLE *Param2Ptr,	//out
MIL_DOUBLE *Param3Ptr,	//out
MIL_DOUBLE *Param4Ptr,	//out
MIL_INT64 ControlFlag	//in

)

Description

This function retrieves the translation, rotation, or scale defined by a given transformation matrix object.

Note that M3dgeoMatrixGetTransform() 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.

All coordinates are expressed in world units in the working coordinate system.

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

Matrix3dgeoId

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

This function only supports matrices that can qualify as matrices of any type other than M_AFFINE or M_PROJECTION. A transformation matrix object is supported if passing it in a call to M3dgeoInquire() with the M_TRANSFORMATION_TYPE inquire type returns any value other than M_AFFINE or M_PROJECTION.

For specifying the transformation matrix object identifier
Value	Description
MIL transformation matrix object identifier	Specifies the identifier of a 3D geometry object.

InquireType

Specifies the type of transformation to retrieve from the given transformation matrix object.

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

Param1Ptr

Specifies the first address in which to return information about the transformation required.

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

Param2Ptr

Specifies the second address in which to return information about the transformation required.

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

Param3Ptr

Specifies the third address in which to return information about the transformation required.

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

Param4Ptr

Specifies the fourth address in which to return information about the transformation required.

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.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

Parameter associations

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

For specifying the transformation type

Any parameters for which a value is not returned must be set to M_NULL.

For specifying the transformation type
InquireType			Description
	Param1Ptr - Possible values returned
	Param2Ptr - Possible values returned
	Param3Ptr - Possible values returned
	Param4Ptr - Possible values returned
M_ROTATION_AXIS_ANGLE			Retrieves the axis and angle of rotation. The axis of rotation is defined by a vector. 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. SET (summarize) Retrieves the axis and angle of rotation. SET (more details...)
	Param1Ptr		Returns the X-component of the vector that defines the axis of rotation.
	Param2Ptr		Returns the Y-component of the vector that defines the axis of rotation.
	Param3Ptr		Returns the Z-component of the vector that defines the axis of rotation.
	Param4Ptr		Returns the angle of the rotation, in degrees, around the axis of rotation. (summarize) Returns the angle of the rotation, in degrees, around the axis of rotation. (more details...)
		0 <= Value < 360	Specifies the rotation angle, in degrees.
M_ROTATION_AXIS_X			Retrieves the normalized vector of the X-axis which results from applying the given transformation matrix to the working coordinate system's X-axis. SET (summarize) Retrieves the normalized vector of the X-axis which results from applying the given transformation matrix to the working coordinate system's X-axis. SET (more details...)
	Param1Ptr		Returns the X-component of the vector.
	Param2Ptr		Returns the Y-component of the vector.
	Param3Ptr		Returns the Z-component of the vector.
M_ROTATION_AXIS_Y			Retrieves the normalized vector of the Y-axis which results from applying the given transformation matrix to the working coordinate system's Y-axis. SET (summarize) Retrieves the normalized vector of the Y-axis which results from applying the given transformation matrix to the working coordinate system's Y-axis. SET (more details...)
	Param1Ptr		Returns the X-component of the vector.
	Param2Ptr		Returns the Y-component of the vector.
	Param3Ptr		Returns the Z-component of the vector.
M_ROTATION_AXIS_Z			Retrieves the normalized vector of the Z-axis which results from applying the given transformation matrix to the working coordinate system's Z-axis. SET (summarize) Retrieves the normalized vector of the Z-axis which results from applying the given transformation matrix to the working coordinate system's Z-axis. SET (more details...)
	Param1Ptr		Returns the X-component of the vector.
	Param2Ptr		Returns the Y-component of the vector.
	Param3Ptr		Returns the Z-component of the vector.
M_ROTATION_QUATERNION			Retrieves the components of the rotation quaternion. The quaternion is always normalized. SET (summarize) Retrieves the components of the rotation quaternion. SET (more details...)
	Param1Ptr		Returns the scalar component of the quaternion.
	Param2Ptr		Returns the X-component of the quaternion.
	Param3Ptr		Returns the Y-component of the quaternion.
	Param4Ptr		Returns the Z-component of the quaternion.
M_ROTATION_XYZ			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the X-axis, the Y-axis, and the Z-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the X-axis, the Y-axis, and the Z-axis rotation. SET (more details...)
	Param1Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees.
	Param2Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the positive X-axis.
		270.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the negative X-axis.
	Param3Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees.
M_ROTATION_XZY			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the X-axis, the Z-axis, and the Y-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the X-axis, the Z-axis, and the Y-axis rotation. SET (more details...)
	Param1Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees.
	Param2Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the positive Y-axis.
		270.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the negative Y-axis.
	Param3Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees.
M_ROTATION_YXZ			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Y-axis, the X-axis, and the Z-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Y-axis, the X-axis, and the Z-axis rotation. SET (more details...)
	Param1Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees.
	Param2Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the positive Z-axis.
		270.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the negative Z-axis.
	Param3Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees.
M_ROTATION_YZX			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Y-axis, the Z-axis, and the X-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Y-axis, the Z-axis, and the X-axis rotation. SET (more details...)
	Param1Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees.
	Param2Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the positive Y-axis.
		270.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees, when located between the positive X-axis and the negative Y-axis.
	Param3Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees.
M_ROTATION_ZXY			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Z-axis, the X-axis, and the Y-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Z-axis, the X-axis, and the Y-axis rotation. SET (more details...)
	Param1Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees.
	Param2Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the positive Z-axis.
		270.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees, when located between the positive Y-axis and the negative Z-axis.
	Param3Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees.
M_ROTATION_ZYX			Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Z-axis, the Y-axis, and the X-axis rotation. SET (summarize) Retrieves the three distinct rotations about the axes of the working coordinate system in the following order: the Z-axis, the Y-axis, and the X-axis rotation. SET (more details...)
	Param1Ptr		Returns the Z-axis rotation. (summarize) Returns the Z-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the Z-axis rotation, in degrees.
	Param2Ptr		Returns the Y-axis rotation. (summarize) Returns the Y-axis rotation. (more details...)
		0.0 <= Value <= 90.0	Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the positive X-axis.
		270.0 <= Value < 360.0	Specifies the Y-axis rotation, in degrees, when located between the positive Z-axis and the negative X-axis.
	Param3Ptr		Returns the X-axis rotation. (summarize) Returns the X-axis rotation. (more details...)
		0.0 <= Value < 360.0	Specifies the X-axis rotation, in degrees.
M_SCALE			Retrieves the scale factor along each axis. SET (summarize) Retrieves the scale factor along each axis. SET (more details...)
	Param1Ptr		Returns the scaling factor in X.
	Param2Ptr		Returns the scaling factor in Y.
	Param3Ptr		Returns the scaling factor in Z.
M_TRANSLATION			Retrieves the translation along each of the axes of the working coordinate system. SET (summarize) Retrieves the translation along each of the axes of the working coordinate system. SET (more details...)
	Param1Ptr		Returns the displacement along the X-axis of the working coordinate system.
	Param2Ptr		Returns the displacement along the Y-axis of the working coordinate system.
	Param3Ptr		Returns the displacement along the Z-axis of the working coordinate system.

Compilation information

Header	Include mil.h.
Library	Use mil.lib; mil3d.lib.
DLL	Requires mil.dll; mil3d.dll.