OSM Visualization and Navigation For Autonomous Robotics

Project Overview

map_data is an open-source Python library and ROS2 package designed to bridge the gap between Geographic Information Systems (GIS) and autonomous mobile robot navigation. It allows developers and researchers to pull real-world geographic features from the OpenStreetMap (OSM) database, parse them, and construct dense, structured layered navigation grids suitable for global path planning, collision mapping, and lane keeping.

The package processes raw geographic geometries—such as roads, intersections, pedestrian pathways, buildings, and fences—and converts them into structured topological road network graphs or costmaps that autonomous planners can consume. It parses a .gpx file containing GPS waypoints into a Python class, queries OpenStreetMap for map features within the area, and serializes the parsed data into a compact .mapdata file.

Key Features

• Automated Geographic Fetching: Downloads raw OSM XML features via Overpass API queries based on coordinate bounding boxes.
• Navigation Layer Segmentation: Parsed features are classified into three distinct categories:
  • Barriers (barriers): Obstacles assumed to be untraversable (walls, buildings, fences, water, etc.).
  • Footways (footways): Paths intended for pedestrian travel and robot traversal.
  • Roads (roads): Main transit areas intended for vehicles.
• Interactive Editing Suite: Incorporates a Flask-based web editor (implemented with Leaflet) to inspect, tag, modify, and manually plan topological waypoint routes.
• ROS2 & GIS Export: Converts the processed map layers directly into ROS2 occupancy grids (nav_msgs/OccupancyGrid) or outputs standard GIS formats like GeoJSON, publishing a cost-aware footway point cloud.

Technical Architecture & ROS2 Integration

The map processing pipeline follows a simple, robust serialization logic:

1. Extraction: Raw nodes and ways are parsed from OpenStreetMap data.
2. Filtering: Elements are classified using standard OSM keys (e.g. highway, barrier, building).
3. Geometry Construction: Lines and points are converted into closed polygons or multi-line graphs representing road corridors.
4. Export: Layers are projected from global GPS coordinates (WGS84) to local metric Cartesian coordinates (UTM) for local path planners.

Standalone Runtime Design

A key design strength of map_data is its decoupled execution. The MapData core class, the path planning modules, and the interactive viewer work standalone — no running ROS2 context is required for data parsing, annotation, or planning. ROS2 is only needed for the osm_cloud publisher node and the create_mapdata CLI node.

• Target OS / Environment: ROS2 Humble or later on Ubuntu 22.04.

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

Python Library Usage

The MapData and Way classes can be imported and used directly in Python scripts as long as the package is installed (e.g., via pip or colcon build) to access base configuration files.

Parse a GPX file and save map data

from map_data.map_data import MapData

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

Load an existing .mapdata file and access parsed features

from map_data.map_data import MapData

# Load serialized data
md = MapData.load("coords.mapdata")

print(f"Roads: {len(md.roads_list)}")        # List of Way objects
print(f"Footways: {len(md.footways_list)}")
print(f"Barriers: {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        # ROS2 node / CLI: 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

For full implementation details, API references, and advanced usage, refer to the Official Documentation Page.