OpenStreetMap Area Graph (osmAG) Overview

• osmAG is a hierarchical semantic topometric map representation using OSM XML that encodes navigable areas and explicit passage connections.
• It integrates indoor/outdoor and multi-floor environments, incorporating topology, metric geometry, and annotations like stairs and elevators.
• The system supports efficient planning, localization, and reactive navigation through compact, structured area and passage graphs.

OpenStreetMap Area Graph (osmAG) is a hierarchical semantic topometric map representation, and later a map standard, that encodes environments in OpenStreetMap (OSM) XML for mobile robotics. Its defining abstraction is an Area Graph in which areas are the primary spatial entities and passages are the traversable connections between them; unlike dense occupancy grids or point clouds, osmAG is intended to store topology, metric geometry, semantics, and hierarchy in one compact representation that spans indoor and outdoor space, multiple floors, and robot-relevant annotations such as stairs, elevators, door types, and terrain attributes (Feng et al., 2023, Zhang et al., 30 Mar 2026).

1. Conceptual origin and evolution

osmAG was introduced as an OSM-XML-based file format for “hierarchical semantic topometric Area Graph maps” because, in the cited formulation, no such format was popular within the robotics community (Feng et al., 2023). The original motivation was to preserve what large-scale navigation and localization require at the global level—free-space structure, passages, semantics, and hierarchy—without inheriting the storage and scaling costs of point clouds, voxels, or monolithic occupancy grids. The representation was explicitly designed for mixed indoor/outdoor, multi-floor environments, and for planning conditioned on robot capabilities such as locomotion mode, curb handling, or door interaction (Feng et al., 2023).

The literature uses closely related expansions of the acronym. One paper describes osmAG as “Area Graph in OpenStreetMap format,” emphasizing the serialization of an Area Graph into OSM XML for compatibility with conventional robotic algorithms, humans, and LLMs (Xie et al., 2024). Later work treats osmAG as the “OpenStreetMap Area Graph” map standard and builds a full ROS2 navigation stack around it, indicating a shift from a file-format proposal to a broader systems substrate for planning, localization, and long-horizon autonomy (Zhang et al., 30 Mar 2026).

A central design decision is that osmAG is region-centric rather than point-centric. In the original formulation, an area is a free-space polygon such as a room, corridor, terrain region, street segment, or larger grouped space, and a passage is a traversable connection between adjacent areas (Feng et al., 2023). Later canonical descriptions sharpen this into an undirected area graph whose vertices are Areas and whose edges are Passages, with inner areas such as rooms, corridors, elevators, and stairs coexisting with structure areas such as floors, sectors, wings, and buildings (Zhang et al., 30 Mar 2026). This makes osmAG closer to architectural and functional decomposition than to classical street-network graphs or occupancy-grid cells.

2. Representational model and OSM encoding

At the data-model level, osmAG reuses the OSM/XML object model. Areas and passages are serialized as OSM way elements, while their geometry is stored as OSM node coordinates in WGS84; a designated root node anchors the local Cartesian robotic frame to geodetic OSM coordinates (Feng et al., 2023, Zhang et al., 30 Mar 2026). In the 2023 formulation, the core reinterpretation is simple: a closed way denotes an area, and a line-like way denotes a passage (Feng et al., 2023). This preserves compatibility with existing OSM tooling while assigning robotics-specific semantics to OSM primitives.

An area is a closed polygon defined by an ordered list of OSM nodes, and a passage is an explicit connector between two areas, represented geometrically as a line segment or short polyline on a shared interface; doors, corridor openings, elevator interfaces, and stair transitions are all modeled this way (Zhang et al., 30 Mar 2026). The hierarchy is encoded through parent-child containment. Rooms can belong to floors, floors to buildings, and buildings to campuses; later work extends the same mechanism to floors, sectors, and wings, with lowest-common-ancestor reasoning used directly by the planner (Feng et al., 2023, Zhang et al., 30 Mar 2026).

The schema has evolved but remains centered on a stable set of tags and constraints (Feng et al., 2023, Zhang et al., 30 Mar 2026).

Tag or field	Function	Note
osmAG:id	Stable osmAG-internal identifier	Introduced to avoid dependence on mutable OSM IDs
osmAG:type	Distinguishes area vs passage	Core discriminator in both early and later descriptions
osmAG:from, osmAG:to	Passage endpoints	Store the two incident areas of a passage
osmAG:parent	Hierarchical containment	Encodes parent area
osmAG:areatype / osmAG:areaType	Area category	Early work emphasizes inner vs structure; later work uses classes such as room, corridor, structure, elevator, stairs
height, level	Elevation and floor information	Used for multi-floor modeling

The later canonical schema also imposes validity constraints: hierarchy must form a tree or forest, children must lie geometrically within parents, sibling areas on the same level under the same parent must have disjoint interiors, and each passage must connect exactly two existing named areas (Zhang et al., 30 Mar 2026). Vertical topology is represented natively rather than by planner-side special cases: each floor-specific elevator or stair footprint is its own area, and inter-floor passages connect those floor-specific vertical areas across adjacent floors (Zhang et al., 30 Mar 2026).

This representational choice also explains why osmAG is described as topometric rather than merely topological. The map is sparse enough for graph reasoning, but areas remain polygons and passages remain geometric connectors. The planner can therefore render local submaps, compute within-area traversal costs, and retain human-readable semantics at the same time (Feng et al., 2023, Zhang et al., 30 Mar 2026).

3. Map generation, hierarchy formation, and source modalities

osmAG maps can be constructed from several upstream modalities. The original paper states that osmAGlib can convert from 2D grid maps using earlier Area Graph extraction work, from CAD files after manual layer cleanup, from 3D point clouds using previous hierarchical topometric mapping work, and by merging multiple maps based on node distances and point consolidation (Feng et al., 2023). This already positioned osmAG as a unifying output layer rather than a sensor-specific map.

The most explicit generation pipeline appears in “Generation of Indoor Open Street Maps for Robot Navigation from CAD Files” (Zhang et al., 1 Jul 2025). There the workflow is a complete and automated system that converts architectural CAD floor plans into a hierarchical topometric OSM representation tailored to robot navigation. The pipeline first isolates key structural layers from raw CAD data, then applies AreaGraph-based topological segmentation to partition the building layout into a hierarchical graph of navigable spaces, automatically associates textual labels from the CAD source, and finally merges multiple building floors into a unified, topologically-correct model (Zhang et al., 1 Jul 2025). The paper characterizes this as an alternative to SLAM-centric map production in large, dynamic indoor spaces, because CAD encodes permanent structural information rather than transient clutter (Zhang et al., 1 Jul 2025).

AreaGraph-based segmentation is the critical intermediate step. The free-space layout inferred from walls and openings is partitioned into rooms, corridors, and related navigable subregions, with passages aligned to doors or other transitions. The details trace back to the cited AreaGraph line of work rather than being re-derived in the CAD paper, but the role is explicit: the final osmAG is an OSM-encoded hierarchical graph of navigable areas rather than a raw floor-plan export (Zhang et al., 1 Jul 2025).

Hierarchy is not only descriptive. In the original osmAG design, multiple neighboring areas can be grouped into larger areas for abstraction, while floors are stacked as 2D areas with height annotations (Feng et al., 2023). Later work generalizes this into building $\supset$ floor $\supset$ sector $\supset$ room containment trees, enabling campus-scale and multi-floor maps to be represented uniformly (Zhang et al., 30 Mar 2026). This suggests that osmAG is best understood as a layered semantic decomposition of navigable space rather than a flat adjacency graph.

4. Planning, localization, and navigation systems

A recurrent theme in the osmAG literature is that planning cost does not reside naturally on area vertices. The 2023 paper argues that planning directly on the area graph is problematic because traversal cost is associated with moving through an area from one passage to another, not merely with entering or leaving a node (Feng et al., 2023). It therefore renders each area as a local 2D grid and computes within-area traversal cost with A*, then transforms the problem into a passage graph in which vertices are passages and edges represent feasible traversals across an area (Feng et al., 2023). The planning procedure finds the leaf areas of the start and goal, temporarily connects start and goal to the passages of their containing areas using A* on rendered 2D grids, then runs A* in the passage-level graph and returns either a list of passages and areas or point-wise traces from the local grids (Feng et al., 2023).

The first quantitative demonstration used a large osmAG map containing two multi-story buildings and one outdoor area, with 4908 nodes, 500 areas, and 347 passages in an 883.9 kb XML file. The reported indoor area was approximately $22300\,m^2$, the outdoor area approximately $3000\,m^2$, the planned path length $157.57\,m$, topological-level planning time about $3100\,\mu s$, and pre-computation time about $200\,ms$ on an Intel i7-6700 CPU (Feng et al., 2023). These results established the compactness and mixed indoor/outdoor, multi-floor planning scope of the representation.

The full systems elaboration is “osmAG-Nav: A Hierarchical Semantic Topometric Navigation Stack for Robust Lifelong Indoor Autonomy” (Zhang et al., 30 Mar 2026). That stack adopts a “System of Systems” architecture separating global semantic-topological reasoning from local metric execution. A Hierarchical osmAG planner replaces dense grid searches with an LCA-anchored pipeline over a passage-centric graph whose edge costs derive from local raster traversability rather than Euclidean distance; a Rolling Window rasterizes a fixed-size local occupancy grid around the robot; and Segmented Execution dispatches intermediate goals to standard ROS2 controllers (Zhang et al., 30 Mar 2026). The frame decomposition is also explicit: AGmap for global semantic-topological reasoning, map for metric navigation consumed by Nav2, and odom for short-term motion (Zhang et al., 30 Mar 2026).

The performance claims are correspondingly system-level. On a real multi-story indoor-outdoor campus of more than $11{,}025\,m^2$, the osmAG representation required 1.4 MB for the whole campus, compared to about 48.5 MB for a 2D occupancy grid at 0.05 m resolution and about 1536 MB for a 0.1 m voxel point cloud (Zhang et al., 30 Mar 2026). On 696 same-floor benchmark queries, hierarchical osmAG planning reached $1.361\,ms$ on long routes versus $\supset$0 for Grid A*, yielding the reported $\supset$1 lower planning latency on long routes while maintaining low path-length overhead (Zhang et al., 30 Mar 2026). A caching ablation showed that removing static caches increased hierarchical query latency from $\supset$2 to $\supset$3 without changing paths, identifying cached compact graphs as a decisive implementation detail (Zhang et al., 30 Mar 2026).

Localization has followed the same structure-first logic. In osmAG-Nav, AGLoc++ performs structure-aware LiDAR localization against permanent architectural priors, filtering dynamic clutter before point-to-line ICP and reporting $\supset$4 per frame, lab ATE $\supset$5, and corridor ATE $\supset$6, compared with larger corridor errors for both the original AGLoc and AMCL (Zhang et al., 30 Mar 2026). A separate WiFi-based localization framework leverages “osmAG's geometric and topological priors” in a large-scale indoor environment: its abstract reports mean AP localization error $\supset$7, a $\supset$8 improvement over trilateration, mean robot localization error $\supset$9 in fingerprinted areas, and $\supset$0 in non-fingerprinted areas, with an $\supset$1 improvement in the latter case over the comparison baseline across an $\supset$2 multi-floor environment (Ma et al., 13 Aug 2025). The supplied material for that paper does not include the missing methods section, so its precise osmAG instantiation is not recoverable from the provided text, but the structural-prior role is explicit (Ma et al., 13 Aug 2025).

5. Textual reasoning, LLM comprehension, and reactive autonomy

A distinctive feature of osmAG is that, because it is serialized in OSM XML and can be reduced to a compact textual form, it has been used not only by conventional planning and localization algorithms but also by LLMs. “Empowering Robot Path Planning with LLMs: osmAG Map Topology & Hierarchy Comprehension with LLMs” treats osmAG as a text-based hierarchical, topometric semantic map representation and evaluates LLMs on topology and hierarchy comprehension rather than metric reasoning (Xie et al., 2024). In that work, areas are graph nodes, passages are line segments of area polygons connecting neighboring areas, and parent-child tags encode containment chains such as room $\supset$3 zone $\supset$4 floor $\supset$5 wing $\supset$6 building (Xie et al., 2024). The authors introduced textual variants of osmAG in which connectivity is made increasingly explicit, including a connected_area tag and a more lexicalized current area name_directly_connected_room form, and found that the textualization materially affected comprehension (Xie et al., 2024).

The quantitative result is that base LLaMA2 models were weak on osmAG comprehension, while fine-tuned models became highly accurate. Fine-tuned LLaMA2-13B reached $\supset$7 on the main topological Dataset 2, $\supset$8 on the unseen-layout Dataset 3, and $\supset$9 on the hierarchical Dataset 4, exceeding ChatGPT-3.5 and, on Dataset 2, surpassing ChatGPT-4.0 as reported in the paper (Xie et al., 2024). The same work also describes a real-life demonstration in which ChatGPT-4 replanned around an elevator closure after being given an email notification, using osmAG as the structural map prior (Xie et al., 2024). This made explicit a use case already implicit in the design: osmAG can serve as a shared textual and geometric substrate between symbolic reasoning and conventional navigation.

HaltNav extends this idea from map comprehension to closed-loop vision-language navigation under changing local connectivity (Li et al., 13 Mar 2026). There the prior is modeled as a dynamic weighted directed graph

$22300\,m^2$0

with semantic nodes corresponding to regions and traversable passages represented in the edge set (Li et al., 13 Mar 2026). The actual planner operates on a derived passage-level graph

$22300\,m^2$1

where stored traversal costs between passages are maintained over time (Li et al., 13 Mar 2026). When Reactive Visual Halting detects that the world contradicts the static prior, the planner updates the cost matrix by

$22300\,m^2$2

This converts a blocked connector into a pruned topological option without rebuilding the whole map (Li et al., 13 Mar 2026).

In simulation and on a real Fetch robot in a university building, the paper reports that this osmAG-grounded hierarchy improves robustness under sparse instructions and blocked doors. In real-world obstacle settings, HaltNav achieved success rates of $22300\,m^2$3 for L0-O and $22300\,m^2$4 for L2-O, while both baselines in those obstacle settings collapsed to $22300\,m^2$5 success rate (Li et al., 13 Mar 2026). The paper interprets this as evidence that lightweight topological priors are essential, not merely helpful, for robust real-world VLN under underspecified instructions and environmental changes (Li et al., 13 Mar 2026).

6. Distinctions, trade-offs, and recurrent misconceptions

osmAG is frequently adjacent to, but should not be conflated with, several other OSM-derived graph families. Street-network graphs such as the OSMnx-style primal, directed, nonplanar weighted multidigraphs of intersections and street segments are fundamentally intersection-centric rather than area-centric (Boeing, 2017). Billion-scale systems such as OSM+ standardize OSM into road-network graphs whose vertices are intersections and POI points and whose edges are road segments, again without an area-passage decomposition (Zheng et al., 7 Dec 2025). Heterogeneous local OSM graphs such as OSMGraphCLIP keep points, lines, and polygons as typed nodes connected by DE-9IM-style relations, which is useful for geospatial representation learning but is not the same as osmAG’s navigable area hierarchy (Michail et al., 6 Jun 2026). WorldKG, similarly, is an ontology-backed semantic geographic knowledge graph over OSM entities rather than a topometric navigation graph over areas and passages (Dsouza et al., 2021).

A common misconception is that osmAG is merely raw OpenStreetMap adapted for indoor maps. The papers are more specific. osmAG is a robotics-oriented convention layered on top of OSM XML that reinterprets OSM primitives to encode navigable free-space areas, passages, hierarchy, and robotics-specific semantics such as locomotion-relevant surface or door properties (Feng et al., 2023). Another misconception is that it simply replaces occupancy grids. The later navigation stack is explicit that local metric rasterization remains necessary; osmAG replaces the monolithic global grid with sparse global semantics and topology, while Nav2 still consumes bounded occupancy grids produced by the Rolling Window mechanism (Zhang et al., 30 Mar 2026).

The trade-offs are equally explicit. The original proposal is largely offline and acknowledges manual effort in some source modalities, such as CAD layer cleanup (Feng et al., 2023). Later work notes that osmAG assumes environments can be decomposed into meaningful areas and passages; in open-plan or weakly structured spaces, segmentation may be ambiguous (Zhang et al., 30 Mar 2026). The topology is treated as structurally static: the current systems invalidate blocked passages or assign infinite traversal cost, but do not learn entirely new connectivity online (Li et al., 13 Mar 2026, Zhang et al., 30 Mar 2026). Edge costs remain geometry-aware proxies derived from raster A* rather than full kinodynamic or learned semantics (Zhang et al., 30 Mar 2026). And while cross-floor planning is native, fully autonomous physical elevator interaction still requires additional engineering modules such as behavior-tree orchestration, floor recognition, and transition-specific recovery (Zhang et al., 30 Mar 2026).

Taken together, these works define osmAG as a compact OSM-based representation for structured navigable space: areas as first-class entities, passages as explicit transitions, hierarchy as a planning primitive, and semantics as a bridge between embodiment, architecture, and high-level reasoning. Its subsequent uses in ROS2 navigation, LiDAR and WiFi localization, LLM map comprehension, and reactive vision-language navigation indicate that the representation is not merely a storage format but a unifying abstraction for large-scale, multi-floor, semantically grounded mobile autonomy (Feng et al., 2023, Zhang et al., 30 Mar 2026, Xie et al., 2024, Li et al., 13 Mar 2026, Ma et al., 13 Aug 2025).