Skip to content

Overview

ROS2 tools to work with OSM data and perform path planning.

About

This package parses a .gpx file with GPS waypoints into a Python class, queries OpenStreetMap for map features within the area, and serializes the result as a .mapdata file.

Parsed features are classified into three categories:

  • barriers — obstacles assumed to be untraversable (walls, buildings, fences, water…)
  • footways — paths intended for pedestrians
  • roads — areas intended for vehicles

Additional tools let you visualize the data, annotate it interactively, perform path planning, and publish a cost-aware footway point cloud for use in autonomous navigation.

The MapData class, the path planning modules, the create_mapdata CLI, and the interactive viewer work standalone — no ROS2 installation is required for data parsing, annotation, or planning. ROS2 is only needed for the osm_cloud publisher.

The package targets ROS2 Jazzy or later on Ubuntu 24.04, and Python 3.12+ for standalone use.

Sample .gpx files are provided in ./data/.

Installation

As a standalone Python package

git clone https://github.com/vras-robotour/map_data.git
cd map_data
pip install -e .

With ROS2 (colcon)

git clone https://github.com/vras-robotour/map_data.git
cd map_data
colcon build --packages-select map_data
source install/setup.bash

ros2_numpy must be built from source

The osm_cloud node depends on ros2_numpy, which is not released as a binary package in any ROS distribution — rosdep install cannot resolve it. Clone its jazzy branch into your colcon workspace and build it alongside this package.

Python Library

MapData and Way can be used directly in Python without a running ROS2 node. The only requirement is that the package is installed (e.g. via pip install -e . or a colcon build) so the parameters/ CSV files are accessible.

Examples

Parse a GPX file and save a .mapdata file:

from map_data.map_data import MapData

md = MapData("./data/coords.gpx")
md.run_all(save=True)  # queries OSM, parses, saves coords.mapdata

Load an existing .mapdata file and access parsed features:

from map_data.map_data import MapData

md = MapData.load("coords.mapdata")

print(len(md.roads_list))  # list of Way objects
print(len(md.footways_list))
print(len(md.barriers_list))

Project Structure

map_data/
├── map_data.py              # MapData class — parses GPX + OSM into roads/footways/barriers
├── info.py                  # CLI tool to print information about a .mapdata file
├── create_mapdata.py        # CLI (standalone or ROS2): download and parse OSM data
├── osm_cloud.py             # ROS2 node: publishes footway grid and intersections
├── pathsolver/              # Path planning algorithms
│   ├── graph_planner.py     # Global A* planning on OSM ways
│   ├── replan.py            # Local/Grid-based replanning (Grid A*, RRT*)
│   ├── grid_astar.py        # Grid-based A* implementation
│   ├── rrt_star.py          # RRT* implementation
│   └── astar.py             # Generic A* search logic
├── utils/                   # Shared utility functions
│   ├── way.py               # Way class — represents a single OSM feature with geometry
│   ├── overpass.py          # OSM Overpass API client
│   ├── parsing.py           # OSM XML/JSON parsing logic
│   ├── serialization.py     # .mapdata file I/O
│   └── points_to_graph_points.py # Equidistant point interpolation
└── viewer/                  # Modular interactive viewer (Flask + Leaflet)
    ├── app.py               # App factory and server entry point
    ├── routes.py            # REST API endpoints and GeoJSON conversion
    ├── helpers.py           # Geometry and annotation utility functions
    ├── cache.py             # MapData object caching
    ├── templates/           # HTML templates
    └── static/              # External CSS and Modular JS assets

License