6.1. Kinematic Transformations

The voraus Robot Control converts poses between joint space and Cartesian space on request, without moving the robot. Two functions of the OPC UA interface are provided for this purpose:

ForwardKinematic converts a set of joint positions into a Cartesian pose, see Forward Kinematic.
InverseKinematic converts a Cartesian pose into a set of joint positions, see Inverse Kinematic.

Both functions are commonly used to prepare and check a target pose before it is sent as a motion command (see System and Motion Commands), to convert a pose between the available coordinate systems, or to determine the configuration vector that belongs to a known pose (see Configuration Vector).

6.1.1. Common Properties

Both functions are pure calculations on the kinematics model of the currently loaded robot (see Robot Config File). They do not move the robot and do not require a specific robot state. A transformation that cannot be calculated is reported through the ErrorMessage output described in Error Handling.

Coordinate Systems

The coordinate system of the Cartesian pose is selected with the TargetCS and SourceCS parameter respectively, using the numeric identifiers listed in Table 1. Only Cartesian coordinate systems that are fixed in space are supported:

Table 89 Coordinate Systems Supported by the Kinematic Transformations
Coordinate System	Supported	Remark
Robot CS (`ROBOT_CS`)	Yes
User CS 01–16 (`UserCS_01` … `UserCS_16`)	Yes	The user coordinate system must be defined beforehand, see Defining User Coordinate Systems.
Joint CS (`JOINT_CS`)	No	Not a Cartesian coordinate system; it is the result of the transformation, not a reference frame for it.
Tool CS (`TOOL_CS`), Camera CS (`CAMERA_CS`)	No	Both move with the end effector and are therefore not available as a reference frame.

A Cartesian pose is always specified as \([x, y, z, A, B, C]\) in \([\mathrm{m}]\) and \([\mathrm{rad}]\), with the intrinsic X Y' Z'' (Cardan) rotation order, see voraus Conventions and Units Summary. Joint positions are always specified in \([\mathrm{rad}]\) for rotational axes and in \([\mathrm{m}]\) for prismatic axes.

Tool Transformation

The tool is always passed explicitly to the transformation, with the two parameters ToolTransformation and ToolTransformationOffset. The tool that is configured in the system (see Tool Transformation) is not applied automatically, so the same call can be used to evaluate a pose for any tool.

ToolTransformation describes the transformation from the Flange CS to the Tool CS.
ToolTransformationOffset describes an additional transformation from the previous Tool CS defined with ToolTransformation. It is defined in tool coordinates. The total transformation of Tool CS is given by applying first ToolTransformation and then ToolTransformationOffset.

Both parameters must contain six elements. If both are submitted as [0, 0, 0, 0, 0, 0], the Cartesian pose refers to the Flange CS.

Configuration Vector

Which of the possible joint solutions of a Cartesian pose is used is selected by the configuration vector, see Configuration Vector. ForwardKinematic returns it and InverseKinematic accepts it as an input argument, both in the fixed six-element array described in Number of Elements.

6.1.2. Forward Kinematic

The ForwardKinematic function converts joint positions into the corresponding Cartesian pose. The result is unambiguous: one set of joint positions always leads to exactly one pose. In addition to the pose, the function returns the configuration vector of the submitted joint positions, which is the recommended way to determine the flag values of a known arm configuration, see Specifying a Configuration.

Table 90 Ids for `ForwardKinematic`
Command Name	NodeId	ParentId
`ForwardKinematic`	310101	310000

Table 91 Parameter Input for `ForwardKinematic`
Name	Type	Description
`AxesPose`	Array of double	Joint positions to be converted, in \([\mathrm{rad}]\) for rotational axes and in \([\mathrm{m}]\) for prismatic axes. The array must contain exactly six elements.
`ToolTransformation`	Array of double	Transformation \([x, y, z, A, B, C]\) from the Flange CS to the tool endpoint, see Common Properties.
`ToolTransformationOffset`	Array of double	Additional transformation \([x, y, z, A, B, C]\) from the tool endpoint to the resulting Tool CS, defined in tool coordinates.
`TargetCS`	Int32	Coordinate system in which the resulting pose is returned, see Table 89.

Table 92 Parameter Output for `ForwardKinematic`
Name	Type	Description
`CartesianPose`	Array of double	Resulting pose \([x, y, z, A, B, C]\) of the Tool CS in the selected target coordinate system, in \([\mathrm{m}]\) and \([\mathrm{rad}]\).
`Quaternion`	Array of double	Orientation of the resulting pose as a unit quaternion with four elements in the order \([w, x, y, z]\). It describes the same orientation as the angles \(A\), \(B\) and \(C\) of `CartesianPose`.
`ConfigurationVector`	Array of int32	Configuration vector of the submitted joint positions, always with six elements, see Configuration Vector.
`ErrorMessage`	String	Empty if the result is valid, otherwise the reason why the transformation failed, see Error Handling.

Note

The function currently supports only six entries in the AxesPose vector, even if the current robot has fewer than six joints. A submitted AxesPose with a different number of elements is rejected. Unnecessary entries should be set to 0.0, see Edge Cases and Known Limitations.

Edge Cases and Known Limitations

This section describes specific situations that require special consideration when using the ForwardKinematic function.

Robots with Fewer Than Six Joints

Currently, the unnecessary entries of the AxesPose vector are not ignored for robots with fewer than six joints. They are included in the calculation, so values other than 0.0 falsify the result of the transformation. Set all unnecessary entries to 0.0.

6.1.3. Inverse Kinematic

The InverseKinematic function converts a Cartesian pose into the corresponding joint positions. Because the inverse kinematics is ambiguous, the requested solution is selected with the ConfigurationVector input parameter, see Configuration Vector.

Table 93 Ids for `InverseKinematic`
Command Name	NodeId	ParentId
`InverseKinematic`	310102	310000

Table 94 Parameter Input for `InverseKinematic`
Name	Type	Description
`CartesianPose`	Array of double	Pose \([x, y, z, A, B, C]\) of the Tool CS to be converted, in \([\mathrm{m}]\) and \([\mathrm{rad}]\). The array must contain exactly six elements.
`ToolTransformation`	Array of double	Transformation \([x, y, z, A, B, C]\) from the Flange CS to the tool endpoint, see Common Properties.
`ToolTransformationOffset`	Array of double	Additional transformation \([x, y, z, A, B, C]\) from the tool endpoint to the resulting Tool CS, defined in tool coordinates.
`SourceCS`	Int32	Coordinate system in which the submitted pose is defined, see Table 89.
`ConfigurationVector`	Array of int32	Joint configuration to be calculated. Each element must be either `1` or `-1`. If an empty array is submitted, the currently commanded configuration of the robot is used, see Configuration Vector.

Table 95 Parameter Output for `InverseKinematic`
Name	Type	Description
`AxesPose`	Array of double	Resulting joint positions, in \([\mathrm{rad}]\) for rotational axes and in \([\mathrm{m}]\) for prismatic axes.
`ErrorMessage`	String	Empty if the result is valid, otherwise the reason why the transformation failed, see Error Handling.

Note

The transformation only determines whether a mathematical solution exists for the requested configuration. The resulting joint positions are not checked against the axis position limits (see Limitations), the workspace, or the collision model (see Workspace Monitoring). A pose that is converted successfully can therefore still be rejected when it is used as the target of a motion command.

6.1.4. Error Handling

Both functions report a failed transformation through their ErrorMessage output parameter instead of a failing method call: the OPC UA call itself completes successfully even if the transformation could not be calculated. The ErrorMessage is empty if and only if the result is valid.

Warning

Always evaluate ErrorMessage before using any other output parameter. If the transformation fails, the remaining output parameters are empty and must not be interpreted as a pose or as joint positions.

Table 96 lists the causes of a failed transformation.

Table 96 Causes of a Failed Transformation
Cause	Function	Remedy
The number of submitted joint positions is not supported.	`ForwardKinematic`	See Table 91.
The submitted Cartesian pose does not contain six elements.	`InverseKinematic`	See Table 94.
The submitted tool transformation or tool transformation offset does not contain six elements.	Both	Use `[0, 0, 0, 0, 0, 0]` if no transformation is required.
The selected coordinate system is not supported.	Both	See Table 89.
The submitted configuration vector is invalid, i.e., it contains too few elements or an element that is neither `1` nor `-1`.	`InverseKinematic`	See Number of Elements, or submit an empty array.
The transformation itself could not be calculated, for example because the pose cannot be reached in the requested configuration.	`InverseKinematic`	Check the pose and the requested configuration. The error message contains the reason reported by the kinematics.

6. Kinematics and Dynamics

7. Cyclic Position Commands