Topological YAML Format

Topological Navigation Map Format Documentation

DISCLAIMER: This Documentation has been created with the help of an LLM, based on examples and some contextual information. It may not be entirely accurate

This document describes the YAML format used for topological navigation maps in ROS2-based navigation systems. The format defines a graph-based representation of navigable spaces, where nodes represent locations and edges represent navigable paths between locations.

File Structure Overview

The topological map is defined in YAML format with the following top-level structure:

meta:
  last_updated: YYYY-MM-DD_HH-MM-SS
metric_map: <map_name>
name: <topological_map_name>
nodes: 
  - <node_definitions>
pointset: <pointset_name>
transformation: <optional_transformation_data>

Field Descriptions

Top-Level Fields

• meta: Contains metadata about the map
  • last_updated: Timestamp of the last map update
• metric_map: Name of the underlying metric map
• name: Identifier for the topological map
• nodes: Array of node definitions that make up the topological map
• pointset: Name of the point set collection
• transformation: Optional transformation data

Node Structure

Each node in the nodes array has the following structure:

- meta:
    map: <map_name>
    node: <node_id>
    pointset: <pointset_name>
  node:
    edges: []
    localise_by_topic: ""
    name: <node_name>
    parent_frame: <frame_id>
    pose: {}
    properties: {}
    restrictions_planning: <string>
    restrictions_runtime: <string>
    verts: []

Node Fields

• meta: Node metadata

  • map: Reference to the metric map
  • node: Unique node identifier
  • pointset: Reference to the point set collection

• node: Main node definition

  • edges: Array of connected edges
  • localise_by_topic: Topic name for localization (if used)
  • name: Human-readable node name
  • parent_frame: Reference coordinate frame (usually "map")
  • pose: Node position and orientation
  • properties: Node-specific properties
  • restrictions_planning: Planning-time restrictions
  • restrictions_runtime: Runtime restrictions
  • verts: Vertex definitions for node geometry

Edge Structure

Each edge in a node's edges array has the following structure:

- action: NavigateToPose
  action_type: geometry_msgs/PoseStamped
  config: []
  edge_id: <source_node>_<target_node>
  fail_policy: fail
  fluid_navigation: true
  goal:
    target_pose:
      header:
        frame_id: $node.parent_frame
      pose: $node.pose
  node: <target_node>
  recovery_behaviours_config: ""
  restrictions_planning: <string>
  restrictions_runtime: <string>

Edge Fields

• action: Navigation action to execute (typically "NavigateToPose")
• action_type: Message type for the action
• config: Additional configuration parameters
• edge_id: Unique identifier for the edge (typically source_node_target_node)
• fail_policy: Behavior on navigation failure
• fluid_navigation: Enable/disable fluid navigation
• goal: Target pose information
• node: Target node identifier
• recovery_behaviours_config: Recovery behavior settings
• restrictions_planning: Planning-time restrictions
• restrictions_runtime: Runtime restrictions

Pose Structure

The pose field uses the following structure:

pose:
  orientation:
    w: <float>
    x: <float>
    y: <float>
    z: <float>
  position:
    x: <float>
    y: <float>
    z: <float>

Properties

Common node properties include:

properties:
  xy_goal_tolerance: <float>  # Typically 0.3
  yaw_goal_tolerance: <float> # Typically 0.1

Vertices

Vertices define the geometry of the node, typically in a polygon format:

verts:
  - x: <float>
    y: <float>

Example

Here's a minimal example of a topological map:

meta:
  last_updated: 2024-12-20_10-00-00
metric_map: example_map
name: example_topology
nodes:
  - meta:
      map: example_map
      node: WayPoint1
      pointset: example_pointset
    node:
      edges:
        - action: NavigateToPose
          action_type: geometry_msgs/PoseStamped
          edge_id: WayPoint1_WayPoint2
          fail_policy: fail
          fluid_navigation: true
          goal:
            target_pose:
              header:
                frame_id: map
              pose: $node.pose
          node: WayPoint2
          restrictions_planning: "True"
          restrictions_runtime: obstacleFree_1
      name: WayPoint1
      parent_frame: map
      pose:
        orientation:
          w: 1.0
          x: 0.0
          y: 0.0
          z: 0.0
        position:
          x: 1.0
          y: 1.0
          z: 0.0
      properties:
        xy_goal_tolerance: 0.3
        yaw_goal_tolerance: 0.1
      verts:
        - x: -0.5
          y: 0.5
        - x: 0.5
          y: 0.5
        - x: 0.5
          y: -0.5
        - x: -0.5
          y: -0.5

Common Restrictions

The map format supports two types of restrictions:

• restrictions_planning: Applied during path planning
• restrictions_runtime: Applied during navigation execution

Common values include:

• "True": Default restriction
• obstacleFree_1: Requires obstacle-free space
• robot_short: Specific to shorter robot configurations
• robot_tall: Specific to taller robot configurations

Notes

1. Node names are typically in the format WayPointX where X is a number
2. Edge IDs are formed by combining source and target node names with an underscore
3. The $node.pose and $node.parent_frame are special variables that reference the target node's properties
4. Vertex coordinates are relative to the node's position
5. All coordinates are in meters, and angles are in radians