Operators

# create_pose (Operator)

## Name

create_pose — Create a 3D pose.

## Signature

create_pose( : : TransX, TransY, TransZ, RotX, RotY, RotZ, OrderOfTransform, OrderOfRotation, ViewOfTransform : Pose)

## Description

create_pose creates the 3D pose Pose. A pose describes a rigid 3D transformation, i.e., a transformation consisting of an arbitrary translation and rotation, with 6 parameters: TransX, TransY, and TransZ specify the translation along the x-, y-, and z-axis, respectively, while RotX, RotY, and RotZ 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 OrderOfRotation: If you pass the value 'gba', the rotation is described by the following chain of rotations around the three axes (see hom_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_rotate (HomMat3DIdent, RotZ, 'z', 0, 0, 0, HomMat3DRotZ)
hom_mat3d_rotate (HomMat3DRotZ, RotY, 'y', 0, 0, 0, HomMat3DRotYZ)
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_rotate_local (HomMat3DIdent, RotX, 'x', HomMat3DRotX)
hom_mat3d_rotate_local (HomMat3DRotX, RotY, 'y', HomMat3DRotXY)
hom_mat3d_rotate_local (HomMat3DRotXY, RotZ, 'z', HomMat3DXYZ)
```

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

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

If you pass 'rodriguez' in OrderOfRotation, the rotation parameters RotX, RotY, and RotZ 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, 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_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_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 into coordinate system 2 with a pose, or more exactly, with the corresponding homogeneous transformation matrix (input and output points as homogeneous vectors, see also affine_trans_point_3d). Note that to transform points from coordinate system 1 into system 2, you use the transformation matrix that describes the pose of coordinate system 1 relative to system 2.

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' for the parameter OrderOfTransform and 'point' for ViewOfTransform. 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)' for OrderOfTransform, 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' for ViewOfTransform, 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 Pose which is a tuple of length seven. The first three elements hold the translation parameters TransX, TransY, and TransZ, followed by the rotation parameters RotX, RotY, and RotZ. The last element codes the representation type of the pose that you selected with the parameters OrderOfTransform, OrderOfRotation, and ViewOfTransform. The following table lists the possible combinations. As already noted, we recommend to use only the representation types with OrderOfTransform = 'Rp+T' and ViewOfTransform = 'point' (codes 0, 2, and 4).

OrderOfTransform OrderOfRotation ViewOfTransform Code
'Rp+T' 'gba' 'point' 0
'Rp+T' 'abg' 'point' 2
'Rp+T' 'rodriguez' 'point' 4
'Rp+T' 'gba' 'coordinate_system' 1
'Rp+T' 'abg' 'coordinate_system' 3
'Rp+T' 'rodriguez' 'coordinate_system' 5
'R(p-T)' 'gba' 'point' 8
'R(p-T)' 'abg' 'point' 10
'R(p-T)' 'rodriguez' 'point' 12
'R(p-T)' 'gba' 'coordinate_system' 9
'R(p-T)' 'abg' 'coordinate_system' 11
'R(p-T)' 'rodriguez' 'coordinate_system' 13

You can convert poses into other representation types using convert_pose_type and query the type using get_pose_type.

## Parallelization

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

## Parameters

TransX (input_control)  real (real)

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

Default value: 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

TransY (input_control)  real (real)

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

Default value: 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

TransZ (input_control)  real (real)

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

Default value: 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

RotX (input_control)  real (real)

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

Default value: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Typical range of values: 0 ≤ RotX ≤ 360

RotY (input_control)  real (real)

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

Default value: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Typical range of values: 0 ≤ RotY ≤ 360

RotZ (input_control)  real (real)

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

Default value: 90.0

Suggested values: 0.0, 90.0, 180.0, 270.0

Typical range of values: 0 ≤ RotZ ≤ 360

OrderOfTransform (input_control)  string (string)

Order of rotation and translation.

Default value: 'Rp+T'

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

OrderOfRotation (input_control)  string (string)

Meaning of the rotation values.

Default value: 'gba'

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

ViewOfTransform (input_control)  string (string)

View of transformation.

Default value: 'point'

Suggested values: 'point', 'coordinate_system'

Pose (output_control)  pose (real / integer)

3D pose.

Number of elements: 7

## Example (HDevelop)

```*  Goal: Calibration with non-standard calibration object
*  Read start values for internal camera parameters
*  (Read 3D world points [WorldPointsX,WorldPointsY,WorldPointsZ],
*   extract corresponding 2D image points [PixelsRow,PixelsColumn])
*  Task: Create starting value for the external camera parameters, i.e., the
*        pose of the calibration object in the calibration images
*  First image: Calibration object placed at a distance of 0.5 and 0.1
*               'below' the camera coordinate system
*               orientation 'read from left to right': rotated 30 degrees
*               around the optical axis of the camera (z-axis),
*               then tilted 10 degrees around the new y-axis
create_pose(0.1, 0.0, 0.5, 30, 10, 0, 'Rp+T', 'abg', 'point', StartPose1)
*  (Accumulate all poses in StartPoses = [StartPose1, StartPose2, ...])
*  perform the calibration
camera_calibration(WorldPointsX, WorldPointsY, WorldPointsZ, \
PixelsRow, PixelsColumn, CameraParam, StartPoses, \
'pose', FinalCamParam, FinalPoses, Errors)
```

## Result

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