Add layered Wavemap support for continuous and discrete voxel attributes

[GuilhermeCabaco]

Description

This PR extends Wavemap from occupancy-only mapping to compile-time-defined layered voxel maps containing continuous and discrete attributes. It adds the core layered storage and integration framework, .lwvmp persistence, ROS1 messages and server support, RViz visualization, sensor examples, tests, and user documentation.

A demonstration is available in the Layered Wavemap video.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that causes existing functionality to not work as expected)
• Other (please describe):

Detailed Summary

Provide the motivation, context, and links to any related issues, PRs, or documentation:

• Motivation: Standard Wavemap cells represent occupancy only. Applications such as digital twins and semantic mapping also need aligned sensor attributes, including reflectivity, RGB, signal strength, semantic classes, and Boolean state.
• Context: The extension preserves occupancy as the primary Wavemap layer while allowing applications to define additional layers through compile-time schemas and update policies.
• Related issues/PRs: None.

The implementation includes:

• Wavelet-compatible continuous layers stored alongside occupancy.
• Compressed discrete layers using dominant values, observed offsets, and exact exceptions.
• Reusable and user-defined update policies.
• Hashed and chunked layered wavelet backends.
• Versioned .lwvmp persistence with stored layer schemas.
• Runtime .lwvmp decoding in RViz for built-in layer codecs, without requiring the exact application schema to be registered.
• ROS1 messages, conversions, layered server extensions, publication support, and RViz displays.
• Point-cloud attribute adapters and Ouster-based reference integrations.
• A synthetic RGB layered-map demonstration.
• Documentation covering installation, execution, schemas, storage, update policies, persistence, and extension points.

API Changes

List any changes to wavemap's APIs to help users update their code. Write "None" if there are no changes.

C++ API:

• Added generic cell-data traits and templated wavelet-map storage for custom voxel data.
• Added layered map schemas, descriptors, storage bundles, and map definitions.
• Added continuous and discrete update-policy interfaces.
• Added layered observation and integration APIs.
• Added weighted-mean and RGB layer types.
• Added .lwvmp schema-aware persistence APIs.
• Existing occupancy map aliases remain available, but users linking compiled Wavemap libraries should rebuild because core map and integrator implementations changed.

Python API:

• None.

ROS1 Interface:

• Added LayeredMap, LayeredMapUpdate, continuous-layer, and discrete-layer messages.
• Extended wavemap_msgs/Map with a layered hashed-wavelet representation.
• Added layered map conversions, publication operations, server builders, and point-cloud attribute adapters.
• Added a LayeredMap RViz display with selectable continuous and discrete layers.
• Added runtime loading of .lwvmp files that use the built-in scalar, RGB, weighted-mean, integer, and Boolean codecs.
• Existing ROS1 consumers must regenerate messages and rebuild because wavemap_msgs/Map changed.

Review Notes

Please focus review on:

• The algebra and pruning behavior of continuous layered voxel data.
• The dominant-value and exception representation used for discrete layers.
• Compatibility of the templated map and integrator changes with occupancy-only use.
• ROS1 message compatibility and incremental layered-map updates.
• .lwvmp schema validation and runtime decoding.
• RViz reconstruction and visualization of continuous and discrete layers.

Version 1 of .lwvmp stores layer names and codec identifiers, but it does not store application-specific visualization ranges, category labels, or colors. RViz uses default visualization settings when loading a schema dynamically; registered schema factories can still provide richer metadata.

Testing

Automated Tests

Automated Tests

• Full layered implementation test run: 518 passed, 0 failed, and 6 skipped.
• Rebuilt wavemap_ros_conversions and wavemap_rviz_plugin successfully.
• All 10 ROS conversion tests pass.
• Added a persistence regression test covering an unregistered schema with scalar, RGB, weighted-mean, integer, and Boolean layers.
• Validated the layered tutorial as reStructuredText.