Skip to content

Nav2 Obstacle Layer: Marking and Clearing

Source: obstacle-layer

Why This Matters

The obstacle layer is where most robots decide what is currently in the way. If its marking and clearing rules are wrong, the robot either invents obstacles that do not exist or misses ones that do.

Distilled Takeaways

  • marking and clearing are separate behaviors. Good obstacle handling usually needs both.
  • obstacle_range defines how far detections can create obstacles. raytrace_range defines how far beams can clear free space.
  • raytrace_range should be at least as large as obstacle_range, or marked cells can persist unnaturally.
  • Observation-source order is not the same as plugin order. Sources within the layer are combined; the layer itself still participates in the broader plugin sequence.
  • footprint_clearing_enabled is often useful because it prevents the robot from treating its own occupied footprint area as blocked.

Practical Guidance

  • Keep the source list explicit and per-sensor parameters honest. Do not copy lidar distances into depth cameras or vice versa.
  • If phantom obstacles remain after the robot moves away, inspect clearing first, then source update rate, then TF.
  • If thin or low objects are missed, the limitation may be sensing geometry rather than planner tuning.
  • Use multiple observation sources in one layer only when they represent compatible 2D projection logic.

Debugging Checklist

  • Verify the sensor topic is live and timestamped correctly.
  • Confirm the sensor frame exists in TF.
  • Check whether clearing: true is actually enabled.
  • Confirm expected_update_rate and stale-data handling fit the device.
  • Compare obstacle_range and raytrace_range.

Corroborating References

When to Read the Original Source

Read the source skill when you need the exact meaning of per-source parameters like marking, clearing, obstacle_range, raytrace_range, and height filters, or when you are diagnosing stale obstacle cells.