diff --git a/docs/specs/Open_Space_Planner.md b/docs/specs/Open_Space_Planner.md
index 6a0bb4347af76538de724885c10b2fb4025437ed..adeccb871952d314046c207af6af79d2ccb21aba 100644
--- a/docs/specs/Open_Space_Planner.md
+++ b/docs/specs/Open_Space_Planner.md
@@ -8,7 +8,7 @@ This algorithm was initially inspired by several papers[1][2]
## Algorithm Flow
-
+
This algorithm takes in input from two different sources:
- Perception data which includes but is not limited to obstacles
@@ -19,9 +19,9 @@ Once the data is in place, Open Space planner is triggered as seen in the image
### Searching - Based Planning
In step 1, a raw trajectory is generated for the ego-car. This stage applies vehicle kinemetic model in algorithm to create the raw trajectory with a series of distance equidistant points as seen in the image below.
-The red line represents the raw trajectory output which is sent to the next step, Optimization to calculate the green smoothened line.
+The red line represents the raw trajectory output from Hybrid A*, which is sent to the next step, Optimization to calculate the green smoothened line.
-
+
### Optimization
@@ -34,15 +34,29 @@ This step involves two major tasks,
The received raw trajectory is taken as an initial guess for optimization to iterate on. The generated result is a set of points that are not distributed evenly but are closer to eachother near the turning while those on a linear path are more spread-out.
This not only ensures better turns, but as time/space is fixed, the nearer the points, the slower the speed of the ego-car. Which also means that velocity tracking in this step is possible but more reasonable acceleration, braking and steering.
-
+
Once this stage is complete, the output is directly sent to the Control module to have it sent to the ego-car.
-
+
+
+## Use Cases
+
+Currently Open Space Planner is used for 2 parking scenarios in the planning stage namely:
+
+### Valet
+
+This scenario is designed to park the ego car in a designated parking spot using a zig-zag trajectory.
+
+### Pull Over
+
+This scenario is designed to park the ego car along the curb, either normally or requiring parallel parking.
+
+To learn more about the existing planning scenarios, please refer to the [Planning README](https://github.com/ApolloAuto/apollo/tree/master/modules/planning)
## Future Applications
-As the algorithm is currently in development, it is currently used for reverse parking, but can also be implemented in scenarios that involve tight U-turns. The main aim of scenario-based planning is to ensure efficient planning of the car's trajectory using targeted algorithms for individual scenarios just like with Open Space Planning for reverse parking.
+As the algorithm is currently in development, it is currently used for reverse and/or parallel parking, but can also be implemented in scenarios that involve tight U-turns or for curb-side parking when an emergency vehicle passes by. The main aim of scenario-based planning is to ensure efficient planning of the car's trajectory using targeted algorithms for individual scenarios just like with Open Space Planning for reverse parking.
## References
diff --git a/docs/specs/images/os_planner.png b/docs/specs/images/os_planner.png
new file mode 100644
index 0000000000000000000000000000000000000000..53cb526bc2a316c92c7a69a4b7b8afa8164de8c1
Binary files /dev/null and b/docs/specs/images/os_planner.png differ
diff --git a/docs/specs/images/os_step1.png b/docs/specs/images/os_step1.png
new file mode 100644
index 0000000000000000000000000000000000000000..22d89d31f9172fdc94659b0a5909d68330f6eed7
Binary files /dev/null and b/docs/specs/images/os_step1.png differ
diff --git a/docs/specs/images/os_step2.png b/docs/specs/images/os_step2.png
new file mode 100644
index 0000000000000000000000000000000000000000..e281eec909144c41e713c66e0cc2bbcd0f14c687
Binary files /dev/null and b/docs/specs/images/os_step2.png differ
diff --git a/docs/specs/images/os_step3.png b/docs/specs/images/os_step3.png
new file mode 100644
index 0000000000000000000000000000000000000000..6fb13cea9fa501ce0b833041d91ebc6724b65ac8
Binary files /dev/null and b/docs/specs/images/os_step3.png differ
diff --git a/docs/specs/images/step1.png b/docs/specs/images/step1.png
deleted file mode 100644
index 812a4646e6ed84f80b0a7c853a7ab56866c96d9b..0000000000000000000000000000000000000000
Binary files a/docs/specs/images/step1.png and /dev/null differ
diff --git a/docs/specs/images/step2.png b/docs/specs/images/step2.png
deleted file mode 100644
index 72a3ecf98567040027e15c2c988fba2ab5432119..0000000000000000000000000000000000000000
Binary files a/docs/specs/images/step2.png and /dev/null differ
diff --git a/docs/specs/images/step3.png b/docs/specs/images/step3.png
deleted file mode 100644
index 5b73614a7ef0f4f9e38a71e276e7d804ee05c001..0000000000000000000000000000000000000000
Binary files a/docs/specs/images/step3.png and /dev/null differ
diff --git a/modules/planning/README.md b/modules/planning/README.md
index 58f42c902676fd753c5340a24d21b9400eb61c21..cb26cac2162c548e2afe2839b0e699a1323a2efb 100644
--- a/modules/planning/README.md
+++ b/modules/planning/README.md
@@ -21,16 +21,18 @@ While the functionality of side pass still exists, it has now been made universa
### Intersection
+The new intersection scenario includes STOP Signs, Traffic Lights and Bare Intersections which do not have either a light or a sign.
+
#### STOP Sign
There are two separate driving scenarios for STOP signs:
-- Unprotected: In this scenario, the car is expected to navigate through a crossroad having a two-way STOP. Our ADC therefore has to creep through and gauge the crossroad's traffic density before continuing onto its path.
+- **Unprotected**: In this scenario, the car is expected to navigate through a crossroad having a two-way STOP. Our ADC therefore has to creep through and gauge the crossroad's traffic density before continuing onto its path.
-- Protected: In this scenario, the car is expected to navigate through a crossroad having a four-way STOP. Our ADC will have to gauge the cars that come to a STOP before it and understand its position in the queue before moving.
+- **Protected**: In this scenario, the car is expected to navigate through a crossroad having a four-way STOP. Our ADC will have to gauge the cars that come to a STOP before it and understand its position in the queue before moving.
@@ -48,35 +50,59 @@ Note: The team is working to add additional driving scenarios into our planner.
#### Traffic Light
-In order to safely and smoothly through a traffic light, we created three scenarios
+In order to safely and smoothly pass through a traffic light, we created 3 driving scenarios:
-- Protected
-- Unprotected Left
-- Unprotected Right
+- **Protected**: In this scenario, our ego car has to pass through a intersection with a clear traffic light indicator. A left arrow or right arrow in green for the corresponding turn.
+- **Unprotected Left**: In this scenario, our ego car will have to make a left turn without a distinct light, meaning the car would need to yeild to oncoming traffic. Just like in the unprotected STOP scenario, our ego car would have to creep to ensure that it is safe to cross the intersection before safely moving through the lane.
+- **Unprotected Right**: In this scenario, our ego car is expected to make an unprotected right turn while yeilding to oncoming traffic. Our ego car will need to creep slowly and gauge the traffic and then make a safe turn.
-In a traffic light scenario, the following steps are performed:
+As discussed above, based on the three driving scenarios, the following 3 steps are performed:
-- Stop/Approach: if a stop is required, ADV stops in front of traffic light stop line
-- Move forward slightly (Creep): Check to see if any other car is moving or in the case of unprotected stop, check to see if there are any oncoming vehicles on either side of the lane
-- Safely move through the intersection
+- **Stop/Approach**: If a stop is required, our ego car will stop in front of traffic light stop line
+- **Move forward slightly (Creep)**: Check to see if any other car is moving or in the case of unprotected turns, check to see if there are any oncoming vehicles on either side of the lane
+- **Move**: Safely drive through the intersection
#### Bare Intersection
-Bare intersection is an scenario to handle intersection without traffic lights or stop sign. In this scenario, the following steps are performed:
+Bare intersection is a scenario designated to an intersection without either a STOP sign or a traffic light. In this scenario, the following steps are performed:
-- Approach: reach the intersection
-- Move forward slightly (Creep): Check to see if any other car is moving or in the case of unprotected stop, check to see if there are any oncoming vehicles on either side of the lane
-- Safely move through the intersection
+- **Approach**: Reach the intersection
+- **Move forward slightly (Creep)**: Check to see if any other car is moving or in the case of unprotected stop, check to see if there are any oncoming vehicles on either side of the lane
+- **Move**: Safely move through the intersection
### Park
-- Pull Over
-- Valet
+The Apollo team is proud to introduce Open Space Planner, a new planning algorithm that can be used for several use cases especially the parking scenario. To learn more about Open Space Planner, please refer to the [following document](https://github.com/ApolloAuto/apollo/blob/master/docs/specs/Open_Space_Planner.md)
+
+- **Valet**: The Valet scenario was designed to safely park your ego car in a targeted parking spot. There are 2 main stages that are performed in order to park your ego car:
+ 1. **Approaching the Parking Spot**: In this stage, standard planning algorithms are used to approach the designated parking spot. The car will gradually cruise to a halt once it has found the right stopping point required in order to reverse into the parking spot as seen in the image below
+
+ 
+
+ 2. **Parking**: In this stage, Open Space Planner algorithm is used to generate a zig-zag trajectory which involves both forward and reverse driving (gear changes) in order to safely park the ego car. A sample trajectory generated for the scenario in the previous image, can be seen below:
+
+ 
+
+- **Pull Over**: The Pull Over scenario was designed especially for maneuvering to the side of the road upon reaching your destination like for curb-side parallel parking. There are 3 main stages to accomplish the pull over scenario.
+ 1. **Approaching**: In this stage, as there is no clear designated parking spot, the ego car simply approaches the side of the road where it seems feasible to park. Standard Planning algorithms are used for this stage. Once it comes to a halt, the second stage begins. An example of stage 1 can be seen in the image below:
+
+ 
+
+ 2. **Retry Approach Parking**: In this stage the ego car adjusts itself to enter the parking spot. It is similar to the `Approach Parking Spot` case in the Valet scenario. An example of stage 2 can be seen in the image below:
+
+ 
+ 3. **Retry Parking**: This stage uses Open Space Planner to parallel park the vehicle. A zig-zag trajectory is generated to help the ego car park itself on the side of the road. A sample trajectory generated for the scenario in the previous image, can be seen below:
+
+ 
+
+ There is a special case in the Pull Over scenario that does not need the Open Space Planner stage. This case occurs when there are no obstacles blocking the curb-side parking of the ego car. An example can be seen below. In such a case, the car simply approaches the parking spot and then enters the spot using standard planning.
+
+ 
## Planning Module Architecture
-The architecture of the planning module has changed in Apollo 3.5 to reflect our modular approach towards different driving scenarios.
-As seen in the figure below, in the planner, are individual driving scenarios discussed above along with their handlers.
+The architecture of the planning module had changed in Apollo 3.5, to reflect our modular approach towards different driving scenarios.
+As seen in the figure below, in the planner, are individual driving scenarios discussed above along with their handlers. With only a few changes in how the scenarios are divided, the overall architecture of the Planning module remains the same in Apollo 5.0.
Each driving scenario has its set of driving parameters that are unique to that scenario making it safer, efficient, easier to customize and debug and more flexible. Each stage is also configurable as it is divided into tasks and each task can be moved or created by editing the `config` file of that scenario.
Some of the key features include:
@@ -92,4 +118,4 @@ Note:
If you wish to include your own driving scenarios, please refer to existing scenarios as a reference. We currently do not have a template for writing your own planning scenario.
```
-
+
diff --git a/modules/planning/images/architecture.png b/modules/planning/images/architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..7eab23eef07d462df82322f42df3de3830d9f505
Binary files /dev/null and b/modules/planning/images/architecture.png differ
diff --git a/modules/planning/images/parking1.png b/modules/planning/images/parking1.png
new file mode 100644
index 0000000000000000000000000000000000000000..07efaee702ae47f61fd1f81f174c91f22525b070
Binary files /dev/null and b/modules/planning/images/parking1.png differ
diff --git a/modules/planning/images/parking2.png b/modules/planning/images/parking2.png
new file mode 100644
index 0000000000000000000000000000000000000000..23c48300f43921b5da1021674f8dc5fd917a38df
Binary files /dev/null and b/modules/planning/images/parking2.png differ
diff --git a/modules/planning/images/planning_architecture.png b/modules/planning/images/planning_architecture.png
deleted file mode 100644
index 4bf3df5521ec182be62a826735fc6cf45a9c403e..0000000000000000000000000000000000000000
Binary files a/modules/planning/images/planning_architecture.png and /dev/null differ
diff --git a/modules/planning/images/pull_over.png b/modules/planning/images/pull_over.png
new file mode 100644
index 0000000000000000000000000000000000000000..9654fb98a9f458b39e56c5b636fe9ec08f261da5
Binary files /dev/null and b/modules/planning/images/pull_over.png differ
diff --git a/modules/planning/images/pull_over1.png b/modules/planning/images/pull_over1.png
new file mode 100644
index 0000000000000000000000000000000000000000..1f8e933fd3974b2c67d148ed1cdcb8919ad4e58f
Binary files /dev/null and b/modules/planning/images/pull_over1.png differ
diff --git a/modules/planning/images/pull_over2.png b/modules/planning/images/pull_over2.png
new file mode 100644
index 0000000000000000000000000000000000000000..f5fac99ef0ee54c5a6a4758a887dac8a4b7302f3
Binary files /dev/null and b/modules/planning/images/pull_over2.png differ
diff --git a/modules/planning/images/pull_over3.png b/modules/planning/images/pull_over3.png
new file mode 100644
index 0000000000000000000000000000000000000000..30655fc6527e61ce77858c90dbb55d5d5aec9906
Binary files /dev/null and b/modules/planning/images/pull_over3.png differ