Awesome Open Source
Awesome Open Source

A manifold geometry library for robotics

Build Status Documentation

wave_geometry is a header-only C++17 library for working with rotations and transformations in robotics and computer vision applications. It differs from similar libraries by offering:

  • Fast operations using expression templates
  • Fast on-manifold automatic differentiation
  • Compile-time coordinate frame semantics checking

Source code is available under the MIT License. Documentation is available online.

If you use this library, please cite the following paper in your work:

Koppel, Leonid and Waslander, Steven L., "Manifold Geometry with Fast Automatic Derivatives and Coordinate Frame Semantics Checking in C++." In 15th Conference on Computer and Robot Vision (CRV), Toronto, ON, 2018.

@inproceedings{koppel2018manifold,
  title={Manifold Geometry with Fast Automatic Derivatives and Coordinate Frame Semantics Checking in {C++}},
  author={Koppel, Leonid and Waslander, Steven L.},
  booktitle={15th Conference on Computer and Robot Vision (CRV)},
  year={2018},
}

Features

Manifold operations Docs

wave_geometry includes operations on SO(3), the Lie group of 3D rotations, and SE(3), the group of 3D rigid transformations.

Automatic differentiation Docs

Any expression can be differentiated with respect to its variables.

wave::RotationMd R = wave::RotationMd::Random();
wave::Translationd p1 = wave::Translationd::Random();
wave::Translationd p2 = R * p1;

auto [p2, J_p2_wrt_R, J_p2_wrt_p1] = (R * p1).evalWithJacobians(R, p1);

wave_geometry computes local Jacobians, which are independent of the choice of parametrization for R (e.g., rotation matrix or quaternion), and are useful for on-manifold optimization.

Coordinate frame semantics Docs

Representing poses without confusion is notoriously difficult, and mistakes such as using a quantity expressed in the wrong coordinate frame have bogged down many a robotics project. wave_geometry provides built-in coordinate frame semantics checking.

Coordinate frame semantics checking can detect invalid operations at compile time. Consider this example:

struct BodyFrame;
struct CameraFrame;
struct WorldFrame;

wave::RotationMFd<WorldFrame, BodyFrame> r1;
wave::RotationMFd<CameraFrame, BodyFrame> r2;

// Let's get the rotation between World and Camera (maybe)
wave::RotationMFd<WorldFrame, CameraFrame> result = r1 * r2;

This code has a mistake, but is saved by semantics checking. When we try to compile it, we get the following error message (from clang 7, not showing colours):

In file included from /.../example.cpp:1:
In file included from /.../wave/geometry/geometry.hpp:54:
/.../wave/geometry/src/geometry/op/Compose.hpp:22:5: error: static_assert failed due to requirement 'std::is_same<RightFrameOf<const Framed<MatrixRotation<Matrix<double, 3, 3, 0, 3, 3> >, WorldFrame, BodyFrame> &>, LeftFrameOf<const Framed<MatrixRotation<Matrix<double, 3, 3, 0, 3, 3> >, CameraFrame, BodyFrame> &> >()' "Adjacent frames do not match"
    static_assert(std::is_same<RightFrameOf<Lhs>, LeftFrameOf<Rhs>>(),
    ^             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/.../wave/geometry/src/geometry/base/TransformBase.hpp:167:12: note: in instantiation of template class 'wave::Compose<const wave::Framed<wave::MatrixRotation<Eigen::Matrix<double, 3, 3, 0, 3, 3> >, WorldFrame, BodyFrame> &, const wave::Framed<wave::MatrixRotation<Eigen::Matrix<double, 3, 3, 0, 3, 3> >, CameraFrame, BodyFrame> &>' requested here
    return Compose<internal::cr_arg_t<L>, internal::cr_arg_t<R>>{lhs.derived(),
           ^
/.../example.cpp:12:60: note: in instantiation of function template specialization 'wave::operator*<wave::Framed<wave::MatrixRotation<Eigen::Matrix<double, 3, 3, 0, 3, 3> >, WorldFrame, BodyFrame>, wave::Framed<wave::MatrixRotation<Eigen::Matrix<double, 3, 3, 0, 3, 3> >, CameraFrame, BodyFrame> >' requested here
    wave::RotationMFd<WorldFrame, CameraFrame> result = r1 * r2;
                                                           ^

The corrected code below compiles successfully:

// Let's get the rotation between World and Camera (fixed)  
wave::RotationMFd<WorldFrame, CameraFrame> result = r1 * inverse(r2);

Installation

wave_geometry is a header-only library, meaning no prior compilation is required to use it in your project. It requires Eigen 3.3.2 or above, Boost 1.58 or above (header-only libraries), and a C++17 compiler.

wave_geometry can be installed with CMake: see installation instructions.

The library is in the initial development stage and the API may change at any time. See CHANGELOG.md for recent changes.


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
c-plus-plus (18,756
computer-vision (1,275
robotics (340
math (231
geometry (115
kinematics (21