docs: auto/update behavior velocity doc (#741) (#189)

* update docs * update docs * add more derails * fix pre-commit * update dpcs * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * add reason for separate module * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * [kimura]update readme * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * Apply suggestions from code review * typo * minor fix * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * update Signed-off-by: Takamasa Horibe <horibe.takamasa@gmail.com> * fix precomimt * fix typo Co-authored-by: Takamasa Horibe <horibe.takamasa@gmail.com> Co-authored-by: tomoya.kimura <tomoya.kimura@tier4.jp> Co-authored-by: taikitanaka3 <65527974+taikitanaka3@users.noreply.github.com> Co-authored-by: Takamasa Horibe <horibe.takamasa@gmail.com> Co-authored-by: tomoya.kimura <tomoya.kimura@tier4.jp>
autowarefoundation · Dec 16, 2021 · 4f04fab · 4f04fab
1 parent 740cce2
commit 4f04fab
Show file tree

Hide file tree

Showing 19 changed files with 383 additions and 68 deletions.
diff --git a/planning/behavior_velocity_planner/README.md b/planning/behavior_velocity_planner/README.md
@@ -9,6 +9,7 @@ It consists of several modules. Please refer to the links listed below for detai
 - [Crosswalk](crosswalk-design.md)
 - [Detection Area](detection-area-design.md)
 - [Intersection](intersection-design.md)
+- [MergeFromPrivate](merge-from-private-design.md)
 - [Stop Line](stop-line-design.md)
 - [Traffic Light](traffic-light-design.md)
 - [Occlusion Spot](occlusion-spot-design.md)

diff --git a/planning/behavior_velocity_planner/blind-spot-design.md b/planning/behavior_velocity_planner/blind-spot-design.md
@@ -1,12 +1,16 @@
-### Blind Spot
+## Blind Spot
 
-#### Role
+### Role
 
-Blind spot check while turning right/left by a dynamic object information, and planning and planning of a velocity of the start/stop.
+Blind spot check while turning right/left by a dynamic object information and planning a velocity of the start/stop.
 
 ![brief](./docs/blind_spot/blind_spot.svg)
 
-### Definition
+### Activation Timing
+
+This function is activated when the lane id of the target path has an intersection label (i.e. the `turn_direction` attribute is `left` or `right`).
+
+### Inner-workings / Algorithms
 
 Sets a stop line, a pass judge line, a detection area and conflict area based on a map information and a self position.
 
@@ -18,7 +22,16 @@ Sets a stop line, a pass judge line, a detection area and conflict area based on
 
 - Conflict area : Right/left side area from the self position to the stop line.
 
-#### Module Parameters
+Stop/Go state: When both conditions are met for any of each object, this module state is transited to the "stop" state and insert zero velocity to stop the vehicle.
+
+- Object is on the detection area
+- Object’s predicted path is on the conflict area
+
+In order to avoid a rapid stop, the “stop” judgement is not executed after the judgment line is passed.
+
+Once a "stop" is judged, it will not transit to the "go" state until the "go" judgment continues for a certain period in order to prevent chattering of the state (e.g. 2 seconds).
+
+### Module Parameters
 
 | Parameter                       | Type   | Description                                                                 |
 | ------------------------------- | ------ | --------------------------------------------------------------------------- |
@@ -27,7 +40,7 @@ Sets a stop line, a pass judge line, a detection area and conflict area based on
 | `ignore_width_from_center_line` | double | [m] ignore threshold that vehicle behind is collide with ego vehicle or not |
 | `max_future_movement_time`      | double | [s] maximum time for considering future movement of object                  |
 
-#### Flowchart
+### Flowchart
 
 ```plantuml
 @startuml

diff --git a/planning/behavior_velocity_planner/crosswalk-design.md b/planning/behavior_velocity_planner/crosswalk-design.md
@@ -1,13 +1,55 @@
-### CrossWalk
+## CrossWalk
 
-#### Role
+### Role For Crosswalk
 
 Judgement whether a vehicle can go into a crosswalk and plan a velocity of the start/stop.
 
-#### Launch Timing
+![crosswalk](docs/crosswalk/crosswalk.png)
+
+### Role For Walkway
+
+tbd.
+
+### Activation Timing
 
 Launches when there is a crosswalk on the target lane.
 
+### Limitations
+
+#### For Crosswalk
+
+In order to prevent perception failure, the detection area is limited by using pre-defined areas (deceleration area and stop area). Therefore this module does not respond to pedestrians or bicycles outside these areas.
+
+#### For Walkway
+
+tbd.
+
+### Inner-workings / Algorithms
+
+#### Scene Crosswalk
+
+The crosswalk module considers the following objects as target objects.
+
+- pedestrian
+- cyclist
+
+##### Stop condition
+
+If any of conditions below is met, the vehicle will stop at stop point.
+
+- A target object exists in the **stop area**.
+- A target object in the **crosswalk area** is predicted to enter the stop area within 3 seconds based on its prediction path.
+
+##### Decelerate condition
+
+If any of conditions below is met, the vehicle will decelerate to be 10 km/h at slow point.
+
+- A target object exists in the **deceleration area**.
+
+#### Scene Walkway
+
+- TBD
+
 #### Module Parameters
 
 | Parameter                                                | Type   | Description                                                              |
@@ -24,3 +66,14 @@ Launches when there is a crosswalk on the target lane.
 #### Flowchart
 
 flow chart is almost the same as stop line.
+
+### Known Issues
+
+#### Crosswalk
+
+- The logic for determining speed should be set more strictly from safety reasons.
+- The deceleration speed from the deceleration area logic is set to a constant value (10 [km/h]), which does not take into account the safety distance from obstacles.
+
+#### Walkway
+
+- If the vehicle exceeds the stop line more than the threshold distance, this module will get stuck in STOP state and will not start moving.
diff --git a/planning/behavior_velocity_planner/detection-area-design.md b/planning/behavior_velocity_planner/detection-area-design.md
@@ -6,9 +6,9 @@ If pointcloud is detected in a detection area defined on a map, the stop plannin
 
 ![brief](./docs/detection_area/detection_area.svg)
 
-#### Launch Timing
+#### Activation Timing
 
-Launches if there is a detection area on the target lane.
+This module is activated when there is a detection area on the target lane.
 
 ### Algorithm
 

diff --git a/planning/behavior_velocity_planner/docs/crosswalk/crosswalk.png b/planning/behavior_velocity_planner/docs/crosswalk/crosswalk.png
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_fig.png b/planning/behavior_velocity_planner/docs/intersection/intersection_fig.png
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_left.png b/planning/behavior_velocity_planner/docs/intersection/intersection_left.png
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_right.png b/planning/behavior_velocity_planner/docs/intersection/intersection_right.png
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_straight.png b/planning/behavior_velocity_planner/docs/intersection/intersection_straight.png
diff --git a/planning/behavior_velocity_planner/docs/intersection/merge_from_private.png b/planning/behavior_velocity_planner/docs/intersection/merge_from_private.png
diff --git a/planning/behavior_velocity_planner/docs/occlusion_spot/occupancy_grid.svg b/planning/behavior_velocity_planner/docs/occlusion_spot/occupancy_grid.svg
diff --git a/planning/behavior_velocity_planner/docs/stop_line/stop_line.svg b/planning/behavior_velocity_planner/docs/stop_line/stop_line.svg
diff --git a/planning/behavior_velocity_planner/docs/traffic_light/crosswalk.png b/planning/behavior_velocity_planner/docs/traffic_light/crosswalk.png