Merge pull request #96 from ucla-mobility/feature/doc_review

doc review
ucla-mobility · Jul 26, 2021 · 6ecc681 · 6ecc681
2 parents 232a18f + b02f923
commit 6ecc681
Show file tree

Hide file tree

Showing 55 changed files with 178 additions and 126 deletions.
diff --git a/README.md b/README.md
@@ -46,8 +46,7 @@ year={2021}
 ```
 The arxiv link to the paper:  https://arxiv.org/abs/2107.06260
 
-Also, under this LICENSE, OpenCDA is for non-commercial research only. Researchers to be able to modify the source code for their own research only. Contracted work that generates corporate revenues and other general commecial use are prohibited under this lICENSE. See the LICENSE file for details and possible opportunities for commercial use.
-
+Also, under this LICENSE, OpenCDA is for non-commercial research only. Researchers can modify the source code for their own research only. Contracted work that generates corporate revenues and other general commercial use are prohibited under this LICENSE. See the LICENSE file for details and possible opportunities for commercial use.
 ## Get Started
 
  ![teaser](docs/md_files/images/platoon_joining_2lanefree_complete.gif)

diff --git a/docs/index.rst b/docs/index.rst
@@ -5,14 +5,12 @@
 
 Welcome to OpenCDA's documentation!
 ===================================
-OpenCDA is a generalized framework for fast developing and testing
-cooperative driving automation applications(e.g., cooperative
-perception, platooning) as well as autonomous vehicle components(e.g.,
-perception, localization, planning, control) under Co-simulation(CARLA-SUMO).
+OpenCDA is a generalized framework for prototyping cooperative driving automation (CDA; see SAE J3216) applications (e.g., cooperative perception, platooning) as well as automated driving components (e.g., perception, localization, planning, control) integrated with automated driving simulation (CARLA), traffic simulation (SUMO), and Co-simulation (CARLA + SUMO). OpenCDA builds upon standard automated driving system (ADS) platforms and focuses on various classes of data exchanges and cooperation between vehicles, infrastructure, and other road users (e.g., pedestrians).
 
-OpenCDA is a work in progress, and many features are still in the future
-roadmap. We welcome your contribution and please visit our Github repo
-for latest release.
+The goal of the OpenCDA project is to enable researchers and engineers to prototype any cooperative driving applications using our full-stack CDA platform and test them from both automated driving and traffic operations perspectives. OpenCDA bridges the gaps between the communities of automated driving and transporation engineering. Eventually, OpenCDA can be used to develop and test cooperative driving functions and applications for improving safety, sustainability, and efficiency of future transportation systems.
+
+OpenCDA is a work in progress. Many features on the roadmap are being continuously developed. We welcome your contribution and please visit our Github repo
+for the latest release.
 
     `OpenCDA source code on  Github <https://github.com/ucla-mobility/OpenCDA>`_
 
@@ -49,8 +47,7 @@ for latest release.
 
 **Citing OpenCDA**\ :
 
-If you use OpenCDA in a scientific publication, we would appreciate
-citations to the following paper::
+If you are using our OpenCDA framework or codes for your development, please cite the following paper:
 
     @inproceedings{xu2021opencda,
       author  = {Runsheng Xu, Yi Guo, Xu Han, Xin Xia, Hao Xiang, Jiaqi Ma},
@@ -62,6 +59,8 @@ citations to the following paper::
 
 Our paper can be accessed by arxiv: https://arxiv.org/abs/2107.06260
 
+Also, under this LICENSE, OpenCDA is for non-commercial research only. Researchers can modify the source code for their own research only. Contracted work that generates corporate revenues and other general commercial use are prohibited under this LICENSE. See the LICENSE file for details and possible opportunities for commercial use.
+
 Indices and tables
 ==================
 

diff --git a/docs/md_files/contributor.md b/docs/md_files/contributor.md
@@ -1,5 +1,11 @@
-## About us
-OpenCDA is funded and mainly support by [UCLA Mobility Lab](https://mobility-lab.seas.ucla.edu/).
+## About Us
+OpenCDA is brought to you by [UCLA Mobility Lab](https://mobility-lab.seas.ucla.edu/).
+
+### Supervisor
+Dr. Jiaqi Ma (Associate Professor @ UCLA)
+- Lab Principal Investigator
+- [Linkedin](https://www.linkedin.com/in/jiaqi-ma-17037838/)
+- [Google Scholar](https://scholar.google.com/citations?user=S3cQz1AAAAAJ&hl=en)
 
 ### Supervisor
 Dr. Jiaqi Ma (Associate Professor @ UCLA)
@@ -9,25 +15,29 @@ Dr. Jiaqi Ma (Associate Professor @ UCLA)
 
 ### Core Developer
 Runsheng Xu (Ph.D. Student @ UCLA):
-- OpenCDA System Architect
+- Project Lead and OpenCDA System Architect
 - [Homepage](https://derrickxunu.github.io/)
 - [Linkedin](https://www.linkedin.com/in/runsheng-xu/)
 
 Xu Han (Ph.D. Student @ UCLA):
-- Map customization
+- Maps
 - [Linkedin](https://www.linkedin.com/in/xu-han-12851a64/)
 
 Hao Xiang (Ph.D. Student @ UCLA):
-- Trajectory prediction module, functionality enhancement
+- Trajectory Prediction, Functionality Enhancement
 - [Homepage](https://xhwind.github.io/)
 - [Linkedin](https://www.linkedin.com/in/hao-xiang-42bb5a1b2/)
 
-### Theoretical Support
 Dr. Xin Xia (Postdoc @ UCLA):
-- Theoretical guidance on cooperative localization
+- Cooperative Localization
 - [Linkedin](https://www.linkedin.com/in/xin-xia-3b6589189/)
 
 Dr. Yi Guo (Postdoc @ UC):
+<<<<<<< HEAD
+- SUMO Integration, platooning algorithm, SUMO Only Mode (under dev)
+- [Linkedin](https://www.linkedin.com/in/yi-guo-4008baaa/)
+=======
 - Help on Sumo part
 - [Linkedin](https://www.linkedin.com/in/yi-guo-4008baaa/)
 
+>>>>>>> 232a18fe1724891b03327ab54f14f5849ae11214
diff --git a/docs/md_files/getstarted.md b/docs/md_files/getstarted.md
@@ -1,6 +1,6 @@
 ## Quick Start 
 
-OpenCDA provides benchmark scenarios that researchers can use directly without any modification. Running these 
+OpenCDA provides benchmark scenarios that researchers can use directly without any modification. We will also be adding new testing scenarios in future releases. Running these 
 scenario testings only need one line of command:
 ```she
 cd ~/OpenCDA
@@ -14,15 +14,15 @@ Parameters explanation:
 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/).
 
-Below we will demonstrate some examples of running the benchmark testings in OpenCDA
+Below we will demonstrate some examples of running the benchmark testings in OpenCDA.
 
 ---
 ### Single Vehicle Test
 ####  1. Two-lane highway test
 ```sh
 python opencda.py -t single_2lanefree_carla
 ```
-In this scenario , a single Connected Automated Vehicle will be spawn at a 2-lane highway customized map.  This
+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
 with the surrounding traffic flow. The CAV's localization, planning, and control modules will be activated, and the perception module will be deactivated
 by default, thus <strong> pytorch is NOT required in this testing </strong>. <br>
@@ -63,7 +63,7 @@ In this scenario, a platoon with 4 members will be placed at the 2-lane highway
 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 join a platoon
+#### 2. Cooperative merge and joining a platoon
 ```sh
 python opencda.py -t platoon_joining_2lanefree_carla
 ```
@@ -72,7 +72,7 @@ merging lane, communicate with the platoon to cooperatively merge into the mainl
 
 ![](images/platoon_joining_2lanefree.gif)
 
-#### 3. Cooperative merge and join a platoon under co-simulation (Sumo required)
+#### 3. Cooperative merge and joining a platoon under co-simulation (SUMO required)
 ```sh
 python opencda.py -t platoon_joining_2lanefree_cosim
 ```
@@ -82,6 +82,6 @@ python opencda.py -t platoon_joining_2lanefree_cosim
 ```sh
 python opencda.py -t platoon_joining_town06_carla --apply_ml
 ```
-A single CAV will try to overtake several human-drive vehicles to join the platoon from the back side.
+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)
diff --git a/docs/md_files/installation.md b/docs/md_files/installation.md
@@ -2,7 +2,7 @@
 
 * [__System/Hardware Requirements__](#requirements)
 * [__Local Installation__](#local-installation)
-    * [__1,CARLA installation__](#1-carla-installation0911-required)
+    * [__1. CARLA installation__](#1-carla-installation0911-required)
 	    * [1.1 Package installation](#11-package-installation)  
 	    * [1.2 Build from source](#12-build-from-source)  
 
@@ -20,13 +20,13 @@ To get started, the following requirements should be fulfilled.
 
 * __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.
 * __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.
+* __Python__ Python3.7 or higher version is required for full functions.
 
 
 ---
 ## Local Installation
 To get OpenCDA v0.1 running with complete functionality, you will need four things: CARLA, OpenCDA, and
-Pytorch (optional). Pytorch is required only when you want to activate the perception module, otherwise OpenCDA
+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)
@@ -36,7 +36,7 @@ Note: If you want to use the customized highway map with full assets (.fbx, .xml
 you have to build from source. Visit CARLA's tutorial [ADD a new map](https://carla.readthedocs.io/en/latest/tuto_A_add_map_overview/) for more information.
 
 
-#### 1.1 Package installation
+#### 1.1 Package Installation
 
 <div class="build-buttons">
 <p>
@@ -122,10 +122,10 @@ After pytorch installation, install the requirements for Yolov5. <br>
 pip install -qr https://raw.githubusercontent.com/ultralytics/yolov5/master/requirements.txt  # install dependencies
 ```
 
-### 4. Install Sumo (Optional)
-Sumo installation is only required for the users who require to conduct co-simulation testing.
+### 4. Install SUMO (Optional)
+SUMO installation is only required for the users who require to conduct co-simulation testing and use future release of SUMO-only mode.
 
-You can install sumo directly by apt-get:
+You can install SUMO directly by apt-get:
 ```sh
 sudo add-apt-repository ppa:sumo/stable
 sudo apt-get update

diff --git a/docs/md_files/introduction.md b/docs/md_files/introduction.md
@@ -1,9 +1,14 @@
 ## OpenCDA Overview
 Current autonomous driving simulation platforms that support scene rendering and traffic simulation mainly concentrate
+<<<<<<< HEAD
+on single-vehicle intelligence; therefore, developing and testing Cooperative Driving Automation applications (e.g., cooperative perception, 
+platooning, signalized intersection approach and departure) under a realistic simulated environment becomes difficult.
+=======
 on single-vehicle intelligence, therefore, developing and testing Cooperative Driving Automation applications (e.g., cooperative perception,
 cooperative merge) under a realistic simulated environment becomes difficult.
+>>>>>>> 232a18fe1724891b03327ab54f14f5849ae11214
 
-OpenCDA is created to fill such gap. 
+OpenCDA is created to fill such gaps. 
 
 <div class="build-buttons">
 <p>
@@ -19,19 +24,19 @@ OpenCDA is created to fill such gap.
     Built  upon these basic modules, OpenCDA supports a range of  <strong>common cooperative  driving  applications</strong>. <br />
  2. <em>Co-Simulation Tools</em>: <br />OpenCDA provides interfaces to integrate multiple open-source simulation tools
  with the cooperative driving system. Through the interfaces, OpenCDA is able to take advantage of the high-quality scene rendering
-  and realistic dynamic modelling from <strong>CARLA</strong> , and the realistic traffic simulation from <strong>SUMO</strong>.
+  and realistic dynamic modelling from <strong>CARLA</strong> , and the realistic traffic simulation from <strong>SUMO</strong>. Also, CARLA only and SUMO only mode of OpenCDA also offers researchers the flexibility to test vehicle-level and traffic-level performance, respectively.
 
  3. <em>Scenario Manager</em>:  <br />By defining the parameters in the Yaml file,  OpenCDA is able to <strong>construct the simulation scenario</strong>,
 <strong> creating the traffic flows</strong>, and <strong>assigning various dynamic driving tasks </strong> to different connected automated vehicles. 
  Through such lightweight configuration, researchers can conveniently test and evaluate their algorithms under different scenarios. In the next verision v0.2, 
  OpenScenario will be supported to trigger special events.
 
 ### Key Features
-The key features of OpenCDA can be summarized as <strong>CIFMB</strong>:
-* <strong>C</strong>onnectivity and <strong>C</strong>ooperation: OpenCDA supports various levels and categories of cooperation between CAVs in simulation.
+The key features of OpenCDA are:
+* <strong>Full-stack CDA System</strong>: OpenCDA provides a full-stack automated driving and cooperative driving software system that contains perception, localization, planning, control, and V2X communication modules.
+* <strong>Connectivity and Cooperation</strong>: OpenCDA supports various levels and categories of cooperation between CAVs in simulation. This differentiates OpenCDA with other single vehicle automation tools.
   This differentiates OpenCDA with other single vehicle automation tools.
-* <strong>I</strong>ntegration: OpenCDA integrates CARLA and SUMO together for realistic scene rendering, vehicle modeling and traffic simulation.
-* <strong>F</strong>ull-stack System: OpenCDA provides a full-stack software system that contains perception, localization, planning, control, and V2X communication modules.
-* <strong>M</strong>odularity: OpenCDA is highly modularized, enabling users to conveniently replace any default algorithms or protocols with their own customzied design. 
-* <strong>B</strong>enchmark: OpenCDA offers benchmark testing scenarios, state-of-the-art benchmark algorithms for all modules, benchmark testing road maps, and benchmark evaluation metrics.
+* <strong>Integration</strong>: OpenCDA utilizes CARLA and SUMO separately, as well as integrates them together for realistic scene rendering, vehicle modeling, and traffic simulation. It is also efficient and flexible enough to be applied for software-in-the-loop and hardware-in-the-loop testing.
+* <strong>Modularity</strong>: OpenCDA is highly modularized, enabling users to conveniently replace any default algorithms or protocols with their own customzied design. 
+* <strong>Benchmark</strong>: OOpenCDA offers benchmark testing scenarios, benchmark baseline maps, state-of-the-art benchmark algorithms for ADS and Cooperative ADS functions, and benchmark evaluation metrics.
 
diff --git a/docs/md_files/traffic_generation.md b/docs/md_files/traffic_generation.md
@@ -1,6 +1,6 @@
 ## Traffic Generation
 
-OpenCDA supports two different ways to generate the background traffic flow: CARLA traffic manager and Sumo traffic simulation.
+OpenCDA supports two different ways to generate the background traffic flow: CARLA traffic manager and SUMO traffic simulation. The traffic and other scenario generation function are currently being enhanced and will be released in the future.
 
 ---
 ### CARLA Traffic Manager

diff --git a/opencda.py b/opencda.py
@@ -4,7 +4,7 @@
 """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import argparse
 import importlib

diff --git a/opencda/core/actuation/control_manager.py b/opencda/core/actuation/control_manager.py
@@ -3,7 +3,7 @@
 Controller interface
 """
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import importlib
 

diff --git a/opencda/core/actuation/pid_controller.py b/opencda/core/actuation/pid_controller.py
@@ -2,8 +2,13 @@
 """
 PID Control Class
 """
-# Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+
+# Copyright (c) # Copyright (c) 2018-2020 CVC.
+#
+# This work is licensed under the terms of the MIT license.
+# For a copy, see <https://opensource.org/licenses/MIT>.
+
+
 from collections import deque
 
 import math

diff --git a/opencda/core/application/platooning/fsm.py b/opencda/core/application/platooning/fsm.py
@@ -4,7 +4,7 @@
 """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 from enum import Enum
 

diff --git a/opencda/core/application/platooning/platoon_behavior_agent.py b/opencda/core/application/platooning/platoon_behavior_agent.py
@@ -3,7 +3,7 @@
 """Behavior manager for platooning specifically
 """
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import weakref
 from collections import deque

diff --git a/opencda/core/application/platooning/platoon_debug_helper.py b/opencda/core/application/platooning/platoon_debug_helper.py
@@ -3,7 +3,7 @@
 Analysis + visualization functions for platooning
 """
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 from opencda.core.plan.planer_debug_helper \
     import PlanDebugHelper

diff --git a/opencda/core/application/platooning/platooning_manager.py b/opencda/core/application/platooning/platooning_manager.py
@@ -4,7 +4,7 @@
 """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import uuid
 import weakref

diff --git a/opencda/core/application/platooning/platooning_plugin.py b/opencda/core/application/platooning/platooning_plugin.py
@@ -4,7 +4,7 @@
 """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import warnings
 

diff --git a/opencda/core/common/cav_world.py b/opencda/core/common/cav_world.py
@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import importlib
 

diff --git a/opencda/core/common/data_dumper.py b/opencda/core/common/data_dumper.py
@@ -4,7 +4,7 @@
 """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import os
 

diff --git a/opencda/core/common/v2x_manager.py b/opencda/core/common/v2x_manager.py
@@ -3,7 +3,7 @@
 """Communication manager for cooperation
 """
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 from collections import deque
 import weakref

diff --git a/opencda/core/common/vehicle_manager.py b/opencda/core/common/vehicle_manager.py
@@ -3,7 +3,7 @@
 Basic class of CAV
 """
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 
 import uuid
 

diff --git a/opencda/core/plan/behavior_agent.py b/opencda/core/plan/behavior_agent.py
@@ -1,14 +1,12 @@
-# Copyright (c) # Copyright (c) 2018-2020 CVC.
-#
-# This work is licensed under the terms of the MIT license.
-# For a copy, see <https://opensource.org/licenses/MIT>.
+# -*- coding: utf-8 -*-
 
-
-""" This module implements an agent that roams around a track following random
-waypoints and avoiding other vehicles. The agent also responds to
- traffic lights, traffic signs, and has different possible configurations.
+"""Behavior planning module
 """
 
+# Author: Runsheng Xu <rxx3386@ucla.edu>
+# License: TDG-Attribution-NonCommercial-NoDistrib
+
+
 import math
 import random
 import sys

diff --git a/opencda/core/plan/collision_check.py b/opencda/core/plan/collision_check.py
@@ -2,7 +2,7 @@
 """ This module is used to check collision possibility """
 
 # Author: Runsheng Xu <rxx3386@ucla.edu>
-# License: MIT
+# License: TDG-Attribution-NonCommercial-NoDistrib
 import math
 from math import sin, cos
 from scipy import spatial