Using relations

In the Robotics API, a Relation defines a geometrical relationship between two Frames (see 2.2.1). The previous sections already indicated different characteristics of Frames, like being bound to robots or defined relative to other Frames. These characteristics of a Frame are defined by the set of Relations it is equipped with.

Relations have in common that they connect exactly two Frames. The Relation itself has no defined direction, i.e. the Frames are not assigned any semantic role like being parent or child in this context. A Relation really just describes the geometric relationship, without introducing further dependencies.

Mathematically, the geometric displacement described by a Relation is modeled by a Cartesian Transformation associated to that Relation. The Transformation itself is neutral with respect to Frames, i.e. it can be applied to any Frame. When applied, it calculates the position of a second Frame relative to the Frame it has been applied to. Relations store one of their Frames as ’from’ Frame and the other one as ’to’ Frame. The Transformation associated with the Relation then defines the pose of the ’to’ Frame relative to the ’from’ Frame. As a Transformation is always reversable (i.e. the reversed Transformation defines the pose of ’from’ relative to ’to’), this again does not assign roles to the Frames of a Relation, but just clarifies calculation rules.

Different types (subclasses) of Relations carry different semantics of the behaviour of the Frame relationship over time:

• A StaticConnection describes a fixed, invariable relationship. It is intended to be used for Frames that are tied together in a static way. Examples are the connection between the flange of a robot and the endeffector of the tool it carries, and the connection between two edges of some workpiece.

  The following code snippet connects a Frame tool statically to the flange of a robot lwr and defines a displacement of 20cm along the z axis of the flange:

  Frame tool = FrameRegistry.getFrame("Tool"); 
  lwr.getFlange().addRelation(new StaticConnection(new Transformation(0, 0, 0.2, 0, 0, 0)), tool);
• Placement describes a non-dynamic relationship that may change during runtime of a program in a user-defined way. The Transformation a Placement carries can be adjusted anytime, in contrast to that of a StaticConnection. Placements are used for Frames whose relation needs to be described at some time, but may be different at another time, e.g. the position of a workpiece reference Frame relative to some magazine it is currently placed in. Users need to take care of adjusting or removing Placements once they are no longer valid.

  Placements are created similar to StaticConnections, but are modifyable afterwards:

  Frame workpiece = FrameRegistry.getFrame("Workpiece"); 
  Placement p = new Placement(new Transformation(0.5, 0.2, 0, 0, 0, 0)); 
  lwr.getBase().addRelation(p, workpiece); 
  p.setTransformation(new Transformation(1.0, 0.5, 0, Math.PI, 0, 0));
• DynamicConnection models a persistent connection between Frames that may change dynamically over time. The most common examples are the connections between the Frames of the respective robot axes, which change when joints move. The Transformation associated with a DynamicConnection is automatically calculated by the connection itself when needed. Most DynamicConnections are created and managed by devices like a Robot (for its joints). However, there exist some user-definable DynamicConnections like the TransformationSensorConnection, whose usage is explained in section 2.7.2.

As shown in the above examples, a Relation has to be added to the ’from’ Frame after it has been defined. When adding it, the ’to’ Frame has to be given as argument. The Relation is automatically added to the ’to’ Frame as well. Relations can be removed by the method Frame.removeRelation(Relation). It is then removed from both Frames.

Each Frame can have an arbitrary number of Relations to other Frames. Note again that Relations do not induct a hierarchy between Frames. This means that the last two lines in the following code snippet are semantically exactly equal: