Obstacle Cruise

Role

The obstacle_cruise module does the cruise planning against a dynamic obstacle in front of the ego.

Activation

This module is activated if the launch parameter launch_obstacle_cruise_module is set to true.

Inner-workings / Algorithms

Obstacle Filtering

The obstacles meeting the following condition are determined as obstacles for cruising.

• The lateral distance from the object to the ego’s trajectory is smaller than obstacle_filtering.max_lat_margin.

• The object type is for cruising according to obstacle_filtering.object_type.*.
• The object is not crossing the ego’s trajectory (*1).
• If the object is inside the trajectory.
  • The object type is for inside cruising according to obstacle_filtering.object_type.inside.*.
  • The object velocity is larger than obstacle_filtering.obstacle_velocity_threshold_from_cruise.
• If the object is outside the trajectory.
  • The object type is for outside cruising according to obstacle_filtering.object_type.outside.*.
  • The object velocity is larger than obstacle_filtering.outside_obstacle.obstacle_velocity_threshold.
  • The highest confident predicted path collides with the ego’s trajectory.
  • Its collision’s period is larger than obstacle_filtering.outside_obstacle.ego_obstacle_overlap_time_threshold.

NOTE

*1: Crossing obstacles

Crossing obstacle is the object whose orientation’s yaw angle against the ego’s trajectory is smaller than obstacle_filtering.crossing_obstacle.obstacle_traj_angle_threshold.

Yield for vehicles that might cut in into the ego’s lane

It is also possible to yield (cruise) behind vehicles in neighbor lanes if said vehicles might cut in the ego vehicle’s current lane.

The obstacles meeting the following condition are determined as obstacles for yielding (cruising).

• The object type is for cruising according to obstacle_filtering.object_type.* and it is moving with a speed greater than obstacle_filtering.yield.stopped_obstacle_velocity_threshold.
• The object is not crossing the ego’s trajectory (*1).
• There is another object of type obstacle_filtering.object_type.side_stopped stopped in front of the moving obstacle.
• The lateral distance (using the ego’s trajectory as reference) between both obstacles is less than obstacle_filtering.yield.max_lat_dist_between_obstacles
• Both obstacles, moving and stopped, are within obstacle_filtering.yield.lat_distance_threshold and obstacle_filtering.yield.lat_distance_threshold + obstacle_filtering.yield.max_lat_dist_between_obstacles lateral distance from the ego’s trajectory respectively.

If the above conditions are met, the ego vehicle will cruise behind the moving obstacle, yielding to it so it can cut in into the ego’s lane to avoid the stopped obstacle.

Cruise Planning

The role of the cruise planning is keeping a safe distance with dynamic vehicle objects with smoothed velocity transition. This includes not only cruising a front vehicle, but also reacting a cut-in and cut-out vehicle.

The module calculates the minimum safe braking distance dynamically by using the following equation:

\[d_{braking} = v_{ego} t_{idling} + \frac{v_{ego}^2}{2 a_{ego}} - \frac{v_{obstacle}^2}{2 a_{obstacle}} + l_{margin},\]

assuming that $d_{braking}$ is the calculated safe distance, $t_{idling}$ is the idling time for the ego to detect the front vehicle’s deceleration, $v_{ego}$ is the ego’s current velocity, $v_{obstacle}$ is the front obstacle’s current velocity, $a_{ego}$ is the ego’s acceleration, $a_{obstacle}$ is the obstacle’s acceleration, and $l_{margin}$ is the safety margin. These values are parameterized as follows. Other common values such as ego’s minimum acceleration is defined in common.param.yaml.

Parameter	Type	Description
cruise_planning.idling_time	double	idling time for the ego to detect the front vehicle starting deceleration [s]
cruise_planning.min_ego_accel_for_rss	double	ego’s acceleration for minimum safe braking distance [m/ss]
cruise_planning.min_object_accel_for_rss	double	front obstacle’s acceleration for minimum safe braking distance [m/ss]
cruise_planning.safe_distance_margin	double	safety margin for minimum safe braking distance [m]

The detailed formulation is as follows.

\[\begin{align} d_{error} & = d - d_{braking} \\ d_{normalized} & = lpf(d_{error} / d_{obstacle}) \\ d_{quad, normalized} & = sign(d_{normalized}) *d_{normalized}*d_{normalized} \\ v_{pid} & = pid(d_{quad, normalized}) \\ v_{add} & = v_{pid} > 0 ? v_{pid}* w_{acc} : v_{pid} \\ v_{target} & = max(v_{ego} + v_{add}, v_{min, cruise}) \end{align}\]

Variable	Description
d	actual distance to obstacle
d_{braking}	ideal distance to obstacle based on minimum safe braking distance
v_{min, cruise}	min_cruise_target_vel
w_{acc}	output_ratio_during_accel
lpf(val)	apply low-pass filter to val
pid(val)	apply pid to val

Algorithm selection for cruise planner

Currently, only a PID-based planner is supported. Each planner will be explained in the following.

Parameter	Type	Description
option.planning_algorithm	string	cruise and stop planning algorithm, selected from “pid_base”

File truncated at 100 lines see the full file

Changelog for package autoware_motion_velocity_obstacle_cruise_module

0.53.0 (2026-09-29)

• Merge remote-tracking branch 'origin/main' into prepare-0.53.0-changelog

• fix(pre-commit): update pre-commit-hooks-ros to v0.10.3 and adapt include guards (#13083)

  • chore: sync files

  * fix(pre-commit): adapt include guards to pre-commit-hooks-ros v0.10.3 ros-include-guard v0.10.3 only recognises an include guard when #endif is the last non-empty line of the file, so that feature test macros are no longer mistaken for guards. 29 headers failed that check. 25 headers wrap the guard in "// clang-format off" / "// clang-format on" because the #endif comment plus its // NOLINT exceeds the 100 column limit. Drop only the trailing "on" marker; the "off" marker then runs to end of file and still protects the line from being wrapped. 3 CUDA headers ended with "/* INDENT-ON /". Move it above the #endif so it stays paired with the "/ INDENT-OFF */" near the top of the file. autoware_behavior_path_planner/test/input.hpp closed its guard immediately after opening it, leaving the entire body unguarded. Move the #endif to the end. Also hold clang-format at v21.1.8. clang-format 22 migrates "AlignAfterOpenBracket: AlwaysBreak" to "BreakAfterOpenBracketIf: true", which forces a break after every "if (" whose condition does not fit on one line and reformats 88 files. ---------Co-authored-by: github-actions <<github-actions@github.com>> Co-authored-by: Mete Fatih Cırıt <<mfc@autoware.org>>

• Contributors: Ryohsuke Mitsudome, awf-autoware-bot[bot]

0.52.0 (2026-06-30)

0.51.0 (2026-05-01)

• Merge remote-tracking branch 'origin/main' into tmp/bot/bump_version_base

• chore(planning): remove unused lanelet2_extension header (#12294)

  • unused lanelet2_extension in planning component
  • unused lanelet2_extension in planning component (2)

  * unused lanelet2_extension in planning component (3) ---------Co-authored-by: Mamoru Sobue <<hilo.soblin@gmail.com>>

• Contributors: Sarun MUKDAPITAK, github-actions

0.50.0 (2026-02-14)

• Merge remote-tracking branch 'origin/main' into humble
• feat!: remove ROS 2 Galactic codes (#11905)
• feat(motion_velocity_planner): publish debug trajectory for each module (#11781)
• docs(obstacle_cruise): revise documentation (#11841)
• Contributors: Maxime CLEMENT, Ryohsuke Mitsudome, Zulfaqar Azmi

0.49.0 (2025-12-30)

• Merge remote-tracking branch 'origin/main' into prepare-0.49.0-changelog

• refactor: fix leftover dependent autoware_utils from updating vehicle_info_utils (#11734)

• feat(motion_velocity_planner): refactor time publisher (#11646)

  • delete bdp time publish
  • delete dynamic_obstacle_stop time publish
  • delete obstacle_cruise time publish
  • delete obstacle_slow_down time publish
  • delete obstacle_velocity_limiter time publish
  • delete out of lane time publish
  • delete run out time publish

  * add short module name function ---------

• Contributors: Mete Fatih Cırıt, Ryohsuke Mitsudome, Yuki TAKAGI

0.48.0 (2025-11-18)

• Merge remote-tracking branch 'origin/main' into humble
• fix: tf2 uses hpp headers in rolling (and is backported) (#11620)
• chore(obstacle_*_module): add maintainer (#11506)
• feat(obstacle_slow_down_module, obstacle_cruise_module): add safety_factor

File truncated at 100 lines see the full file