Operator Reference

HALCON Operator Reference / Transformations / Poses
ClassesClasses | | Operators

create_poseT_create_poseCreatePoseCreatePosecreate_pose (Operator)

create_poseT_create_poseCreatePoseCreatePosecreate_pose — Create a 3D pose.

Signature

Herror T_create_pose(const Htuple TransX, const Htuple TransY, const Htuple TransZ, const Htuple RotX, const Htuple RotY, const Htuple RotZ, const Htuple OrderOfTransform, const Htuple OrderOfRotation, const Htuple ViewOfTransform, Htuple* Pose)

void CreatePose(const HTuple& TransX, const HTuple& TransY, const HTuple& TransZ, const HTuple& RotX, const HTuple& RotY, const HTuple& RotZ, const HTuple& OrderOfTransform, const HTuple& OrderOfRotation, const HTuple& ViewOfTransform, HTuple* Pose)

void HPose::HPose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const HString& OrderOfTransform, const HString& OrderOfRotation, const HString& ViewOfTransform)

void HPose::HPose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const char* OrderOfTransform, const char* OrderOfRotation, const char* ViewOfTransform)

void HPose::HPose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const wchar_t* OrderOfTransform, const wchar_t* OrderOfRotation, const wchar_t* ViewOfTransform)   ( Windows only)

void HPose::CreatePose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const HString& OrderOfTransform, const HString& OrderOfRotation, const HString& ViewOfTransform)

void HPose::CreatePose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const char* OrderOfTransform, const char* OrderOfRotation, const char* ViewOfTransform)

void HPose::CreatePose(double TransX, double TransY, double TransZ, double RotX, double RotY, double RotZ, const wchar_t* OrderOfTransform, const wchar_t* OrderOfRotation, const wchar_t* ViewOfTransform)   ( Windows only)

static void HOperatorSet.CreatePose(HTuple transX, HTuple transY, HTuple transZ, HTuple rotX, HTuple rotY, HTuple rotZ, HTuple orderOfTransform, HTuple orderOfRotation, HTuple viewOfTransform, out HTuple pose)

public HPose(double transX, double transY, double transZ, double rotX, double rotY, double rotZ, string orderOfTransform, string orderOfRotation, string viewOfTransform)

void HPose.CreatePose(double transX, double transY, double transZ, double rotX, double rotY, double rotZ, string orderOfTransform, string orderOfRotation, string viewOfTransform)

def create_pose(trans_x: float, trans_y: float, trans_z: float, rot_x: float, rot_y: float, rot_z: float, order_of_transform: str, order_of_rotation: str, view_of_transform: str) -> Sequence[Union[int, float]]

Description

create_posecreate_poseCreatePoseCreatePosecreate_pose creates the 3D pose PosePosePoseposepose. A pose describes a rigid 3D transformation, i.e., a transformation consisting of an arbitrary translation and rotation, with 6 parameters: TransXTransXTransXtransXtrans_x, TransYTransYTransYtransYtrans_y, and TransZTransZTransZtransZtrans_z specify the translation along the x-, y-, and z-axis, respectively, while RotXRotXRotXrotXrot_x, RotYRotYRotYrotYrot_y, and RotZRotZRotZrotZrot_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 OrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation: If you pass the value 'gba'"gba""gba""gba""gba", the rotation is described by the following chain of rotations around the three axes (see hom_mat3d_rotatehom_mat3d_rotateHomMat3dRotateHomMat3dRotatehom_mat3d_rotate for the content for the rotation matrices ):

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, 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, 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 from right to left corresponds to the following sequence of operator calls:

hom_mat3d_identity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)
hom_mat3d_rotate(HomMat3DIdent, RotZ, 'z', 0, 0, 0, HomMat3DRotZ)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(HomMat3DRotZ, RotY, 'y', 0, 0, 0, HomMat3DRotYZ)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(HomMat3DRotYZ, RotX, 'x', 0, 0, 0, HomMat3DXYZ)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)

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

hom_mat3d_identity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)HomMat3dIdentity(HomMat3DIdent)hom_mat3d_identity(HomMat3DIdent)
hom_mat3d_rotate_local(HomMat3DIdent, RotX, 'x', HomMat3DRotX)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(HomMat3DRotX, RotY, 'y', HomMat3DRotXY)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(HomMat3DRotXY, RotZ, 'z', HomMat3DXYZ)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)

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

is referred to as the Roll-Pitch-Yaw convention in the literature.

If you pass 'rodriguez'"rodriguez""rodriguez""rodriguez""rodriguez" in OrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation, the rotation parameters RotXRotXRotXrotXrot_x, RotYRotYRotYrotYrot_y, and RotZRotZRotZrotZrot_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:

Please note that these 3D poses can be ambiguous, meaning a homogeneous transformation matrix can have several pose representations. For example, for with 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, 30, 90, 54, "Rp+T", "gba", "point", Pose1)CreatePose(0, 0, 0, 30, 90, 54, "Rp+T", "gba", "point", Pose1)CreatePose(0, 0, 0, 30, 90, 54, "Rp+T", "gba", "point", Pose1)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)create_pose(0, 0, 0, 17, 90, 67, "Rp+T", "gba", "point", Pose2)CreatePose(0, 0, 0, 17, 90, 67, "Rp+T", "gba", "point", Pose2)CreatePose(0, 0, 0, 17, 90, 67, "Rp+T", "gba", "point", Pose2)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_quataxis_angle_to_quatAxisAngleToQuatAxisAngleToQuataxis_angle_to_quat) to represent rotations.

Corresponding homogeneous transformation matrix

You can obtain the homogeneous transformation matrix corresponding to a pose with the operator pose_to_hom_mat3dpose_to_hom_mat3dPoseToHomMat3dPoseToHomMat3dpose_to_hom_mat3d. 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)):

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 (input and output points as homogeneous vectors, see also affine_trans_point_3daffine_trans_point_3dAffineTransPoint3dAffineTransPoint3daffine_trans_point_3d). Note that to transform points from cs1 into cs2, you use the transformation matrix that describes the pose of cs1 relative to cs2.

This corresponds to the following operator calls:

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""Rp+T""Rp+T""Rp+T" for the parameter OrderOfTransformOrderOfTransformOrderOfTransformorderOfTransformorder_of_transform and 'point'"point""point""point""point" for ViewOfTransformViewOfTransformViewOfTransformviewOfTransformview_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)""R(p-T)""R(p-T)""R(p-T)" for OrderOfTransformOrderOfTransformOrderOfTransformorderOfTransformorder_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:

If you select 'coordinate_system'"coordinate_system""coordinate_system""coordinate_system""coordinate_system" for ViewOfTransformViewOfTransformViewOfTransformviewOfTransformview_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!

Returned data structure

The created 3D pose is returned in PosePosePoseposepose which is a tuple of length seven. The first three elements hold the translation parameters TransXTransXTransXtransXtrans_x, TransYTransYTransYtransYtrans_y, and TransZTransZTransZtransZtrans_z, followed by the rotation parameters RotXRotXRotXrotXrot_x, RotYRotYRotYrotYrot_y, and RotZRotZRotZrotZrot_z. The last element codes the representation type of the pose that you selected with the parameters OrderOfTransformOrderOfTransformOrderOfTransformorderOfTransformorder_of_transform, OrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation, and ViewOfTransformViewOfTransformViewOfTransformviewOfTransformview_of_transform. The following table lists the possible combinations. As already noted, we recommend to use only the representation types with OrderOfTransformOrderOfTransformOrderOfTransformorderOfTransformorder_of_transform = 'Rp+T'"Rp+T""Rp+T""Rp+T""Rp+T" and ViewOfTransformViewOfTransformViewOfTransformviewOfTransformview_of_transform = 'point'"point""point""point""point" (codes 0, 2, and 4).

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

You can convert poses into other representation types using convert_pose_typeconvert_pose_typeConvertPoseTypeConvertPoseTypeconvert_pose_type and query the type using get_pose_typeget_pose_typeGetPoseTypeGetPoseTypeget_pose_type.

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

TransXTransXTransXtransXtrans_x (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 0.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

TransYTransYTransYtransYtrans_y (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 0.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

TransZTransZTransZtransZtrans_z (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 0.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

RotXRotXRotXrotXrot_x (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Value range: 0 ≤ RotX RotX RotX rotX rot_x ≤ 360

RotYRotYRotYrotYrot_y (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Value range: 0 ≤ RotY RotY RotY rotY rot_y ≤ 360

RotZRotZRotZrotZrot_z (input_control)  real → HTuplefloatHTupleHtuple (real) (double) (double) (double)

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

Default: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Value range: 0 ≤ RotZ RotZ RotZ rotZ rot_z ≤ 360

OrderOfTransformOrderOfTransformOrderOfTransformorderOfTransformorder_of_transform (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Order of rotation and translation.

Default: 'Rp+T' "Rp+T" "Rp+T" "Rp+T" "Rp+T"

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

OrderOfRotationOrderOfRotationOrderOfRotationorderOfRotationorder_of_rotation (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

Meaning of the rotation values.

Default: 'gba' "gba" "gba" "gba" "gba"

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

ViewOfTransformViewOfTransformViewOfTransformviewOfTransformview_of_transform (input_control)  string → HTuplestrHTupleHtuple (string) (string) (HString) (char*)

View of transformation.

Default: 'point' "point" "point" "point" "point"

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

PosePosePoseposepose (output_control)  pose → HPose, HTupleSequence[Union[int, float]]HTupleHtuple (real / integer) (double / int / long) (double / Hlong) (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)

Example (HDevelop)

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

Example (C++)

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

Example (HDevelop)

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

Result

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

Possible Successors

pose_to_hom_mat3dpose_to_hom_mat3dPoseToHomMat3dPoseToHomMat3dpose_to_hom_mat3d, write_posewrite_poseWritePoseWritePosewrite_pose, camera_calibrationcamera_calibrationCameraCalibrationCameraCalibrationcamera_calibration, hand_eye_calibrationhand_eye_calibrationHandEyeCalibrationHandEyeCalibrationhand_eye_calibration

Alternatives

read_poseread_poseReadPoseReadPoseread_pose, hom_mat3d_to_posehom_mat3d_to_poseHomMat3dToPoseHomMat3dToPosehom_mat3d_to_pose

See also

hom_mat3d_rotatehom_mat3d_rotateHomMat3dRotateHomMat3dRotatehom_mat3d_rotate, hom_mat3d_translatehom_mat3d_translateHomMat3dTranslateHomMat3dTranslatehom_mat3d_translate, convert_pose_typeconvert_pose_typeConvertPoseTypeConvertPoseTypeconvert_pose_type, get_pose_typeget_pose_typeGetPoseTypeGetPoseTypeget_pose_type, hom_mat3d_to_posehom_mat3d_to_poseHomMat3dToPoseHomMat3dToPosehom_mat3d_to_pose, pose_to_hom_mat3dpose_to_hom_mat3dPoseToHomMat3dPoseToHomMat3dpose_to_hom_mat3d, write_posewrite_poseWritePoseWritePosewrite_pose, read_poseread_poseReadPoseReadPoseread_pose

Module

Foundation

ClassesClasses | | Operators