Ekumen-OS/beluga

Beluga – A C++17 Monte Carlo Localization Library

What it is – Beluga is an extensible C++17 library that implements the Monte Carlo Localization (MCL) family of particle‑filter algorithms. It is written to be ROS‑agnostic, with optional ROS bindings, and targets robots that need reliable pose estimation (e.g., TurtleBot 2, Andino). The codebase is heavily tested and includes benchmarking tools.

Key components

Package	Role
beluga	Core, ROS‑agnostic library – provides the generic particle‑filter framework and utilities.
beluga_ros	Thin ROS wrapper – lets ROS nodes use the core library (message conversion, parameter handling).
beluga_amcl	Ready‑to‑run ROS node/component that mirrors the interface of the popular nav2_amcl/amcl packages, making migration easy.
beluga_example	Sample launch files that demonstrate how to start a Beluga‑based AMCL node on a robot.
beluga_benchmark	Scripts for performance profiling and for comparing Beluga against other MCL implementations.
beluga_system_tests	Integration‑level tests that run the whole stack on simulated or real hardware.
beluga_vdb	Optional extension that plugs OpenVDB into the library, enabling 3‑D voxel‑based localization.

Why it matters

• Modular design – algorithms are built from orthogonal components (motion model, sensor model, resampling, etc.), so you can swap parts without rewriting the whole filter.
• Test‑driven development – CI pipelines (Colcon, Bazel) and code‑coverage badges show a strong focus on regression safety.
• Benchmarks out of the box – the beluga_benchmark package lets developers quantify latency, memory use, and accuracy for different configurations.
• ROS compatibility – while the core is independent of ROS, the beluga_ros and beluga_amcl packages provide drop‑in replacements for existing ROS navigation stacks.
• 3‑D support via OpenVDB – the beluga_vdb extension makes it feasible to run particle filters in volumetric maps, useful for drones or legged robots.

Typical workflow

1. Add the library to your CMake workspace (supports both Colcon and Bazel builds).
2. Configure a particle filter by selecting motion and sensor models from the core package.
3. Wrap it with ROS using beluga_ros if you need topics/services, or run the standalone filter in a custom C++ program.
4. Launch the beluga_amcl node (or your own node) with a YAML file that mirrors the nav2_amcl parameter format.
5. Validate using the provided system tests or the benchmark suite.

Getting started – The README points to the online documentation site (https://ekumen-os.github.io/beluga) for detailed build instructions, API reference, and example launch files. Contributions are welcomed via the CONTRIBUTING.md guide.

---

Beluga is a genuine, production‑grade robotics library focused on Monte Carlo Localization, not a generic AI/LLM project.