traversability_generator3d

CI build (paper):

JOSS Paper:

A C++ library for 3D traversability estimation from Multi-Level Surface (MLS) maps, developed at the DFKI Robotics Innovation Center.

The library takes an MLS map as input and produces a TraversabilityMap3d enriched with slope, step height, orientation constraints, and soil semantics. This enables safe and robot-specific navigation in unstructured outdoor environments.

Features

• Input: Multi-Level Surface (MLS) maps
• Plane fitting with PCL RANSAC
• Slope and step height checks using AABB/OBB methods with CGAL
• Orientation-dependent motion constraints (incline limiting)
• Robot radius-based collision checking for precise obstacle detection
• Configurable obstacle inflation for safety margins
• Frontier detection and inflation
• Soil-aware traversability (sand, gravel, rocks, concrete) with uncertainty propagation
• ROS/ROS2 compatibility and RViz visualization support

Dependencies

• Eigen3
• PCL (>=1.7) with segmentation module
• CGAL (Core)
• Boost.Serialization
• OpenSceneGraph
• Rock base-types
• Rock maps
• vizkit3d_debug_drawings (optional, for visualization)

Automatic Install of Dependencies & Build

Install dependencies automatically when building traversability_generator3d. Defining -DINSTALL_DEPS=ON for cmake, builds and installs the source dependencies automatically. When -DCMAKE_INSTALL_PREFIX is used, the dependencies are also installed there. The install script generates an env.sh file in the CMAKE_INSTALL_PREFIX folder. It exports all neccessary environment variables.

git clone https://github.com/dfki-ric/traversability_generator3d.git -b paper
cd traversability_generator3d
mkdir build && cd build
cmake -DINSTALL_DEPS=ON -DRUN_TESTS=ON -DCMAKE_INSTALL_PREFIX=./install ..
make install
source install/env.sh

Node types

The core output of traversability_generator3d is a TraversabilityMap3d, where each cell is represented as a node enriched with slope, step height, soil information, etc.
To support planning and decision-making, nodes are classified into the following categories:

• 🟩 Traversable: The robot can stand (with its center) on this patch in at least one orientation without hitting an obstacle.
• 🟥 Obstacle: There is no way that the robot can stand (with its center) on this patch.
• 🟦 Frontier: Borders to the end of the map. Should be traversable (I am not 100% sure about this. check the code!)
• 🟪 Unknown: This is a virtual patch that serves as boundary for algorithms. This patch does not exist in reality. Patches also become unknown if there is not enough support in the MLS to be sure that a patch exists in this location.
• ⬛ Hole: This is part of the map specification but is not used by traversability_generator3d.
• 🟨 Unset: This is the starting state of a new patch. It should not be visible in a fully explored map. If you see a yellow patch after map expansion is done, you have found a bug in the TraversabilityMapGenerator and should investigate.
• 🟧 Inflated Obstacle: An obstacle patch expanded to include a safety buffer around the actual obstacle. These are not traversable.
• Inflated Frontier: A frontier patch that has been inflated for planning safety margins. Indicates proximity to exploration boundaries.

Why node types matter

This rich classification scheme provides more than just a binary safe/unsafe map. It enables planners to:

• Prioritize safe traversal while accounting for soil costs.
• Use frontier nodes to guide exploration and map growth.
• Maintain safety margins by considering inflated nodes.

Together, these node types form the backbone of the TraversabilityMap3d, making it both a planning tool and a research framework for robust traversability estimation.

Soil-Aware Traversability

Traversability estimation can optionally incorporate semantic soil information that influences traversal costs and feasibility.

Supported soil types:

• Concrete
• Rocks
• Sand
• Gravel
• Unknown / Unlabeled

Each soil sample is modeled as a Gaussian distribution over the map with configurable parameters:

• sigmaX, sigmaY – spatial influence (spread)
• uncertainty ∈ [0,1] – confidence of the soil label

This allows soft, probabilistic integration of sparse soil observations into the traversability map.

---

Configuration Parameters

Key parameters in TraversabilityConfig that control traversability generation:

Obstacle Detection and Inflation

• maxStepHeight – Maximum step height the robot can traverse (default: 0.05m)
• obstacleInflationMultiplier – Scales robot radius for collision checking safety margins (default: 1.0)

Robot Configuration

• robotHeight – Robot body height including clearance to ground (default: 0.5m)

• robotSizeX, robotSizeY – Robot footprint dimensions (default: 0.5m)

• distToGround – Distance from body frame origin to ground (default: 0m)

• maxSlope – Maximum traversable slope in radians (default: 0.45 rad ≈ 26°)

• inclineLimittingMinSlope – Minimum slope where incline limiting activates (default: 0.22 rad)

• inclineLimittingLimit – Maximum path deviation from steepest slope direction (default: 0.43 rad)

• enableInclineLimitting – Enable orientation constraints on steep terrain (default: false)

• slopeMetric – Slope calculation method: NONE, AVG_SLOPE, MAX_SLOPE, TRIANGLE_SLOPE (default: NONE)

• slopeMetricScale – Scale factor for slope metric (default: 1.0)

Grid and Detection

• gridResolution – Resolution of traversability map (default: 0.3m)
• initialPatchVariance – Initial variance for patch generation (default: 0.0001)
• minTraversablePercentage – Threshold for unknown patch detection (default: 0.5)
• costFunctionDist – Corridor width for cost function influence (default: 0.0m)

Soil and Movement

• useSoilInformation – Enable soil-aware traversability (default: false)
• traverseSand, traverseRocks, traverseGravel, traverseConcrete – Soil type traversability flags
• allowForwardDownhill – Allow forward downhill movement (default: true)

---

Interactive GUI

GUI Controls

Below the visualization window, the GUI provides:

• Soil type dropdown
  • No selection (default)
  • CONCRETE
  • ROCKS
  • SAND
  • GRAVEL
• σx, σy spin boxes
  • Control the Gaussian spread of the soil sample
• Uncertainty spin box
  • Confidence of the soil label in the range [0, 1]

Interaction Logic

• Left-click on MLS Map with “No selection”

  • Sets the start pose
  • Triggers traversability expansion

• Left-click on MLS Map with a soil type selected

  • Sets the start pose
  • Adds a SoilSample at the clicked location
  • Triggers traversability expansion
  • Soil influence is applied on the traversability expansion

• Left-Click on button Reset Traversability and Soil Maps

  • Resets the data structures for traversability and soil map.

This interaction model ensures a clear separation between navigation setup and environment annotation.

Run Example with Test Data

You can quickly verify the setup by downloading and running the provided test datasets.

1. Download the sample point clouds

wget https://zenodo.org/records/13771864/files/utah.ply
wget https://zenodo.org/records/13771864/files/test_area.ply
wget https://zenodo.org/record/13789320/files/parking_deck.ply

2. Run the traversability generator

./build/gui/traversability_generator3d_bin-qt5 utah.ply
./build/gui/traversability_generator3d_bin-qt5 test_area.ply
./build/gui/traversability_generator3d_bin-qt5 parking_deck.ply

💡 Tip: The following enviroment variables can be used to control the behaviour of the logger: BASE_LOG_LEVEL Set to one of DEBUG, INFO, WARN, ERROR or FATAL to define the maximum logging level.

3. Inspect the results in the GUI

• After the GUI loads, left-click on the MLS map.
• The corresponding TraversabilityMap3d will expand and display navigable vs. non-navigable regions.

4. Code Walkthrough

A minimal executable is provided to demonstrate the full traversability generation pipeline on a real 3D point cloud. The walkthrough loads a point cloud, builds the MLS map, and computes the traversability and frontier regions.

💡 Tip: The start position is assumed to be at (0, 0, -distToGround).
If your point cloud is offset or uses a different coordinate frame, update the start position accordingly to ensure expansion begins on the ground surface.

Run the walkthrough using:

./build/test/travgen3d_walkthrough utah.ply

5. Tests

The traversability generator is validated using unit tests. The tests cover core functionality such as:

• Traversability map generation from MLS input
• Step-height handling and obstacle detection
• Frontier detection and frontier inflation

To build and run the test suite:

./build/test/test_TraversabilityGenerator3d

Acknowledgements

This library was developed at the DFKI Robotics Innovation Center and funded by the German Federal Ministry of Education and Research (BMBF).

License

This project is released under the BSD-3-Clause License.