Transformation

The API often needs to handle 3D poses or transformations between two coordinate systems. These transformations have six degrees of freedom and are always represented by a translation Vector in combination with a rotation in Axis-Angle representation. The corresponding node structure is described below. Please note that we provide dedicated commands to modify transformations:

• ConvertTransformation: Convert between different transformation formats.

• ChainTransformations: Chain multiple or invert a single transformation.

Format

NxLib uses the Axis-angle notation for transformations in command results and for transformations in tree entries. If a transformation has to be specified as input parameter NxLib supports three different notations, Axis-angle, Euler rotations and matrix representation.

Axis-angle

Object/Transformation - This node represents a pose or transformation in 3D space. Its sub nodes contain the transformation parameters and have the following structure:

• Rotation (Object) - Subnode containing the 3D rotation part of the transformation specified via angle and rotation axis. Its sub nodes contain the rotation parameters.

  • Angle - The rotation angle \(\varphi\) in radians.

  • Axis - A Vector specifying the axis of rotation. This vector is normalized when rotations are returned via the API. Although it does not need to be normalized when specifying a rotation.

    • 0 (Number) - The x component of the rotation axis vector.

    • 1 (Number) - The y component of the rotation axis vector.

    • 2 (Number) - The z component of the rotation axis vector.

  Note: Any rotation in 3D space can be represented as a rotation around a single axis.

• Translation (Array/Vector) - A Vector specifying the translation part \(t\) of the transformation.

  • 0 (Number) - The x component of the translation vector.

  • 1 (Number) - The y component of the translation vector.

  • 2 (Number) - The z component of the translation vector.

• Inverse (Boolean, optional) - When set to true, the transformation will be inverted before it is used.

Euler rotations

When a transformation has to be specified as a parameter, this notation can be used alternatively. It is not used as part of a return.

Object/Transformation - This node represents a pose or transformation in 3D space. Its sub nodes contain the transformation parameters and have the following structure:

• Rotation (Object) - Subnode containing the 3D rotation part of the transformation specified via Euler rotations. Its sub nodes contain the rotation parameters.

  • Convention (Object) - Subnode containing the convention specification for how Angles have to be interpreted.

    • Axes (String) - A string specifying the order of axis-aligned rotations, such as “XYZ”, “ZYX”, “ZYZ”, etc. Note: An alias for Axes is Axis

    • Extrinsic (Boolean, optional) - When set to true, the elemental rotations are performed about the axes of the fixed coordinate system. When set to false the axes of the rotated target will be used. They change their orientation after each elemental rotation. Defaults to false.

    Convention (String) - For intrinsic conventions and known manufacturers, one can use shorthand notations such as {"Convention": "XYZ"} or {"Convention": "<Manufacturer name>"}. See the list of known manufacturers below.

  • Angles - A Vector specifying the angles in radians to the corresponding axis.

    • 0 (Number) - The angle of rotation around the given axis. For example, if Convention/Axes is “ZYX”, this angle defines a rotation around the z-axis.

    • 1 (Number) - The angle of rotation around the given axis. For example, if Convention/Axes is “ZYX”, this angle defines a rotation around the y-axis.

    • 2 (Number) - The angle of rotation around the given axis. For example, if Convention/Axes is “ZYX”, this angle defines a rotation around the x-axis.

• Translation (Array/Vector) - A Vector specifying the translation part \(t\) of the transformation.

  • 0 (Number) - The x component of the translation vector.

  • 1 (Number) - The y component of the translation vector.

  • 2 (Number) - The z component of the translation vector.

• Inverse (Boolean, optional) - When set to true, the transformation will be inverted before it is used.

Matrix

Array/Matrix - A 4x4 matrix representing the (homogeneous) transformation.

Notes

Shorthand Formats

When specifying poses or transformations with zero translation or rotation, it is allowed to set the Rotation or Translation nodes to the Number value 0, or to completely omit the corresponding node. Transformations stored in the tree or output from commands will always have the full format.

Manufacturer Conventions

When specifying transformations using Euler rotations, one can use the following manufacturer names in the shorthand notation. The “Axes” and “Extrinsic” columns describe how the specification will be interpreted. These are aliases provided to the best of our knowledge, but we cannot guarantee their correctness. The actual rotation convention is up to the manufacturer and may differ for individual products. Additionally, conversions from degrees to radians and from meters to millimeters should be performed by the user as necessary. NxLib interprets all angles in radians and all translations in millimeters.

Manufacture Name	Axes	Extrinsic
ABB	ZYX	false
Adept	ZYZ	false
Comau	ZYZ	false
Doosan	ZYZ	false
Epson	ZYX	false
Fanuc	XYZ	true
Fruitcore	XYZ	true
Kawasaki	ZYZ	false
Kuka	ZYX	false
Mecademic	XYZ	false
Mitsubishi	XYZ	true
Nachi	ZYX	false
Staeubli	XYZ	false
Techman	XYZ	true
Yaskawa	XYZ	true

Coordinate systems

In this manual, you will find parameter and return value descriptions that mention the format described above along with the associated coordinate systems, as shown in the following example.

Object/Transformation

The Transformation between A and B. Reference: Coordinate system A. Target: Coordinate system B.

Interpretation

Poses and transformations within NxLib are always specified as the relative pose of the target system inside the reference system (Figure 1). When the transformation is represented as a 4x4 homogeneous matrix, the columns of the upper left 3x3 matrix represent the axis directions \((x, y, z)\) of the target system inside the reference system and the upper right 3x1 column vector indicates the location of the target origin inside the reference system (\(t\)).

Figure 1: Pose of target coordinate system inside the reference coordinate system, with rotation axis \(\alpha\), rotation angle \(\varphi\) and translation vector to target origin \(t\).	Figure 2: Transformation of a point from the reference to the target coordinate system and vice versa.

There are two equivalent ways on how to interpret the transformations and poses. Note that the two following formulations are mathematically equivalent and both define the same transformation direction:

• Active Transformation: Transformations and poses can be interpreted as active transformations in their reference system: Applying the transformation to a point \(p_{ref}\) in the reference system will move the point to the corresponding location of the target system and result in the coordinates \(p_{ref}^{'}\) in the reference system.

• Passive Transformation / Change of Basis: Another interpretation of the transformation is a change of basis from the target pose to the reference system. Applying the transformation to a point \(p^{'}\) in the target system will yield the coordinates \(p_{ref}^{'}\) in the reference system.