Positions, Orientations and Coordinates

1 General

• If only the position is required, the specification can look like this (in metres):
  

  {"xyz": [x, y, z]}                      

• The orientation can be described by Euler angles (Rx, Ry, Rz, in degrees) or by quaternions (q0, q1, q2, q3):
  

  {"euler": [Rx, Ry, Rz]}
  {"quat": [q0, q1, q2, q3]}                   

• A pose always consists of the Cartesian position (x, y, z) and the orientation. There are therefore two ways of specifying a pose:
  

  {"xyz+euler": [x, y, z, Rx, Ry, Rz]}
  {"xyz+quat": [x, y, z, q0, q1, q2, q3]}                      

• The axis angles can be specified in the same way (j1, ..., j6, in degrees):
  

  {"joints": [j1, j2, j3, j4, j5, j6]}

---

2 Interpolation

2.1 Interpolating orientations

The method getInterpolatedRotation(r1q0, r1q1, r1q2, r1q3, r2q0, r2q1, r2q2, r2q3, percent) can be used to interpolate an orientation that lies between the two specified orientations. r1q0, ... , r1q3 describes the first orientation, r1q0, ..., r1q3 describes the second orientation, r2q0, ..., r2q3 describes the second orientation, percent specifies how far between the two orientations the output orientation lies.
A map with q0, ..., q3 is returned, which describes the new orientation.

Example:

var rotation = getInterpolatedRotation(0, 0.7, 0, 0.7, 1, 0, 1, 0, 0.5);

showHint(rotation.q1);

2.2 Determine missing Z coordinate using 4 defined points

There are camera systems that output the position of objects in x and y coordinates. However, as the robot is located in three-dimensional space, the Z coordinate is also required. If both the camera and the robot and the plane that the camera captures are perfectly parallel to the Z coordinate of the world coordinate system, this value is of course always fixed. If this is not the case, Z must be determined.

Procedure

In order to determine the Z coordinate, a reference plane must first be taught in. Two functions are therefore described here. One for teaching in the plane and one for determining the Z coordinate using an XY coordinate.

Teaching the plane

The plane is taught using the teachPlane() function. This function has 12 parameters. These parameters are the x, y and z coordinates of 4 points. These can be determined by moving the TCP to the corner points of the plane to be defined.

teachPlane(x1, y1, z1, x2, y2, z2, x3, y3, z3, x4, y4, z4)

Here is an example:

Four different points are travelled to (e.g. using the Define waypoint command) and the current position is displayed at each point.
We only consider the position, not the rotation. We now pass the positions of these four points to the teachPlane() method.

joints(0.000000, 0.000000, 0.000000, 0.000000, 85.220371, 0.000000, 1.000000, "Waypoint 1", false);

var one = getCurrentPose();

joints(-22.290554, 5.129221, 3.172679, 1.856705, 77.280641, -22.629531, 1.000000, "Waypoint 2", false);

var two = getCurrentPose();

joints(-17.163997, 26.062826, -27.035683, 1.411788, 86.406272, -17.196313, 1.000000, "Waypoint 3", false);

var three = getCurrentPose();

joints(16.878389, 25.613710, -22.733409, -1.398059, 82.547275, 17.004389, 1.000000, "Waypoint 4", false);

var four = getCurrentPose();

 

teachPlane(one.x, one.y, one.z, two.x, two.y, two.z, three.x, three.y, three.z, four.x, four.y, four.z)

A plane has now been taught and the z-coordinate can be calculated using xy-coordinates.

Determining the z-coordinate

Once the plane has been taught using the teachPlane() function, the z coordinate on the plane can now be calculated using x and y coordinates. The getZByTeachedPlane() function is used for this purpose.

This function requires the x and y position of a point as parameters. The return value is the z-coordinate, which is located on the previously defined plane and has the transferred x- and y-coordinates.

var z = getZByTeachedPlane(x,y)

---

3 Convert quaternions to Euler angles

Quaternions can be uniquely converted into Euler angles, but this is not always possible the other way round. The convertQuaternionToEuler() method receives a quaternion q0, ..., q3 as a parameter and returns a map containing the three Euler angles.

Beispiel

var pose = convertQuaternionToEuler(0, 0, 1, 0);

showInfo("rx: " + pose.rx + ", ry: " + pose.ry + ", rz: " + pose.rz);

---

4 External axis values

This article describes how externally specified axis values can be read out.

Since version 2023.04, these axis values can also be set within a programme instead of only via the external interface. Further information can be found here.

The getNextJoints() function is required to read out the current axis values. To ensure that meaningful values are returned, these must first be set via the external interface using the nextJoints command. An object with 6 attributes (j1, j2, j3, j4, j5, j6) is returned, whereby each value represents the angle of an axis. The following example shows how the individual attributes can be accessed.

var nextJoints = getNextJoints();

var j1 = nextJoints.j1;

var j6 = nextJoints.j6;

---

5 Accessing the next axis values

Two parameters are passed to the getClosestJoints() method:

1. an axis position (not necessarily the current axis position)

2. a desired target pose

As a result, the method returns the "next" target axis values.

var old_joints = new Joints(0,0,0,0,0,0);
var new_pose = new Pose(0.460,0, 0.2, 0, 0, 1,0);
var pose = getClosestJoints(old_joints, new_pose);
showHint(pose);

---

6 Set/change external axis values

The value of nextJoints can be set via the external interface. This value can also be set from within a programme using the setNextJoints() method. An object of the type Joints is expected as a parameter.

var new_joints = new Joints(20, 14, 42, 10, 22, -10);
setNextJoints(new_joints);

---

7 Current axis values

This article describes how the current axis values can be read out in textual programming.

The getCurrentJoints() function is required to read out the current axis values. An object with 6 attributes (j1, j2, j3, j4, j5, j6) is returned, where each value represents the angle of an axis. The following example shows how the individual attributes can be accessed.

var currentJoints = getCurrentJoints();

var j1 = currentJoints.j1;

var j6 = currentJoints.j6;

---

8 Current pose

This article describes how the current pose can be read out in textual programming.

The getCurrentPose() function is required to read out the current joint angles. An object with 10 attributes is returned. These are the positions in Cartesian space (x, y, z), as well as the orientation as quaternions (q0, q1, q2, q3) and the orientation as Euler angles (rx, ry, rz). The following example shows how the individual attributes can be accessed.

var pose = getCurrentPose();

var x = pose.x;

var q3 = pose.q3;

var rx = pose.rx;

---

9 Externally specified pose

This article describes how an externally specified pose can be read out in textual programming.

Since version 2023.04, this pose can also be set within a programme instead of only via the external interface. Further information can be found here.

The getNextPose() function is required to read an externally specified pose. To ensure that meaningful values are returned, these must first be set via the external interface using the nextPose command. An object with 10 attributes is returned. These are the positions in Cartesian space (x, y, z), as well as the orientation as quaternions (q0, q1, q2, q3) and the orientation as Euler angles (rx, ry, rz). The following example shows how the individual attributes can be accessed.

var pose = getNextPose();

var x = pose.x;

var q3 = pose.q3;

var rx = pose.rx;

---

10 Set/change external pose

The value of nextPose can be set via the external interface. This value can also be set from within a programme using the setNextPose() method. An object of the type Pose is expected as a parameter.

var new_pose = new Pose(0.460,0.2, 0.3, 0, 0, 1, 0); //x,y,z,q0,q1,q2,q3
setNextPose(new_pose);

---

Normal vector using Euler angle

This article describes how to obtain the normal vector using Euler angles. This can be useful for mathematical operations. An example of this is that a camera also provides a rotation in Euler angles in addition to the translation. If the TCP is not supposed to move there directly, but first at a certain distance along the orientation of the target object.

The getSurfaceNormalByEuler function returns a map containing three entries: x, y and z. These specify the normal vector of the Z axis of the TCP if it is aligned according to the Euler angles transferred. The corresponding entries can be accessed with getX(), getY() and getZ().

var normal = getSurfaceNormalByEuler(rx, ry, rz);

var x = normal.getX();

var y = normal.getY();

vaz z = normal.getZ();

Example

The values obtained from the function can be used, for example, to place the TCP at a certain distance from a target object in the orientation of the target object. Here is a small example.

In this example, the normal vector is first determined using the getSurfaceNormalByEuler() function described here. The orientation of the target object obtained from a camera, for example, is given as a parameter.
A move command is now used to place the TCP at a certain distance from the target object in the orientation of the target object. The target orientation is the orientation of the target object. The target position is the position of the target object plus a certain distance. The factor moveFactor is used here to determine the length of the distance.

var target = {x: 0.3, y: 0.4, z: 0.5, rx: 20, ry: 30, rz: 60};

var normal = getSurfaceNormalByEuler(target.rx, target.ry, target.rz);

var moveFactor = 0.1;

move({

    'Coord': 'CARTESIAN_BASIS',

    'MoveType': 'LINEAR',

    'PoseRelation': 'ABSOLUTE',

    'speed.ratio': 1.0,

    'targetpose.rx': target.rx,

    'targetpose.ry': target.ry,

    'targetpose.rz': target.rz,

    'targetpose.x':  target.x + moveFactor * normal.getX(),

    'targetpose.y':  target.y + moveFactor * normal.getY(),

    'targetpose.z':  target.z + moveFactor * normal.getZ()

}, "Wegpunkt 1");

---

Normal vector using the Z-axis of the TCP

This article describes how to get the normal vector that points from the TCP in the direction of the TCP's Z-axis. This can be useful for mathematical operations or simply for travelling along this axis.

The getSurfaceNormal() function returns a map containing three entries: x, y and z. These specify the normal vector of the Z-axis of the TCP. The corresponding entries can be accessed with getX(), getY() and getZ().

var normal = getSurfaceNormal();

var x = normal.getX();

var y = normal.getY();

var z = normal.getZ();

Example

The values obtained from the function can be used, for example, in textual programming along the Z-axis of the TCP. Here is a small example.

In this example, the normal vector is first determined using the getSurfaceNormal() function described here.

In addition, the current position of the TCP is determined using the getCurrentPose() function.

A move command is now used to move along the Z axis. The orientation of the TCP should not be changed. We therefore adopt the 4 quaternions from the current position. However, the position of the TCP should change along its Z-axis. We therefore add the corresponding component of the normal vector to the current position. The factor moveFactor is used here so that the length of the movement can be determined.

var normal = getSurfaceNormal();

var moveFactor = 0.1;

var pose = getCurrentPose(); 

move({

    'Coord': 'CARTESIAN_BASIS',

    'MoveType': 'JOINT',

    'PoseRelation': 'ABSOLUTE',

    'speed.ratio': 1.0,

    'targetpose.q0': pose.q0,

    'targetpose.q1': pose.q1,

    'targetpose.q2': pose.q2,

    'targetpose.q3': pose.q3,

    'targetpose.x':  pose.x + moveFactor * normal.getX(),

    'targetpose.y':  pose.y + moveFactor * normal.getY(),

    'targetpose.z':  pose.z + moveFactor * normal.getZ()

}, "Waypoint1");