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:

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:

Frame workpiece = FrameRegistry.getFrame("Workpiece"); 
lwr.getBase().addRelation(new Placement(new Transformation(0.5, 0.2, 0, 0, 0, 0)), workpiece); 
workpiece.addRelation(new Placement(new Transformation(-0.5, -0.2, 0, 0, 0, 0)), lwr.getBase());

Robotics API Frames do not have a unique reference Frame, but can have Relations to an arbitrary number of Frames. Relations do not induct a hierarchy on Frames.