[RPP] Prevent collision check premature termination with scaled_lookahead

[EricoMeger]

Basic Info

Info	Please fill out this column
Ticket(s) this addresses	#5595 #5598 #5616
Primary OS tested on	Ubuntu 24.04
Robotic platform tested on	Differential Drive bot, TB4 simulation
Does this PR contain AI generated software?	Used for the warning descriptions
Was this PR description generated by AI software?	Out of respect for maintainers, AI for human-to-human communications are banned

---

Description of contribution in a few bullet points

• Fixes a bug causing the robot to "creep" forward after stopping for an obstacle. This occurred when use_velocity_scaled_lookahead_dist was true and carrot_dist got smaller than min_distance_to_obstacle.
• The isCollisionImminent logic is updated to ensure the simulation distance always covers at least up to min_distance_to_obstacle, even when carrot_dist shrinks.
• Creates a new parameter, use_path_aware_obstacle_distance, to dynamically cap the min_distance_to_obstacle check by the remaining path distance. This allows the robot to reach goals near obstacles.
• Adds three new warnings:
  • When min_distance_to_obstacle > max_lookahead_dist
  • When use_path_aware_obstacle_distance is true but min_distance_to_obstacle is <= 0
  • When use_path_aware_obstacle_distance is true but scaled_lookahead is false.

Description of documentation updates required from your changes

Added new parameter, so need to add that to default configs and documentation page

Description of how this change was tested

Ran multiple tests on both a physical platform and simulation. Tests included different maps, routes, and parameter configurations (e.g., varying footprint sizes, velocities, and safety distances)

Future work that may be required in bullet points

For Maintainers:

• Check that any new parameters added are updated in docs.nav2.org
• Check that any significant change is added to the migration guide
• Check that any new features OR changes to existing behaviors are reflected in the tuning guide
• Check that any new functions have Doxygen added
• Check that any new features have test coverage
• Check that any new plugins is added to the plugins page
• If BT Node, Additionally: add to BT's XML index of nodes for groot, BT package's readme table, and BT library lists
• Should this be backported to current distributions? If so, tag with backport-*.

[EricoMeger]

@SteveMacenski @doisyg

This PR should address the cases we discussed.
Please review when you have a moment. Thanks!

[codecov]

Codecov Report

❌ Patch coverage is 59.25926% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
..._pure_pursuit_controller/src/collision_checker.cpp	30.00%	7 Missing ⚠️
..._pure_pursuit_controller/src/parameter_handler.cpp	73.33%	4 Missing ⚠️

Files with missing lines	Coverage Δ
...ated_pure_pursuit_controller/collision_checker.hpp	100.00% <ø> (ø)
...ated_pure_pursuit_controller/parameter_handler.hpp	100.00% <ø> (ø)
...ntroller/src/regulated_pure_pursuit_controller.cpp	85.86% <100.00%> (+0.07%)	⬆️
..._pure_pursuit_controller/src/parameter_handler.cpp	92.48% <73.33%> (-1.15%)	⬇️
..._pure_pursuit_controller/src/collision_checker.cpp	77.27% <30.00%> (-8.70%)	⬇️

... and 15 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.