create_poseCreatePoseCreatePosecreate_poseT_create_pose🔗

Short description🔗

create_poseCreatePoseCreatePosecreate_poseT_create_pose — Create a 3D pose.

Signature🔗

create_pose( real TransX, real TransY, real TransZ, real RotX, real RotY, real RotZ, string OrderOfTransform, string OrderOfRotation, string ViewOfTransform, out pose Pose )

Description🔗

create_poseCreatePose creates the 3D pose Poseposepose. A pose describes a rigid 3D transformation, i.e., a transformation consisting of an arbitrary translation and rotation, with 6 parameters: TransXtransXtrans_x, TransYtransYtrans_y, and TransZtransZtrans_z specify the translation along the x-, y-, and z-axis, respectively, while RotXrotXrot_x, RotYrotYrot_y, and RotZrotZrot_z describe the rotation.

3D poses are typically used in two ways: First, to describe the position and orientation of one coordinate system relative to another (e.g., the pose of a part’s coordinate system relative to the camera coordinate system - in short: the pose of the part relative to the camera) and secondly, to describe how coordinates can be transformed between two coordinate systems (e.g., to transform points from part coordinates into camera coordinates).

Representation of orientation (rotation)🔗

A 3D rotation around an arbitrary axis can be represented by 3 parameters in multiple ways. HALCON lets you choose between three of them with the parameter OrderOfRotationorderOfRotationorder_of_rotation: If you pass the value 'gba'"gba", the rotation is described by the following chain of rotations around the three axes (see hom_mat3d_rotateHomMat3dRotate for the content for the rotation matrices \(\mvAxisRotationMatrixVar{x}{}, \mvAxisRotationMatrixVar{y}{}, and \mvAxisRotationMatrixVar{z}{}\)):

\[\begin{eqnarray*} \mvAxisRotationMatrixVar{gba}{} = \mvAxisRotationMatrixVar{x}{\textrm{RotX}} \cdot \mvAxisRotationMatrixVar{y}{\textrm{RotY}} \cdot \mvAxisRotationMatrixVar{z}{\textrm{RotZ}} \end{eqnarray*}\]

\(\mvAxisRotationMatrixVar{gba}{}\) is referred to as the Yaw-Pitch-Roll convention in the literature. Please note that you can “read” this chain in two ways: If you start from the right, the rotations are always performed relative to the global (i.e., fixed or “old”) coordinate system. Thus, \(\mvAxisRotationMatrixVar{gba}{}\) can be read as follows: First rotate around the z-axis, then around the “old” y-axis, and finally around the “old” x-axis. In contrast, if you read from the left to the right, the rotations are performed relative to the local (i.e., “new”) coordinate system. Then, \(\mvAxisRotationMatrixVar{gba}{}\) corresponds to the following: First rotate around the x-axis, the around the “new” y-axis, and finally around the “new(est)” z-axis.

Reading \(\mvAxisRotationMatrixVar{gba}{}\) from right to left corresponds to the following sequence of operator calls:


`hom_mat3d_identity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)`
`hom_mat3d_rotate(HomMat3DIdent, RotZ, 'z', 0, 0, 0, HomMat3DRotZ)HomMat3dRotate(HomMat3DIdent, RotZ, "z", 0, 0, 0, HomMat3DRotZ)HomMat3dRotate(HomMat3DIdent, RotZ, "z", 0, 0, 0, HomMat3DRotZ)hom_mat3d_rotate(HomMat3DIdent, RotZ, "z", 0, 0, 0, HomMat3DRotZ)hom_mat3d_rotate(HomMat3DIdent, RotZ, "z", 0, 0, 0, HomMat3DRotZ)`
`hom_mat3d_rotate(HomMat3DRotZ, RotY, 'y', 0, 0, 0, HomMat3DRotYZ)HomMat3dRotate(HomMat3DRotZ, RotY, "y", 0, 0, 0, HomMat3DRotYZ)HomMat3dRotate(HomMat3DRotZ, RotY, "y", 0, 0, 0, HomMat3DRotYZ)hom_mat3d_rotate(HomMat3DRotZ, RotY, "y", 0, 0, 0, HomMat3DRotYZ)hom_mat3d_rotate(HomMat3DRotZ, RotY, "y", 0, 0, 0, HomMat3DRotYZ)`
`hom_mat3d_rotate(HomMat3DRotYZ, RotX, 'x', 0, 0, 0, HomMat3DXYZ)HomMat3dRotate(HomMat3DRotYZ, RotX, "x", 0, 0, 0, HomMat3DXYZ)HomMat3dRotate(HomMat3DRotYZ, RotX, "x", 0, 0, 0, HomMat3DXYZ)hom_mat3d_rotate(HomMat3DRotYZ, RotX, "x", 0, 0, 0, HomMat3DXYZ)hom_mat3d_rotate(HomMat3DRotYZ, RotX, "x", 0, 0, 0, HomMat3DXYZ)`

In contrast, reading from left to right corresponds to the following operator sequence:


`hom_mat3d_identity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)`
`hom_mat3d_rotate_local(HomMat3DIdent, RotX, 'x', HomMat3DRotX)HomMat3dRotateLocal(HomMat3DIdent, RotX, "x", HomMat3DRotX)HomMat3dRotateLocal(HomMat3DIdent, RotX, "x", HomMat3DRotX)hom_mat3d_rotate_local(HomMat3DIdent, RotX, "x", HomMat3DRotX)hom_mat3d_rotate_local(HomMat3DIdent, RotX, "x", HomMat3DRotX)`
`hom_mat3d_rotate_local(HomMat3DRotX, RotY, 'y', HomMat3DRotXY)HomMat3dRotateLocal(HomMat3DRotX, RotY, "y", HomMat3DRotXY)HomMat3dRotateLocal(HomMat3DRotX, RotY, "y", HomMat3DRotXY)hom_mat3d_rotate_local(HomMat3DRotX, RotY, "y", HomMat3DRotXY)hom_mat3d_rotate_local(HomMat3DRotX, RotY, "y", HomMat3DRotXY)`
`hom_mat3d_rotate_local(HomMat3DRotXY, RotZ, 'z', HomMat3DXYZ)HomMat3dRotateLocal(HomMat3DRotXY, RotZ, "z", HomMat3DXYZ)HomMat3dRotateLocal(HomMat3DRotXY, RotZ, "z", HomMat3DXYZ)hom_mat3d_rotate_local(HomMat3DRotXY, RotZ, "z", HomMat3DXYZ)hom_mat3d_rotate_local(HomMat3DRotXY, RotZ, "z", HomMat3DXYZ)`

When passing 'abg'"abg" in OrderOfRotationorderOfRotationorder_of_rotation, the rotation corresponds to the following chain:

\[\begin{eqnarray*} \mvAxisRotationMatrixVar{abg}{} = \mvAxisRotationMatrixVar{z}{\textrm{RotZ}} \cdot \mvAxisRotationMatrixVar{y}{\textrm{RotY}} \cdot \mvAxisRotationMatrixVar{x}{\textrm{RotX}} \end{eqnarray*}\]

\(\mvAxisRotationMatrixVar{abg}{}\) is referred to as the Roll-Pitch-Yaw convention in the literature.

If you pass 'rodriguez'"rodriguez" in OrderOfRotationorderOfRotationorder_of_rotation, the rotation parameters RotXrotXrot_x, RotYrotYrot_y, and RotZrotZrot_z are interpreted as the x-, y-, and z-component of the so-called Rodriguez rotation vector. The direction of the vector defines the (arbitrary) axis of rotation. The length of the vector usually defines the rotation angle with positive orientation. Here, a variation of the Rodriguez vector is used, where the length of the vector defines the tangent of half the rotation angle:

\[\begin{eqnarray*} \mvAxisRotationMatrixVar{rodriguez}{} \quad = \quad rotate\,\, around\quad \mvVectorThreeD{\textrm{RotX}}{\textrm{RotY}}{\textrm{RotZ}} \quad by \quad 2 \cdot \arctan(\sqrt{\textrm{RotX}^2 + \textrm{RotY}^2 + \textrm{RotZ}^2}) \end{eqnarray*}\]

Please note that these 3D poses can be ambiguous, meaning a homogeneous transformation matrix can have several pose representations. For example, for \(\mvAxisRotationMatrixVar{gba}{}\) with \(b=\pm90\) the following poses correspond to the same homogeneous transformation matrix:


`create_pose(0, 0, 0, 30, 90, 54, 'Rp+T', 'gba', 'point', Pose1)`
`create_pose(0, 0, 0, 17, 90, 67, 'Rp+T', 'gba', 'point', Pose2)`

If this leads to problems, you can instead use homogeneous transformation matrices or quaternions (axis_angle_to_quatAxisAngleToQuat) to represent rotations.

Corresponding homogeneous transformation matrix🔗

You can obtain the homogeneous transformation matrix corresponding to a pose with the operator pose_to_hom_mat3dPoseToHomMat3d. In the standard definition, this is the following homogeneous transformation matrix which can be split into two separate matrices, one for the translation (H(T)) and one for the rotation (H(R)):

\[\begin{eqnarray*} \mvHomMatrixVar{}{pose} & = & \mvHomMatrixThreeDRotTrans{\mvRotationMatrixVar{}{}} {\mvTranslationVectorVar{}{}} = \mvHomMatrixThreeDRotTrans{ \mvRotationMatrixVar{}{}(\textrm{RotX}, \textrm{RotY}, \textrm{RotZ})} {\mvVectorThreeDPlain{\textrm{TransX}}{\textrm{TransY}}{\textrm{TransZ}} } = \\*[0.3cm] & = & \mvHomMatrixThreeDElements{ 1 & 0 & 0 & \textrm{TransX} \\ 0 & 1 & 0 & \textrm{TransY} \\ 0 & 0 & 1 & \textrm{TransZ}} \cdot \mvHomMatrixThreeDRotTrans{ \mvRotationMatrixVar{}{}(\textrm{RotX}, \textrm{RotY}, \textrm{RotZ})} {\mvVectorThreeDPlain{0}{0}{0}} = \mvHomTranslationMatrixVar{}{} \cdot \mvHomRotationMatrixVar{}{} \end{eqnarray*}\]

Transformation of coordinates🔗

The following equation describes how a point can be transformed from coordinate system 1 (cs1) into coordinate system 2 (cs2) with a pose, or more exactly, with the corresponding homogeneous transformation matrix \(\mvHomMatrixVar{cs2}{cs1}\) (input and output points as homogeneous vectors, see also affine_trans_point_3dAffineTransPoint3d). Note that to transform points from cs1 into cs2, you use the transformation matrix that describes the pose of cs1 relative to cs2.

\[\begin{eqnarray*} \mvVectorTwoD{\mvVectorVar[cs2]{p}}{1} = \mvHomMatrixVar{cs2}{cs1} \cdot \mvVectorTwoD{\mvVectorVar[cs1]{p}}{1} = \mvVectorTwoD{ \mvRotationMatrixVar{}{}(\textrm{RotX}, \textrm{RotY}, \textrm{RotZ}) \cdot \mvVectorVar[cs1]{p} + \mvVectorThreeD{\textrm{TransX}}{\textrm{TransY}}{\textrm{TransZ}} }{1} \end{eqnarray*}\]

This corresponds to the following operator calls:


`pose_to_hom_mat3d(PoseOf1In2, HomMat3DFrom1In2)`
`affine_trans_point_3d(HomMat3DFrom1In2, P1X, P1Y, P1Z, P2X, P2Y, P2Z)`

Non-standard pose definitions🔗

So far, we described the standard pose definition. To create such poses, you select the (default) values 'Rp+T'"Rp+T" for the parameter OrderOfTransformorderOfTransformorder_of_transform and 'point'"point" for ViewOfTransformviewOfTransformview_of_transform. By specifying other values for these parameters, you can create non-standard poses types which we describe briefly below. Please note that these representation types are only supported for backwards compatibility; we strongly recommend to use the standard types.

If you select 'R(p-T)'"R(p-T)" for OrderOfTransformorderOfTransformorder_of_transform, the created pose corresponds to the following chain of transformations, i.e., the sequence of rotation and translation is reversed and the translation is negated:

\[\begin{eqnarray*} \mvHomMatrixVar{}{R(p-T)} & = & \mvHomMatrixThreeDRotTrans{ \mvRotationMatrixVar{}{}(\textrm{RotX}, \textrm{RotY}, \textrm{RotZ})} {\mvVectorThreeDPlain{0}{0}{0}} \cdot \mvHomMatrixThreeDElements{ 1 & 0 & 0 & - \textrm{TransX} \\ 0 & 1 & 0 & - \textrm{TransY} \\ 0 & 0 & 1 & - \textrm{TransZ}} = \mvHomRotationMatrixVar{}{} \cdot \mvHomMatrixVar{}{}(- \mvVectorVar{T}) \end{eqnarray*}\]

If you select 'coordinate_system'"coordinate_system" for ViewOfTransformviewOfTransformview_of_transform, the sequence of transformations remains constant, but the rotation angles are negated. Please note that, contrary to its name, this is not equivalent to transforming a coordinate system!

\[\begin{eqnarray*} \mvHomMatrixVar{}{coordinate\_system} & = & \mvHomMatrixThreeDElements{ 1 & 0 & 0 & \textrm{TransX} \\ 0 & 1 & 0 & \textrm{TransY} \\ 0 & 0 & 1 & \textrm{TransZ}} \cdot \mvHomMatrixThreeDRotTrans{ \mvRotationMatrixVar{}{}(-\textrm{RotX}, -\textrm{RotY}, -\textrm{RotZ})} {\mvVectorThreeDPlain{0}{0}{0}} \end{eqnarray*}\]

Returned data structure🔗

The created 3D pose is returned in Poseposepose which is a tuple of length seven. The first three elements hold the translation parameters TransXtransXtrans_x, TransYtransYtrans_y, and TransZtransZtrans_z, followed by the rotation parameters RotXrotXrot_x, RotYrotYrot_y, and RotZrotZrot_z. The last element codes the representation type of the pose that you selected with the parameters OrderOfTransformorderOfTransformorder_of_transform, OrderOfRotationorderOfRotationorder_of_rotation, and ViewOfTransformviewOfTransformview_of_transform. The following table lists the possible combinations. As already noted, we recommend to use only the representation types with OrderOfTransformorderOfTransformorder_of_transform = 'Rp+T'"Rp+T" and ViewOfTransformviewOfTransformview_of_transform = 'point'"point" (codes 0, 2, and 4).

`OrderOfTransformorderOfTransformorder_of_transform`	`OrderOfRotationorderOfRotationorder_of_rotation`	`ViewOfTransformviewOfTransformview_of_transform`	Code
'Rp+T'"Rp+T"	'gba'"gba"	'point'"point"	0
'Rp+T'"Rp+T"	'abg'"abg"	'point'"point"	2
'Rp+T'"Rp+T"	'rodriguez'"rodriguez"	'point'"point"	4
'Rp+T'"Rp+T"	'gba'"gba"	'coordinate_system'"coordinate_system"	1
'Rp+T'"Rp+T"	'abg'"abg"	'coordinate_system'"coordinate_system"	3
'Rp+T'"Rp+T"	'rodriguez'"rodriguez"	'coordinate_system'"coordinate_system"	5
'R(p-T)'"R(p-T)"	'gba'"gba"	'point'"point"	8
'R(p-T)'"R(p-T)"	'abg'"abg"	'point'"point"	10
'R(p-T)'"R(p-T)"	'rodriguez'"rodriguez"	'point'"point"	12
'R(p-T)'"R(p-T)"	'gba'"gba"	'coordinate_system'"coordinate_system"	9
'R(p-T)'"R(p-T)"	'abg'"abg"	'coordinate_system'"coordinate_system"	11
'R(p-T)'"R(p-T)"	'rodriguez'"rodriguez"	'coordinate_system'"coordinate_system"	13

You can convert poses into other representation types using convert_pose_typeConvertPoseType and query the type using get_pose_typeGetPoseType.

Execution information🔗

Execution information

Multithreading type: reentrant (runs in parallel with non-exclusive operators).
Multithreading scope: global (may be called from any thread).
Processed without parallelization.

Parameters🔗

TransXtransXtrans_x (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Translation along the x-axis (in [m]).

Default: 0.10.1
Suggested values: -1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0.0, 0.01, 0.125, 0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0

TransYtransYtrans_y (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Translation along the y-axis (in [m]).

Default: 0.10.1
Suggested values: -1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0.0, 0.01, 0.125, 0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0

TransZtransZtrans_z (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Translation along the z-axis (in [m]).

Default: 0.10.1
Suggested values: -1.0, -0.75, -0.5, -0.25, -0.2, -0.1, -0.5, -0.25, -0.125, -0.01, 0.0, 0.01, 0.125, 0.25, 0.5, 0.1, 0.2, 0.25, 0.5, 0.75, 1.0

RotXrotXrot_x (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Rotation around x-axis or x component of the Rodriguez vector (in [°] or without unit).

Default: 90.090.0
Suggested values: 0.0, 90.0, 180.0, 270.00.0, 90.0, 180.0, 270.0
Value range: 0 ≤ RotX ≤ 360

RotYrotYrot_y (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Rotation around y-axis or y component of the Rodriguez vector (in [°] or without unit).

Default: 90.090.0
Suggested values: 0.0, 90.0, 180.0, 270.00.0, 90.0, 180.0, 270.0
Value range: 0 ≤ RotY ≤ 360

RotZrotZrot_z (input_control) real → (real)HTuple (double)HTuple (double)floatHtuple (double)

Rotation around z-axis or z component of the Rodriguez vector (in [°] or without unit).

Default: 90.090.0
Suggested values: 0.0, 90.0, 180.0, 270.00.0, 90.0, 180.0, 270.0
Value range: 0 ≤ RotZ ≤ 360

OrderOfTransformorderOfTransformorder_of_transform (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Order of rotation and translation.

Default: 'Rp+T'"Rp+T"
Suggested values: 'Rp+T', 'R(p-T)'"Rp+T", "R(p-T)"

OrderOfRotationorderOfRotationorder_of_rotation (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

Meaning of the rotation values.

Default: 'gba'"gba"
Suggested values: 'gba', 'abg', 'rodriguez'"gba", "abg", "rodriguez"

ViewOfTransformviewOfTransformview_of_transform (input_control) string → (string)HTuple (HString)HTuple (string)strHtuple (char*)

View of transformation.

Default: 'point'"point"
Suggested values: 'point', 'coordinate_system'"point", "coordinate_system"

Poseposepose (output_control) pose → (real / integer)HTuple (double / Hlong)HPose, HTuple (double / int / long)Sequence[Union[int, float]]Htuple (double / Hlong)

3D pose.

Number of elements: 7

Example🔗

(HDevelop)

* Create a pose.
create_pose (0.1, 0.2, 0.3, 40, 50, 60, 'Rp+T', 'gba', 'point', Pose)

(C++)

HTuple Pose, Pose2\;
// Create a pose.
create_pose (0.1, 0.2, 0.3, 40, 50, 60, "Rp+T", "gba", "point", &Pose)\;

Result🔗

create_poseCreatePose returns 2 (H_MSG_TRUE) if all parameter values are correct. If necessary, an exception is raised.

Combinations with other operators🔗

Combinations

Possible successors

pose_to_hom_mat3dPoseToHomMat3d, write_poseWritePose, camera_calibrationCameraCalibration, hand_eye_calibrationHandEyeCalibration

Alternatives

read_poseReadPose, hom_mat3d_to_poseHomMat3dToPose

Module🔗

Foundation