diff --git a/planning/behavior_velocity_planner/README.md b/planning/behavior_velocity_planner/README.md
index d8b0744e52ae3..a7ea3675ba8f4 100644
--- 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
index 2a6e944604dee..869355ae2e75e 100644
--- 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.
-### 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
index ab87ac1323027..470e606ef48ff 100644
--- 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
+
+
+### 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
index 15f3c991fa61d..6d36b45509783 100644
--- 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
-#### 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
new file mode 100644
index 0000000000000..9de8f05971a23
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/crosswalk/crosswalk.png differ
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_fig.png b/planning/behavior_velocity_planner/docs/intersection/intersection_fig.png
new file mode 100644
index 0000000000000..2b1b2bc979ece
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/intersection/intersection_fig.png differ
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_left.png b/planning/behavior_velocity_planner/docs/intersection/intersection_left.png
new file mode 100644
index 0000000000000..2dcb8f86919f8
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/intersection/intersection_left.png differ
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_right.png b/planning/behavior_velocity_planner/docs/intersection/intersection_right.png
new file mode 100644
index 0000000000000..03251cbb82376
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/intersection/intersection_right.png differ
diff --git a/planning/behavior_velocity_planner/docs/intersection/intersection_straight.png b/planning/behavior_velocity_planner/docs/intersection/intersection_straight.png
new file mode 100644
index 0000000000000..5cbd6262c57fc
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/intersection/intersection_straight.png differ
diff --git a/planning/behavior_velocity_planner/docs/intersection/merge_from_private.png b/planning/behavior_velocity_planner/docs/intersection/merge_from_private.png
new file mode 100644
index 0000000000000..ab6d898003197
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/intersection/merge_from_private.png differ
diff --git a/planning/behavior_velocity_planner/docs/occlusion_spot/occupancy_grid.svg b/planning/behavior_velocity_planner/docs/occlusion_spot/occupancy_grid.svg
new file mode 100644
index 0000000000000..bde498e3c0d0c
--- /dev/null
+++ b/planning/behavior_velocity_planner/docs/occlusion_spot/occupancy_grid.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/planning/behavior_velocity_planner/docs/stop_line/stop_line.svg b/planning/behavior_velocity_planner/docs/stop_line/stop_line.svg
new file mode 100644
index 0000000000000..72fe42712e839
--- /dev/null
+++ b/planning/behavior_velocity_planner/docs/stop_line/stop_line.svg
@@ -0,0 +1 @@
+
diff --git a/planning/behavior_velocity_planner/docs/traffic_light/crosswalk.png b/planning/behavior_velocity_planner/docs/traffic_light/crosswalk.png
new file mode 100644
index 0000000000000..9de8f05971a23
Binary files /dev/null and b/planning/behavior_velocity_planner/docs/traffic_light/crosswalk.png differ
diff --git a/planning/behavior_velocity_planner/intersection-design.md b/planning/behavior_velocity_planner/intersection-design.md
index 4e12cf401bbbc..d039c77b789b8 100644
--- a/planning/behavior_velocity_planner/intersection-design.md
+++ b/planning/behavior_velocity_planner/intersection-design.md
@@ -1,6 +1,6 @@
-### Intersection
+# Intersection
-#### Role
+## Role
Judgement whether a vehicle can go into an intersection or not by a dynamic object information, and planning a velocity of the low-down/stop.
This module is designed for rule-based intersection velocity decision that is easy for developers to design its behavior. It generates proper velocity for intersection scene.
@@ -9,62 +9,77 @@ In addition, the external users / modules (e.g. remote operation) to can interve
-### Limitations
+## Activation Timing
+
+This function is activated when the attention lane conflicts with the ego vehicle's lane.
+
+## Limitations
This module allows developers to design vehicle velocity in intersection module using specific rules. This module is affected by object detection and prediction accuracy considering as stuck vehicle in this intersection module.
-### Inner-workings / Algorithms
+## Inner-workings / Algorithms
-#### Attention Target Objects
+### How To Select Attention Target Objects
-Car, truck, bus, motorbike are included in the attention target object for the velocity planning in the intersection and bicycle, pedestrian, animal, unknown are not.
+Objects that satisfy all of the following conditions are considered as target objects (possible collision objects):
-#### Attention Lane
+- The type of object type is **car**, **truck**, **bus** or **motorbike**. (Bicycle, pedestrian, animal, unknown are not.)
+- The center of gravity of object is **located within a certain distance** from the attention lane (threshold = `detection_area_margin`) .
+ - In the past, the decision was made based on whether any points of the object's polygon exists in the attention lane, but since there were many false positives, the logic has changed to the current one.
+- The posture of object is **the same direction as the attention lane** (threshold = `detection_area_angle_threshold`).
+ - The orientation of the target is recalculated in this module according to the `orientation_reliable` and the sign of the velocity of the target.
+- Not being **in the same lane as the ego vehicle**.
+ - To avoid judging the vehicle ahead as a collision target. This logic needs to be improved.
-The lane crossing with driving lane and has high priority for the driving lane is defined as attention lane. (Priority tags are needed to be configured according to the situation.)
+### How to Define Attention Lanes
-#### Crossing Judgement
+Target objects are limited by lanelets to prevent unexpected behavior. A lane that satisfies the following conditions is defined as an "Attention Lane" and used to define the target object.
-Time to pass the intersection will be calculated with the length of the intersection (Supposed constant velocity : 10km/h). Driving lane polygon is defined from the position of the ego vehicle to the end point of the lane with intersection tag. It is checked if the polygon and the predicted path of the attention target objects will be crossed.
+- The lane crosses with the driving lane of the ego-vehicle
+- The lane has high priority for the driving lane of the ego-vehicle (priority tags are needed to be configured in Lanelet-map according to the situation).
-#### State Transition (go / stop)
+See the following figures to know how to create an attention area and its rationale.
-If there is no crossing more than a certain period (default : 2.0s), the state transits to “go”. If crossing is detected even once, the state transits to “stop”.
+
-#### Stop Line Automatic Generation
+
-The driving lane is complemented at a certain intervals (default : 20cm), and the line which is a margin distance (default : 100cm) in front of the attention lane is defined as a stop line. (Also the length of the vehicle is considered and the stop point is set at the base_link point in front of the stop lane.)
+
-#### Pass Judge Line
+### Collision Check and Crossing Judgement
-To avoid a rapid braking, in case that a deceleration more than a threshold (default : 0.5G) is needed, the ego vehicle doesn’t stop. In order to judge this condition, pass judge line is set a certain distance (default : 0.5\*v_curr^2/a_max) in front of the stop line.
-To prevent a chattering, once the ego vehicle passes this line, “stop” decision in the intersection won’t be done any more.
-To prevent going over the pass judge line before the traffic light stop line, the distance between stopline and pass judge line become 0m in case that there is a stop line between the ego vehicle and an intersection stop line.
+The following process is performed for the attention targets to determine whether the ego vehicle can cross the intersection safely. If it is judged that the ego vehicle cannot pass through the intersection with enough margin, it will insert the stopping speed on the stop line of the intersection.
-#### Vehicle In a Same Lane Removal
+1. calculate the passing time and the time that the ego vehicle is in the intersection. This time is set as $t_s$ ~ $t_e$
+2. extract the predicted path of the target object whose confidence is greater than `min_predicted_path_confidence`.
+3. detect collision between the extracted predicted path and ego's predicted path in the following process.
+ 1. obtain the passing area of the ego vehicle $A_{ego}$ in $t_s$ ~ $t_e$.
+ 2. calculate the passing area of the target object $A_{target}$ at $t_s$ - `collision_start_margin_time` ~ $t_e$ + `collision_end_margin_time` for each predicted path (\*1).
+ 3. check if $A_{ego}$ and $A_{target}$ regions are overlapped (has collision).
+4. when a collision is detected, the module inserts a stop velocity in front of the intersection. Note that there is a time margin for the stop release (\*2).
-Ignore the object in front of/ behind the ego vehicle in the same lane (Improvement needed : the linkage with the uuid in tracking is needed)
+(\*1) The parameters `collision_start_margin_time` and `collision_end_margin_time` can be interpreted as follows:
-#### Stuck vehicle
+- If the ego vehicle passes through the intersection earlier than the target object, the collision is detected if the time difference between the two is less than `collision_start_margin_time`.
+- If the ego vehicle passes through the intersection later than the target object, the collision is detected if the time difference between the two is less than `collision_end_margin_time`.
-If there is any object in a certain distance (default : 5m) from the end point of the intersection lane on the driving lane and the object velocity is less than a threshold (default 3.0km/h), the object is regarded as a stuck vehicle. If the stuck vehicle exists, the ego vehicle cannot enter the intersection.
+(\*2) If the collision is detected, the state transits to "stop" immediately. On the other hand, the collision judgment must be clear for a certain period (default : 2.0[s]) to transit from "stop" to "go" to prevent to prevent chattering of decisions.
-### Launch Timing
+### Stop Line Automatic Generation
-Launches when there is a conflicting lanelet in ego lane.
+The driving lane is complemented at a certain intervals (default : 20 [cm]), and the line which is a margin distance (default : 100cm) in front of the attention lane is defined as a stop line. (Also the length of the vehicle is considered and the stop point is set at the base_link point in front of the stop lane.)
-### How to Decide Intersection Stop
+### Pass Judge Line
+
+To avoid a rapid braking, in case that a deceleration more than a threshold (default : 0.5[G]) is needed, the ego vehicle doesn’t stop. In order to judge this condition, pass judge line is set a certain distance (default : 0.5 \* v_current^2 / a_max) in front of the stop line.
+To prevent a chattering, once the ego vehicle passes this line, “stop” decision in the intersection won’t be done any more.
+To prevent going over the pass judge line before the traffic light stop line, the distance between stop line and pass judge line become 0m in case that there is a stop line between the ego vehicle and an intersection stop line.
-The intersection stop target should be limited to stuck vehicle in the middle of the road or incoming cruising vehicle that will collide with ego vehicle. Therefore, target vehicles for considering intersection stop meet the following specific conditions.
+### Stuck Vehicle Detection
-- It is inside detection area polygon created in this module and is stopped(parametrized)
- - This means that moving object inside ego lane is not considered as stop target.
-- It is a specific class.
- - User can change intersection stop targets (e.g. do not stop unknown-class targets).
-- It will collide with ego vehicle.
- - This means that the other incoming vehicle from conflicting lanelet can collide with ego vehicle.
+If there is any object in a certain distance (default : 5[m]) from the end point of the intersection lane on the driving lane and the object velocity is less than a threshold (default 3.0[km/h]), the object is regarded as a stuck vehicle. If the stuck vehicle exists, the ego vehicle cannot enter the intersection.
-### Module Parameters
+## Module Parameters
| Parameter | Type | Description |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------- |
@@ -73,17 +88,17 @@ The intersection stop target should be limited to stuck vehicle in the middle of
| `intersection/path_expand_width` | bool | [m] path area to see with expansion |
| `intersection/stop_line_margin` | double | [m] margin before stop line |
| `intersection/stuck_vehicle_detect_dist` | double | [m] this should be the length between cars when they are stopped. |
-| `intersection/stuck_vehicle_ignore_dist` | double | [m] obstacle stop max distance(5.0m) + stuck vehicle size / 2 (0.0m-) |
+| `intersection/stuck_vehicle_ignore_dist` | double | [m] obstacle stop max distance(5.0[m]) + stuck vehicle size / 2.0[m]) |
| `intersection/stuck_vehicle_vel_thr` | double | [m/s] velocity below 3[km/h] is ignored by default |
| `intersection/intersection_velocity` | double | [m/s] velocity to pass intersection. 10[km/h] is by default |
| `intersection/intersection_max_accel` | double | [m/s^2] acceleration in intersection |
| `intersection/detection_area_margin` | double | [m] range for expanding detection area |
-| `intersection/detection_area_length` | double | [m] range for lidar detection 200m is by default |
+| `intersection/detection_area_length` | double | [m] range for lidar detection 200[m] is by default |
| `intersection/detection_area_angle_threshold` | double | [rad] threshold of angle difference between the detection object and lane |
| `intersection/min_predicted_path_confidence` | double | [-] minimum confidence value of predicted path to use for collision detection |
| `merge_from_private_road/stop_duration_sec` | double | [s] duration to stop |
-### How To Tune Parameters
+## How To Tune Parameters
- The time to change state form `Stop` to `GO` is too long.
- Change `state_transit_margin_time` to lower value. Be careful if this margin is too small then vehicle is going to change state many times and cause chattering.
@@ -92,7 +107,7 @@ The intersection stop target should be limited to stuck vehicle in the middle of
- The speed in intersection is too slow
- Change `intersection_velocity` to higher value.
-### Flowchart
+## Flowchart
```plantuml
@startuml
@@ -177,6 +192,30 @@ stop
NOTE current state is treated as `STOP` if `is_entry_prohibited` = `true` else `GO`
-### Known Limits
+## Known Limits
- This module generate intersection stop line and ignoring lanelet automatically form lanelet map , however if you want to set intersection stop line and ignoring lanelet manually you need to tag `right_of_way` and `yield` to all conflicting lanes properly.
+
+---
+
+## How to Set Lanelet Map fot Intersection
+
+
+
+### Set a turn_direction tag (Fig. 1)
+
+IntersectionModule will be activated by this tag. If this tag is not set, ego-vehicle don’t recognize the lane as an intersection. Even if it’s a straight lane, this tag is mandatory if it is located within intersection.
+
+Set a value in `turn_direction` tag to light up turn signals.
+
+Values of `turn_direction` must be one of “straight”(no turn signal), “right” or “left”. Autoware will light up respective turn signals 30[m] before entering the specified lane. You may also set optional tag “turn_signal_distance” to modify the distance to start lighting up turn signals.
+
+Lanes within intersections must be defined as a single Lanelet. For example, blue lane in Fig.3 cannot be split into 2 Lanelets.
+
+### Explicitly describe a stop position [RoadMarking] (Optional) (Fig. 2)
+
+As a default, IntersectionModule estimates a stop position by the crossing point of driving lane and attention lane. But there are some cases like Fig.2 in which we would like to set a stop position explicitly. When a `stop_line` is defined as a `RoadMarking` item in the intersection lane, it overwrites the stop position. (Not only creating `stop_line`, but also defining as a `RoadMaking` item are needed.)
+
+## Exclusion setting of attention lanes [RightOfWay] (Fig.3)
+
+By default, IntersectionModule treats all lanes crossing with the registered lane as attention targets (yellow and green lanelets). But in some cases (e.g. when driving lane is priority lane or traffic light is green for the driving lane), we want to ignore some of the yield lanes. By setting `RightOfWay` of the `RegulatoryElement` item, we can define lanes to be ignored. Register ignored lanes as “yield” and register the attention lanes and driving lane as “right_of_way” lanelets in `RightOfWay` RegulatoryElement (For an intersection with traffic lights, we need to create items for each lane in the intersection. Please note that it needs a lot of man-hours.)
diff --git a/planning/behavior_velocity_planner/merge-from-private-design.md b/planning/behavior_velocity_planner/merge-from-private-design.md
new file mode 100644
index 0000000000000..4443ebecfe61e
--- /dev/null
+++ b/planning/behavior_velocity_planner/merge-from-private-design.md
@@ -0,0 +1,26 @@
+## Merge From Private
+
+### Role
+
+When an ego vehicle enters a public road from a private road (e.g. a parking lot), it needs to face and stop before entering the public road to make sure it is safe.
+
+This module is activated when there is an intersection at the location where the vehicle enters the public road from the private road. The basic behavior is the same as the intersection module, but the ego vehicle must stop once at the stop line.
+
+
+
+### Activation Timing
+
+This module is activated when the following conditions are met:
+
+- ego-lane has a `private` tag
+- ego-lane has a conflict with other no-private lanelets
+
+### Module Parameters
+
+| Parameter | Type | Description |
+| ------------------------------------------- | ------ | ------------------------------- |
+| `merge_from_private_road/stop_duration_sec` | double | [m] time margin to change state |
+
+### Known Issue
+
+If ego vehicle go over the stop line for a certain distance, then ego vehicle will not transit from STOP.
diff --git a/planning/behavior_velocity_planner/no-stopping-area-design.md b/planning/behavior_velocity_planner/no-stopping-area-design.md
index 4672f2d162d1c..340b6934d80e9 100644
--- a/planning/behavior_velocity_planner/no-stopping-area-design.md
+++ b/planning/behavior_velocity_planner/no-stopping-area-design.md
@@ -15,7 +15,7 @@ This module plans to avoid stop in 'no stopping area`.
### Limitation
-This module allows developers to design vehicle velocity in `no_stopping_area` module using specific rules. Once ego vehicle go through pass through point, ego vehicle does't insert stop velocity and does't change decision from GO.
+This module allows developers to design vehicle velocity in `no_stopping_area` module using specific rules. Once ego vehicle go through pass through point, ego vehicle does't insert stop velocity and does't change decision from GO. Also this module only considers dynamic object in order to avoid unnecessarily stop.
#### ModelParameter
diff --git a/planning/behavior_velocity_planner/occlusion-spot-design.md b/planning/behavior_velocity_planner/occlusion-spot-design.md
index 187840f97bbab..cedb85154aef3 100644
--- a/planning/behavior_velocity_planner/occlusion-spot-design.md
+++ b/planning/behavior_velocity_planner/occlusion-spot-design.md
@@ -1,29 +1,58 @@
-### Occlusion Spot
+## Occlusion Spot
-#### Role
+### Role
This module plans safe velocity to slow down before reaching collision point that hidden object is darting out from `occlusion spot` where driver can't see clearly because of obstacles.
-#### Occlusion Spot Private
+### Activation Timing
-This module only works in private road and use occupancy grid map to detect occlusion spots.
+This module is activated when the ego-lane has a private/public attribute.
-#### Occlusion Spot Public
+### Limitation
-This module only works in public road and use dynamic objects to detect occlusion spots.
+To solve the excessive deceleration due to false positive of the perception, the logic of collision spot is switched according to the road type (public/private). This point has not been discussed in detail and needs to be improved (see the description below).
-Considering all occupancy grid cells inside focus range requires a lot of computation cost, so this module ignores to search farther occlusion spot which is longitudinally or laterally slice once occlusion spot is found.
+### Inner-workings / Algorithms
-
+#### Logics Working In Private/Public Load
+
+Deceleration for the occlusion spot works on **different logic** depending on whether the driving road is **public or private**.
+
+There are several types of occlusions, such as "occlusions generated by parked vehicles" and "occlusions caused by obstructions". In situations such as driving on **private roads**, where people jump out of the way frequently, all possible occlusion spots must be taken into account. Therefore, on private roads, the deceleration plan considers all occlusion spots calculated from the **occupancy grid**. On the other hand, while driving at high speeds, it is not reasonable to take into account all occlusion spots (e.g., jumping out from behind a guardrail). Therefore, on **public roads**, the target of the deceleration calculation is currently limited to only the occlusion spots generated by vehicles parked on the road shoulder, which uses the **dynamic object** information.
-##### Definition
+Note that this decision logic is still under development and needs to be improved.
-This module insert safe velocity at collision point and show virtual wall at intersection below.
+#### Occlusion Spot Public
+This module inserts safe velocity at the collision point estimated from the associated occlusion spot under assumption that the pedestrian possibly coming out of the occlusion spot.
+This module consider 3 policies that are very important for risk predicting system for occlusion spot.
+
+1. "Passable" without deceleration (Not implemented yet)
+ If ego vehicle speed is high enough to pass the occlusion spot and expected to have no collision with any objects coming out of the occlusion spot, then it's possible for ego vehicle to pass the spot without deceleration.
+
+2. "Predictable" with enough distance to occlusion
+ If ego vehicle has enough distance to the occlusion spot, then ego vehicle is going to slow down to the speed that is slow enough to stop before collision with full brake.
+ If ego vehicle pass the possible collision point, then ego vehicle is going to drive normally.
+
+3. "Unavoidable" without enough distance to occlusion spot
+ This module assumes the occlusion spot is detected stably far from the ego vehicle. Therefore this module can not guarantee the safety behavior for the occlusion spot detected suddenly in front of the ego vehicle. In this case, slow velocity that does not cause the strong deceleration is only applied.
+
+#### Occlusion Spot Private
+
+This module considers any occlusion spot around ego path computed from the occupancy grid.
+
+
+
+Occlusion spot computation: searching occlusion spots for all cells in the occupancy_grid inside "focus range" requires a lot of computational cost, so this module will stop searching if the first occlusion spot is found in the following searching process.
+
+
+
+Note that the accuracy and performance of this search method is limited due to the approximation.
+
#### Module Parameters
| Parameter | Type | Description |
@@ -55,6 +84,8 @@ This module insert safe velocity at collision point and show virtual wall at int
#### Flowchart
+##### Rough overview of the whole process
+
```plantuml
@startuml
title modifyPathVelocity (Private/Public) Road
@@ -63,9 +94,9 @@ start
:get current road type;
if (road type is PUBLIC) then (yes)
- :use dynamic object array info;
+ :preprocess dynamic object;
else if (road type is PRIVATE) then (yes)
- :use occupancy grid map info;
+ :preprocess occupancy grid map info;
else (no)
stop
endif
@@ -88,3 +119,140 @@ endif
stop
@enduml
```
+
+##### Detail process for public road
+
+```plantuml
+@startuml
+title modifyPathVelocity For Public Road
+start
+partition parking_vehicle_selection {
+:get all lanelet id on ego path;
+:get right/left lanelets around ego path;
+:get center lane lines from lanelets around ego path;
+:get parked vehicle from dynamic object array;
+note right
+ target parked vehicle is define as follow .
+ - dynamic object's semantic type is "car","bus","track".
+ - velocity is below `stuck_vehicle_vel`.
+ - lateral position from lane center is farther than `lateral_deviation_threshold`.
+end note
+}
+partition offset_calculation {
+:interpolate ego path;
+note right
+ using spline interpolation and interpolate (x,y,z,v)
+end note
+:get closest index from ego position in interpolated path;
+:calculate offset from path start to ego;
+}
+:convert interpolated path to `path_lanelet`;
+note right
+ `path_lanelet` is lanelet which is created by ego path
+ and mainly used for arc coordinate conversion.
+end note
+partition generate_possible_collision {
+:generate possible collision behind parked vehicle;
+note right
+ - occlusion spot candidate is stuck vehicle polygon 2 points farther which is closer to ego path.
+ - consider occlusion which is nearer than `lateral_distance_threshold`.
+end note
+:calculate collision path point and intersection point;
+note right
+ - occlusion spot is calculated by stuck vehicle polygon.
+ - intersection point is where ego front bumper and darting object will crash.
+ - collision path point is calculated by arc coordinate consider ego vehicle's geometry.
+end note
+}
+:extract target road type start/end distance by arc length;
+:calculate original velocity and height for the possible collision;
+note right
+calculated (x,y,z,v) at the path using linear interpolation between interpolated path points.
+end note
+partition calculate_safe_velocity {
+:calculate safe velocity consider lateral distance and safe velocity;
+note right
+calculated by
+- ebs deceleration [m/s] emergency braking system consider lateral distance to the occlusion spot.
+- pbs deceleration [m/s] predictive braking system consider distance to the possible collision.
+- min velocity [m/s] the velocity that is allowed on the road.
+- original_velocity [m/s]
+end note
+}
+:insert safe velocity to path;
+note right
+ set minimum velocity for path point after occlusion spot.
+end note
+stop
+@enduml
+```
+
+##### Detail process for private road
+
+```plantuml
+@startuml
+title modifyPathVelocity For Private Road
+start
+partition occupancy_grid_preprocess {
+:convert occupancy grid to image;
+note right
+ convert from occupancy grid to image to use opencv functions.
+end note
+:remove noise from occupancy to apply dilate and erode;
+note right
+ applying dilate and erode is much better and faster than rule base noise reduction.
+end note
+:quantize image to categorize to free_space,unknown,occupied;
+:convert image to occupancy grid;
+note right
+ convert from occupancy grid to image to use opencv functions.
+end note
+}
+partition offset_calculation {
+:interpolate ego path;
+note right
+ using spline interpolation and interpolate (x,y,z,v)
+end note
+:get closest index from ego position in interpolated path;
+:calculate offset from path start to ego;
+}
+:convert interpolated path to `path_lanelet`;
+note right
+ `path_lanelet` is lanelet which is created by ego path
+ and mainly used for arc coordinate conversion.
+end note
+partition generate_possible_collision {
+:generate possible collision from occlusion spot;
+note right
+ - occlusion spot candidate is N by N size unknown cells.
+ - consider occlusion which is nearer than `lateral_distance_threshold`.
+end note
+:calculate collision path point and intersection point;
+note right
+ - occlusion spot is calculated by longitudinally closest point of unknown cells.
+ - intersection point is where ego front bumper and darting object will crash.
+ - collision path point is calculated by arc coordinate consider ego vehicle's geometry.
+end note
+}
+:extract target road type start/end distance by arc length;
+:calculate original velocity and height for the possible collision;
+note right
+calculated (x,y,z,v) at the path using linear interpolation between interpolated path points.
+end note
+partition calculate_safe_velocity {
+:calculate safe velocity consider lateral distance and safe velocity;
+note right
+calculated by
+- ebs deceleration [m/s] emergency braking system consider lateral distance to the occlusion spot.
+- pbs deceleration [m/s] predictive braking system consider distance to the possible collision.
+- min velocity [m/s] the velocity that is allowed on the road.
+- original_velocity [m/s]
+end note
+}
+:insert safe velocity to path;
+note right
+ set minimum velocity for path point after occlusion spot.
+end note
+stop
+@enduml
+```
diff --git a/planning/behavior_velocity_planner/stop-line-design.md b/planning/behavior_velocity_planner/stop-line-design.md
index 05178b7d0550a..d1980469c7482 100644
--- a/planning/behavior_velocity_planner/stop-line-design.md
+++ b/planning/behavior_velocity_planner/stop-line-design.md
@@ -1,17 +1,30 @@
-### Stop Line
+## Stop Line
-#### Role
+### Role
This module plans velocity so that the vehicle can stop right before stop lines and restart driving after stopped.
-#### Module Parameters
+
+
+### Activation Timing
+
+This module is activated when there is a stop line in a target lane.
+
+### Inner-workings / Algorithms
+
+- Gets a stop line from map information.
+- insert a stop point on the path from the stop line defined in the map and the ego vehicle length.
+- Sets velocities of the path after the stop point to 0[m/s].
+- Release the inserted stop velocity when the vehicle stops within a radius of 2[m] from the stop point.
+
+### Module Parameters
| Parameter | Type | Description |
| ----------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `stop_margin` | double | a margin that the vehicle tries to stop before stop_line |
| `stop_check_dist` | double | when the vehicle is within `stop_check_dist` from stop_line and stopped, move to STOPPED state |
-#### Flowchart
+### Flowchart
```plantuml
@startuml
diff --git a/planning/behavior_velocity_planner/traffic-light-design.md b/planning/behavior_velocity_planner/traffic-light-design.md
index dfcbed7eeb1ef..2c5921e555604 100644
--- a/planning/behavior_velocity_planner/traffic-light-design.md
+++ b/planning/behavior_velocity_planner/traffic-light-design.md
@@ -13,9 +13,9 @@ In addition, the STOP/GO interface of behavior_velocity_planner allows external
This module allows developers to design STOP/GO in traffic light module using specific rules. Due to the property of rule-based planning, the algorithm is greatly depends on object detection and perception accuracy considering traffic light. Also, this module only handles STOP/Go at traffic light scene, so rushing or quick decision according to traffic condition is future work.
-#### Launch Timing
+#### Activation Timing
-Launches when there is traffic light in ego lane.
+This module is activated when there is traffic light in ego lane.
#### Algorithm