๐ 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:
- MINOR version increases when API compatibility is broken;
- PATCH version increases when functionality are added in a backwards-compatible manner;
- Devel branch version adds 100 to PATCH version number, i.e. 0.MINOR.(PATCH+100).
- 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.