Reading a Nav2 Costmap: Why a Colored Grid Is Not the Same as a Floor Plan

A robot navigation display may show a floor plan, a colored grid and a planned path at the same time. These are related views, but they are not interchangeable. When a robot refuses to plan through an apparently clear corridor, the first useful step is to identify which layer and which moment the display represents. A screenshot by itself does not establish the cause or prove that the route is safe.

What a costmap represents

Nav2 describes its environmental representation as a grid whose cells represent conditions such as free, occupied, unknown or inflated cost. Its environmental representation guide explains how layers combine information for navigation. The display is a representation used by the navigation system, not a complete physical survey of everything in the environment.

A source map, a sensor observation and a costmap are different artifacts. A source map may describe relatively persistent features; a sensor may observe something at a particular time; the costmap combines selected inputs according to its configuration. A planner then uses available information to calculate a path. Each step has its own settings and potential limitations.

Read the layers separately

The Nav2 navigation plugin list identifies a static layer, an obstacle layer and an inflation layer among other plugins. The static layer uses map information; the obstacle layer can mark obstacles from supported sensor observations; the inflation layer adds cost around obstacles. The installed Nav2 version and actual configuration determine which plugins are present and how they behave.

Consider a hypothetical corridor that appears open on the underlying map but has a high-cost band near a shelf in the navigation display. A reviewer should establish whether the band comes from a static map, a sensor observation, inflation or another configured layer. Merely seeing a color near the shelf does not prove that the sensor reported a physical object at every colored cell.

Check time and reference frames

Record when the map, sensor data, robot pose and costmap were observed. A visualization may show information produced at different times, especially when a system is being started or data is delayed. Note the coordinate frames used and whether the expected transforms were available. A visually plausible overlay is not enough to prove that all inputs refer to the same time and location.

For a reproducible report, capture the software release, map identity, configured layers, sensor source and the relevant log or recording. If the map or settings changed, include the revision. If an observation is missing, write that it was not captured instead of describing the missing data as free space.

Separate a planning question from a safety decision

A path that is not produced can have several explanations, including the goal, robot footprint, configured costs, available transforms or planner conditions. A path that is produced does not by itself prove that a real robot can safely travel it. People, moving objects, sensor blind spots and the wider system's safeguards require their own assessment.

Do not reduce obstacle-related costs or change the robot footprint simply to make a route appear in a demonstration. Such changes can affect behavior and safety. Use a controlled simulation or approved test area first, and have the responsible engineering and safety personnel review any configuration changes before deployment.

Make a comparison that another learner can repeat

A useful exercise starts with a fixed example map and a harmless simulated obstacle. Record which layer is enabled, where the simulated object is placed and which view is being examined. Compare the source map with the costmap and document what changed. Then remove the simulated object using the tutorial's approved process and observe whether the displayed result changes. The exact behavior depends on the version and configuration, so keep the exercise notes with the setup.

If the display does not change as expected, check the data source and recorded timestamps before asserting a software defect. Preserve the original configuration and logs for review. Avoid collecting or publishing identifiable images or sensitive facility maps unless sharing is authorized.

What to hand over to an engineer

Provide a concise description of the goal, the observed path or planning failure, the time, the relevant map and the layers shown. Include the robot model and software versions only to the extent needed, and state whether the example was simulated or observed on physical equipment. Ask a specific question such as “Which input marked this area?” instead of “Why is navigation broken?”

Related introductions on this site explain nodes, topics and frames and ROS 2 services and actions. The robot learning section contains further context. This article is an educational reading aid, not a deployment or safety validation procedure.