Nav2 Costmap Architecture and Plugin Order

Source: costmap-architecture

Why This Matters

Most Nav2 path-quality and collision-margin problems are not planner bugs. They come from costmap construction: the wrong frame, the wrong update timing, or a plugin sequence that causes one layer to overwrite or dilute another.

Distilled Takeaways

• A Nav2 costmap is not a single map. It is a master grid assembled from ordered plugins, and order is part of the algorithm.
• Global and local costmaps should usually solve different problems. Global costmaps carry map structure and planning-scale context; local costmaps carry immediate obstacle truth near the robot.
• Inflation should normally run last so earlier layers can mark lethal or unknown cells before inflation expands their cost gradients.
• Timing parameters matter operationally. A good plugin stack with poor update_frequency, publish_frequency, or transform_tolerance still produces laggy or inconsistent behavior.
• Cost interpretation matters: free is 0, unknown is typically 255, lethal is 254, and intermediate values carry the soft gradient that planners and controllers use differently.

Practical Guidance

• Treat the plugins list as ordered logic, not an unordered registry. If you move layers around, expect behavior to change.
• Put structural map content first, dynamic obstacle content next, policy filters after that, and inflation last.
• Use the global costmap to answer "where can I reasonably plan through the mapped world?" Use the local costmap to answer "what can I safely drive through right now?"
• Keep raytrace_range at least as large as obstacle_range for clearing layers, or stale obstacle marks will accumulate.
• If the robot seems to hug walls, clip corners, or refuse narrow corridors, inspect the costmap before replacing the planner or controller.

Typical Layer Sequences

Global costmap often starts from a pattern like:

plugins: ["static_layer", "obstacle_layer", "keepout_filter", "speed_filter", "inflation_layer"]

Local costmap often starts from a pattern like:

plugins: ["voxel_layer", "range_sensor_layer", "keepout_filter", "inflation_layer"]

The exact list varies by robot, but the sequence is deliberate: map and sensed obstacles first, policy overlays next, inflation last.

High-Value Parameters to Check First

• global_frame
• robot_base_frame
• resolution
• update_frequency
• publish_frequency
• transform_tolerance
• always_send_full_costmap
• track_unknown_space
• Per-layer combination_method

These explain a large fraction of real-world Nav2 failures.

Corroborating References

• Nav2 costmap configuration guide
• Nav2 costmap 2d package docs
• Nav2 tuning guide

When to Read the Original Source

Read the source skill when you want the exact cell-value conventions, plugin ordering rules, or a compact refresher on how the master costmap update loop combines layers.