Wavemap 2.0

[victorreijgwart]

Description

This PR introduces significant enhancements to the framework's generality and functionality. Wavemap's core library is now a standalone CMake C++ package, enabling its use on non-ROS platforms and paving the way for future integrations, including a Python API. Other major updates include generic spatial data structures, new path-planning utilities, and a plugin system for map operations.

Type of change

• Bug fix
• New feature
• Breaking change

Users who created custom configs for a previous wavemap version will have to update these manually.
This PR changes the high-level structure of wavemap's configuration files, to accommodate new functionalities and improve user-friendliness. However, no functionality has been removed.

Detailed summary

This PR introduces major changes to wavemap's code base, focused on improving its generality, user-friendliness, and code quality. In terms of functionality, wavemap's spatial data structures can now be used to store arbitrary data types. We also added a wide range of new utilities, with a special focus on path-planning applications. In terms of code, wavemap can now be used as a pure CMake C++ library. This makes the framework usable without ROS and lays the groundwork for our upcoming Python API. Further improvements include a modular system to add and configure map operations, much like plugins. We already include new operations to publish the map in alternative formats (e.g. obstacle pointcloud) and perform local mapping, and expect to add many more in the future.

This PR addresses GH issues #25 and #59.

New features

• Make wavemap's C++ library available as a pure CMake package
  • Installable and compatible with find_package (and FetchContent)
  • Supports automatically fetching missing system deps with FetchContent
  • Embeds header-only minkindr library, including minor cleanup of its code
  • Extend documentation to cover installation and usage without ROS
  • Restructure examples into generic cpp and ros1-specific examples
• Generic spatial data structures
  • Decouple our spatial data structures from our occupancy map types
  • Directly usable for path planning, semantic mapping and other tasks
  • Improved code quality, performance and consistency between interfaces
• Euclidean Signed Distance Fields
  • Quasi and Fully Euclidean ESDF generators
  • Extensive unit tests
  • (De)serialization to files
  • (De)serialization to ROS msgs
  • Extend the Rviz plugin to support rendering ESDFs
• Hierarchical, multi-resolution classified maps
  • Classifies space based on occupancy or collision radius (ESDF) thresholds
  • Enables fast, hierarchical traversability and visibility checking
  • Provides convenience functions, e.g. visit all free & observed map leaves
  • Use classified map to speed up voxel visibility culling in wavemap's Rviz plugin
• Additional utilities for path planning, to simplify
  • Iterating over cell neighborhoods
  • Determining adjacency types between fixed and multi-resolution cells
  • Sampling random points
    • Supports occupancy, observedness, and collision radius constraints
  • Computing best and worst-case distances between AABBs
• Class that emulates single-node pointers chunked octrees
  • Enables traversing and manipulating chunked trees as if they're regular trees
  • Improves code readability and reduces chance of bookkeeping bugs
• Implement a plugin system for map operations, including plugins to
  • Crop the map for local mapping
  • Publish obstacles as a fixed-resolution pointcloud
• Separate configuration of inputs and measurement integrators
  • Allows one set of integrator settings to be used by multiple inputs (e.g. on a robot with 6 identical depth cameras)
  • Cleaner coupling between ROS interface and ROS-agnostic integration pipeline

Improvements

• Extend query accelerator
  • Add support for ClassifiedMaps and most of our generic spatial data structures
  • Expose height (resolution) of query result, useful for multi-resolution ray tracing
• Migrate functional code from ROS packages into C++ library
  • Motivation
    • The goal is to keep the interfaces thin
    • Simplifies adding new interfaces in the future (e.g. ROS2, Zenoh,...)
    • Reduces code duplication
  • Make measurement integration and map operation pipeline ROS-agnostic
  • Move pointcloud undistortion code into C++ library
  • Make utility/code management scripts usable without ROS
• Tidy up CMake files
  • Switch from catkin_simple to vanilla catkin
    • catkin_simple internals are messy and hide what's happening under the hood, making the old ROS1 pkgs hard to use as examples when porting wavemap to other interfaces
  • Remove dependencies on catkinized gflags, glog and Eigen
    • Needed to make wavemap usable as a pure CMake C++ library
• Refactoring and code quality improvements
  • Improve consistency and reduce code duplication between occupancy map types
  • Update all factories to return unique_ptrs
    • Users are then free to choose if they keep it unique or auto-convert it to a shared ptr
  • Reorganize and refactor unit tests
  • Define and use bit_ops::is_bit_set method to make bit manipulation code easier to read
  • Simplify DECLARE_CONFIG_MEMBERS macro
• Improve user friendliness
  • Improve the structure of the utils directory
  • Interaction with configs
    • Improve syntax for handling TypeSelectors
    • Improve syntax and add helper methods for handling nested params
    • Make it possible to pass expressions in param validators
  • Add helper methods to configure the C++ library's logging level (verbosity)
  • Improve index conversion vector operation syntax
  • Make it easier to configure an integrator's max update resolution, by allowing it to set it explicitly instead of through termination_height
  • Extend methods to convert geometry (points, transforms) in wavemap_ros_conversions pkg

Bug fixes

• Fix GCC hanging when compiling with UBSAN enabled

Package changelogs

• Libraries
  • C++
• Interfaces
  • ROS1
    • wavemap
    • wavemap_msgs
    • wavemap_ros_conversions
    • wavemap_ros
    • wavemap_rviz_plugin
    • wavemap_all
• Examples
  • C++
  • ROS1

Testing

Unit tests

All unit tests are passing. Note that the C++ library's tests can now be run using GoogleTest standard mechanisms. For compatibility, we also configured the ROS1 wavemap interface package to run the library's tests when called with catkin test wavemap.

End-to-end tests

We reran all the demos on an Intel desktop and AMD laptop. We did not notice issues or regressions.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• Any required changes in dependencies have been committed and pushed

[victorreijgwart]

@LionelOtt, the new version of the documentation is ready for review. Thanks for the comments you've already made on the code! I'll start going through them tomorrow and also complete the full description for this PR.

[LionelOtt]

Looked over it and the restructuring and novel features look good to me.