📚 Bayes Filters Library

A flexible, modern, cross-platform C++ recursive Bayesian estimation library.

Overview

• ⚠️ About versioning
• 📖 Background
• 📦Installing with conda
• 🎛 Dependencies
• 🔨 Build and test the library
• 🔬 Test the library
• 🔗 Link the library
• 📝 API documentation and example code
• 📑 Reference

⚠️ About versioning

The project is undergoing heavy development: APIs will be subject to changes quite often. To be able to understand API compatibility during development, the project will follow SemVer specs.

In particular, the library will have zero major version, i.e. 0.MINOR.PATCH, as specified by SemVer spec. 4 and the project will comply with the following rules:

1. MINOR version increases when API compatibility is broken;
2. PATCH version increases when functionality are added in a backwards-compatible manner;
3. Devel branch version adds 100 to PATCH version number, i.e. 0.MINOR.(PATCH+100).
4. Additional labels for pre-release and build metadata are available as extensions to the 0.MINOR.PATCH format.

📖 Background

The main interest of the present library is estimation, which refers to inferring the values of a set of unknown variables from information provided by a set of noisy measurements whose values depend on such unknown variables. Estimation theory dates back to the work of Gauss on determining the orbit of celestial bodies from their observations. These studies led to the technique known as Least Squares. Over centuries, many other techniques have been proposed in the field of estimation theory, e.g., the Maximum Likelihood, the Maximum a Posteriori and the Minimum Mean Square Error estimation. The Bayesian approach models the quantities to be estimated as random variables characterized by Probability Density Functions (PDFs), and provides an improved estimation of such quantities by conditioning the PDFs on the available noisy measurements. Recursive Bayesian estimation (or Bayesian filtering/filters) are a renowned and well-established probabilistic approach for recursively propagating, in a principled way via a two-step procedure, a PDF of a given time-dependent variable of interest. Popular Bayes filters are the Kalman [1]-[4] and particle filters [5]-[7].

The aim of this library is to provide interfaces and implementations for new and existing recursive Bayesian filters!

📦 Installing with conda

You can install the binaries with conda. All the dependencies will be automatically installed in the conda environment.

conda install -c conda-forge libbayes-filters-lib

Building from sources

If you want to build the project from sources you need to follow the following passages

🎛 Dependencies

Bayes Filters Library depends on

• Eigen3 - version >= 3.3 (no beta)

🔨 Build and test the library

Use the following commands to build, install and link the library.

Build

With make facilities:

$ git clone https://github.com/robotology/bayes-filters-lib
$ cd bayes-filters-lib
$ mkdir build && cd build
$ cmake ..
$ make
$ [sudo] make install

With ninja generator:

$ git clone https://github.com/robotology/bayes-filters-lib
$ cd bayes-filters-lib
$ mkdir build && cd build
$ cmake -GNinja ..
$ ninja
$ [sudo] ninja install

You can also generate IDE project (e.g. Visual Studio and Xcode) to use their build tool facilities.

🔬 Test the library

We have designed some test to run with CMake to see whether everything run smoothly or not. Simply use

$ ctest [-VV]

to run all the tests.

Tests are also a nice starting points to learn how to use the library and how to implement your own filters! Just have a look at them!

🔗 Link the library

Once the library is installed, you can link it using CMake with as little effort as writing the following line of code in your project CMakeLists.txt:

...
find_package(BayesFilters 0.MINOR.PATCH EXACT REQUIRED)
...
target_link_libraries(<target> BayesFilters::BayesFilters)
...

📝 API documentation and example code

Doxygen-generated documentation is available here.

📑 Reference

[1] R. E. Kalman, “A new approach to linear filtering and prediction problems,” Trans. Trans. ASME - Journal of Basic Engineering, vol. 82 (Series D), no. 1, pp. 35– 45, 1960.
[2] R. E. Kalman and R. S. Bucy, “New results in linear filtering and prediction theory,” Trans. ASME - Journal of Basic Engineering, vol. 83 (Series D), no. 1, pp. 95–108, 1961.
[3] L. A. McGee, S. F. Schmidt and G. L. Smith, “Applications of statistical filter theory to the optimal estimation of position and velocity on board a circumlunar vehicle”, NASA Technical Report R-135, Tech. Rep., 1962.
[4] S. J. Julier and J. K. Uhlmann, "Unscented filtering and nonlinear estimation", Proceedings of the IEEE, vol. 92, num. 3, pp. 401-422, 2004.
[5] A. Doucet, N. De Freitas, N. Gordon, Sequential Monte Carlo methods in practice. Springer-Verlag, 2001. [6] M. S. Arulampalam, S. Maskell, N. Gordon and T. Clapp, "A tutorial on particle filters for online nonlinear/non-Gaussian Bayesian tracking." IEEE Transactions on signal processing, vol. 50, num. 2, pp. 174-188, 2002.
[7] N. Gordon, B. Ristic and S. Arulampalam. Beyond the kalman filter: Particle filters for tracking applications. Artech House, Boston, London, 2004.

---