Commit 3a734941 authored by Florent Lamiraux's avatar Florent Lamiraux
Browse files

Remove obsolete file.

parent 0ab2265f
Developing in Hpp
=================
This page explains some development rules applied in *HPP* project.
General rules to be followed in HPP developement
------------------------------------------------
Make clear distinction between algorithms, middleware and graphical interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.*HPP* architecture: the functionalities are distributed into separate software packages. The architecture is composed of three types of packages: algorithms, CORBA interfaces and KPP-SDK interfaces.
image:figures/archi.png[HPP architecture]
*HPP* is composed of several software packages divided into three
groups as explained in the above figure:
* algorithms,
* Corba server
* KPP-interfaces
KPP-interface and Corba server should be considered as visualization
and debugging-testing tools. It is mostly important that packages
implementing path planning algorithms for humanoid robots are
independent from a given middleware (CORBA) and from a given GUI
(KineoPathPlanner). As a consequence, no CORBA::xxx attribute should
be in a class belonging to the algorithm part.
This simple principle will enable to easily insert the algorithmic
software packages into different middlewares (GenoM, RT-middleware for
instance).
Modularity
~~~~~~~~~~
Try to avoid developing huge packages including many
functions. Instead, build several small packages with simple
interfaces and easy to understand functionalities.
Example
^^^^^^^
Let us assume that you are developing a path planning algorithm and
you want to use quaternions to represent the orientations of
rigid-bodies.
* The first step consists in trying to find an existing implementation
of quaternions that you can use.
* Let us assume (this is very unlikeky) that you cannot find a good
implementation of quaternions, then, instead of developing
operations on quaternions in your path planning package, it is much
more clever to create a package that will handle quaternion
operations and to make your path planning package depend on
it. Later, other users will be able to use your quaternion package.
Level of generality
~~~~~~~~~~~~~~~~~~~
When you implement an algorithm, always ask yourself the question:
"Could my algorihtm be applied to applications more general than the
one I am dealing with?" If yes, try to make your algorithm take more
general input than your practical problem of today.
Example
^^^^^^^
Let us assume that you want to implement Newton algoritm to find a
root of a polynomial function. Your algorithm requires the derivative
of the polynomial. You can get an expression of a polynomial
derivative using the polynomial coefficients.
However, it would be more clever to develop the same algorithm taking
as input a function that might not be a polynomial. For that you can
define an abstract class:
[source,cc]
class Cmapping {
public:
virtual double value(double inParamter) = 0;
virtual double derivative(double inParamter) = 0;
};
make your Newton implementation take as input an object Cmapping and
then derive this class into a concrete polynomial class. Thus, your
algorithm can be used by other people wanting to find the root of
non-polynomial functions.
Humanoid robots
^^^^^^^^^^^^^^^
The algorithms we develop are mostly applied to one type of humanoid
robot: HRP2. It is therefore important to develop these algorithms in
such a way that they can be applied to any other humanoid robot. For
that developers should avoid to make too strong asumptions about the
robot structure. The abstract CjrlHumanoidDynamicRobot interface for
dynamic humanoid robots have been designed in this aim.
How to implement a new algorithm in HPP
----------------------------------------
To implement a new algorithm in HPP, you need to create new software
packages as described below. To create new software packages, we
advise developers to use perl script packageCreate.
[source,shell]
[~] cd devel/src
[src] cg-clone git+ssh://[git|softs].laas.fr/git/robots/scripts
Create a new software package implementing your algorithm
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To create a new package depending on hppCore, type the following
commands.
[source,shell]
[~] cd devel/src
[src] perl ./scripts/packageCreate hppNewAlgo -d hppCore HPPCORE
If you want your package to depend on other packages add `-d package
PACKAGE` for each dependence.
This operation creates a template of software package with all
necessary files to compile. There are four subdirectories in this
package:
* `doc` contains necessary files to generate doxygen documentation,
* `include` contains headers files
* `src` contains source code files
* `unitTesting` contains files used to test the algorithm developed in
the package.
Define in `include/hppNewAlgo.h` a class that derives from `ChppPlanner`.
[source,cc]
---------------------------------------------------------------------
#include "hppPlanner.h"
class ChppNewAlgo : public ChppPlanner {
public:
...
ktStatus solve();
};
---------------------------------------------------------------------
`Class ChppPlanner` proposes an interface functions to insert a robot
and obstacles:
[source,cc]
ktStatus ChppPlanner::addHppProblem(CkppDeviceComponentShPtr robot);
[source,cc]
ktStatus ChppPlanner::addObstacle(CkcdObjectShPtr object);
Independently from how the robot and obstacles are inserted, you can
use them as the input of your algorithm in your `class ChppNewAlgo`:
[source,cc]
CkppDeviceComponentShPtr robot = robotIthProblem(0);
Write in `src/hppNewAlgo.cpp` function:
[source,cc]
---------------------------------------------------------------------
ktStatus ChppNewAlgo::solve()
{
CkwsPath path = resultOfNewAlgo();
ChppProblem& hppProblem = hppProblemVector[problemId];
hppProblem.addPath(kwsPath);
}
---------------------------------------------------------------------
that runs your algorithm. The two last lines insert the result of your
path in KPP interface if the interface is running.
To compile and install your package do the following step:
[source,shell]
[~] cd devel/src/hppNewAlgo
[hppNewAlgo] mkdir build
[hppNewAlgo] cd build
[hppNewAlgo] cmake -DCMAKE_INSTALL_PREFIX=${HOME}/devel ..
[hppNewAlgo] make install
Create a new KPP-interface for your package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To be able to see the result of your algorithm, you need to create a
new KPP-interface deriving from CkppInterface:
[source,shell]
[~] cd devel/src
[src] perl ./scripts/packageCreate kppInterfaceNewAlgo -d kppInterface KPPINTERFACE -d hppNewAlgo HPPNEWALGO
and depending on your algorithm software package.
See package kppInterfaceTutorial for an example, and especially for
managing Kineo license issue in `src/Makefile.am`:
[source,shell]
[~] cd devel/src
[src] cg-clone git+ssh://[git|softs].laas.fr/git/jrl/hppTutorialPlanner
[src] cg-clone git+ssh://[git|softs].laas.fr/git/jrl/kppInterfaceTutorial
To run your interface into KineoPathPlanner, do the following:
[source,shell]
[~] KineoPathPlanner -ModulePath ${HOME}/lib/modules/${HOST}/libkppInterfaceNewAlgo
Programming conventions
-----------------------
Programming rules
~~~~~~~~~~~~~~~~~
Besides the general rules explained above, some more specific rules
should be enforced when writing a new class.
Private attributes
^^^^^^^^^^^^^^^^^^
All attributes in a class should be private since they represent the
internal state of the object. Access to these attributes can be
controlled through protected or public access functions.
.Example
[source,cc]
---------------------------------------------------------------------
class ConeClass {
public:
/**
\brief Public read access
\return Internal value of the object.
*/
inline double value()
{
return inValue;
};
protected:
/**
\brief Write access for derived classes
\param inValue new internal value of the object.
*/
inline void value(double inValue)
{
attValue = inValue;
};
private:
/**
\brief Internal value of the object
*/
double attValue;
};
---------------------------------------------------------------------
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment