From 9883352cfc20de2641fae3876b8289631448a56a Mon Sep 17 00:00:00 2001
From: Kenji Miyake
Date: Sat, 5 Feb 2022 00:06:02 +0900
Subject: [PATCH 1/7] chore: sync check-build-depends.yaml with autoware_common
Signed-off-by: Kenji Miyake
Signed-off-by: tanaka3
---
.github/sync-files.yaml | 1 +
1 file changed, 1 insertion(+)
diff --git a/.github/sync-files.yaml b/.github/sync-files.yaml
index fb330f8468990..4ae5d6f62eec0 100644
--- a/.github/sync-files.yaml
+++ b/.github/sync-files.yaml
@@ -24,6 +24,7 @@
- source: .github/workflows/build-and-test-arm-pr.yaml
- source: .github/workflows/build-and-test.yaml
- source: .github/workflows/build-and-test-pr.yaml
+ - source: .github/workflows/check-build-depends.yaml
- source: .github/workflows/pre-commit.yaml
- repository: autowarefoundation/autoware-documentation
From 415d62189f37b717d6d1d8af48a3e25e8f9635e7 Mon Sep 17 00:00:00 2001
From: tanaka3
Date: Mon, 7 Feb 2022 11:56:09 +0900
Subject: [PATCH 2/7] fix(behavior_velocity): fix duplicated polygon
Signed-off-by: tanaka3
---
.../src/scene_module/occlusion_spot/debug.cpp | 1 +
1 file changed, 1 insertion(+)
diff --git a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
index 9df784a02ef96..9c9ca3902dbc8 100644
--- a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
@@ -151,6 +151,7 @@ visualization_msgs::msg::MarkerArray makePolygonMarker(
debug_marker.points.push_back(point);
}
debug_markers.markers.push_back(debug_marker);
+ debug_marker.points.clear();
}
return debug_markers;
}
From 399c39ef1c0c2c50ad6b76fdaa479c6b97f3bbe6 Mon Sep 17 00:00:00 2001
From: tanaka3
Date: Mon, 7 Feb 2022 12:00:11 +0900
Subject: [PATCH 3/7] feat(behavior_velocity): Add paths used by the occluded
spot module to the debug visualization of BehaviorVelocityPlanner
Signed-off-by: Maxime CLEMENT
Signed-off-by: tanaka3
---
.../occlusion_spot/scene_occlusion_spot_in_private_road.hpp | 2 ++
.../occlusion_spot/scene_occlusion_spot_in_private_road.cpp | 2 ++
2 files changed, 4 insertions(+)
diff --git a/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp b/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
index 586678f8cd2f0..13504c5cda7b9 100644
--- a/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
+++ b/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
@@ -48,6 +48,8 @@ class OcclusionSpotInPrivateModule : public SceneModuleInterface
std::string road_type = "private";
std::vector sidewalks;
std::vector possible_collisions;
+ PathWithLaneId original_path;
+ PathWithLaneId interpolated_path;
};
OcclusionSpotInPrivateModule(
diff --git a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
index d2bce48eacbff..f8fedaf3b6c58 100644
--- a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
@@ -101,6 +101,8 @@ bool OcclusionSpotInPrivateModule::modifyPathVelocity(
path, possible_collisions, ego_velocity, param_.private_road, param_);
debug_data_.z = path->points.front().point.pose.position.z;
debug_data_.possible_collisions = possible_collisions;
+ debug_data_.original_path = *path;
+ debug_data_.interpolated_path = interp_path;
return true;
}
From a0b82be9f866b0b99b0c2621854bf95f4e301407 Mon Sep 17 00:00:00 2001
From: tanaka3
Date: Mon, 7 Feb 2022 13:30:01 +0900
Subject: [PATCH 4/7] fix(behavior_velocity): add visualize marker and fix
angle of last point
Signed-off-by: tanaka3
---
.../scene_occlusion_spot_in_private_road.hpp | 4 +-
.../src/scene_module/intersection/util.cpp | 2 +-
.../scene_no_stopping_area.cpp | 2 +-
.../src/scene_module/occlusion_spot/debug.cpp | 38 ++++++++++++++++++-
.../scene_occlusion_spot_in_private_road.cpp | 4 +-
5 files changed, 43 insertions(+), 7 deletions(-)
diff --git a/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp b/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
index 13504c5cda7b9..93d382576c29e 100644
--- a/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
+++ b/planning/behavior_velocity_planner/include/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.hpp
@@ -48,8 +48,8 @@ class OcclusionSpotInPrivateModule : public SceneModuleInterface
std::string road_type = "private";
std::vector sidewalks;
std::vector possible_collisions;
- PathWithLaneId original_path;
- PathWithLaneId interpolated_path;
+ PathWithLaneId path_raw;
+ PathWithLaneId interp_path;
};
OcclusionSpotInPrivateModule(
diff --git a/planning/behavior_velocity_planner/src/scene_module/intersection/util.cpp b/planning/behavior_velocity_planner/src/scene_module/intersection/util.cpp
index adda9e2189ae9..9e0ba6c518273 100644
--- a/planning/behavior_velocity_planner/src/scene_module/intersection/util.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/intersection/util.cpp
@@ -131,7 +131,7 @@ bool splineInterpolate(
if (output->points.size() > 1) {
size_t l = resampled_s.size();
output->points.front().point.pose.orientation = output->points.at(1).point.pose.orientation;
- output->points.back().point.pose.orientation = output->points.at(l - 1).point.pose.orientation;
+ output->points.back().point.pose.orientation = output->points.at(l - 2).point.pose.orientation;
}
return true;
}
diff --git a/planning/behavior_velocity_planner/src/scene_module/no_stopping_area/scene_no_stopping_area.cpp b/planning/behavior_velocity_planner/src/scene_module/no_stopping_area/scene_no_stopping_area.cpp
index 53a70b3af8c26..c4c8a4489cf83 100644
--- a/planning/behavior_velocity_planner/src/scene_module/no_stopping_area/scene_no_stopping_area.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/no_stopping_area/scene_no_stopping_area.cpp
@@ -104,7 +104,7 @@ bool splineInterpolate(
if (output->points.size() > 1) {
size_t l = resampled_s.size();
output->points.front().point.pose.orientation = output->points.at(1).point.pose.orientation;
- output->points.back().point.pose.orientation = output->points.at(l - 1).point.pose.orientation;
+ output->points.back().point.pose.orientation = output->points.at(l - 2).point.pose.orientation;
}
return true;
}
diff --git a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
index 9c9ca3902dbc8..9dea5b7784ec3 100644
--- a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/debug.cpp
@@ -140,7 +140,7 @@ visualization_msgs::msg::MarkerArray makePolygonMarker(
debug_marker.action = visualization_msgs::msg::Marker::ADD;
debug_marker.pose.position = tier4_autoware_utils::createMarkerPosition(0.0, 0.0, z);
debug_marker.pose.orientation = tier4_autoware_utils::createMarkerOrientation(0, 0, 0, 1.0);
- debug_marker.scale = tier4_autoware_utils::createMarkerScale(0.05, 0.05, 0.05);
+ debug_marker.scale = tier4_autoware_utils::createMarkerScale(0.1, 0.1, 0.1);
debug_marker.color = tier4_autoware_utils::createMarkerColor(1.0, 0.0, 1.0, 0.3);
debug_marker.lifetime = rclcpp::Duration::from_seconds(0.1);
debug_marker.ns = "sidewalk";
@@ -151,11 +151,41 @@ visualization_msgs::msg::MarkerArray makePolygonMarker(
debug_marker.points.push_back(point);
}
debug_markers.markers.push_back(debug_marker);
+ debug_marker.id++;
debug_marker.points.clear();
}
return debug_markers;
}
+visualization_msgs::msg::MarkerArray createPathMarkerArray(
+ const PathWithLaneId & path, const std::string & ns, const int64_t lane_id, const double r,
+ const double g, const double b)
+{
+ visualization_msgs::msg::MarkerArray msg;
+ int32_t uid = planning_utils::bitShift(lane_id);
+ int32_t i = 0;
+ for (const auto & p : path.points) {
+ visualization_msgs::msg::Marker marker{};
+ marker.header.frame_id = "map";
+ marker.ns = ns;
+ marker.id = uid + i++;
+ marker.lifetime = rclcpp::Duration::from_seconds(0.3);
+ marker.type = visualization_msgs::msg::Marker::ARROW;
+ marker.action = visualization_msgs::msg::Marker::ADD;
+ marker.pose = p.point.pose;
+ marker.scale = createMarkerScale(0.6, 0.3, 0.3);
+ if (std::find(p.lane_ids.begin(), p.lane_ids.end(), lane_id) != p.lane_ids.end()) {
+ // if p.lane_ids has lane_id
+ marker.color = createMarkerColor(r, g, b, 0.999);
+ } else {
+ marker.color = createMarkerColor(0.5, 0.5, 0.5, 0.999);
+ }
+ msg.markers.push_back(marker);
+ }
+
+ return msg;
+}
+
template
visualization_msgs::msg::MarkerArray createMarkers(
T & debug_data, [[maybe_unused]] const int64_t module_id_)
@@ -214,6 +244,12 @@ visualization_msgs::msg::MarkerArray OcclusionSpotInPrivateModule::createDebugMa
appendMarkerArray(createMarkers(debug_data_, module_id_), current_time, &debug_marker_array);
appendMarkerArray(
makePolygonMarker(debug_data_.sidewalks, debug_data_.z), current_time, &debug_marker_array);
+ appendMarkerArray(
+ createPathMarkerArray(debug_data_.path_raw, "path_raw", 0, 0.0, 1.0, 1.0), current_time,
+ &debug_marker_array);
+ appendMarkerArray(
+ createPathMarkerArray(debug_data_.interp_path, "path_interp", 0, 0.0, 1.0, 1.0), current_time,
+ &debug_marker_array);
return debug_marker_array;
}
} // namespace behavior_velocity_planner
diff --git a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
index f8fedaf3b6c58..ffc53f8efa586 100644
--- a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/scene_occlusion_spot_in_private_road.cpp
@@ -65,6 +65,7 @@ bool OcclusionSpotInPrivateModule::modifyPathVelocity(
utils::clipPathByLength(*path, clipped_path, max_range);
PathWithLaneId interp_path;
utils::splineInterpolate(clipped_path, 1.0, &interp_path, logger_);
+ debug_data_.interp_path = interp_path;
int closest_idx = -1;
if (!planning_utils::calcClosestIndex(
interp_path, ego_pose, closest_idx, param_.dist_thr, param_.angle_thr)) {
@@ -101,8 +102,7 @@ bool OcclusionSpotInPrivateModule::modifyPathVelocity(
path, possible_collisions, ego_velocity, param_.private_road, param_);
debug_data_.z = path->points.front().point.pose.position.z;
debug_data_.possible_collisions = possible_collisions;
- debug_data_.original_path = *path;
- debug_data_.interpolated_path = interp_path;
+ debug_data_.path_raw = *path;
return true;
}
From e2bceb0ecc305588e3f7cdebca0a3fa455187dcb Mon Sep 17 00:00:00 2001
From: tanaka3
Date: Mon, 7 Feb 2022 13:55:34 +0900
Subject: [PATCH 5/7] fix(behavior_velocity): fix occlusion spot last angle
after interpolation
Signed-off-by: tanaka3
---
.../src/scene_module/occlusion_spot/occlusion_spot_utils.cpp | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/occlusion_spot_utils.cpp b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/occlusion_spot_utils.cpp
index ef38e929025d8..140f142b0e772 100644
--- a/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/occlusion_spot_utils.cpp
+++ b/planning/behavior_velocity_planner/src/scene_module/occlusion_spot/occlusion_spot_utils.cpp
@@ -124,7 +124,7 @@ bool splineInterpolate(
if (output->points.size() > 1) {
size_t l = resampled_s.size();
output->points.front().point.pose.orientation = output->points.at(1).point.pose.orientation;
- output->points.back().point.pose.orientation = output->points.at(l - 1).point.pose.orientation;
+ output->points.back().point.pose.orientation = output->points.at(l - 2).point.pose.orientation;
}
return true;
}
From 0613d1d800c3368873f79ca0865b819c6f6b9964 Mon Sep 17 00:00:00 2001
From: Tomoya Kimura
Date: Mon, 7 Feb 2022 11:00:33 +0900
Subject: [PATCH 6/7] fix: fix external velocity in smoother (#340)
Signed-off-by: tomoya.kimura
Signed-off-by: tanaka3
---
.../src/motion_velocity_smoother_node.cpp | 5 +----
1 file changed, 1 insertion(+), 4 deletions(-)
diff --git a/planning/motion_velocity_smoother/src/motion_velocity_smoother_node.cpp b/planning/motion_velocity_smoother/src/motion_velocity_smoother_node.cpp
index 9c6edbf1d29a4..5f1c27539bcc1 100644
--- a/planning/motion_velocity_smoother/src/motion_velocity_smoother_node.cpp
+++ b/planning/motion_velocity_smoother/src/motion_velocity_smoother_node.cpp
@@ -367,7 +367,7 @@ void MotionVelocitySmootherNode::onExternalVelocityLimit(const VelocityLimit::Co
// constraints
if (!prev_output_.empty()) {
// if external velocity limit decreases
- if ((external_velocity_limit_ - msg->max_velocity) > eps) {
+ if (std::fabs((external_velocity_limit_ - msg->max_velocity)) > eps) {
if (prev_closest_point_) {
const double v0 = prev_closest_point_->longitudinal_velocity_mps;
const double a0 = prev_closest_point_->acceleration_mps2;
@@ -404,9 +404,6 @@ void MotionVelocitySmootherNode::onExternalVelocityLimit(const VelocityLimit::Co
}
}
}
- // if external velocity limit increases
- } else if ((msg->max_velocity - external_velocity_limit_) > eps) {
- max_velocity_with_deceleration_ = msg->max_velocity;
}
}
From 9f125cba4a66d51a882d3aa832bdf8b0358fefdb Mon Sep 17 00:00:00 2001
From: Zulfaqar Azmi <93502286+zulfaqar-azmi-t4@users.noreply.github.com>
Date: Mon, 7 Feb 2022 11:53:53 +0900
Subject: [PATCH 7/7] feat(behavior_path_planner): better avoidance drivable
areas extension in behavior path planning (#287)
* feat: Increases the flexibility of the function in dealing with several scenarios
The implementation updates generateExtendedDrivableArea
this is a part of .iv PR (tier4/autoware.iv#2383) port
Signed-off-by: Muhammad Zulfaqar Azmi
* feat: change shift_length computation method
The new method considers the availability of the lane on the left side or right
side of ego vehicle, depending on the position of the obstacles.
Will not generate avoidance path if the adjacent lane is not a lanelet.
this is a part of .iv PR (tier4/autoware.iv#2383) port
Signed-off-by: Muhammad Zulfaqar Azmi
* feat: Adds documentation and debug marker visualization.
The visualization will show the remaining distance between the overhang_pose and
referenced linestring.
this is a part of .iv PR (tier4/autoware.iv#2383) port
Signed-off-by: Muhammad Zulfaqar Azmi
* fix: change debug naming to show clearer intent
The fix also removes a space character from one of the debug printing function call.
Signed-off-by: Muhammad Zulfaqar Azmi
* fix: replace equation from latex to math jax
Also remove the equation's image
Signed-off-by: Muhammad Zulfaqar Azmi
* fix: equation spacing
Signed-off-by: Muhammad Zulfaqar Azmi
* Fix: slight improvement in debug marker
1. Increase line ID text size and
2. Remove unnecessary visualization of connection between last point and the
front point linestring.
Signed-off-by: Muhammad Zulfaqar Azmi
* fix: drivable area not extend to third lane during extension
Signed-off-by: Muhammad Zulfaqar Azmi
* fix: slightly increase lateral_collision_safety_buffer to 0.7
The decision to increase is based on discussion with the planning control team
and also from input by FI team.
Signed-off-by: Muhammad Zulfaqar Azmi
Co-authored-by: taikitanaka3 <65527974+taikitanaka3@users.noreply.github.com>
Signed-off-by: tanaka3
---
.../avoidance/avoidance.param.yaml | 8 +-
.../behavior_path_planner_avoidance-design.md | 146 +++++++-
...ehavior_path_planner_design_limitations.md | 52 +++
.../config/avoidance/avoidance.param.yaml | 10 +-
.../image/limitations/limitation-corner.png | Bin 0 -> 20295 bytes
.../limitations/limitation-intersection.png | Bin 0 -> 379694 bytes
.../image/limitations/limitation01-01.png | Bin 0 -> 512868 bytes
.../limitations/limitation01-02-not-work.png | Bin 0 -> 264788 bytes
.../limitation01-03-not-equal-length.png | Bin 0 -> 529797 bytes
.../limitation01-04-equal-length.png | Bin 0 -> 38821 bytes
.../limitations/limitation01-04-not-equal.png | Bin 0 -> 26006 bytes
.../obstacle_to_road_shoulder_distance.png | Bin 0 -> 629268 bytes
.../image/shift_length_computation.png | Bin 0 -> 113434 bytes
.../image/shift_length_parameters.png | Bin 0 -> 443089 bytes
.../avoidance/avoidance_module.hpp | 2 +-
.../avoidance/avoidance_module_data.hpp | 24 ++
.../avoidance/avoidance_utils.hpp | 3 +-
.../scene_module/avoidance/debug.hpp | 6 +
.../src/behavior_path_planner_node.cpp | 5 +
.../avoidance/avoidance_module.cpp | 325 ++++++++++++++++--
.../avoidance/avoidance_utils.cpp | 21 +-
.../src/scene_module/avoidance/debug.cpp | 75 ++++
22 files changed, 641 insertions(+), 36 deletions(-)
create mode 100644 planning/behavior_path_planner/behavior_path_planner_design_limitations.md
create mode 100644 planning/behavior_path_planner/image/limitations/limitation-corner.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation-intersection.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation01-01.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation01-02-not-work.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation01-03-not-equal-length.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation01-04-equal-length.png
create mode 100644 planning/behavior_path_planner/image/limitations/limitation01-04-not-equal.png
create mode 100644 planning/behavior_path_planner/image/obstacle_to_road_shoulder_distance.png
create mode 100644 planning/behavior_path_planner/image/shift_length_computation.png
create mode 100644 planning/behavior_path_planner/image/shift_length_parameters.png
diff --git a/launch/tier4_planning_launch/config/scenario_planning/lane_driving/behavior_planning/behavior_path_planner/avoidance/avoidance.param.yaml b/launch/tier4_planning_launch/config/scenario_planning/lane_driving/behavior_planning/behavior_path_planner/avoidance/avoidance.param.yaml
index bfe310b73725f..4ddd16a8f7d1e 100644
--- a/launch/tier4_planning_launch/config/scenario_planning/lane_driving/behavior_planning/behavior_path_planner/avoidance/avoidance.param.yaml
+++ b/launch/tier4_planning_launch/config/scenario_planning/lane_driving/behavior_planning/behavior_path_planner/avoidance/avoidance.param.yaml
@@ -7,11 +7,15 @@
detection_area_right_expand_dist: 0.0
detection_area_left_expand_dist: 1.0
+ enable_avoidance_over_same_direction: true
+ enable_avoidance_over_opposite_direction: true
+
threshold_distance_object_is_on_center: 1.0 # [m]
threshold_speed_object_is_stopped: 1.0 # [m/s]
object_check_forward_distance: 150.0 # [m]
object_check_backward_distance: 2.0 # [m]
- lateral_collision_margin: 2.0 # [m]
+ lateral_collision_margin: 1.0 # [m]
+ lateral_collision_safety_buffer: 0.7 # [m]
prepare_time: 2.0 # [s]
min_prepare_distance: 1.0 # [m]
@@ -20,6 +24,8 @@
min_nominal_avoidance_speed: 7.0 # [m/s]
min_sharp_avoidance_speed: 1.0 # [m/s]
+ road_shoulder_safety_margin: 0.5 # [m]
+
max_right_shift_length: 5.0
max_left_shift_length: 5.0
diff --git a/planning/behavior_path_planner/behavior_path_planner_avoidance-design.md b/planning/behavior_path_planner/behavior_path_planner_avoidance-design.md
index 6a1fbe5f587c8..ed1adff4f6181 100644
--- a/planning/behavior_path_planner/behavior_path_planner_avoidance-design.md
+++ b/planning/behavior_path_planner/behavior_path_planner_avoidance-design.md
@@ -238,6 +238,148 @@ The shift points are modified by a filtering process in order to get the expecte
- Similar gradient removal: Connect two shift points with a straight line, and remove the shift points in between if their shift amount is in the vicinity of the straight line.
- Remove momentary returns: For shift points that reduce the avoidance width (for going back to the center line), if there is enough long distance in the longitudinal direction, remove them.
+#### Computing shift length (available as of develop/v0.25.0)
+
+**Note**: This feature is available as of develop/`v0.25.0`.
+
+The shift length is set as a constant value before the feature is implemented (develop/`v0.24.0` and below). Setting the shift length like this will cause the module to generate an avoidance path regardless of actual environmental properties. For example, the path might exceed the actual road boundary or go towards a wall. Therefore, to address this limitation, in addition to [how to decide the target obstacle](#how-to-decide-the-target-obstacles), the upgraded module also takes into account the following additional element
+
+- The obstacles' current lane and position.
+- The road shoulder with reference to the direction to avoid.
+ - Note: Lane direction is disregarded.
+
+These elements are used to compute the distance from the object to the road's shoulder (`(class ObjectData.to_road_shoulder_distance)`).
+
+
+
+##### Computing shift length
+
+To compute the shift length, in addition to the vehicle's width and the parameterized `lateral_collision_margin`, the upgraded feature also adds two new parameters; `lateral_collision_safety_buffer` and `road_shoulder_safety_margin`.
+
+- The `lateral_collision_safety_buffer` parameter is used to set a safety gap that will act as the final line of defense when computing avoidance path.
+ - The rationale behind having this parameter is that the parameter `lateral_collision_margin` might be changed according to the situation for various reasons. Therefore, `lateral_collision_safety_buffer` will act as the final line of defense in case of the usage of `lateral_collision_margin` fails.
+ - It is recommended to set the value to more than half of the ego vehicle's width.
+- The `road_shoulder_safety_margin` will prevent the module from generating a path that might cause the vehicle to go too near the road shoulder.
+
+
+
+The shift length is subjected to the following constraints.
+
+
+
+$$
+\text{shift_length}=\begin{cases}d_{lcsb}+d_{lcm}+\frac{1}{2}(W_{ego})&\text{if}&(d_{lcsb}+d_{lcm}+W_{ego}+d_{rssm})\lt d_{trsd}\\0 &\textrm{if}&\left(d_{lcsb}+d_{lcm}+W_{ego}+d_{rssm}\right)\geq d_{trsd}\end{cases}
+$$
+
+where
+
+- 
= `lateral_collision_safety_buffer`
+- 
= `lateral_collision_margin`
+- 
= ego vehicle's width
+- 
= `road_shoulder_safety_margin`
+- 
= `(class ObjectData).to_road_shoulder_distance`
+
+```plantuml
+@startuml
+skinparam monochrome true
+skinparam defaultTextAlignment center
+skinparam noteTextAlignment left
+
+title avoidance path planning
+start
+partition calcAvoidanceTargetObjects() {
+:calcOverhangDistance;
+note right
+ - get overhang_pose
+end note
+
+:getClosestLaneletWithinRoute;
+note right
+ - obtain overhang_lanelet
+end note
+
+if(Is overhang_lanelet.id() exist?) then (no)
+stop
+else (\n yes)
+
+if(isOnRight(obstacle)?) then (yes)
+partition getLeftMostLineString() {
+repeat
+repeat
+:getLeftLanelet;
+note left
+ Check both
+ - lane-changeable lane
+ - non lane-changeable lane
+end note
+repeat while (Same direction Lanelet exist?) is (yes) not (no)
+:getLeftOppositeLanelet;
+repeat while (Opposite direction Lanelet exist?) is (yes) not (no)
+}
+:compute\n(class ObjectData).to_road_shoulder_distance;
+note left
+distance from overhang_pose
+to left most linestring
+end note
+else(\n no)
+partition getrightMostLineString() {
+repeat
+repeat
+:getRightLanelet;
+note right
+ Check both
+ - lane-changeable lane
+ - non lane-changeable lane
+end note
+repeat while (Same direction Lanelet exist?) is (yes) not (no)
+:getRightOppositeLanelet;
+repeat while (Opposite direction Lanelet exist?) is (yes) not (no)
+}
+:compute\n(class ObjectData).to_road_shoulder_distance;
+note right
+distance from overhang_pose
+to right most linestring
+end note
+endif
+endif
+}
+
+partition calcRawShiftPointsFromObjects() {
+:compute max_allowable_lateral_distance;
+note right
+The sum of
+- lat_collision_safety_buffer
+- lat_collision_margin
+- vehicle_width
+end note
+:compute max_shift_length;
+note right
+subtract
+- road_shoulder_safety_margin
+- 0.5 x vehicle_width
+from (class ObjectData).to_road_shoulder_margin
+end note
+if(isOnRight(object)?) then (yes)
+if((class ObjectData).to_road_shoulder_distance \n\l>\l\n max_allowable_lateral_distance ?) then (yes)
+:max_left_shift_limit = max_shift_length;
+else (\n No)
+:max_left_shift_limit = 0.0;
+endif
+else (\n No)
+if((class ObjectData).to_road_shoulder_distance \n\l>\l\n max_allowable_lateral_distance ?) then (yes)
+:max_right_shift_limit = -max_shift_length;
+else (\n No)
+:max_right_shift_limit = 0.0;
+endif
+endif
+:compute shift length;
+}
+stop
+@enduml
+```
+
+
+
#### How to keep the consistency of the planning
TODO
@@ -250,7 +392,8 @@ TODO
| :----------------------------------------- | :----- | :----- | :---------------------------------------------------------------------------------------------------------- | :------------ |
| resample_interval_for_planning | [m] | double | Path resample interval for avoidance planning path. | 0.3 |
| resample_interval_for_output | [m] | double | Path resample interval for output path. Too short interval increases computational cost for latter modules. | 3.0 |
-| lateral_collision_margin | [m] | double | The lateral distance between ego and avoidance targets. | 2.0 |
+| lateral_collision_margin | [m] | double | The lateral distance between ego and avoidance targets. | 1.5 |
+| lateral_collision_safety_buffer | [m] | double | Creates an additional gap that will prevent the vehicle from getting to near to the obstacle | 0.5 |
| longitudinal_collision_margin_min_distance | [m] | double | when complete avoidance motion, there is a distance margin with the object for longitudinal direction. | 0.0 |
| longitudinal_collision_margin_time | [s] | double | when complete avoidance motion, there is a time margin with the object for longitudinal direction. | 0.0 |
| prepare_time | [s] | double | Avoidance shift starts from point ahead of this time x ego_speed to avoid sudden path change. | 1.0 |
@@ -262,6 +405,7 @@ TODO
| min_sharp_avoidance_speed | [m/s] | double | Minimum speed for jerk calculation in a sharp situation (\*1). | 1.0 |
| max_right_shift_length | [m] | double | Maximum shift length for right direction | 5.0 |
| max_left_shift_length | [m] | double | Maximum shift length for left direction | 5.0 |
+| road_shoulder_safety_margin | [m] | double | Prevents the generated path to come too close to the road shoulders. | 0.5 |
### Speed limit modification
diff --git a/planning/behavior_path_planner/behavior_path_planner_design_limitations.md b/planning/behavior_path_planner/behavior_path_planner_design_limitations.md
new file mode 100644
index 0000000000000..7ffd89f2b495c
--- /dev/null
+++ b/planning/behavior_path_planner/behavior_path_planner_design_limitations.md
@@ -0,0 +1,52 @@
+# Design limitation
+
+The document describes the limitations that are currently present in the `behavior_path_planner` module.
+
+The following items (but not limited to) fall in the scope of limitation:
+
+- limitations due to the third-party API design and requirement
+- limitations due to any shortcoming out of the developer's control.
+
+## Limitation: Multiple connected opposite lanes require Linestring with shared ID
+
+To fully utilize the `Lanelet2`'s [API](https://github.com/fzi-forschungszentrum-informatik/Lanelet2/blob/master/lanelet2_core/doc/LaneletPrimitives.md#lanelet), the design of the vector map (`.osm`) needs to follow all the criteria described in `Lanelet2` documentation. Specifically, in the case of 2 or more lanes, the Linestrings that divide the current lane with the opposite/adjacent lane need to have a matching `Linestring ID`. Assume the following **ideal case**.
+
+
+
+In the image, `Linestring ID51` is shared by `Lanelet A` and `Lanelet B`. Hence we can directly use the available `left`, `adjacentLeft`, `right`, `adjacentRight` and `findUsages` method within `Lanelet2`'s API to directly query the direction and opposite lane availability.
+
+```cpp
+const auto right_lane = routing_graph_ptr_->right(lanelet);
+const auto adjacent_right_lane = routing_graph_ptr_->adjacentRight(lanelet);
+const auto opposite_right_lane = lanelet_map_ptr_->laneletLayer.findUsages(lanelet.rightBound().invert());
+```
+
+The following images show the situation where **these API does not work directly**. This means that we cannot use them straight away, and several assumptions and logical instruction are needed to make these APIs work.
+
+
+
+In this example (multiple linestring issues), `Lanelet C` contains `Linestring ID61` and `ID62`, while `Lanelet D` contains `Linestring ID63` and `ID 64`. Although the `Linestring ID62` and `ID64` have identical point IDs and seem visually connected, the API will treat these Linestring as though they are separated. When it searches for any `Lanelet` that is connected via `Linestring ID62`, it will return `NULL`, since `ID62` only connects to `Lanelet C` and not other `Lanelet`.
+
+Although, in this case, it is possible to forcefully search the lanelet availability by checking the lanelet that contains the points, using`getLaneletFromPoint` method. But, the implementation requires complex rules for it to work. Take the following images as an example.
+
+
+
+Assume `Object X` is in `Lanelet F`. We can forcefully search `Lanelet E` via `Point 7`, and it will work if `Point 7` is utilized by **only 2 lanelet**. However, the complexity increases when we want to start searching for the **direction** of the opposite lane. We can infer the direction of the lanelet by using mathematical operations (dot product of vector `V_ID72` (`Point 6` minus `Point 9`), and `V_ID74` (`Point 7` minus `Point 8`). But, notice that we did not use Point 7 in V_ID72. This is because searching it requires an iteration, adding additional non-beneficial computation.
+
+Suppose the points are used by **more than 2 lanelets**. In that case, we have to find the differences for all lanelet, and the result might be undefined. The reason is that the differences between the coordinates do not reflect the actual **shape** of the lanelet. The following image demonstrates this point.
+
+
+
+
+
+There are many other available solutions to try. However, further attempt to solve this might cause issues in the future, especially for maintaining or scaling up the software.
+
+In conclusion, the multiple Linestring issues will not be supported. Covering these scenarios might give the user an "everything is possible" impression. This is dangerous since any attempt to create a non-standardized vector map is not compliant with safety regulations.
+
+## Limitation: Avoidance at Corners and Intersections
+
+Currently, the implementation doesn't cover avoidance at corners and intersections. The reason is similar to here. However, this case can still be supported in the future (assuming the vector map is defined correctly).
+
+
+
+
diff --git a/planning/behavior_path_planner/config/avoidance/avoidance.param.yaml b/planning/behavior_path_planner/config/avoidance/avoidance.param.yaml
index bfe310b73725f..34951cc91d30a 100644
--- a/planning/behavior_path_planner/config/avoidance/avoidance.param.yaml
+++ b/planning/behavior_path_planner/config/avoidance/avoidance.param.yaml
@@ -7,11 +7,15 @@
detection_area_right_expand_dist: 0.0
detection_area_left_expand_dist: 1.0
+ enable_avoidance_over_same_direction: true
+ enable_avoidance_over_opposite_direction: true
+
threshold_distance_object_is_on_center: 1.0 # [m]
threshold_speed_object_is_stopped: 1.0 # [m/s]
object_check_forward_distance: 150.0 # [m]
object_check_backward_distance: 2.0 # [m]
- lateral_collision_margin: 2.0 # [m]
+ lateral_collision_margin: 1.0 # [m]
+ lateral_collision_safety_buffer: 0.7 # [m]
prepare_time: 2.0 # [s]
min_prepare_distance: 1.0 # [m]
@@ -20,6 +24,8 @@
min_nominal_avoidance_speed: 7.0 # [m/s]
min_sharp_avoidance_speed: 1.0 # [m/s]
+ road_shoulder_safety_margin: 0.5 # [m]
+
max_right_shift_length: 5.0
max_left_shift_length: 5.0
@@ -30,7 +36,7 @@
# For prevention of large acceleration while avoidance
min_avoidance_speed_for_acc_prevention: 3.0 # [m/s]
- max_avoidance_acceleration: 0.5 # [m/ss]
+ max_avoidance_acceleration: 0.5 # [m/s2]
# for debug
publish_debug_marker: false
diff --git a/planning/behavior_path_planner/image/limitations/limitation-corner.png b/planning/behavior_path_planner/image/limitations/limitation-corner.png
new file mode 100644
index 0000000000000000000000000000000000000000..fe32071edd6dce906feb09f7fd3a6d419d41579c
GIT binary patch
literal 20295
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
literal 0
HcmV?d00001
diff --git a/planning/behavior_path_planner/image/limitations/limitation-intersection.png b/planning/behavior_path_planner/image/limitations/limitation-intersection.png
new file mode 100644
index 0000000000000000000000000000000000000000..eb78094b516555514bb1bc4bb8e5f964157d5b1a
GIT binary patch
literal 379694
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
z