Author: Philipp Allgeuer
Version: 1.2.0
Date: 14/08/14
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.
This library is implemented as a collection of platform-independent C++ source files. To get started (if you haven't done so already) download the latest ZIP of the library from the SourceForge page, and extract it to the desired location on your computer.
There are three ways of using the library:
1) Directly include the source files in your project, and build them with the rest of your project.
2) Build a static library (e.g. *.a
or *.lib
) of the source code and link your project to it.
3) Build a dynamic library (e.g. *.so
or *.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.0
, 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. This can be found in the library ZIP archive under:
Attitude Estimator vX.X.X/doc/Attitude Estimator.html
Or equivalently:
Attitude Estimator vX.X.X/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 contact the author at the email address given in the Bugs and Improvements section.
I welcome all feedback, suggestions and bug reports. 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!
Email: pallgeuer[at]ais.uni-bonn.de
The following screenshots show the Attitude Estimator in use in various real and simulated state estimation scenarios: