Docs: Planning Readme + Open Space Planner doc

docs/specs/Open_Space_Planner.md

@@ -8,7 +8,7 @@ This algorithm was initially inspired by several papers<cite>[1]</cite><cite>[2]
 
 ## Algorithm Flow
 
-![](images/Open_space_planner.png)
+![](images/os_planner.png)
 
 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.
 
-![](images/step1.png)
+![](images/os_step1.png)
 
 
 ### 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.
 
-![](images/step2.png)
+![](images/os_step2.png)
 
 Once this stage is complete, the output is directly sent to the Control module to have it sent to the ego-car.
 
-![](images/step3.png)
+![](images/os_step3.png)
+
+## 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
 

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.
 
      ![](images/unprotected1.png)
 
 
-- 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.
 
     ![](images/protected.png)
 
@@ -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
+
+        ![](images/parking2.png)
+
+    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:
+
+        ![](images/parking1.png) 
+
+- **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:
+
+        ![](images/pull_over.png)
+
+    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:
+    
+        ![](images/pull_over1.png)
+    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:
+
+    ![](images/pull_over2.png)
+
+    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.
+
+    ![](images/pull_over3.png)
 
 ## 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.
 ```
 
-![](images/planning_architecture.png)
+![](images/architecture.png)