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.

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 • 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	$\mathbf \Phi^{-1}$	`X.inverse()`
Composition	$\mathbf \mathcal{X} \circ \mathbf \mathcal{Y}$	`X * Y` `X.compose(Y)`
Hat		`w.hat()`
Retract to group element	$\exp(\mathbf \varphi^{^})$	`w.retract()`
Act on vector		`X.act(v)`
Lift to tangent space	$\log(\mathbf \Phi)$	`X.lift()`
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, $\mathcal{Y}$ 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 .

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.

$\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.,

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

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

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

  SO2::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

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.

Documentation

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

Type in the terminal

cd [manif]
doxygen .doxygen.txt

to obtain the code documentation. 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.
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 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.

deliangye/manif