- The design idea
- The design
- The software structure and content
- Core library: geometric_semantics
- KDL support: geometric_semantics_kdl
- ROS tf support: geometric_semantics_tf
- ROS messages: geometric_semantics_msgs
- ROS message conversions: geometric_semantics_msgs_conversions
- ROS tf messages support: geometric_semantics_tf_msgs
- ROS tf message conversions: geometric_semantics_tf_msgs_conversions
- Examples: geometric_semantics_examples

The software implements the geometric relation semantics, hereby offering support for semantic checks for your rigid body relations. This will avoid commonly made errors, and hence reduce application (and, especially, system integration) development time considerably. The proposed software is to our knowledge the first to offer a semantic interface for geometric operation software libraries.

## The design idea

The goal of the geometric_relations_semantics library is to**provide semantic checking for calculations with geometric relations**between rigid bodies

**on top of existing geometric libraries**, which are only working on specific coordinate representations. Since there are already a lot of libraries with good support for geometric calculations on specific coordinate representations (The Orocos Kinematics and Dynamics library, the ROS geometry library, boost, ...) we do not want to design yet another library but rather will

**extend these existing geometric libraries with semantic support**. The effort to extend an existing geometric library with semantic support is very limited: it boils down to the implementation of about six function template specializations.

For the semantic checking, we created the (templated) **geometric_semantics core library**, providing all the necessary **semantic support** for geometric relations (relative positions, orientations, poses, translational velocities, rotational velocities, twists, forces, torques, and wrenches) *and* the operations on these geometric relations (composition, integration, inversion, ...).

If you want to perform actual geometric relation calculations, you will need particular coordinate representations (for instance a homogeneous transformation matrix for a pose) and a geometric library offering support for calculations on these coordinate representations (for instance multiplication of homogeneous transformation matrices). To this end, you can build your own library depending on the geometric_semantics core library in which you implement a limited number of functions, which make the connection between semantic operations (for instance composition) and actual coordinate representation calculations (for instance multiplication of homogeneous transformation matrices). We already provide support for two geometric libraries: the Orocos Kinematics and Dynamics library and the ROS geometry library, in the geometric_semantics_kdl and geometric_semantics_tf libraries, respectively.

## The design

For every geometric relation (position, orientation, pose, translational velocity, rotational velocity, twist, force, torque, and wrench) the geometric_semantics library contains four classes. Here we will explain the design with the position geometric relation, but all other geometric relations have a similar design. For the position geometric relation there are four classes:*PositionSemantics*: This class contains the semantics of the (coordinate-free) Position geometric relation. For instance in this case it contains the information on the point, reference point, body, and reference body.*PositionCoordinatesSemantics*: This class contains a PositionSemantics object of the geometric relation at hand and the extra semantic information needed for semantics of position coordinate geometric relation, i.e. the coordinate frame in which the coordinates are expressed.*PositionCoordinates*: This templated class contains the actual coordinate representation of the geometric relation, for instance a position vector for the position geometric relation. The template is the actual geometry object (of an external library) you will use as a coordinate representation, for instance a KDL::Vector.*Position*: This templated class is a composition of a PositionCoordinatesSemantics object and a PositionCoordinates object. In case you want both semantic support and want to do actual geometric calculations, this is the level you will work at.

Again, the template is the actual geometry (of an external library) you will use as a coordinate representation, for instance a KDL::Vector.

The above described design is illustrated by the figure below.

Remark that all four of the above 'levels' are of actual use:

*PositionSemantics*: to do coordinate-free semantic checking (without actual geometric calculations);*PositionCoordinateSemantics*: to do semantic checking involving coordinate systems (without actual geometric calculations);*PositionCoordinates*: to do the actual geometric calculations; and*Position*: to do both semantic checking and the actual geometric calculations.