artivis/manif: a header-only C++11 Lie theory library for state estimation

What manif is for, and who actually needs it

manif is a Lie theory library for state estimation targeted at robotics applications, according to its README. That sentence is narrower than it sounds. Lie groups show up in robotics because poses, rotations and velocities do not live in a vector space: you cannot average two rotation matrices by adding them and dividing by two, and a naive Kalman filter that treats a rotation as three independent numbers will drift or break near singularities. manif gives you the group operations (inverse, composition, exponential and logarithm maps, adjoints) plus the manifold plus and minus operators that let you treat a curved space as locally flat. The README states that it provides analytic computation of Jacobians for all the listed operations, which matters because numerical Jacobians are slow and error-prone in exactly the filters where you need them most.

The target reader is a robotics or computer vision engineer writing an extended Kalman filter, an invariant EKF, an unscented filter or a smoothing and mapping solver. The examples directory confirms this: se2_localization.cpp, se3_localization_iekf.cpp, se3_sam.cpp, se3_sam_selfcalib.cpp, se_2_3_localization.cpp and a bundle_sam.cpp for composite manifolds. If you are writing a web app that needs quaternion math, manif is heavier than you need. If you are writing a factor graph with IMU preintegration or a pose graph, it is aimed at you.

The Lie groups and the tangent space ordering that will bite you

The library covers Rn, SO(2), SE(2), SO(3), SE(3), SE_2(3) (extended pose: rotation, translation and velocity), SGal(3) (the Special Galilean group: rotation, translation, velocity and time) and Bundle<>, which lets you treat a manifold bundle as a single Lie group, referred to as a composite manifold in the reference paper.

The design decision worth understanding before you write any code is that manif favors Cartesian representations of the tangent spaces, so tangent elements are plain vectors in R^n. The ordering of the elements in those vectors determines the layout of every Jacobian and covariance matrix you build on top. The README publishes a table for this, and it flags its own inconsistency: the tangent element order in SE_2(3) is position, orientation, velocity, while SGal(3) is position, velocity, orientation, time. The README calls this an unfortunate order mismatch. That is an honest admission, and it is the kind of detail that silently corrupts a covariance matrix if you assume the two groups follow the same convention. If you use both groups in one system, write the block indices down before you write the code.

Installing manif and running a first SE(3) operation

manif is header-only for C++. The README points to quick start guides for C++ (docs/pages/cpp/Quick-start.md) and Python (docs/pages/python/Quick-start.md); those files are where the project says to get started, and the README does not inline a full install procedure for the C++ side. The Python side is built through pyproject.toml, which declares the build requirements. If you want the Python wrappers, the declared build system needs CMake, ninja, pybind11 and cmake-build-extension:

pip install .

That invokes setup.py, which configures the CMake project with -DBUILD_PYTHON_BINDINGS:BOOL=ON and -DCALL_FROM_SETUP_PY:BOOL=ON, and installs the extension under the prefix manifpy. The pyproject.toml pins setuptools>=45 and cmake>=3.18.2, so an older CMake will fail at configure time rather than at compile time.

For C++, the repository ships a top-level CMakeLists.txt and a cmake/ directory, so the expected route is add_subdirectory or an installed package, with include/ on the include path. Once that is done, the operations table maps directly onto method calls. The README gives the equivalent spellings for composition and for the manifold right plus:

X * Y
X.compose(Y)
X + w
X.plus(w)
X.rplus(w)

Those forms come straight from the operations table, so the operator overloads are a convenience layer over the named methods. If you prefer explicitness in a codebase that mixes group elements and tangent vectors, use .plus() and .compose() and skip the operators.

Where manif is the wrong tool

The version number is the first limitation, and it is not cosmetic. The most recent release is 0.0.5, published on 2024-08-11. Before that, the previous release was 0.0.2 on 2020-02-03. A library that has shipped three releases in six years and is still on a 0.0.x line is telling you that the API is not a stability contract. The README itself says other Lie groups can and will be added. If your project needs a dependency whose surface will not move under you, pin a commit hash and read the diff before you bump it.

Second, manif is not a state estimation framework. It has no filter, no optimizer, no factor graph and no sensor models. The examples show localization and smoothing, but the estimation logic lives in the example files, not in the library. If you want a battery-included SLAM or optimization stack, manif is a component inside it, not a replacement for it.

Third, the mathematical prerequisite is real. The README recommends every user read a 17-page paper before starting, and offers a video lecture and a cheat sheet for those in a hurry. That is an unusual amount of required reading for a header-only library, and it reflects the subject rather than the documentation. If nobody on your team is comfortable with the exponential map and adjoints, adding manif will produce code that compiles and is wrong.

How manif compares with Sophus

The obvious alternative in this space is Sophus, the other long-standing C++ Lie group library used in robotics and computer vision. The difference in approach is mostly about scope and packaging. Sophus is also header-only and covers the classic groups (SO(2), SO(3), SE(2), SE(3)) plus some additional types, and it has been widely used as a dependency of larger stacks. manif goes further into the state estimation corner: SE_2(3) for extended pose with velocity, SGal(3) with time, and Bundle<> for treating a composite of groups as one manifold. Those three are the reason to pick manif over Sophus if you are working on inertial navigation or on manifolds that mix pose and velocity.

The other difference is the tangent space convention. manif explicitly documents its Cartesian tangent ordering and the Jacobians that follow from it, and it publishes the table of what that ordering is per group. If your covariance matrices are already laid out for another library's convention, moving to manif means rewriting the index arithmetic, not just the calls. That is a one-time cost, but it is a real one, and it is the kind of thing that is easy to underestimate when the API looks like a drop-in.

Maintenance, licence and what an upgrade costs

The repository is not archived. The last push to the devel branch was on 2026-08-05, which is recent enough that the project is being touched, but the release history is the more useful signal for planning: 0.0.1 on 2020-01-24, 0.0.2 on 2020-02-03, and 0.0.5 on 2024-08-11. The gap between 0.0.2 and 0.0.5 is over four years, and the version jump skips 0.0.3 and 0.0.4 in the release list. For a consumer, that means upgrades are infrequent but potentially large when they come, and there is no long-term support branch to fall back on.

The licence is MIT, declared in the LICENSE file and in the README. MIT is permissive: it allows use in closed-source products provided the copyright notice and permission notice are retained. That is a summary of what the licence text is, not legal advice; if your organisation has a policy on permissive licences, run it past whoever owns that policy. The practical implication is that manif will not force you to open your own code, which is why it is usable inside commercial robotics products.

Upgrade cost is mostly about the API surface you touch. If you use only composition, inverse, exp and log, a version bump is likely mechanical. If you depend on Jacobian layouts or covariance block ordering, verify those against the tangent space table after any bump, because that table is the contract and it has changed shape across groups before.

Editorial conclusion

Adopt manif if you are doing robotics state estimation and want Lie group operations with analytic Jacobians in a header-only C++11 package, or in Python through the wrappers. Do not adopt it if you need a stable versioned API: the latest release is 0.0.5, so pin a commit rather than a tag. Before committing, read the 17-page Lie theory paper the README recommends, confirm the tangent space ordering for your group in the table (SE_2(3) and SGal(3) disagree), and check that your compiler and CMake version satisfy the pyproject.toml build requirements if you plan to build the Python bindings.

Frequently asked questions

Official sources

1. artivis/manif on GitHub
2. License: MIT
3. Project website
4. README
5. Releases