manif

A small header-only library for Lie theory.

Package Summary

manif is a header-only C++11 Lie theory library for state-estimation targeted at robotics applications.

At the moment, it provides the groups:

R(n): Euclidean space with addition.
SO(2): rotations in the plane.
SE(2): rigid motion (rotation and translation) in the plane.
SO(3): rotations in 3D space.
SE(3): rigid motion (rotation and translation) in 3D space.

Other Lie groups can and will be added, contributions are welcome.

manif is based on the mathematical presentation of the Lie theory available in this paper. We recommend every user of manif to read the paper (17 pages) before starting to use the library. The paper provides a thorough introduction to Lie theory, in a simplified way so as to make the entrance to Lie theory easy for the average robotician who is interested in designing rigorous and elegant state estimation algorithms. In a rush? Check out our Lie group cheat sheet.

manif has been designed for an easy integration to larger projects:

A single dependency on Eigen,
header-only for easy integration,
templated on the underlying scalar type so that one can use its own,
and C++11, since not everyone gets to enjoy the latest C++ features, especially in industry.

It provides analytic computation of Jacobians for all the operations. It also supports template scalar types. In particular, it can work with the ceres::Jet type, allowing for automatic Jacobian computation -- see related paragraph on Jacobians below.

All Lie group classes defined in manif have in common that they inherit from a templated base class (CRTP). It allows one to write generic code abstracting the Lie group details.
Please find more information in the related wiki page

Details

Maintainer status: maintained
Maintainer: Jeremie Deray deray.jeremie@gmail.com
Authors:
- Jeremie Deray deray.jeremie@gmail.com
- Joan Sola jsola@iri.upc.edu
License: MIT
Bug / feature tracker: github.com/artivis/manif/issues
Source: github.com/artivis/manif.git (branch: devel)

Installation • Features • Documentation • Tutorials • Publications • They use manif • Contributing

Quick Start

Dependencies

Eigen 3 :

Linux ( Ubuntu and similar )
```
apt-get install libeigen3-dev
```
OS X
```
brew install eigen
```

lt::optional : included in the external folder

Installation

$ git clone https://github.com/artivis/manif.git
$ cd manif && mkdir build && cd build
$ cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON ..
$ make
$ make install

Using catkin_tools

$ git clone https://github.com/artivis/manif.git
$ catkin build manif --cmake-args -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON

Generate the documentation

$ cd manif
$ doxygen .doxygen.txt

Use manif in your project

In your project CMakeLists.txt :

project(foo)
# Find the Eigen library
find_package(Eigen3 REQUIRED)
target_include_directories(${PROJECT_NAME} SYSTEM PUBLIC ${EIGEN3_INCLUDE_DIRS})
# Find the manif library
find_package(manif REQUIRED)
add_executable(${PROJECT_NAME} src/foo.cpp)
# Add manif include directories to the target
target_include_directories(${PROJECT_NAME} SYSTEM PUBLIC ${manif_INCLUDE_DIRS})

Features

Available Operations

Operation		Code
	Base Operation
Inverse	$\mathbf \Phi^{-1}$	`X.inverse()`
Composition	$\mathbf \mathcal{X} \circ \mathbf \mathcal{Y}$	`X * Y` `X.compose(Y)`
Hat		`w.hat()`
Act on vector		`X.act(v)`
Retract to group element	$\exp(\mathbf \varphi^{^})$	`w.exp()`
Lift to tangent space	$\log(\mathbf \Phi)$	`X.log()`
Manifold Adjoint		`X.adj()`
Tangent adjoint		`w.smallAdj()`
	Composed Operation
Manifold right plus		`X + w` `X.plus(w)` `X.rplus(w)`
Manifold left plus		`w + X` `w.plus(X)` `w.lplus(X)`
Manifold right minus		`X - Y` `X.minus(Y)` `X.rminus(Y)`
Manifold left minus		`X.lminus(Y)`
Between		`X.between(Y)`
Inner Product		`w.inner(t)`
Norm		`w.weightedNorm()` `w.squaredWeightedNorm()`

Above, $\mathcal{Y}$ represent group elements, represent elements in the Lie algebra of the Lie group, or w,t represent the same elements of the tangent space but expressed in Cartesian coordinates in , and or v represents any element of .

Jacobians

All operations come with their respective analytical Jacobian matrices.
Throughout manif, Jacobians are differentiated with respect to a local perturbation on the tangent space.

Currently, manif implements the right Jacobian (see here for reference), whose definition reads:

$\frac{\delta f(\mathbf\mathcal{X})}{\delta\mathbf\mathcal{X}}\to\lim_{\varphi\to0}\frac{ f(\mathbf\mathcal{X}\oplus\varphi)\ominus f(\mathbf\mathcal{X})}{\varphi}$

The Jacobians of any of the aforementionned operations can then be evaluated, e.g.,

  SO2d X = SO2d::Random(),
       Y = SO2d::Random();

  SO2d::Jacobian J_c_x, J_c_y;
  auto compose = X.compose(Y, J_c_x, J_c_y);

  SO2d::Jacobian J_m_x, J_m_y;
  auto minus   = X.minus(Y, J_m_x, J_m_y);

  SO2d::Jacobian J_i_x;
  auto inverse = X.inverse(J_i_x);

  // etc...

Shall you be interested only in a specific Jacobian, it can be retrieved without evaluating the other:

  auto composition = X.compose(Y, J_c_x);

or conversely,

  auto composition = X.compose(Y, SO2d::_, J_c_y);

A note on Jacobians

The manif package differentiates Jacobians with respect to a local perturbation on the tangent space. These Jacobians map tangent spaces, as described in this paper.

However, many non-linear solvers (e.g. Ceres) expect functions to be differentiated with respect to the underlying representation vector of the group element (e.g. with respect to quaternion vector for ).

For this reason manif is compliant with Ceres auto-differentiation and the ceres::Jet type.

For reference of the size of the Jacobians returned when using ceres::Jet, manif implements rotations in the following way:

SO(2) and SE(2): as a complex number with real = cos(theta) and imag = sin(theta) values.
SO(3) and SE(3): as a unit quaternion, using the underlying Eigen::Quaternion type.

Therefore, the respective Jacobian sizes using ceres::Jet are as follows:

SO(2) : size 2
SO(3) : size 4
SE(2) : size 4
SE(3) : size 7

For more information, please refer to the Ceres wiki page.

Documentation

The API documentation can be found online at codedocs.xyz/artivis/manif.

Some more general documentation and tips on the use of the library is available on the wiki-page.

To generate the documentation on your machine, type in the terminal

$ cd manif
$ doxygen .doxygen.txt

and find it at manif/doc/html/index.html.

Throughout the code documentation we refer to 'the paper' which you can find in the section Publications.

Tutorials and application demos

We provide some self-contained and self-explained executables implementing some real problems. Their source code is located in manif/examples/. These demos are:

se2_localization.cpp: 2D robot localization based on fixed landmarks using SE2 as robot poses. This implements the example V.A in the paper.
se3_localization.cpp: 3D robot localization based on fixed landmarks using SE3 as robot poses. This re-implements the example above but in 3D.
se2_sam.cpp: 2D smoothing and mapping (SAM) with simultaneous estimation of robot poses and landmark locations, based on SE2 robot poses. This implements a the example V.B in the paper.
se3_sam.cpp: 3D smoothing and mapping (SAM) with simultaneous estimation of robot poses and landmark locations, based on SE3 robot poses. This implements a 3D version of the example V.B in the paper.
se3_sam_selfcalib.cpp: 3D smoothing and mapping (SAM) with self-calibration, with simultaneous estimation of robot poses, landmark locations and sensor parameters, based on SE3 robot poses. This implements a 3D version of the example V.C in the paper.

Publications

If you use this software, please consider citing this paper as follows:

@article{Deray-20-JOSS,
  doi = {10.21105/joss.01371},
  url = {https://doi.org/10.21105/joss.01371},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {46},
  pages = {1371},
  author = {Jérémie Deray and Joan Solà},
  title = {Manif: A micro {L}ie theory library for state estimation in robotics applications},
  journal = {Journal of Open Source Software}
}

You can also consider citing this paper as follows:

@techreport{SOLA-18-Lie,
    Address = {Barcelona},
    Author = {Joan Sol\`a and Jeremie Deray and Dinesh Atchuthan},
    Institution = {{Institut de Rob\`otica i Inform\`atica Industrial}},
    Number = {IRI-TR-18-01},
    Title = {A micro {L}ie theory for state estimation in robotics},
    Howpublished="\url{http://arxiv.org/abs/1812.01537}",
    Year = {2018}
}

Notice that this reference is the one referred to throughout the code documentation. Since this is a versioned work, please refer to version 4, available here, of the paper when cross-referencing with the manif documentation. This will give the appropriate equation numbers.

Lie group cheat sheets

In a rush? Here is your Lie group theory take away: Lie group cheat sheet.

They use manif

You may find here a list of work and projects using manif.
Your project is not listed? Let us know about it!

Contributing

manif is developed according to Vincent Driessen's Gitflow Workflow. This means,

the master branch is for releases only.
development is done on feature branches.
finished features are integrated via PullRequests into the branch devel.

For a PullRequest to get merged into devel, it must pass

Review by one of the maintainers.
- Are the changes introduced in scope of manif?
- Is the documentation updated?
- Are enough reasonable tests added?
- Will these changes break the API?
- Do the new changes follow the current style of naming?
Compile / Test / Run on all target environments.

prashanthr05 / manif