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.
- SE_2(3): extended pose (rotation, translation and velocity) in 3D space, introduced (to the best of knowledge) in this paper. NOTE: The implementation here differs slightly from the developments in the paper.
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
- 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
___-
Eigen 3 :
-
Linux ( Ubuntu and similar )
apt-get install libeigen3-dev
-
OS X
brew install eigen
-
-
lt::optional : included in the
external
folder
$ git clone https://github.com/artivis/manif.git
$ cd manif && mkdir build && cd build
$ cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON ..
$ make
$ make install
$ git clone https://github.com/artivis/manif.git
$ catkin build manif --cmake-args -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON
$ cd manif
$ doxygen .doxygen.txt
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})
Above, 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 .
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:
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);
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)
andimag = sin(theta)
values. - SO(3), SE(3) and SE_2(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
- SE_2(3): size 10
For more information, please refer to the Ceres wiki page.
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.
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.se_2_3_localization.cpp
: A strap down IMU model based 3D robot localization, with measurements of fixed landmarks, using SE_2_3 as extended robot poses (translation, rotation and linear velocity).
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.
In a rush? Here is your Lie group theory take away: Lie group cheat sheet.
You may find here a list of work and projects using manif.
Your project is not listed? Let us know about it!
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.