User guide

If you are looking for installation instructions you should read the quick start.

Setting the build options of the core library

You can customize the behavior of the semantic checking (checking or not, and screen output or not) by changing the build options of the geometric_semantics library (see CMakeLists.txt of geometric_semantics package)

add_definitions(-DCHECK): when using this build flag, the semantic checking will be enabled.
add_definitions(-DOUTPUT_CORRECT): when using this build flag, you will get screen output for operations that are semantically correct.
add_definitions(-DOUTPUT_WRONG): when using this build flag, you will get screen output for operations that are semantically wrong.

Using the geometric relations semantics in your own application

Here we will explain how you can use the geometric relations semantics in your application, in particular using the Orocos Kinematics and Dynamics library as a geometry library, supplemented with the semantic support.

Preparing your own application using the ROS-build system

Create a new ROS package (in this case with name myApplication), with a dependency on the geometric_semantics_kdl:

roscreate-pkg myApplication geometric_semantics_kdl

This will automatically create a directory with name myApplication and a basic build infrastructure (see the roscreate-pkg documentation)

Add the newly created directory to your ROS_PACKAGE_PATH environment variable:

cd myApplication
export ROS_PACKAGE_PATH=$PWD:$ROS_PACKAGE_PATH

Writing your own application

Go to the application directory:

roscd myApplication

Create a main C++ file

touch myApplication.cpp

Edit the C++ file with your favorite editor
- Include the necessary headers. For instance:

#include <Pose/Pose.h>
#include <Pose/PoseCoordinatesKDL.h>

- It can be convenient to use the geometric_semantics namespace and for instance the one of your geometry library (in this case KDL):

using namespace geometric_semantics;                                                                                                                                                                                                    using namespace KDL;

- In your main you should create the necessary geometric relations. For instance for a pose, first create the KDL coordinates:

Rotation coordinatesRotB2_B1=Rotation::EulerZYX(M_PI,0,0);
Vector coordinatesPosB2_B1(2.2,0,0);
KDL::Frame coordinatesFrameB2_B1(coordinatesRotB2_B1,coordinatesPosB2_B1)

Then use this KDL coordinates to create a PoseCoordinates object:

PoseCoordinates<KDL::Frame> poseCoordB2_B1(coordinatesFrameB2_B1);

Then create a Pose object using both the semantic information and the PoseCoordinates:

Pose<KDL::Frame> poseB2_B1("b2","b2","B2","b1","b1","B1","b1",poseCoordB2_B1);

- Now you are ready to do actual calculations using semantic checking. For instance to take the inverse:

Pose<KDL::Frame> poseB1_B2 = poseB2_B1.inverse()

Building your own application

To build you application you should edit the CMakeLists.txt file created in you application directory. Add the your C++ main file to be build as an executable adding the following line:

rosbuild_add_executable(myApplication myApplication.cpp)

Now you are ready to build, so type

rosmake myApplication

and the executable will be created in the bin directory.

To run the executable do:

bin/myApplication

You will get the semantic output on your screen.

Extending your geometry library with semantic checking

Imagine you have your own geometry library with support for geometric relation coordinate representations and calculations with these coordinate representations. You however would like to have semantic support on top of this geometry library. Probably the best thing to do in this case is to mimic our support for the Orocos Kinematics and Dynamics Library. To have a look at it do:

roscd geometric_semantics_kdl/

Template specialization

The only thing you have to do is write template specializations. So for instance to get support for KDL::Rotation, which is a coordinate representation for a Orientation geometric relation, you have to write the template specialization for OrientationCoordinates<T>, i.e. OrientationCoordinates<KDL::Rotation>.

Semantic constraints invoked by your coordinate representations

The first thing to find out is which semantic constraints are invoked by the particular coordinate representation you use. For instance a KDL::Rotation represents a 3x3 rotation matrix and invokes the semantic constraint that the reference orientation frame is equal to the coordinate frame.

The possible semantic constraints are listed in the *Coordinates.h files in the geometric_semantics core library. So for instance for OrientationCoordinates we find there an enumeration of the different possible semantic constraints imposed by Orientation coordinate representations:

    /**                                                                                                                                                                                                                                      
      *\brief Constraints imposed by the orientation coordinate representation to the semantics                                                                                                                                              
      */                                                                                                                                                                                                                                     
    enum Constraints{                                                                                                                                                                                                                        
        noConstraints = 0x00,                                                                                                                                                                                                                
        coordinateFrame_equals_referenceOrientationFrame = 0x01, // constraint that the orientation frame on the reference body has to be equal to the coordinate frame                                                                      
    };

You should specify the constraint when writing the template specialization of the OrientationCoordinates<KDL::Rotation>:

// template specialization for KDL::Rotation                                                                                                                                                                                             
    template <>                                                                                                                                                                                                                              
    OrientationCoordinates<KDL::Rotation>::OrientationCoordinates(const KDL::Rotation& coordinates):                                                                                                                                         
        data(coordinates),                                                                                                                                                                                                                   
        constraints(coordinateFrame_equals_referenceOrientationFrame){    };

Specializing other functions to do actual coordinate calculations

The other function template specializations specify the actual coordinate calculations that have to be performed for semantic operations like inverse, changing the coordinate frame, changing the orientation frame, ... For instance, to specialize the inverse for KDL::Rotation coordinate representations:

   template <>                                                                                                                                                                                                                              
    OrientationCoordinates<KDL::Rotation> OrientationCoordinates<KDL::Rotation>::inverse2Impl() const                                                                                                                                        
    {                                                                                                                                                                                                                                        
        return OrientationCoordinates<KDL::Rotation>(this->data.Inverse());                                                                                                                                                                  
    }