Feature: Add SurfaceConditionFilter costmap filter plugin

[aki1770-del]

Background

Nav2's costmap filter framework provides SpeedFilter, KeepoutFilter, and BinaryFilter as built-in plugins. Each reads an OccupancyGrid filter mask and applies a different behavior when the robot enters a marked zone.

There is currently no filter for hazardous road surface conditions — ice roads, snow-covered passes, or zones where the map data (OSM highway=winter_road, highway=ice_road) indicates degraded traction. Operators who annotate such zones on their maps have no pluggable way to feed that annotation into the Nav2 costmap/planner pipeline.

Proposal

Add SurfaceConditionFilter — a new costmap filter plugin following the SpeedFilter pattern:

• Reads a CostmapFilterInfo + OccupancyGrid filter mask (same subscription pattern as existing filters)
• When the robot is in a marked cell, publishes std_msgs::msg::Bool to a configurable surface_condition_topic (allows downstream nodes to adapt behavior — slow down, increase warning threshold, change planner params)
• Inflates costmap costs in hazardous zones by a configurable cost_scaling_factor, causing the planner to prefer routes that avoid those zones when alternatives exist
• Adds SURFACE_CONDITION_FILTER = 4 to filter_values.hpp

Motivation

With growing OSM coverage of highway=winter_road (~35K ways) and highway=ice_road (~15K ways), and ADAS systems reading surface condition signals from VSS (Vehicle.RoadCondition.SurfaceCondition), there is a clear integration gap in Nav2. This plugin would close it at the costmap layer — the right architectural boundary.

Implementation sketch

3 new files + 3 modified files:

• plugins/costmap_filters/surface_condition_filter.cpp (~200 lines)
• include/nav2_costmap_2d/costmap_filters/surface_condition_filter.hpp (~60 lines)
• costmap_plugins.xml — add class entry
• CMakeLists.txt — add to filters library
• filter_values.hpp — add constant

Happy to open a PR if this direction looks good to you.

AI-assisted — authored with Claude, reviewed by Komada.

[SteveMacenski]

Is this a sufficiently generalized need for us to put this in the Nav2 stack itself? SurfaceConditionFilter seems pretty use-case specific. I think we'd all be happy in the community to have more user-generated costmap layers / filters but perhaps this is something more suitable for you to open-source on your own github profile / company organization.

For it to be in Nav2, we'd probably want this to be more generalized, which also may be possible if we reframe this a little. Is the only action you plan to take to adjust the inflation parameters in these zones? If so, a costmap filter that adjusts parameter profiles by its position is very reasonable (so that it changes the inflation cost scaling, max speeds, etc all in 1 go). Certainly could still publish out an "FYI" message on a topic as well that the event occurred.

[aki1770-del]

Is this a sufficiently generalized need for us to put this in the Nav2 stack itself? SurfaceConditionFilter seems pretty use-case specific. I think we'd all be happy in the community to have more user-generated costmap layers / filters but perhaps this is something more suitable for you to open-source on your own github profile / company organization.

For it to be in Nav2, we'd probably want this to be more generalized, which also may be possible if we reframe this a little. Is the only action you plan to take to adjust the inflation parameters in these zones? If so, a costmap filter that adjusts parameter profiles by its position is very reasonable (so that it changes the inflation cost scaling, max speeds, etc all in 1 go). Certainly could still publish out an "FYI" message on a topic as well that the event occurred.

Thanks for the feedback, Steve — the generalization point is well taken.

To answer your question: the core actions I had in mind were exactly what you described — adjusting inflation cost scaling and max speed in marked zones. The surface condition framing was the motivating use case (winter roads, ice), but you're right that the mechanism is general: a costmap filter that applies a parameter profile based on position.

I like your reframe. A ZoneParameterFilter (or whatever name fits Nav2 conventions) that takes a filter mask and a set of parameter overrides — inflation radius, cost scaling factor, max speed, optionally a notification topic — would cover the winter road use case and a lot more besides. Construction zones, school zones, indoor/outdoor transitions.

Would you be open to a PR along those lines? I'm happy to draft it if the general shape sounds right to you.

[SteveMacenski]

Please! I would just point out this as a reference of an old PR that intended to do something somewhat similar but was either blocked, never completed, or otherwise not properly designed #3796

I'd suggest maybe having the mask represent some enum value (i.e. 1,2,3,4) which in the configuration of the layer corresponds with a state (i.e. state 1 = full speed, inflation radius = X). Also probably need some "reset" state for value 0 or unset to reset all the values back to their nominal conditions.

[aki1770-del]

Please! I would just point out this as a reference of an old PR that intended to do something somewhat similar but was either blocked, never completed, or otherwise not properly designed #3796

I'd suggest maybe having the mask represent some enum value (i.e. 1,2,3,4) which in the configuration of the layer corresponds with a state (i.e. state 1 = full speed, inflation radius = X). Also probably need some "reset" state for value 0 or unset to reset all the values back to their nominal conditions.

Thanks for the reference to #3796 — I read through it. The boolean-param approach there ran into two problems: it only handled bool parameters (not the double values needed for speed/inflation_radius), and the spin_until_future_complete in the callback drew review friction.

The enum design you're describing addresses both: each integer state in the mask maps to a configured set of parameters (any type), and state 0 is an explicit reset. Something like:

surface_condition_filter:
states:
1: {/controller_server.FollowPath.max_vel_x: 0.5, /local_costmap.inflation_layer.inflation_radius: 0.8}
2: {/controller_server.FollowPath.max_vel_x: 0.2, /local_costmap.inflation_layer.inflation_radius: 1.2}

Does this match what you had in mind? And is there an existing enum type in nav2 that makes sense to reuse for the state definition, or should I define a new one?

[SteveMacenski]

Yeah exactly. Occ grids are 0-255, so you have that many possible states to work with (where we should probably set 0 as a special "reset" default base state). I don't think we need any custom enums; basically just have the layer's configuration file map each possible value (1,2,3,etc) to the parameters. If a value is in the occ grid not in the configuration file, log warnings / throw exceptions as an invalid state or something.

[SteveMacenski]

Any update?