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.

It provides a base structure which is implemented using CRTP for the groups SO(2), SO(3), SE(2) and SE(3):

• SO(2): rotations in the plane.
• SE(2): righd motion (rotation and translation) in the plane.
• SO(3): rotations in 3D space.
• SE(3): righd motion (rotation and translation) in 3D space.

Other Lie groups can and will be added, and 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 average robotician who is interested in designing rigorous and elegant state estimation algorithms.

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.

manif 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.

Details

• Maintainer status: maintained
• Maintainer: Jeremie Deray [email protected]
• Authors:
  • Jeremie Deray [email protected]
  • Joan Sola [email protected]
• License: MIT
• Bug / feature tracker: github.com/artivis/manif/issues
• Source: github.com/artivis/manif.git (branch: devel)

---

Installation • Features • Documentation • Tutorials • Publications • Contributing

---

Quick Start

Dependencies

• Eigen 3 : apt-get install libeigen3-dev
• lt::optional : included in the external folder

Installation

$ git clone https://github.com/artivis/manif.git
$ cd manif && mkdir build && cd build
$ cmake ..
$ make

To build also examples/tests

$ cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON ..
$ make

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 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 ${manif_INCLUDE_DIRS})

Features

Available Operations

Operation		Code
	Base Operation
Inverse		X.inverse()
Composition		X * Y X.compose(Y)
Hat		w.hat()
Act on vector		X.act(v)
Retract to group element		w.exp()
Lift to tangent space		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, 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:

 

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, SO2::_, 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 wrt the underlying representation vector of the group element (e.g. wrt 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, 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.

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.

Publications

If you use this work, please 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.

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.