[FEAT]: Flexible Node and Edge Properties System

[marc-hanheide]

Description

This feature request proposes extending the topological map schema to support arbitrary properties dictionaries for both nodes and edges, enabling flexible, application-specific metadata without requiring schema modifications.

Motivation

The current topological map structure has a fixed properties field in nodes (currently containing xy_goal_tolerance and yaw_goal_tolerance), but lacks extensibility for domain-specific applications. Different robotic applications require varied metadata that shouldn't necessitate core schema changes.

Proposed Feature

Add flexible properties dictionaries (represented as YAML maps) to both nodes and edges in the topological map schema.

Node Properties Examples

• row: Identifies which row a node belongs to (e.g., in agricultural polytunnel scenarios)
• semantics: Describes the semantic meaning of a node (e.g., "charging_station", "inspection_point", "rest_area")
• zone: Operational zone designation
• access_level: Permission level required for access
• capacity: Maximum number of robots that can occupy the node simultaneously

Edge Properties Examples

• max_speed: Maximum traversal speed for safety or operational constraints (m/s)
• priority: Preference weight for path planning (higher values indicate more preferred routes)
• width: Physical width of the traversable path (m)
• surface_type: Terrain classification (e.g., "concrete", "grass", "gravel")
• bidirectional: Boolean indicating if edge is bidirectional
• weather_restrictions: Conditions under which edge should not be used

Design Requirements

1. Backwards Compatibility: The properties field must be optional. Existing maps without properties should remain valid.
2. Flexible Schema: Support arbitrary key-value pairs without requiring schema updates for new property types.
3. YAML Map Format: Properties should be represented as YAML dictionaries for readability and ease of editing.
4. Type Flexibility: Support various data types (strings, numbers, booleans, lists) as property values.

Schema Extension

The schema should be extended as follows:

For nodes (at nodes[].node.properties):

properties:
  type: object
  additionalProperties: true
  description: "Flexible dictionary of application-specific node properties"

For edges (at nodes[].node.edges[].properties):

properties:
  type: object
  additionalProperties: true
  description: "Flexible dictionary of application-specific edge properties"

Example Usage

nodes:
- meta:
    map: riseholme
    node: ChargingStation1
    pointset: riseholme
  node:
    name: ChargingStation1
    parent_frame: map
    pose: # ... pose details
    properties:
      xy_goal_tolerance: 0.3
      yaw_goal_tolerance: 0.1
      semantics: "charging_station"
      row: 3
      zone: "A"
      capacity: 2
    edges:
    - edge_id: ChargingStation1_WayPoint2
      node: WayPoint2
      properties:
        max_speed: 0.5
        priority: 10
        surface_type: "concrete"
        bidirectional: true
      # ... other edge fields

Implementation Considerations

1. The schema file at config/tmap-schema.yaml needs to be updated to include the properties definitions.
2. Validation should ensure properties is a dictionary but not enforce specific keys.
3. Navigation and planning components should safely handle missing or unexpected properties.
4. Documentation should provide guidance on common property conventions while allowing application-specific extensions.

Related Issues

This feature builds upon the topological map structure discussion in #203.

Additional Context

The example map at network.tmap2.yaml already demonstrates node properties in use. This feature request formalises and extends this capability to edges whilst ensuring schema consistency and backwards compatibility.

Benefits

• Extensibility: Applications can add custom metadata without modifying core code
• Semantic Richness: Enable rich semantic annotations for improved decision-making
• Application Specialisation: Support domain-specific requirements (agriculture, warehousing, hospitals, etc.)
• Planning Enhancement: Enable property-aware path planning (speed limits, priorities, restrictions)
• Backwards Compatibility: Existing maps continue to work without modification