Author: Philipp Allgeuer
Version: 1.2.1
Date: 18/03/2022
Attitude Estimator is a generic platform-independent C++ library that implements an IMU sensor fusion algorithm. Up to 3-axis gyroscope, accelerometer and magnetometer data can be processed into a full 3D quaternion orientation estimate, with the use of a nonlinear Passive Complementary Filter. The library is targeted at robotic applications, but is by no means limited to this. Features of the estimator include gyro bias estimation, transient quick learning, multiple estimation algorithms, tuneable estimator parameters, and near-global stability backed by theoretical analysis.
Great emphasis has been placed on having a very efficient, yet totally numerically and algorithmically robust implementation of the filter. The code size has also been kept to a minimum, and has been extremely well-commented. The programmatic interface has also been made as easy as possible. Please refer to the extensive documentation of the library for more information on its capabilities and usage caveats.
Attitude Estimator was developed as part of the NimbRo-OP project at the University of Bonn.
The library has been unofficially ported to Go, thanks to knei-knurow, and is available here.
- Small and highly efficient performance-oriented cross-platform C++ library
- Implements fusion of IMU sensor data (3-axis gyroscope, 3-axis accelerometer, 3-axis magnetometer), forming a reliable 3D attitude (orientation) estimate in the form of a quaternion
- Able to dynamically deal with missing or non-present sensor data, even if there is theoretically no longer enough information to reconstruct a full 3D attitude
- Gyro bias estimation, tuneable algorithm parameters, interface to provide state/system priors if desired
- Multiple fallback estimation algorithms to choose from, including the ZYX yaw method, fused yaw method, and absolute fused yaw method
- Transient quick learning phase for fast initial settling of the attitude estimate
- Guaranteed numerical and algorithmic stability, with much effort having gone into ensuring the complete robustness of the implementation
- Independent code with no external dependencies other than certain maths functions of the C++ Standard Library
- Documented using the Doxygen documentation generation tool, including a code sample and a discussion of all usage caveats
- Extremely well-commented library source code detailing and discussing the implementation details
- Tried and tested by the author in simulation and on various robotic platforms
This library is implemented as a collection of platform-independent C++ source
files. To get started just clone the attitude_estimator repository.
There are three ways of using the library:
-
Directly include the source files in your project, and build them with the rest of your project.
-
Build a static library (e.g.
*.aor*.lib) of the source code and link your project to it. -
Build a dynamic library (e.g.
*.soor*.dll) of the source code and link your project to it.
Due to the small and efficient nature of the library, one of the first two options is recommended. Very minimal benefit is expected from building a dynamic library.
Note that as at release v1.2.1, the required (non-test) source files are
simply attitude_estimator.h and attitude_estimator.cpp.
A sample makefile for building the static and dynamic libraries using gcc is
included in the release. The makefile also demonstrates how the
test_attitude_estimator unit test can be built. As mentioned in the makefile
however, the Attitude Estimator could equivalently be built using any other
compiler, such as for example MSVC.
The library does not require C++11, and has no external dependencies other than
the C++ Standard Library, of which only cmath is required. More precisely, the
only standard library functions that are required are abs, sqrt, asin and
atan2.
The first place to look for help and guidance when trying to use the Attitude
Estimator is the Doxygen documentation. It can be generated by running a shell
script in doc/generate_doc.sh. The generated documentation can then be found
in:
doc/Attitude Estimator.html
Or equivalently:
doc/out/html/index.html
The Doxygen documentation provides a complete explanation of the entire library, including all caveats and details, and includes a code sample to make the task of integrating the library into user code as simple as possible. Complete documentation of all functions, classes and namespaces of the library is also included. As such, the Doxygen documentation is intended to be the primary help resource when working with the library.
If anything is not adequately explained in the Doxygen documentation, or more
details as to the inner workings of the library are required, the next place to
look would be in the library source code. The code is extremely well-commented
and should thus be fairly self-explanatory. A good starting point is
attitude_estimator.h.
If neither the Doxygen documentation nor a look into the source code can resolve your issues for whatever reason, you can open a GitHub issue.
I welcome all feedback, suggestions and bug reports (by opening a GitHub issue). If you improve or fix anything about the library then I encourage you to let me know so that the library can be improved for everyone!