Skip to content
drawtonomy drawtonomy

ROS occupancy grid map format

The ROS occupancy grid map is a pair of files — typically map.pgm and map.yaml — that describes a 2D top-down view of a robot’s environment. It is the canonical map format consumed by ROS navigation stacks (nav1 map_server, nav2 map_server) and produced by SLAM packages like gmapping, Cartographer, and slam_toolbox.

What the two files contain

Section titled “What the two files contain”

The .pgm file is a grayscale Portable Gray Map image. Pixel values encode occupancy:

  • Dark pixels — occupied (obstacles, walls).
  • Light pixels — free space.
  • A specific gray (often 205) — unknown.

The .yaml file describes how to interpret the image in metric coordinates:

image: map.pgm
resolution: 0.05            # metres per pixel
origin: [-12.2, -28.5, 0.0] # bottom-left corner in (x, y, yaw)
negate: 0
occupied_thresh: 0.65
free_thresh: 0.196

resolution and origin together let any downstream tool turn pixel coordinates into world coordinates and back.

Where this format comes from in practice

Section titled “Where this format comes from in practice”

The most common pipelines:

  1. Drive the robot manually and feed odometry + 2D lidar to gmapping or slam_toolbox; save the resulting map.
  2. Run Cartographer offline on a bag file and export the occupancy grid.
  3. Convert from another format — .bt, OctoMap projection, or a custom format.

The output is then loaded by map_server for localisation (AMCL) and planning (nav2).

Where drawtonomy fits

Section titled “Where drawtonomy fits”

drawtonomy imports .pgm + .yaml pairs and lets you annotate the occupancy grid in the browser:

  • The map is shown to scale on the canvas using the resolution and origin metadata.
  • You can draw lanes, intersections, vehicles, pedestrians, and traffic signs on top of the map.
  • The annotations are stored separately as drawtonomy shapes — the original .pgm is not modified.
  • Useful for paper figures (a SLAM map with planned routes drawn on it), teaching (annotate what the planner sees), and quick ground-truth labelling.

This is intentionally a one-way import: drawtonomy is not a replacement for nav2’s map editing tools. It’s a convenient option when you want a visually clean, publishable annotation of a SLAM map.

See Import ROS occupancy grid for the import workflow.

Section titled “Related reading”