Input-Contract Wrapper for Volumetric Mapping

Repository: volumetric-mapping-input-contract

ROS 2 input-contract wrapper for volumetric mapping pipelines.

This repository externalizes input assumptions that are often left implicit in mapping systems, such as pose availability, frame interpretation, cloud-pose timing, and observation admissibility. Instead of modifying the volumetric backend itself, the wrapper conditions inputs before integration so that these assumptions become explicit, configurable, and auditable.

Overview

Volumetric mapping pipelines often depend on upstream assumptions that are distributed across launch files, topic conventions, TF trees, and dataset habits. When those assumptions are violated, map degradation can be hard to attribute: the backend appears unstable even when the actual mismatch occurred earlier at the input boundary.

This repository exposes that boundary explicitly. It provides:

• pose normalization into a stable odometry interface
• cloud-pose pairing with timing admissibility checks
• frame- and extrinsic-aware backend pose construction
• wrapper-side auditability before volumetric integration
• helper scripts for replay, export, and proxy-map evaluation

Repository Layout

volumetric-mapping-input-contract/
├── README.md
├── docker/
├── docs/
├── examples/
├── ros2_ws/
│   └── src/
├── scripts/
└── third_party/

Main components:

• ros2_ws/src/pose_provider
  • normalizes upstream pose sources into a stable odometry interface
• ros2_ws/src/dense_mapping_tsdf
  • enforces the input contract and forwards admissible observations to the backend
• ros2_ws/src/map_interfaces
  • lightweight shared interfaces used by the wrapper stack
• examples/
  • reusable configuration profiles for common integration regimes
• scripts/
  • small replay, export, cleanup, and metric helpers
• docs/
  • user-facing documentation for configuration and integration

Backend

This repository focuses on the wrapper. The backend path used by the public workflow is DB-TSDF, kept as a pinned Git submodule under third_party/.

Input Contract

The wrapper externalizes four contract dimensions:

1. Pose availability
2. Frame interpretation
3. Timing admissibility
4. Observation admissibility

The backend is only invoked after those conditions have been checked under a declared execution regime.

See docs/input_contract.md.

Quick Start

1. Clone the repository

git clone git@github.com:EESC-LabRoM/volumetric-mapping-input-contract.git
cd volumetric-mapping-input-contract

2. Initialize the backend dependency

Expected workflow:

git submodule update --init --recursive

The pinned backend is tracked under:

third_party/DB-TSDF/

and exposed to the ROS 2 workspace through the link:

ros2_ws/src/DB-TSDF -> ../../third_party/DB-TSDF

3. Build the workspace

Native ROS 2 workflow:

cd ros2_ws
colcon build
source install/setup.bash

Docker workflow:

./docker/scripts/build.sh
./docker/scripts/run.sh
./docker/scripts/shell.sh

Inside the container:

cd /workspace/ros2_ws
colcon build
source install/setup.bash

See docker/README.md for Docker details.

Minimal Replay Workflow

The main example launch is:

• ros2_ws/src/dense_mapping_tsdf/launch/input_contract_mapping.launch.py

It starts:

• pose normalization
• conditioned cloud forwarding
• wrapper-side contract enforcement
• backend integration
• optional RViz

Example replay command:

./scripts/replay_example.sh \
  --bag-path /absolute/path/to/bag \
  --db-tsdf-config /absolute/path/to/db_tsdf_profile.yaml \
  --points-topic /your/points \
  --odometry-topic /your/odometry \
  --backend-pose-mode odometry

The repository provides a backend example profile at:

examples/db_tsdf/replay_profile.yaml

This file is provided as a visible, versioned example of a backend configuration that was exercised with the wrapper. It is not the only valid backend profile. External users should replace or adapt it when their sensing range, map bounds, or backend filtering regime differ.

Keeping this example profile on the wrapper side preserves a clean DB-TSDF submodule while making one compatible replay configuration visible from the public repository.

Typical use cases:

• backend_pose_mode=identity
  • cloud already expressed in the backend integration frame
• backend_pose_mode=odometry
  • pose already describes the mapping sensor frame
• backend_pose_mode=odometry with static extrinsic parameters
  • pose describes a body frame and the cloud comes from another sensor frame

Reference profiles are provided in examples/.

Replay Configuration

The following settings summarize the replay configuration used for the public wrapper examples.

Item	Value
ROS runtime	ROS 2 Humble
Bag runtime	rosbag2 replay via ros2 bag play
MCAP support	ros-humble-rosbag2-storage-mcap included in the Docker image
Backend	DB-TSDF
Backend commit	0768beac5dbf6f34555a3c4ec7c2c5890a77d843
Backend profile	examples/db_tsdf/replay_profile.yaml
Voxel size	tdf_grid_res = 0.05 m
Integration range	min_range = 0.5 m, max_range = 40.0 m
Point-cloud filtering	pc_downsampling = 1
Replay speed	--play-rate 1.0
Timing threshold	max_pose_cloud_skew_sec = 0.05 s
Exported map artifact	backend-generated grid_data.pcd, archived as map.pcd
Backend comparability rule	backend parameters were kept fixed across paired comparisons

Notes:

• Sensor rates are dataset-dependent and should be read from the input bag with python3 scripts/rosbag_info.py /absolute/path/to/bag or native ROS bag inspection tools.
• No additional truncation-distance parameter was independently exposed in the wrapper DB-TSDF replay profile.

Export And Proxy Metrics

To keep the replayed pipeline alive for export:

./scripts/replay_example.sh \
  --bag-path /absolute/path/to/bag \
  --db-tsdf-config /absolute/path/to/db_tsdf_profile.yaml \
  --points-topic /your/points \
  --odometry-topic /your/odometry \
  --backend-pose-mode odometry \
  --keep-alive-after-playback

Then export the current map:

./scripts/export_map.sh \
  --output-dir /absolute/path/to/output \
  --workspace /absolute/path/to/ros2_ws \
  --compute-metrics

The export workflow produces:

• an archived map file
• a compact metrics.json summary

The helper script reports proxy metrics such as:

• point count
• axis-aligned bounding-box volume
• XY footprint area
• density proxies
• near-ground plane spread

These metrics are intended for comparative evidence under fixed replay conditions. They should not be interpreted as ground-truth reconstruction accuracy.

Documentation

• docs/input_contract.md
• docs/replay_and_onboarding.md
• docs/observability.md
• docker/README.md
• scripts/README.md
• ros2_ws/src/dense_mapping_tsdf/README.md
• ros2_ws/src/pose_provider/README.md

Citation

Repository metadata is available in CITATION.cff.

Maintained by

• LabRoM - Mobile Robotics Laboratory - University of Sao Paulo
• EESC/USP Mobile Robotics Laboratory