diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index f530e4f97..327192b11 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,36 +1,30 @@ --- name: Bug Report -about: Report a bug in beluga. +about: Create a report to help us improve. title: '' labels: bug --- -## Required info -- Version or commit hash: - - - -## Steps to reproduce issue - - -## Expected behavior - - -## Actual behavior - - -## Additional information - +### Bug description +_A clear and concise description of what the bug is._ + + +**Platform (please complete the following information):** + - OS: [e.g. Ubuntu Focal] + - `Beluga` version: [e.g. tag, commit sha] + +### How to reproduce +_List steps to reproduce the issue:_ +1. ... + +_Code snippets or minimal examples are always helpful, if not necessary._ + +**Expected behavior** +_A clear and concise description of what you expected to happen._ + +**Actual behavior** +_A clear and concise description of what actually happened._ + +### Additional context +_Any other information you think could be meaningful to this issue._ diff --git a/.github/ISSUE_TEMPLATE/documentation_issue_report.md b/.github/ISSUE_TEMPLATE/documentation_issue_report.md index 1bdea068b..5c6a3df6a 100644 --- a/.github/ISSUE_TEMPLATE/documentation_issue_report.md +++ b/.github/ISSUE_TEMPLATE/documentation_issue_report.md @@ -1,28 +1,13 @@ --- name: Documentation Issue Report -about: Report a documentation issue, typographical error or missing content in beluga. +about: Report a documentation issue, typographical error or missing content in this repository. title: '' labels: [bug, documentation] --- -## Required info -- Version or commit hash: - - +### Issue description +_A clear and concise description of what the bug is (e.g a typographical error, incorrect documentation, missing content)._ -## Description - - -## Additional information - +### Additional context +_Any other information you think could be meaningful to this issue._ diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index c9668f458..35b67b9f1 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,22 +1,16 @@ --- name: Feature Request -about: Request a new feature for beluga. +about: Suggest an idea for a new feature. title: '' labels: enhancement +assignees: '' --- -## Description - +### Feature description -## Definition of done - +_A clear and concise description of the feature, as well as to why it is relevant (e.g. the problem it solves, the use cases it supports, how it improves usability, etc.)_. -## Additional considerations - +### Implementation considerations + +_Any special considerations meaningful when implementing this feature._ diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index de106e671..b38c74dda 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,26 +1,25 @@ - +- [ ] 🐛 Bugfix (change which fixes an issue) +- [ ] 🚀 Feature (change which adds functionality) +- [ ] 📚 Documentation (change which fixes or extends documentation) -## Summary - +### Checklist -## Checklist -- [ ] Read the [contributing guidelines](https://github.com/Ekumen-OS/beluga/blob/main/CONTRIBUTING.md). -- [ ] Configured pre-commit and ran colcon test locally. -- [ ] Signed all commits for DCO. -- [ ] Added tests (regression tests for bugs, coverage of new code for features). -- [ ] Updated documentation (as needed). -- [ ] Checked that CI is passing. +_Put an `x` in the boxes that apply. This is simply a reminder of what we will require before merging your code._ + +- [ ] Lint and unit tests (if any) pass locally with my changes +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] I have added necessary documentation (if appropriate) +- [ ] All commmits have been signed for [DCO](https://developercertificate.org/) + +### Additional comments + +_Anything worth mentioning to the reviewers._ diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..f5bf6ae98 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +# Colcon build +build/ +install/ +logs/ + +# Development environments +.vscode/ +.idea/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 868958d0c..9379798d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,115 +1,144 @@ -# How to contribute to Beluga + +# Contributing to Beluga -Thank you for investing your time in contributing to this project! +First off, thanks for taking the time to contribute! ❤️ -## Contributions +All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉 -Any contribution that you make to this repository will -be under the Apache 2 License, as dictated by the -[license](./LICENSE): +> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about: +> - Star the project +> - Tweet about it +> - Refer this project in your project's readme +> - Mention the project at local meetups and tell your friends/colleagues -~~~ -5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. -~~~ + +## Table of Contents -Contributors must sign-off each commit by adding a `Signed-off-by: ...` -line to commit messages to certify that they have the right to submit -the code they are contributing to the project according to the -[Developer Certificate of Origin (DCO)](https://developercertificate.org/). +- [I Have a Question](#i-have-a-question) +- [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Requesting Features](#requesting-features) + - [Your First Code Contribution](#your-first-code-contribution) +- [Styleguides](#styleguides) -## Getting started +## I Have a Question -### Issues +> If you want to ask a question, we assume that you have read the available [Documentation](https://github.com/Ekumen-OS/beluga). -#### Create a new issue +Before opening a new issue to ask for help, it is best to check for already existing [Issues](https://github.com/Ekumen-OS/beluga/issues) that might be relevant to your question. In case you have found a suitable issue and still need clarification, you can write your question in there. It is also advisable to search the internet for answers first. -If you spot a problem or have a feature request you'd like to discuss, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). -If a related issue doesn't exist, you can [open a new issue](https://github.com/Ekumen-OS/beluga/issues/new/choose). +If you then still feel the need to ask a question and need clarification, we recommend the following: -### Make changes +- Open an [Issue](https://github.com/Ekumen-OS/beluga/issues/new). +- Provide as much context as you can about what you're running into. +- Provide project and platform versions, depending on what seems relevant. -#### Prerequisites +We will try to answer back as soon as possible. -- Make sure you have [`docker compose`](https://github.com/docker/compose/tree/v2) installed ([`v2.10+`](https://github.com/docker/compose/releases/tag/v2.10.0)). - ```bash - docker compose version - ``` - If you don't, please follow [these instructions](https://docs.docker.com/compose/install/linux/). +## I Want To Contribute -#### Make changes locally +> ### Legal Notice +> When contributing to this project, you must agree that you have authored 100% of the content, +> that you have the necessary rights to the content and that the content you contribute may be +> provided under the [Apache 2.0 License](./LICENSE) (item 5). -1. Clone the repository. - ```bash - git clone --recursive git@github.com:Ekumen-OS/beluga.git - ``` +### Reporting Bugs -1. Build and run the development docker container. - ```bash - cd - docker/run.sh - ``` - To build the image before starting the container, use: - ```bash - docker/run.sh --build - ``` - To target an specific ROS distribution, use: - ```bash - ROSDISTRO=humble docker/run.sh - ``` - Supported distributions include `humble` and `rolling`. + +#### Before Submitting a Bug Report -1. **[Optional]** Install pre-commit hooks. _This will probably cause you to not be able to create commits from your host machine since the hooks have dependencies that only exist in the development container._ - ```bash - cd /ws/src/beluga - pre-commit install - ``` - Alternatively, you can run the hooks manually. - ```bash - cd /ws/src/beluga - pre-commit run --all-files - ``` +A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information, and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible. -1. Create a working branch and start with your changes. The suggested branch name convention is `/`. +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible versions (Make sure that you have read the [documentation](https://github.com/Ekumen-OS/beluga). If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](https://github.com/Ekumen-OS/beluga/issues?q=label%3Abug). +- Collect information about the bug: + - Stack trace (Traceback) + - OS, Platform and Version (Windows, Linux, macOS, x86, ARM) + - Version of the interpreter, compiler, middleware, package manager, depending on what is relevant. + - Possibly your input and the output + - Can you reliably reproduce the issue? And can you also reproduce it with older versions? -1. Build and test the project. - ```bash - cd /ws - colcon build --symlink-install - colcon test - ``` + +#### How Do I Submit a Good Bug Report? -1. Run an example application using a pre-recorded rosbag. +We use GitHub issues to track bugs and errors. If you run into an issue with the project: +- Open an [Issue](https://github.com/Ekumen-OS/beluga/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.) +- Explain the behavior you would expect and the actual behavior. +- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case. +- Provide the information you collected in the previous section. + +After the issue has been submitted: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with the steps you provided. If no reproducible sequence of steps was provided or if the provided sequence does not seem to trigger the issue being reported, the team will ask you for further information about this and they will label the issue as `needs-repro`. Bugs with the `needs-repro` label will not be addressed until they've been successfully reproduced. +- If the team is able to reproduce the issue it will be labeled `needs-fix`, as well as possibly other labels, and the issue will be left to be [fixed by someone](#your-first-code-contribution). + +### Requesting Features + +This section guides you through submitting a feature request for Beluga, **including completely new additions and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions. + + +#### Before Submitting a Feature Request + +- Make sure that you are using the latest version. +- Read the [documentation](https://github.com/Ekumen-OS/beluga) carefully and find out if the functionality is already covered. +- Perform a [search](https://github.com/Ekumen-OS/beluga/issues) to see if the feature has already been requested. If it has, add a comment to the existing issue instead of opening a new one. +- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. + + +#### How Do I Submit a Good Feature Request? + +Feature requests are tracked as [GitHub issues](https://github.com/Ekumen-OS/beluga/issues). + +- Use a **clear and descriptive title** for the issue to identify the suggestion. +- Provide a **step-by-step description of the suggested feature** in as many details as possible. +- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. +- **Explain why this feature would be useful** to most Beluga users. You may also want to point out the other projects that solved it better and which could serve as inspiration. + +### Your First Code Contribution + +This section guides you through contributing code to Beluga. Following these guidelines will help maintainers and ensure your contributions are reviewed and eventually accepted. + +#### A Primer On Project Workflow + +This projects adopts a [feature branch workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#feature-branching-git-workflow) ([forking workflow](https://about.gitlab.com/topics/version-control/what-is-git-workflow/#forking-git-workflow) for contributors that are not maintainers), with pull requests for code integration. Every code contribution must be associated to a [feature request](#requesting-features) or [bug report](#reporting-bugs) with enough consensus and evidence to move forward, signaled with `needs-work` and `needs-fix` labels respectively. Contributors must sign-off each commit by adding a `Signed-off-by: ...` line to every commit message to certify that they have the right to submit the code they are contributing to the project according to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/). Pull requests must have been reviewed and approved at least once to be merged. + +#### How Do I Submit a Good Code Contribution? + +1. **Fork [the Beluga repository](https://github.com/Ekumen-OS/beluga/) to your GitHub account**. +1. **Clone the repository fork locally**. ```bash - cd /ws - source install/setup.bash - ros2 launch beluga_example example_rosbag_launch.py - ``` - You also can use `teleop_twist_keyboard` to control a simulated robot. In two separate terminals run: - ```bash - cd /ws - source install/setup.bash - ros2 launch beluga_example example_launch.py + git clone --recursive git@github.com:/beluga.git + cd beluga ``` +1. **Create a new branch where your work will go**. ```bash - cd /ws - source install/setup.bash - ros2 run teleop_twist_keyboard teleop_twist_keyboard + git checkout -b /fix-issue-12345 main ``` +1. **Work on your contribution**. See [instructions](GETTING_STARTED.md) on how to get started with Beluga development. +1. **Lint and test your changes**. For bug fixes, make sure regression tests are included. +1. **Document your changes as needed**. For new features, make sure added functionality is clearly documented. +1. **Push the branch to your fork on GitHub**. +1. **Open a pull request**. Make sure all tests and linters pass on your branch before opening. + +## Styleguides + + +### Commit messages + +Commit messages should adhere to the following good practices: + +- Limit the subject line to 50 characters. +- Capitalize the subject line. +- Do not end the subject line with a period. +- Use the imperative mood in the subject line. +- Wrap the body at 72 characters. +- Use the body to explain _what_ and _why_ vs. _how_. -1. Push your changes and [create a PR](https://github.com/Ekumen-OS/beluga/compare)! +See https://cbea.ms/git-commit for more information and the reasoning behind this. -1. At the time a feature branch is squashed-and-merged into `main`, the commit message should adhere to the following good practices: - - Limit the subject line to 50 characters. - - Capitalize the subject line. - - Do not end the subject line with a period. - - Use the imperative mood in the subject line. - - Wrap the body at 72 characters. - - Use the body to explain _what_ and _why_ vs. _how_. - - See https://cbea.ms/git-commit/ for more information and the reasoning behind this. + +## Attribution +This guide is based on the **contributing-gen**. [Make your own](https://github.com/bttger/contributing-gen)! diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 000000000..069cc5538 --- /dev/null +++ b/GETTING_STARTED.md @@ -0,0 +1,72 @@ +# Getting started with Beluga + +## Crash course + +1. **Clone the repository**. You will need `git`. + + ```bash + git clone --recursive git@github.com:Ekumen-OS/beluga.git + ``` + +1. **Build and run the development docker container**. You will need [`docker-compose v2.10+`](https://github.com/docker/compose/tree/v2). + + ```bash + (cd beluga && docker/run.sh) + ``` + To rebuild the image before starting the container, use: + ```bash + (cd beluga && docker/run.sh --build) + ``` + To target an specific ROS distribution, use: + ```bash + (cd beluga && ROSDISTRO=humble docker/run.sh) + ``` + Supported distributions include `humble` and `rolling`. + +1. **Build and test the project** (inside development container). + + ```bash + cd /ws + colcon build --symlink-install + colcon test + ``` + +1. **Run an example application using a ROS bag** (inside development container). + + ```bash + cd /ws + source install/setup.bash + ros2 launch beluga_example example_rosbag_launch.py + ``` + +1. **Run an example application using a simulation and teleop controls** (inside development container). + + In two separate terminals run: + ```bash + cd /ws + source install/setup.bash + ros2 launch beluga_example example_launch.py + ``` + ```bash + cd /ws + source install/setup.bash + ros2 run teleop_twist_keyboard teleop_twist_keyboard + ``` + +1. **Lint your code**. You will need [`pre-commit`](https://pre-commit.com/) and ROS dependencies (already installed in the development container). + + ```bash + cd /ws/src/beluga + pre-commit run --all-files + ``` + +1. **Build documentation** (inside development container). + + ```bash + cd /ws + ./src/beluga/docs/generate_docs.sh + ``` + +## Next steps + +If you want to contribute to this project, please read the [contribuing guidelines](CONTRIBUTING.md). diff --git a/README.md b/README.md index 15a74636f..0916816f2 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,31 @@ # Beluga -![CI badge](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml/badge.svg?event=push) +[![CI pipeline](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml/badge.svg?branch=main)](https://github.com/Ekumen-OS/beluga/actions/workflows/ci_pipeline.yml?query=branch:main) +[![License Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE) ## Overview -Beluga is an extensible library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms, -including sensor and motion models. -It also provides a _drop-in_ replacement for the `amcl` node used in [navigation2](https://github.com/ros-planning/navigation2). +Beluga is an extensible C++17 library with a ground-up implementation of the Monte Carlo Localization (MCL) family of estimation algorithms featuring: -https://github.com/Ekumen-OS/beluga/assets/33042669/df2a5e61-3d97-4350-b171-71bb1a09a6d0 +- A modular design based on orthogonal components that can be merged together using the mixin pattern. +- Emphasis on the prevention of regressions and facilitation of code improvements through test coverage. +- Semi-automated benchmarks that can be used to validate different configurations. -## Packages - -| Package | Description | -|--------------------| ------------| -| `beluga` | A ROS agnostic extensible library to implement algorithms based on particle filters. | -| `beluga_amcl` | A ROS 2 wrapper, providing an executable node and a ROS 2 component.
It provides almost feature parity with `nav2_amcl`. | -| `beluga_example` | Example launch files, showing how to run beluga. | -| `beluga_benchmark` | Scripts to benchmark, profile and also compare beluga with other AMCL implementations. | - -## FAQ - -- How can I try an example? - - Check the [contributing guidelines](CONTRIBUTING.md), specifically the [_run an example application_](CONTRIBUTING.md#running_an_example) section. - -- How can I contribute to the project? - - Check the [contributing guidelines](CONTRIBUTING.md). +https://github.com/Ekumen-OS/beluga/assets/33042669/4481cc43-f0cd-40df-a5b4-7e0a8ccb87c6 -- Is there API documentation? - - Yes, but it's not currently being hosted online. - You can use [a script](beluga/docs/generate_docs.sh) to generate docs for the beluga package locally. - -- Are the node parameters documented? - - You can find all the supported parameter documented in the example parameters [yaml file](beluga_example/config/params.yaml). - -- How to benchmark Beluga? - - You can find micro-benchmarks in the [test folder](beluga/test/benchmark/) of Beluga.
- For macro-benchmarking and comparing with other AMCL implementations, check the [benchmarking documentation](beluga_benchmark/docs/BENCHMARKING.md). +## Packages -- How to cpu profile Beluga? +This repository contains the following packages: - Check the [profiling documentation](beluga_benchmark/docs/PROFILING.md). +| Package | Description | +|----------------------------------------------| ------------------------------------------------------------------------------------------------------------------------| +| [`beluga`](beluga) | A ROS-agnostic extensible library to implement algorithms based on particle filters. | +| [`beluga_amcl`](beluga_amcl) | A ROS 2 wrapper, providing an executable node and a ROS 2 component.
It provides interface parity with `nav2_amcl`. | +| [`beluga_example`](beluga_example) | Example launch files, showing how to run Beluga-based nodes. | +| [`beluga_benchmark`](beluga_benchmark) | Scripts to benchmark, profile and also compare Beluga with other MCL implementations. | +| [`beluga_system_tests`](beluga_system_tests) | System integration tests for Beluga. | -## License +## First Steps -Beluga is available under the `Apache 2.0` license. -See [LICENSE](LICENSE). +- Get hands-on experience with the [getting started](GETTING_STARTED.md) tutorial. +- Read the [contributing guidelines](CONTRIBUTING.md). diff --git a/beluga/README.md b/beluga/README.md new file mode 100644 index 000000000..8a5304a88 --- /dev/null +++ b/beluga/README.md @@ -0,0 +1,32 @@ +# 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. + +![Beluga diagram](https://github.com/Ekumen-OS/beluga/assets/33042669/c3a9375c-8beb-44ee-bcde-d4c0f62f576e) + +## Features + +The current set of features includes: + +- A configurable particle filter with support for: + - [Structure of arrays and array of structures][aos_soa] storage policies. + - Fixed resampling and [adaptive KLD resampling][fox2001] policies to determine how many samples to take per iteration. + - [Selective resampling][grisetti2007], on-motion resampling, interval resampling policies to determine when to resample. + - Sequential and parallel execution policies. + - Weighted mean and covariance statistics for pose estimation. +- Likelihood field and beam sensor models. +- Differential drive and omnidirectional motion models. + +## Dependencies + +Beluga is built on top of the following open source libraries: + +- [Eigen](https://gitlab.com/libeigen/eigen): A well-known C++ template library for linear algebra: matrices, vectors, numerical solvers, and related algorithms. +- [Sophus](https://github.com/strasdat/Sophus): A C++ implementation of Lie groups using Eigen. +- [Range](https://github.com/ericniebler/range-v3): The basis library for C++20's `std::ranges`. +- [libciabatta](https://github.com/atomgalaxy/libciabatta): A composable mixin support library. + +[aos_soa]: https://en.wikipedia.org/wiki/AoS_and_SoA +[fox2001]: https://dl.acm.org/doi/10.5555/2980539.2980632 +[grisetti2007]: https://doi.org/10.1109/TRO.2006.889486 diff --git a/beluga_amcl/README.md b/beluga_amcl/README.md new file mode 100644 index 000000000..2bc767f1d --- /dev/null +++ b/beluga_amcl/README.md @@ -0,0 +1,63 @@ +# Beluga AMCL + +Beluga AMCL is a ROS 2 node based on [Beluga](../beluga) featuring interface parity with +[nav2's AMCL][nav2_amcl]. +This package can be easily integrated with code that currently uses `nav2's AMCL`. + +## ROS 2 Interface + +### Parameters + +Beluga AMCL currently supports the majority of ROS parameters used in [nav2's AMCL][nav2_amcl]. +See the [nav2's configuration guide][nav2_configuration_guide] and +[Beluga examples](../beluga_example/config/params.yaml) for reference. +In addition, it supports the following extra parameters: + +| Parameter | Description | +|--------------------------------------------------------------------|-----------------------------------------------------------------------------------| +| `spatial_resolution_[x, y, theta]` | Resolution for [adaptive KLD resampling][fox2001]. | +| `initial_pose.covariance_[x, y, yaw, xy, xyaw, yyaw]` | Covariance to use with the initial pose when initializing the particle filter. | +| `execution_policy` | Execution policy used to process particles [seq: sequential, par: parallel]. | + +### Subscribed Topics + +The subscribed topic names can be changed with the parameters `map_topic`, `scan_topic` and `initial_pose_topic`. + +| Topic | Type | Description | +|------------------|-------------------------------------------|-----------------------------------------------------------------------------| +| `map` | `nav_msgs/OccupancyGrid` | Input topic for map updates. | +| `scan` | `sensor_msgs/LaserScan` | Input topic for laser scan updates. | +| `initial_pose` | `geometry_msgs/PoseWithCovarianceStamped` | Input topic for pose mean and covariance to initialize the particle filter. | + +### Published Topics + +| Topic | Type | Description | +|------------------|-------------------------------------------|--------------------------------------------------------------------------| +| `particle_cloud` | `nav2_msgs/ParticleCloud` | Output topic for particle cloud published at a fixed frequency. | +| `pose` | `geometry_msgs/PoseWithCovarianceStamped` | Output topic for estimated pose mean and covariance in map frame. | + +### Transforms + +The frame names can be changed with the parameters `global_frame_id`, `odom_frame_id` and `base_frame_id`. +Defaults are `map`, `odom` and `base`. + +| Transform | Description | +|-------------------|----------------------------------------------------------------------------------------------------| +| `odom` to `base` | Input transform used by motion models and resampling policies. | +| `base` to `laser` | Input transform used to convert laser scan points to base frame. | +| `map` to `odom` | Output transform calculated from the estimated pose mean and the current _odom-to-base_ transform. | + +### Services + +| Topic | Type | Description | +|------------------------------------|------------------|-------------------------------------------------------------------------------| +| `reinitialize_global_localization` | `std_srvs/Empty` | Request to reinitialize global localization without an initial pose estimate. | + +## Next Steps + +- See [example launch files](../beluga_example) showing how to run Beluga-based nodes. +- See [available benchmarks](../beluga_benchmark) for scripts and comparison with other AMCL implementations. + +[nav2_amcl]: https://github.com/ros-planning/navigation2/tree/main/nav2_amcl +[nav2_configuration_guide]: https://navigation.ros.org/configuration/packages/configuring-amcl.html +[fox2001]: https://dl.acm.org/doi/10.5555/2980539.2980632 diff --git a/beluga_benchmark/README.md b/beluga_benchmark/README.md new file mode 100644 index 000000000..b942fbccd --- /dev/null +++ b/beluga_benchmark/README.md @@ -0,0 +1,9 @@ +# Beluga Benchmark + +This package contains scripts to benchmark, profile and also compare Beluga AMCL with other implementations. + +## Getting Started + +- View [reports](docs/reports/) comparing Beluga's performance to other AMCL implementations. +- [How to benchmark Beluga?](docs/BENCHMARKING.md) +- [How to profile Beluga?](docs/PROFILING.md) diff --git a/beluga_example/README.md b/beluga_example/README.md new file mode 100644 index 000000000..311c808b5 --- /dev/null +++ b/beluga_example/README.md @@ -0,0 +1,22 @@ +# Beluga Example + +This package contains example launch files that demonstrate the use of Beluga-based nodes (e.g. [Beluga AMCL](../beluga_amcl)) with external ROS bags or simulation software. + +## Examples + +See the [getting started](../GETTING_STARTED.md) tutorial to setup a development container or install the package and dependencies from source. + +- Launch a pre-recorded ROS bag. + ```bash + ros2 launch beluga_example example_rosbag_launch.py + ``` + +- Launch a simulation that can be teleoperated. + ```bash + ros2 launch beluga_example example_launch.py + ``` + +- Launch a simulation with Beluga AMCL as a composable node. + ```bash + ros2 launch beluga_example example_component_launch.py + ``` diff --git a/beluga_system_tests/README.md b/beluga_system_tests/README.md new file mode 100644 index 000000000..e45c56b62 --- /dev/null +++ b/beluga_system_tests/README.md @@ -0,0 +1,3 @@ +# Beluga System Tests + +This package contains system integration tests for Beluga.