Beluga

Beluga is a ROS-agnostic C++17 library that provides implementations for Monte Carlo-based localization algorithms widely used in robotics applications. Its modularity allows users to compose solutions from reusable modules and to combine them with new ones to configure the MCL algorithm that best suits their needs.

Features

The current set of features includes:

• Particle containers:
  • Support for Array-of-Structures and Structure-of-Arrays tuple containers
• Composable range adaptor views, actions, and algorithms:
  • Multivariate normal distributions in SE(2) and SE(3) space
  • Multivariate uniform distributions in SE(2) compatible with occupancy grids
  • Multinomial resampling from a particle range
  • Adaptive KLD resampling
  • Selective resampling, on-motion resampling, and interval resampling policies
  • Support for sequential and parallel execution policies
  • Weighted mean and covariance statistics for pose estimation
• Sensor models:
  • Likelihood field model
  • Beam model
  • Landmark-based models (using landmark position or bearing)
• Motion models:
  • Differential drive model
  • Omnidirectional model

Documentation

Auto-generated Doxygen documentation can be found in https://ekumen-os.github.io/beluga/.

Dependencies

Beluga is built on top of the following open source libraries:

• Eigen: A well-known C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms.
• Sophus: A C++ implementation of Lie groups using Eigen.
• Range: The basis library for C++20’s std::ranges.
• libciabatta: A composable mixin support library.

Changelog for package beluga

2.0.2 (2024-06-18)

• Use [no-gnu-zero-variadic-macro-arguments]{.title-ref} only with [clang-tidy]{.title-ref} (#391)
• Add 3D NDT sensor model and tests. (#400)
• Expand grid concepts to n dimensions (#396)
• Add cast from [hsize_t]{.title-ref} to [size_t]{.title-ref} (#392)
• Contributors: Nahuel Espinosa, Ramiro Serra

2.0.1 (2024-05-24)

• Support 32-bit hashes (#386)
• Rewrite [make_from_state]{.title-ref} as a function object (#384)
• Contributors: Alon Druck, Nahuel Espinosa

2.0.0 (2024-05-21)

• Please clang-tidy on Ubuntu Noble (#379)
• Add ROS 2 Jazzy to CI/CD and dev workflows (#378)
• Restore particle cloud visualization using markers (#377)
• Ensure we exercise random state generation every time (#371)
• Add example for NDT sensor model in beluga_example (#360)
• Unify Beluga documentation (#346)
• Transition Beluga to Noble with Rolling (#349)
• Provide sensible defaults for LikelihoodFieldModelParam (#344)
• Add a core AMCL pipeline (#343)
• Add NDT sensor model (#338)
• Add sparse value grid implementation (#336)
• Add HDF5 dependency to beluga core (#335)
• Deprecate all the (mixin) things (#330)
• Add death tests and build in debug mode (#323)
• Remove (unused) cluster customization point object (#331)
• Fix landmark models probability aggregation formula (#329)
• Add AMCL implementation for ROS (#327)
• Migrate sensor models to functional form (#325)
• Use AlignedBox3d as LandmarkMapBoundaries (#326)
• Relocate [make_random_state()]{.title-ref} method (#324)
• Add uniform distribution with bounding regions (#322)
• Migrate motion models to functional form (#321)
• Add generic circular array container (#320)
• Add uniform free-space grid distribution (#319)
• Make test matchers and printers available to users (#300)
• Extend multivariate distribution to support different result types (#298)
• Add normalize action (#297)
• Extend sample view to sample from random distributions (#296)
• Add recovery probability estimator (#295)
• Add declarative policies (#294)
• Add ESS algorithm (#290)
• Motion and sensor models are not mixins (#291)
• Add propagate and reweight actions (#289)
• Fix sample view (#288)
• Add assign action (#287)
• Add zip view and fix tuple vector traits (#286)
• Add support for tuple vector assignment and conversion (#285)
• Integrate views with mixins (#284)
• Improve take_while_kld implementation (#282)
• Add sample view (#281)
• Minor fixes to forward_like test (#283)
• What is a particle? (#280)
• Add random intersperse view (#278)
• Add take_while_kld view (#277)
• Improve spatial_hash function to avoid spatial periodicity in the hash function (#273)
• Rework generic data access (#272)
• Generalize planar laser scan support (#271)
• Add new discrete landmark and bearing sensor models to the beluga library (#268)
• Fix differential drive motion model (#267)
• Use double buffering in particle storage (#266)
• Add cmake-format to pre-commit hooks (#243)
• Refactor resampling policies into filter update control (#233)
• Avoid building docs by default (#234)
• List documentation deps in package.xml (#228)
• Add ROS Noetic CI infrastructure (#217)
• Support [beluga]{.title-ref} builds on Ubuntu Focal (#209)
• Extend raycast microbenchmarks (#201)
• Optimize likelihood field model runtime performance (#199)
• Install doxygen-awesome (#204)
• Optimize beam sensor model runtime performance (#200)
• Re-organize infrastructure scripts (#197)
• Add support for map updates in laser localization filters (#189)
• Remove shared_mutexes to address concurrency performance (#195)
• Add missing documentation links (#192)
• Rework occupancy grids (#188)
• Improve documentation and guidelines (#186)
• Fix unbounded weight growth (#181)
• Add service to reinitialize global localization (#157)
• Update pre-commit hooks (#178)
• Update URLs after transfer (#174)
• Update license year to 2023 (#175)
• Add beam sensor model (#160)
• Add WeightedStateEstimator2d mixin (#161)
• Rename [importance_sample]{.title-ref} method to [reweight]{.title-ref} (#158)
• Integrate sensor probabilities across resampling iterations (#149)
• Add support for per-axis resolution when clustering (#146)
• Run clang-tidy in CI instead of using pre-commit for it (#147)
• Rename [mixin::make_unique]{.title-ref} to [make_mixin]{.title-ref} (#152)
• Add strong typedef for particle properties (#144)
• Make tuple vector work seamlessly with pairs (#140)
• Use [clang_tidy]{.title-ref} instead of [ament_clang_tidy]{.title-ref} (#135)
• Select mixin components at runtime (#126)
• Migrate beluga from ament_cmake to cmake (#133)
• Add omnidirectional motion model (#120)
• Add new resampling policies (#119)
• Update list of maintainers (#130)
• Refactor estimation mixin out of the particle filter (#104)
• Make execution policy configurable (#100)
• Refactor laser_callback method (#89)
• Enable warning as errors when building docs (#75)
• Add documentation build step to CI (#74)
• Move spatial_hash.hpp to algorithm (#73)
• Complete beluga documentation (#66)
• Add documentation for motion and sensor models (#61)
• Complete documentation for beluga/algorithm header files (#59)
• Add reinitialize method to the particle filter (#51)
• Add multivariate normal distribution class (#50)
• Add doxygen docs for particle_filter.hpp (#47)
• Parallelize motion model update (#34)
• Integrate differential drive motion model (#33)
• Parallelize sensor model update (#32)
• Add pose estimation publisher (#30)
• Update header files in the beluga package (#29)
• Add differential drive motion model (#28)
• Decouple ROS message types from the observation model (#27)
• Add likelihood field pre-computation (#24)
• Change ROS distro to [humble]{.title-ref} (#22)
• Add tests for particle filter variants (and fix bugs) (#20)
• Enable [-Wpedantic]{.title-ref} and [-Wconversion]{.title-ref} (#16)
• Add license file and copyright notice (#15)
• The great layout change (#14)
• Implement particle filter variants (#12)
• Add sampling utilities and benchmarks (#9)
• Add [spatial_hash]{.title-ref} implementation (#8)
• Add [tuple_vector]{.title-ref}, [particle_traits]{.title-ref} and [views::all]{.title-ref} interface (#6)
• Install conan and add [range-v3]{.title-ref} as dependency (#5)
• Setup basic infrastructure and CI pipeline (#1)
• Contributors: Gerardo Puga, Guillermo Manzato, Ivan Santiago Paunovic, Michel Hidalgo, Nahuel Espinosa, Olmer Garcia-Bedoya, Ramiro Serra