How to edit a ROS map

1. Open both files. Choose the .pgm image first, then the .yaml file saved next to it by map_saver_cli or slam_toolbox. The metadata panel fills in from the YAML.
2. Zoom in and pick a brush. Use Free to erase stray LiDAR returns, people who walked through the scan and noise in open areas. Use Occupied to close gaps in walls, such as glass doors the laser saw through.
3. Mark areas the robot must avoid. The keep-out rectangle paints a solid occupied block. Use it for stairs, drop-offs and areas the robot must never plan through.
4. Check the metadata. Leave resolution and origin alone unless you know they are wrong: they decide where the map sits in the world, and changing them shifts every saved goal.
5. Export both files. Download the .pgm and .yaml, copy them over the originals (keep a backup), and restart map_server or reload the map in Nav2.

How the colours become a costmap

In the default trinary mode, map_server converts every pixel to an occupancy probability and then to one of three states, using the thresholds in the YAML file:

A pixel of 0 gives p = 1.0 (occupied) and 254 gives p ≈ 0.004 (free). The grey 205 gives p ≈ 0.19608, just above 0.196, so whether it means unknown depends on free_thresh. We loaded the maps that ship with Nav2 on ROS 2 Jazzy into its map_server and counted the result: with free_thresh 0.196 or 0.1, grey pixels came out unknown; with 0.25, as in the shipped depot map, every grey pixel came out free. Maps saved with Nav2's map_saver_cli are written with 0.196, which is safe; hand-written or edited YAML files are where 0.25 creeps in. If you want unexplored space to stay unknown, keep free_thresh at 0.196 or lower; the editor warns you and can fix it.

That is also why the editor paints exactly 0, 254 and 205, and why a soft-edged brush from an ordinary image editor causes trouble: its in-between grey edge pixels land in whichever band the thresholds put them, leaving a ring of speckles around every stroke.

What to fix, and what to leave alone

• Fix: isolated dots in open floor, ghost obstacles from people or doors that moved, holes in walls caused by glass, mirrors or black surfaces, and areas outside the building that the laser saw through windows.
• Leave: real furniture that stays put, even when it is inconvenient, because the localiser (AMCL) uses it to match laser scans. Erasing permanent features makes localisation worse.
• Prefer masks for rules: if an area is only sometimes forbidden, or you want the robot to slow down rather than stop, draw it in a separate mask image and load it with a Nav2 costmap filter instead of painting it into the map itself.

Keep the original files. Map edits are easy to make and hard to undo once a fleet has been running on them for a while.