# wavelab / wave_geometry

Manifold geometry with fast automatic derivatives and coordinate frame semantics checking
C++ CMake Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
3rd-party/Tick
benchmarks
cmake
docs
include/wave/geometry
scripts
test
.clang-format
.gitignore
.travis.yml
CHANGELOG.md
CMakeLists.txt

# A manifold geometry library for robotics

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, WorldFrame> 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 5, not showing colours):

``````In file included from /.../example.cpp:1:
In file included from /.../wave/geometry/geometry.hpp:45:
/.../wave/geometry/src/geometry/op/Compose.hpp:22:5: error: static_assert failed "Adjacent frames do not match"
static_assert(std::is_same<RightFrameOf<Lhs>, LeftFrameOf<Rhs>>(),
^             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/.../example.cpp:31:60: note: in instantiation of template class 'wave::Compose<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, WorldFrame> >' 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.

You can’t perform that action at this time.