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

There has been a remarkable effort in the last years in the robotics community to formulate estimation problems properly. This is motivated by an increasing demand for precision, consistency and stability of the solutions. Indeed, a proper modeling of the states and measurements, the functions relating them, and their uncertainties, is crucial to achieve these goals. This has led to problem formulations involving what has been known as ‘manifolds’, which in this context are no less than the smooth topologic surfaces of the Lie groups where the state representations evolve.

manif was designed for easy integration to larger project. 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.

• 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

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

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

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

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

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

Above, represent group elements, represents an element in the Lie algebra of the Lie group, or w represents the same element 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.

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);

While the manif package differentiates Jacobians with respect to a local perturbation on the tangent space, many non-linear solvers (e.g. Ceres) expect them 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 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.

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.

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

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

• Review by one of the maintainers.
  • Are the changes introduces in scope of the 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.