Merge pull request #132 from ucla-mobility/develop

Develop

.gitignore

@@ -147,3 +147,5 @@ opencda/evaluation_figures/
 evaluation_outputs/
 docs/tmp.py
 data_dumping
+video_dumping
+

docs/index.rst

@@ -45,6 +45,7 @@ for the latest release.
    :caption: Additional Information
 
    md_files/contributor.md
+   md_files/release_history.md
    modules
 
 

docs/md_files/getstarted.md

@@ -4,12 +4,14 @@ OpenCDA provides benchmark scenarios that researchers can use directly without a
 scenario testings only need one line of command:
 ```she
 cd ~/OpenCDA
-python opencda.py -t scenario_name --aply_ml --record
+python opencda.py -t scenario_name -v carla_version --apply_ml --record
 ```
 Parameters explanation:
 * `-t`: The name of the tesitng scenario. A python script with the same name should exist in
 `opencda/scenario_testing/` to construct the simulation, and a yaml file with the same name should exist in 
 `opencda/scenario_testing/config_yaml/` to define the simulation parameters.
+* `-v --version`: Define the CARLA simulator version, default 0.9.11. Right now only 0.9.11 and 0.9.12 are supported.
+  We need this as there are some api changes from 0.9.11 to 0.9.12.
 * `--apply_ml`  (Optional): A flag to indicate whether a deep learning model needs to be loaded. If this flag is 
 set, Pytorch will be imported.
 * `--record` (Optional): A flag to indicate whether to record this simulation. [Check here for more details](https://carla.readthedocs.io/en/latest/adv_recorder/).
@@ -18,9 +20,10 @@ Below we will demonstrate some examples of running the benchmark testings in Ope
 
 ---
 ### Single Vehicle Test
+**Notice: <strong> Change -v 0.9.11 to -v 0.9.12 if you are using CARLA 0.9.12.</strong>
 ####  1. Two-lane highway test
 ```sh
-python opencda.py -t single_2lanefree_carla
+python opencda.py -t single_2lanefree_carla -v 0.9.11
 ```
 In this scenario , a single Connected Automated Vehicle will be spawned at a 2-lane highway customized map.  This
 CAV will try to reach the assigned destination with a desired speed of 100km/h and manage to safely interact
@@ -36,7 +39,7 @@ If you want to activate the perception module, please check [Yaml Defining Rules
 
 #### 2. Town06 test (Pytorch required)
 ```sh
-python opencda.py -t single_town06_carla --apply_ml
+python opencda.py -t single_town06_carla  -v 0.9.11 --apply_ml
 ```
 The apply_ml flag will import the pytorch library and load Yolov5 model (<strong>Thus Pytorch is required</strong>) for object detection. Thus, in this
 scenario, the <strong>perception</strong>, localization, planning and control modules will all be activated.
@@ -46,7 +49,7 @@ scenario, the <strong>perception</strong>, localization, planning and control mo
 
 #### 3. Town06 Co-simulation test (Pytorch and Sumo required)
 ```sh
-python opencda.py -t single_town06_cosim --apply_ml
+python opencda.py -t single_town06_cosim  -v 0.9.11 --apply_ml
 ```
 This scenario applies <strong>Sumo</strong> to generate the traffic flow instead of using Carla traffic manager.
 Yolov5 and simple Lidar fusion are used to detect object 3D bounding box. Therefore, both
@@ -57,15 +60,15 @@ Pytorch and Sumo are required to install to run this benchmark test.
 ### Cooperative Driving Test
 #### 1. Platooning stability test
 ```sh
-python opencda.py -t platoon_stability_2lanefree_carla
+python opencda.py -t platoon_stability_2lanefree_carla -v 0.9.11
 ```
 In this scenario, a platoon with 4 members will be placed at the 2-lane highway map. The platoon leader will dramatically increases
 and decreases its speed to test whether the members can still keep the desired time gap. In this way, the platoon
 stability is verified.
 
 #### 2. Cooperative merge and joining a platoon
 ```sh
-python opencda.py -t platoon_joining_2lanefree_carla
+python opencda.py -t platoon_joining_2lanefree_carla -v 0.9.11
 ```
 In this scenario, a platoon will drive on the mainline together with a mixed traffic flow. A single CAV will come from the 
 merging lane, communicate with the platoon to cooperatively merge into the mainline, and simultaneously join the platoon.
@@ -74,14 +77,14 @@ merging lane, communicate with the platoon to cooperatively merge into the mainl
 
 #### 3. Cooperative merge and joining a platoon under co-simulation (SUMO required)
 ```sh
-python opencda.py -t platoon_joining_2lanefree_cosim
+python opencda.py -t platoon_joining_2lanefree_cosim -v 0.9.11
 ```
 ![](images/platoon_joining_cosim.gif)
 
 #### 4. Platoon back-join (Pytorch required)
 ```sh
-python opencda.py -t platoon_joining_town06_carla --apply_ml
+python opencda.py -t platoon_joining_town06_carla  -v 0.9.11 --apply_ml
 ```
 A single CAV will try to overtake several human-driven vehicles to join the platoon from the back.
 Pytorch is required for this test since we use yolov5 detetion.
-![](images/platoon_joining_town06.gif)
+![](images/platoon_joining_town06.gif)

docs/md_files/installation.md

@@ -18,7 +18,7 @@
 To get started, the following requirements should be fulfilled.
 * __System requirements.__ Any 64-bits OS should run OpenCDA. We highly recommends Ubuntu  16.04/18.04/20.04.
 
-* __Adequate GPU.__ CARLA is a realistic simulation platform based on Unity, which requires at least a 3GB GPU for smooth scene rendering, though 8GB is recommended.
+* __Adequate GPU.__ CARLA is a realistic simulation platform based on Unreal Engine 4, which requires at least a 3GB GPU for smooth scene rendering, though 8GB is recommended.
 * __Disk Space.__ Estimate 100GB of space is recommended to install CARLA and Unreal Engine. 
 * __Python__ Python3.7 or higher version is required for full functions.
 
@@ -29,7 +29,7 @@ To get OpenCDA v0.1 running with complete functionality, you will need four thin
 Pytorch (optional). Pytorch is required only when you want to activate the perception module; otherwise OpenCDA
 will retrieve all perception information from the simulation server directly.
 
-###  1. CARLA Installation (0.9.11 required)
+###  1. CARLA Installation (>= 0.9.11 required)
 
 There are two different recommended ways to install the CARLA simulator and either way is fine for using OpenCDA. <br>
 Note: If you want to use the customized highway map with full assets (.fbx, .xml and .xodr) in OpenCDA, 
@@ -40,15 +40,15 @@ you have to build from source. Visit CARLA's tutorial [ADD a new map](https://ca
 
 <div class="build-buttons">
 <p>
-<a href="https://github.com/carla-simulator/carla/releases/tag/0.9.11" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
-<span class="icon icon-github"></span> CARLA 0.9.11 Package</a>
+<a href="https://github.com/carla-simulator/carla/releases" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
+<span class="icon icon-github"></span> CARLA Released Package</a>
 </p>
 </div>
 
-OpenCDA is only tested at 0.9.11 and thus we highly recommend using this version.
+OpenCDA is tested both at 0.9.11 and 0.9.12.
 To install CARLA as a precompiled package, download and extract the release file. It contains a precompiled version of the simulator, the Python API module and some scripts to be used as examples. <br>
 
-<strong>Note: The  AdditionalMaps_0.9.11.tar.gz also need to be downloaded and extract to the CARLA repo to support
+<strong>Note: The  AdditionalMaps_0.9.1x.tar.gz also need to be downloaded and extract to the CARLA repo to support
 scenario testings in Town06.</strong>
 
 #### 1.2 Build From Source
@@ -84,6 +84,7 @@ After dependencies are installed, we need to install the CARLA python library in
 You can do this by running this script:
 ```sh
 export CARLA_HOME=/path/to/your/CARLA_ROOT
+export CARLA_VERSION=0.9.11 #or 0.9.12 depends on your CARLA
 . setup.sh
 ```
 If everything works correctly, you will see a cache folder is created in your OpenCDA root dir, and the terminal shows
@@ -92,7 +93,7 @@ there should be no error.
 ```sh
 python -c "import carla" # check whether carla is installed correctly.
 ```
-<strong>Note: If you are using Python other than 3.7 and CARLA rather than 0.9.11, then you have to change the setup.sh to your
+<strong>Note: If you are using Python other than 3.7 and CARLA < 0.9.11 then you have to change the setup.sh to your
 carla version's egg file or manually installed carla to your conda environment.</strong>
 
 ### 3. Install Pytorch and Yolov5 (Optional)

docs/md_files/release_history.md

@@ -0,0 +1,34 @@
+## Release History of OpenCDA
+This page demonstrates all the changes since the origin release v0.1.0 with more detailed imags.
+
+---
+### v0.1.1
+#### Cooperative Perception
+OpenCDA now supports data dumping simultaneously for multiple CAVs to develop V2V perception 
+algorithms offline. The dumped data includes: 
+- LiDAR data
+- RGB camera (4 for each CAV)
+- GPS/IMU
+- Velocity and future planned trajectory of the CAV
+- Surrounding vehicles' bounding box position, velocity <br>
+
+Besides the above dumped data, users can also generate the future trajectory for each 
+vehicle for trajectory prediction purpose. Run `python root_of_opencda/scripts/generate_prediction_yaml.py`
+to generate the prediction offline.
+
+This new functionality has been proved helpful. The newest paper <strong>OPV2V: An Open Benchmark Dataset and Fusion Pipeline for Perception with Vehicle-to-Vehicle Communication</strong>
+has utilized this new feature to collect cooperative data. Check https://mobility-lab.seas.ucla.edu/opv2v/ for more information
+
+![](images/opv2v.png )
+
+#### CARLA 0.9.12 Support
+OpenCDA now supports both CARLA 0.9.12 and 0.9.11. Users needs to set CARLA_VERSION variable before
+installing OpenCDA. When users run opencda.py, -v argument is required to classify the CARLA version for
+OpenCDA to select the correct API.
+
+#### Weather Parameters
+To help estimate the influence of weather on cooperative driving automation, users now can 
+define weather setting in the yaml file to control sunlight, fog, rain, wetness and other conditions.
+
+#### Bug Fixes
+Some minor bugs in the planning module are fixed.

docs/md_files/yaml_define.md

@@ -10,6 +10,17 @@ world:  # define the CARLA server setting
   sync_mode: true # whether to use sync mode
   client_port: 2000 # client port to connect to the server
   fixed_delta_seconds: &delta 0.05 # fixed time step 
+  weather: # set weather parameters
+    sun_altitude_angle: 15 # 90 is the midday and -90 is the midnight
+    cloudiness: 0 # 0 is the clean sky and 100 is the thickest cloud
+    precipitation: 0 # rain, 100 is the heaviest rain
+    precipitation_deposits: 0 # Determines the creation of puddles. Values range from 0 to 100, being 0 none at all and 100 a road completely capped with water.
+    wind_intensity: 0 # it will influence the rain
+    fog_density: 0 # fog thickness, 100 is the largest
+    fog_distance: 0  # Fog start distance. Values range from 0 to infinite.
+    fog_falloff: 0 # Density of the fog (as in specific mass) from 0 to infinity. The bigger the value, the more dense and heavy it will be, and the fog will reach smaller heights
+    wetness: 0
+
 
 vehicle_base: &vehicle_base # define cav default parameters
   sensing: &base_sensing # define sensing parameters

opencda.py

@@ -27,6 +27,9 @@ def arg_parse():
                         action='store_true',
                         help='whether ml/dl framework such as sklearn/pytorch is needed in the testing. '
                              'Set it to true only when you have installed the pytorch/sklearn package.')
+    parser.add_argument('-v', "--version", type=str, default='0.9.11',
+                        help='Specify the CARLA simulator version, default'
+                             'is 0.9.11, 0.9.12 is also supported.')
 
     opt = parser.parse_args()
     return opt