From 9bb66cd2509da296d7b07ce283a41443525c2fff Mon Sep 17 00:00:00 2001 From: Natasha Dsouza Date: Tue, 19 Jun 2018 21:24:05 -0400 Subject: [PATCH] Navigation mode (#4598) * made the navigation document consistent and grammatically correct * language, grammar and formatting changes to first 5 How-to docs * update * update * changes to grammar and formatting of how-to docs --- docs/howto/how_to_build_and_release.md | 26 +++--- docs/howto/how_to_build_your_own_kernel.md | 17 ++-- docs/howto/how_to_create_a_pull.md | 16 ++-- docs/howto/how_to_document_code.md | 14 +-- docs/howto/how_to_install_apollo_kernel.md | 6 +- .../how_to_run_apollo_2.5_with_ubuntu16.md | 27 +++--- .../how_to_save_load_docker_image_locally.md | 12 +-- docs/howto/how_to_style_check_to_one_dir.md | 8 +- .../how_to_use_apollo_2.5_navigation_mode.md | 92 ++++++++++--------- 9 files changed, 116 insertions(+), 102 deletions(-) diff --git a/docs/howto/how_to_build_and_release.md b/docs/howto/how_to_build_and_release.md index 5d59fd6121c..e1b82898473 100644 --- a/docs/howto/how_to_build_and_release.md +++ b/docs/howto/how_to_build_and_release.md @@ -7,20 +7,20 @@ Build and Release * [4. Test](#test) ## Install Docker -The system requirement for building Apollo is Ubuntu 14.04. Docker container is the simplest way to set up the build environment for Apollo project. Detailed docker tutorial is [here](https://docs.docker.com/). +The system requirement for building Apollo is Ubuntu 14.04. Using a Docker container is the simplest way to set up the build environment for Apollo project. A Detailed docker tutorial can be found [here](https://docs.docker.com/). -To install, you may refer to -[official guide to install the docker-ce](https://docs.docker.com/install/linux/docker-ce/ubuntu). -Don't forget the +To install docker, you may refer to +[Official guide to install the Docker-ce](https://docs.docker.com/install/linux/docker-ce/ubuntu). +Don't forget to test it using [post-installation steps for Linux](https://docs.docker.com/install/linux/linux-postinstall). ## Build and Release ### Start container -We provide a build image named *dev-latest*. Container will mount your local apollo repo to */apollo*. +We provide a build image named *dev-latest*. The Container will mount your local apollo repo to */apollo*. ```bash bash docker/scripts/dev_start.sh ``` -### Get into container +### Get into the container ```bash bash docker/scripts/dev_into.sh ``` @@ -28,7 +28,7 @@ bash docker/scripts/dev_into.sh ```bash bash apollo.sh build ``` -If the computer is very slow, you can enter the following command to limit the CPU. +`Note:` If your computer is very slow, you can enter the following command to limit the CPU. ``` bash apollo.sh build --local_resources 2048,1.0,1.0 @@ -39,9 +39,9 @@ bash apollo.sh build --local_resources 2048,1.0,1.0 ```bash bash apollo.sh release ``` -This will generate a release directory, which contains ROS environment, running scripts, binaries and dependent shared libraries (.so files). +This command will generate a release directory, which contains the ROS environment, running scripts, binaries and dependent shared libraries (.so files). -To create a release excluding proprietary software (such as ESD CAN library), do: +To create a release excluding proprietary software (such as ESD CAN library), use: ```bash bash apollo.sh release_noproprietary ``` @@ -49,12 +49,12 @@ bash apollo.sh release_noproprietary ```bash bash apollo_docker.sh gen ``` -This will create a new docker image with the release directory. The release image will be named as *release-yyyymmdd_hhmm*. Meanwhile, your most recent built image will be tagged as *release-latest*. **The docker_release needed to be executed outside of container.** +This will create a new docker image with the release directory. The release image will be named as *release-yyyymmdd_hhmm*. Meanwhile, your most recent built image will be tagged as *release-latest*. **The docker_release needed to be executed outside the container.** ### Push docker images ```bash bash apollo_docker.sh push ``` -The command will push your most recent release docker image to the docker hub. +This command will push your most recent release docker image to the docker hub. ## Build in Visual Studio Code ### Install VSCode @@ -69,9 +69,9 @@ Start VSCode with the following command: code ``` ### Open the Apollo project in VSCode -Use the keyboard shortcut (Ctrl+K Ctrl+O) to open the Apollo project. +Use the keyboard shortcut **(Ctrl+K Ctrl+O)** to open the Apollo project. ### Build the Apollo project in VSCode -Use the keyboard shortcut (Ctrl+Shift+B) to build the Apollo project. +Use the keyboard shortcut **(Ctrl+Shift+B)** to build the Apollo project. ### Run all unit tests for the Apollo project in VSCode Select the "Tasks->Run Tasks..." menu command and click "run all unit tests for the apollo project" from a popup menu to check the code style for the Apollo project. ### Run a code style check task for the Apollo project in VSCode diff --git a/docs/howto/how_to_build_your_own_kernel.md b/docs/howto/how_to_build_your_own_kernel.md index 8f405462273..e42ce530cc1 100644 --- a/docs/howto/how_to_build_your_own_kernel.md +++ b/docs/howto/how_to_build_your_own_kernel.md @@ -1,13 +1,16 @@ -# Installing Your Own Kernel. +# Installing Your Own Kernel -## Helpful hints before you begin. -If you have modified the kernel, or the pre-built kernel is not the best for your platform, you can build your own kernel with the following steps. +## Helpful hints before you begin +If you have modified the kernel, or the pre-built kernel is not the best for your platform, you can build your own kernel with the following steps: -## Installing your own kernel. +## Installing your own kernel 1. Clone the code from repository. -```git clone https://github.com/ApolloAuto/apollo-kernel.git``` -```cd apollo-kernel``` +``` +git clone https://github.com/ApolloAuto/apollo-kernel.git +cd apollo-kernel +``` + 2. Add the ESD CAN driver source code according to [ESDCAN-README.md](https://github.com/ApolloAuto/apollo-kernel/blob/master/linux/ESDCAN-README.md). -3. Build the kernel with the following command. +3. Build the kernel with the following command: ```bash build.sh``` 4. Install the kernel the same way as using a pre-built [Apollo Kernel](https://github.com/ApolloAuto/apollo/blob/master/docs/howto/how_to_install_apollo_kernel.md). diff --git a/docs/howto/how_to_create_a_pull.md b/docs/howto/how_to_create_a_pull.md index cf530150c13..02797c169dd 100644 --- a/docs/howto/how_to_create_a_pull.md +++ b/docs/howto/how_to_create_a_pull.md @@ -1,10 +1,9 @@ -How to create a pull request -========================== +# How to create a pull request -You can follow the standard [github approach](https://help.github.com/articles/using-pull-requests/) to contribute code. Here is one sample setup. +You can follow the standard [github approach](https://help.github.com/articles/using-pull-requests/) to contribute code to Apollo. Here is a sample setup: - Fork a new repo with your GitHub username. -- Set up your github personal email and user name +- Set up your GitHub personal email and user name ``` git config user.name "XXX" @@ -25,7 +24,12 @@ git config user.email "XXX@[XXX.com]" (Use HTTPS) git remote add upstream https://github.com/ApolloAuto/apollo.git ``` -- Create a new branch, make changes and commit. +- Confirm that the upstream branch has been added +``` +git remote -v +``` + +- Create a new branch, make changes and commit ``` git checkout -b "my_dev" @@ -44,6 +48,6 @@ git push -f -u origin "my_dev" ``` - Generate a new pull request between "Apolloauto/apollo:master" and "forked repo:my_dev" -- Collaborators will review and merge the commit. +- Collaborators will review and merge the commit (this may take some time, please be patient) Thanks a lot for your contributions! diff --git a/docs/howto/how_to_document_code.md b/docs/howto/how_to_document_code.md index 9b96f29f188..b4d4f0c2f27 100644 --- a/docs/howto/how_to_document_code.md +++ b/docs/howto/how_to_document_code.md @@ -1,9 +1,9 @@ # How to document source code for doxygen -Developers who are not familiar with doxygen can get more information from its official website [http://www.stack.nl/~dimitri/doxygen/](http://www.stack.nl/~dimitri/doxygen/). +Developers who are not familiar with doxygen can get more information from its [official website](http://www.stack.nl/~dimitri/doxygen/). -We use [time.h](https://github.com/ApolloAuto/apollo/blob/master/modules/common/time/time.h) as an example to explain how to document. -## file +We use [time.h](https://github.com/ApolloAuto/apollo/blob/master/modules/common/time/time.h) as an example to explain how to successfully document code. +### File ``` /** * @file @@ -14,7 +14,7 @@ We use [time.h](https://github.com/ApolloAuto/apollo/blob/master/modules/common/ */ ``` -## namespace +### Namespace ``` /** * @namespace apollo::common::time @@ -25,7 +25,7 @@ namespace common { namespace time { ``` -## class +### Class ``` /** * @class Clock @@ -39,7 +39,7 @@ class Clock { ... ``` -## function +### Function ``` /** * @brief Set the behavior of the \class Clock. @@ -52,7 +52,7 @@ class Clock { } ``` -## public / protected class member variables +### Public / protected class member variables ``` /// Stores the currently set timestamp, which serves mock clock /// queries. diff --git a/docs/howto/how_to_install_apollo_kernel.md b/docs/howto/how_to_install_apollo_kernel.md index 0f024323a60..f07ed3778cc 100644 --- a/docs/howto/how_to_install_apollo_kernel.md +++ b/docs/howto/how_to_install_apollo_kernel.md @@ -1,6 +1,6 @@ # Installing the Apollo Kernel ## Helpful hints before you begin -* The Apollo runtime in the vehicle requires the Apollo Kernel. You are strongly recommended to install the pre-built kernel. +* The Apollo runtime environment in the vehicle requires the Apollo Kernel. You are strongly recommended to install the pre-built kernel. ## Installing Apollo Kernel @@ -10,5 +10,5 @@ https://github.com/ApolloAuto/apollo-kernel/releases * ```tar zxvf linux-4.4.32-apollo-1.5.0.tar.gz``` * ```cd install``` * ```sudo bash install_kernel.sh``` -3. Reboot your system by the reboot command -4. After rebooting, build the ESD CAN driver source code. How to build the ESD CAN driver source code can be found at [ESDCAN-README.md](https://github.com/ApolloAuto/apollo-kernel/blob/master/linux/ESDCAN-README.md) +3. Reboot your system using the reboot command +4. After rebooting, build the ESD CAN driver source code. Resources to build the ESD CAN driver source code can be found here: [ESDCAN-README.md](https://github.com/ApolloAuto/apollo-kernel/blob/master/linux/ESDCAN-README.md) diff --git a/docs/howto/how_to_run_apollo_2.5_with_ubuntu16.md b/docs/howto/how_to_run_apollo_2.5_with_ubuntu16.md index 24b9b7b195f..afccaded91f 100644 --- a/docs/howto/how_to_run_apollo_2.5_with_ubuntu16.md +++ b/docs/howto/how_to_run_apollo_2.5_with_ubuntu16.md @@ -1,25 +1,26 @@ # How to Run Apollo in Ubuntu 16 (Apollo 2.5) -We recommend to use Ubuntu 14 for Apollo. For the user using ubuntu 16, here is the extra step you have to follow to run Apollo 2.5 under ubuntu 16. +We recommend using **Ubuntu 14.04** for Apollo. For those users that currently have Ubuntu 16 installed, here is the extra step you have to follow to run Apollo 2.5 successfully on your Ubuntu 16 machine. -1. You need glfw 3.2 and above, which supports EGL and run-time context creation API selection. (Refer to http://www.glfw.org/docs/latest/news.html) +1. You need GLFW(Graphics Library Framework) 3.2 and above, which supports EGL and run-time context creation API selection. (Refer to [http://www.glfw.org/docs/latest/news.html](http://www.glfw.org/docs/latest/news.html) for additional information) +Install the correct version from [this link](https://launchpad.net/ubuntu/+source/glfw3). -Installed the version from https://launchpad.net/ubuntu/+source/glfw3. +2. Add following one line in `glfw_fusion_viewer.cc` file, in GLFWFusionViewer::window_init() before the glfwCreateWindow() call: + ``` + glfwWindowHint(GLFW_CONTEXT_CREATION_API, GLFW_EGL_CONTEXT_API); + ``` -2. Add following one line in glfw_fusion_viewer.cc: -glfwWindowHint(GLFW_CONTEXT_CREATION_API, GLFW_EGL_CONTEXT_API); - -(in GLFWFusionViewer::window_init() before the glfwCreateWindow() call) - - -With this, the perception_lowcost_vis finally works on my machine without a segfault. +With this, the `perception_lowcost_vis` should work on your machine without a segfault. -The issue comes from some behavior changes in the latest nvidia driver and a glfw bug mentioned in http://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx: +The issue comes from a behavior changes in the latest nvidia driver and a glfw bug. You can find information about the bug [here](http://www.glfw.org/docs/latest/window_guide.html#window_hints_ctx). To summarize the behaviour, - “On some Linux systems, creating contexts via both the native and EGL APIs in a single process will cause the application to segfault. Stick to one API or the other on Linux for now.” +``` +“On some Linux systems, creating contexts via both the native and EGL APIs in a single process +will cause the application to segfault. Stick to one API or the other on Linux for now.” +``` So, with the driver (on Ubuntu 16), glfw_fusion_viewer needs to be set up to use EGL_CONTEXT_API instead of the default NATIVE_CONTEXT_API to evade the segfault. -We plan to update the Apollo docker to support these. \ No newline at end of file +We plan to update the Apollo docker to support these soon! \ No newline at end of file diff --git a/docs/howto/how_to_save_load_docker_image_locally.md b/docs/howto/how_to_save_load_docker_image_locally.md index 4cd67bdce66..de4dcf8eda3 100644 --- a/docs/howto/how_to_save_load_docker_image_locally.md +++ b/docs/howto/how_to_save_load_docker_image_locally.md @@ -1,7 +1,7 @@ -# How to save and load docker image -Considering the docker image is more than one Gigabyte, it is better to generate or download the docker image in the WIFI environment and then copy the image to cars. +# How to save and load your docker image +Considering the docker image is more than one Gigabyte, it is better to generate or download the docker image using WiFi or a very stable internet connection, and then copy the image to your car. -## Save Docker Image +## Save the Docker Image After generating or downloading a docker image, you can save the docker image into a local tar file. @@ -12,11 +12,9 @@ e.g. docker save -o apollo_img.tar apolloauto/apollo:release-latest ``` -## Load Docker Image +## Load the Docker Image -After copying the tar file to the car, you need to load the docker image from the tar file. - -e.g. +After copying the .tar file to the car, you need to load the docker image from the .tar file as shown below: ``` # docker load -i diff --git a/docs/howto/how_to_style_check_to_one_dir.md b/docs/howto/how_to_style_check_to_one_dir.md index f47e077c50a..c23a7001026 100644 --- a/docs/howto/how_to_style_check_to_one_dir.md +++ b/docs/howto/how_to_style_check_to_one_dir.md @@ -1,13 +1,13 @@ -## how to add c++ style check to one directory? -1. in BUILD file, at the top, add the following line +## How to add C++ style check to one directory? +1. In the BUILD file, at the top, add the following line ``` load("//tools:cpplint.bzl", "cpplint") ``` -2. in BUILD file, at the bottom, add the following line +2. In the BUILD file, at the bottom, add the following line ``` cpplint() ``` -3. run `apollo.sh check` to verify if the directory passes style check. +3. Run `apollo.sh check` to verify if the directory passes style check. ### Please use the [BUILD](https://github.com/ApolloAuto/apollo/blob/master/modules/canbus/BUILD) file of canbus module as an example. ``` diff --git a/docs/howto/how_to_use_apollo_2.5_navigation_mode.md b/docs/howto/how_to_use_apollo_2.5_navigation_mode.md index 8a65bab07fd..cda5a011f01 100644 --- a/docs/howto/how_to_use_apollo_2.5_navigation_mode.md +++ b/docs/howto/how_to_use_apollo_2.5_navigation_mode.md @@ -2,20 +2,25 @@ ### This article is translated by the Apollo community team. -Apollo is well received and highly commended by developers in the field of autonomous driving for its well-designed architecture, full functionality, robust open-source ecosystem, and standardized coding style. However, previous versions of Apollo had their perception, prediction, routing, and planning modules all heavily reliant on HDMaps, for which development was cumbersome and opaque. For many developers, this posed an insurmountable barrier. Given the inaccessibility of HDMaps, developers could only play demo data bag on Apollo's simulation tools, rather than deploy the Apollo system on vehicles for road testing. This greatly undermined the usage scenarios of Apollo and hampered the development and growth of the Apollo community. Obviously, the Apollo team had been aware of the problem. With months of hard work, they released a new navigation mode in Apollo 2.5 based on relative map. Leveraging navigation mode, developers could easily deploy Apollo for road testing on a real vehicle. +Apollo is well received and highly commended by developers in the field of autonomous driving for its well-designed architecture, full functionality, robust open-source ecosystem, and standardized coding style. However, previous versions of Apollo had their perception, prediction, routing, and planning modules all heavily reliant on HDMaps, for which development was cumbersome and opaque. For many developers, this posed an insurmountable barrier. Given the inaccessibility of HDMaps, developers could only play demo data bag on Apollo's simulation tools, rather than deploy the Apollo system on vehicles for road testing. This greatly undermined the usage scenarios of Apollo and hampered the development and growth of the Apollo community. Obviously, the Apollo team had been aware of this problem. With months of hard work, they released a new navigation mode in Apollo 2.5 based on a relative map. Leveraging navigation mode, developers could easily deploy Apollo for road testing on a real vehicle. -Relative map is the newest feature introduced in Apollo 2.5. From the architectural level, the relative map module is the middle layer linking HDMaps/perception module and planning module. The relative map module generates real-time maps based on the vehicle’s coordinate system (the format is in the same format as HDMaps). The module also outputs reference lines for the planning module. For more information, please refer to the instruction document of the relative map. From the angle of developers, a navigation mode based on relative maps enables developers to implement real-vehicle road tests. As a result, barriers to development have been significantly reduced. +Relative map is the newest feature to be introduced in Apollo 2.5. From the architectural level, the relative map module is the middle layer linking the HDMap to the Perception module and the Planning module as seen in the image below. The relative map module generates real-time maps based on the vehicle’s coordinate system (the format is in the same format as HDMaps). The module also outputs reference lines for the Planning module to use. From the angle of developers, a navigation mode based on relative maps enables developers to implement real-vehicle road tests. As a result, barriers to development have been significantly reduced. + +![Software OverView](https://github.com/ApolloAuto/apollo/blob/master/docs/demo_guide/images/Software_Overview.png) The basic idea behind the navigation mode is: -1.Record the driving path of a manually driven vehicle on a desired path; -2.Use Apollo tools to process the original path and obtain a smoothed path (navigation line). This path is used to 1) replace the global route given by the routing module, 2) serve as the reference line for the planning module, and 3) for generating the relative map. In addition, the path can also be used in combination with the HDMap to replace the lane reference line in the HDMap (by default, the HDMap uses the lane centerline as the reference. However, this method may not suit certain circumstances where using the vehicle's actual navigation line instead could be a more effective solution. This article will not elaborate further on this.) -3.A driver drives the vehicle to the starting point of a desired path, then selects the navigation mode and enables relevant modules in Dreamview. After the above configuration, the vehicle need to be switched to autonomous driving status and run in this status. -4.In the process of autonomous driving, the perception module’s camera will dynamically detect obstacles and road boundaries, while the map module’s relative map sub-module generates a relative map in real time (using a relative coordinate system with the current position of the vehicle as the origin), based on the recorded path (navigation line) and the road boundaries. With the relative map created by the map module and obstacle information created by the perception module, the planning module will dynamically output a local driving path to the control module for execution. -5.At present, the navigation mode only supports single-lane driving. It can perform tasks such as acceleration and deceleration, car following, slowing down and stopping before obstacles, or nudge obstacles within the lane width. Subsequent versions will see further improvements to support multi-lane driving and traffic lights/signs detection. +* Record the driving path of a manually driven vehicle on a desired path +* Use Apollo tools to process the original path and obtain a smoothed out path (navigation line). This path is then used to + * Replace the global route given by the routing module + * Serve as the reference line for the planning modulefor generating the relative map. + * In addition, the path can also be used in combination with the HDMap to replace the lane reference line in the HDMap (by default, the HDMap uses the lane centerline as the reference. However, this method may not suit certain circumstances where using the vehicle's actual navigation line instead could be a more effective solution). +* A driver drives the vehicle to the starting point of a desired path, then selects the navigation mode and enables relevant modules in Dreamview. After the above configuration, the vehicle needs to be switched to autonomous driving status and run in this status. +* While travelling in the autonomous mode, the perception module’s camera will dynamically detect obstacles and road boundaries, while the map module’s relative map sub-module generates a relative map in real time (using a relative coordinate system with the current position of the vehicle as the origin), based on the recorded path (navigation line) and the road boundaries. With the relative map created by the map module and obstacle information created by the perception module, the planning module will dynamically output a local driving path to the control module for execution. +* At present, the navigation mode only supports single-lane driving. It can perform tasks such as acceleration and deceleration, car following, slowing down and stopping before obstacles, or nudge obstacles within the lane width. Subsequent versions will see further improvements to support multi-lane driving and traffic lights/signs detection. -This article fully explains the build of Apollo 2.5, navigation line data collection and production, front end compilation and configuration of Dreamview, and navigation mode usage, etc. Hopefully this will bring convenience to developers when properly using Apollo 2.5. +This article fully explains the build of Apollo 2.5, navigation line data collection and production, front-end compilation and configuration of Dreamview, and navigation mode usage, etc. Hopefully this will bring convenience to developers when properly using Apollo 2.5. -## 1. Building the Apollo 2.5 +## 1. Building the Apollo 2.5 environment First, download the Apollo 2.5 source code from GitHub website. This can be done by either using git command or getting the compressed package directly from the web page. There are two options to build Apollo after downloading the source code to an appropriate directory: 1. in Visual Studio Code (recommended); 2. by using the command line. Of course, the common prerequisite is that Docker has already been successfully installed on your computer. You can use the script file [`install_docker.sh`](https://github.com/ApolloAuto/apollo/blob/master/docker/scripts/install_docker.sh) to install Docker firstly. @@ -51,17 +56,18 @@ The steps are shown in the following figure: ![img](images/navigation_mode/build_with_command.png) -### 1.3 Change the UTM area ID in `localization` module +### 1.3 Change the UTM area ID in `Localization` module The default ID of the localization module in Apollo is the UTM coordinates of the US west coast. If you are in China, this ID must be changed. Outside of Docker, using vi or another text editor, open` [your_apollo_root_dir]/modules/localization/conf/localization.conf`, and change: ``` bash --local_utm_zone_id=10 ``` -To (we are using the UTM area ID of Changsha area, for UTM sub-areas in China, please go to [this page](http://www.360doc.com/content/14/0729/10/3046928_397828751.shtml))： +We are using the UTM area ID of Changsha area, for UTM sub-areas in China, please go to [this page](http://www.360doc.com/content/14/0729/10/3046928_397828751.shtml))： ``` bash --local_utm_zone_id=49 ``` -**Note:** If the coordinates were not changed before recording data, they must not be changed when playing back data during offline testing. Changing the ID after recording will disturb navigation line locating! + +`Note:` If the coordinates were not changed before recording data, they must not be changed when playing back data during offline testing. Changing the ID after recording will disturb navigation line locating! ### 1.4 Configuring your UTM area ID for Dreamview @@ -80,14 +86,16 @@ Open [http://localhost:8888](http://localhost:8888) in a Chrome or Firfox browse ![img](images/navigation_mode/dreamview_interface.png) -2.1 The driver controls the vehicle and parks at the starting location of the road test; -2.2 The operator clicks the `Module Controller` button in the toolbar from the left side of the Dreamview interface. In the `Module Controller` page, select `GPS`, `Localization`, and `Record Bag`. Note: If the recorded data bag will be used in offline test, also select `CAN Bus`. -2.3 The driver starts the engine and drives to the end location as planned; -2.4 The operator unselects the `Record Bag` option in the Dreamview interface, and a directory such as `2018-04-01-09-58-0`0 will be generated in the`/apollo/data/bag` directory (in Docker, an associative directory will be created on the dedicated host` [your your_apollo_root_dir]/data/bag`). The data bag (i.e. `2018-04-01-09-58-00.bag`) will be kept there. Take note of its path and filename as it will be needed next. **Note:** the default recording time in a bag is 1 minute, and the default size of a bag is 2048 MB, which can be edited in `/apollo/scripts/record_bag.sh`. +* The driver controls the vehicle and parks at the starting location of the road test; +* The operator clicks the `Module Controller` button in the toolbar from the left side of the Dreamview interface. In the `Module Controller` page, select `GPS`, `Localization`, and `Record Bag`. Note: If the recorded data bag will be used in offline test, also select `CAN Bus`. +* The driver starts the engine and drives to the end location as planned; +* The operator unselects the `Record Bag` option in the Dreamview interface, and a directory such as `2018-04-01-09-58-0`0 will be generated in the`/apollo/data/bag` directory (in Docker, an associative directory will be created on the dedicated host` [your your_apollo_root_dir]/data/bag`). The data bag (i.e. `2018-04-01-09-58-00.bag`) will be kept there. Take note of its path and filename as it will be needed next. + +`Note:` the default recording time in a bag is 1 minute, and the default size of a bag is 2048 MB, which can be edited in `/apollo/scripts/record_bag.sh`. For convenience, the next steps assume the `2018-04-01-09-58-00.bag` is in the `/apollo/data/bag` directory in this article. ## 3. Generation of navigation lines -Either create a navigation line on an in-car IPC, or other computers. In both situations, we assume we are already in Docker (Step 1.2), have imported the data bag under the `/apollo/data/bag` directory, and the name of the file is `2018-04-01-09-58-00.bag` (which is not the name of the file in your computer, we are using it only as an example). +Either create a navigation line on an in-car IPC, or other computers. In both situations, we assume: we are already in Docker (Step 1.2), we have imported the data bag under the `/apollo/data/bag` directory, and the name of the file is `2018-04-01-09-58-00.bag` (which is not the name of the file in your computer, we are using it only as an example). ### 3.1 Extract raw data from the data bag @@ -101,11 +109,11 @@ To check the data, enter the following command: ``` bash python viewer_raw.py ./path_2018-04-01-09-58-00.bag.txt ``` -And a figure like below will be generated: +And a figure like the image below, will be generated: ![img](images/navigation_mode/view_raw_data.png) -### 3.2 Smooth the raw data +### 3.2 Smoothen the raw data If the test drive was bumpy, the raw path data will not be smooth enough. It must be smoothed in Docker using the following command: ``` bash @@ -122,11 +130,11 @@ The first argument `./path_2018-04-01-09-58-00.bag.txt` is raw data, the second ## 4. Dreamview frontend compilation and configuration -Dreamview frontend uses Baidu Map by default. It can be changed to Google Maps by re-compiling frontend, following these steps (Note: if the map setting does not need to be reset, please ignore this section): +Dreamview frontend uses the Baidu Map by default. It can be changed to Google Maps by re-compiling frontend, as seen in the sub-sections below (Note: if you wish to continue with the default Map application, please ignore the sub-sections below): ### 4.1 Change navigation map settings -Open the file`[your_apollo_root_dir]/modules/dreamview/frontend/src/store/config/ parameters.yml`, change map settings to meet your needs: +Open the file`[your_apollo_root_dir]/modules/dreamview/frontend/src/store/config/ parameters.yml`, change the map settings to meet your needs: ``` bash navigation: @@ -148,15 +156,15 @@ yarn install cd /apollo bash apollo.sh build_fe ``` -You might find errors like this during the process: +You might encounter errors like this one below, during the process: ``` ERROR in ../~/css-loader!../~/sass-loader/lib/loader.js?{"includePaths":["./node_modules"]}!./styles/main.scss* *Module build failed: Error: ENOENT: no such file or directory, scandir '/apollo/modules/dreamview/frontend/node_modules/node-sass/vendor'* ... -(The error continues, but we omit the rest here) +(The error continues, but we have the information we need to debug it) ``` This is because of built-in dependent package inconsistency, which can be resolved by executing the following command in Docker: -(Note: keep your internet connection steady, or you might not be able to download the dependent package again): +(`Note:` keep your internet connection steady, or you might not be able to download the dependent package again): ``` bash cd /apollo/modules/dreamview/frontend/ rm -rf node_modules @@ -165,9 +173,9 @@ cd /apollo bash apollo.sh build_fe ``` -## 5. Usage of navigation mode +## 5. Usage of the navigation mode -### 5.1. Open Dreamview and switch to navigation mode +### 5.1. Open Dreamview and switch to the navigation mode Enter Docker, open Dreamview and execute the following command: ``` bash @@ -184,13 +192,13 @@ For offline mock tests, loop the data bag recorded in Step 2 `/apollo/data/bag/2 # For offline mock tests, loop the data bag recorded in step 2. Please ignore this step for real vehicle commissioning. rosbag play -l /apollo/data/bag/2018-04-01-09-58-00.bag ``` -Open this website[ http://localhost:8888] ( http://localhost:8888) in the browser (do not use proxy), enter Dreamview interface, click on the dropdown box in the upper right, and select `Navigation` mode, as shown in the screenshot: +Open this website[ http://localhost:8888]( http://localhost:8888) in the browser (DO NOT use proxy), enter Dreamview interface, click on the dropdown box in the upper right, and select `Navigation` mode, as shown in the screenshot below: ![img](images/navigation_mode/enable_navigation_mode.png) ### 5.2 Enable relevant modules in the navigation mode -Click on `Module Controller` button in the toolbar on the left side of the Dreamview interface and enter the module controller page. For offline mock tests, select `Relative Map`, `Navi Planning`, and other modules as needed as shown in the screenshot below (the module that shows blank text is the Mobileye module, which will be visible only if the related hardware is installed and configured): +Click on the `Module Controller` button in the toolbar on the left side of the Dreamview interface and enter the module controller page. For offline mock tests, select `Relative Map`, `Navi Planning`, and other modules as needed as shown in the screenshot below (the module that shows blank text is the Mobileye module, which will be visible only if the related hardware is installed and configured): ![img](images/navigation_mode/test_in_navigation_mode.png) @@ -205,23 +213,23 @@ In Docker, execute the following command to send the navigation line data made i cd /apollo/modules/tools/navigator python navigator.py ./path_2018-04-01-09-58-00.bag.txt.smoothed ``` -Next screenshot shows the interface after Dreamview receives navigation line data during offline mock test. You can see the Baidu Map interface in the upper left corner. Our navigation line is shown as red lines in Baidu Map, and white lines in the main interface. +The following screenshot shows the interface after Dreamview receives navigation line data during offline mock testing. You can see the Baidu Map interface in the upper left corner. Our navigation line is shown as red lines in the Baidu Map, and white lines in the main interface. ![img](images/navigation_mode/navigation_mode_with_reference_line_test.png) -Next screenshot shows the interface after Dreamview receives navigation line data during real vehicle commissioning. You can see the Baidu Map interface in the upper left corner. Our navigation line is shown as red lines in Baidu Map, and yellow lines in the main interface. +The next screenshot shows the interface after Dreamview receives navigation line data during real vehicle commissioning. You can see the Baidu Map interface in the upper left corner. Our navigation line is shown as red lines in Baidu Map, and yellow lines in the main interface. ![img](images/navigation_mode/navigation_mode_with_reference_line_car.png) -Some tips: - (1) If the navigation line is not displayed correctly in Dreamview interface, the reasons could be: - i. Navigation line data is not sent correctly - execute the sending command again to solve this problem; - ii. Browser cache is inconsistent, press `Ctrl+R` or `F5` to reload the page or clear the cache; - iii. Dreamview back end service program is not executing correctly - restart the program in Docker, using: -``` bash -# Stop Dreamview and monitoring process -bash scripts/bootstrap.sh stop -# Restart Dreamview and monitoring process -bash scripts/bootstrap.sh -``` -(2) Every time the vehicle returns to the starting point, it is necessary to send the navigation line data again whether it is the offline mock test or the real vehicle commissioning. \ No newline at end of file +A few tips to focus on: +* If the navigation line is not displayed correctly in Dreamview interface, the reasons could be: + * Navigation line data is not sent correctly - execute the sending command again to solve this problem + * If Browser cache is inconsistent, press `Ctrl+R` or `F5` to reload the page or clear the cache + * If the Dreamview back end service program is not executing correctly - restart the program in Docker, using: + ``` bash + # Stop Dreamview and monitoring process + bash scripts/bootstrap.sh stop + # Restart Dreamview and monitoring process + bash scripts/bootstrap.sh + ``` +* Every time the vehicle returns to the starting point, it is necessary to send the navigation line data again, whether it is the offline mock test or the vehicle commissioning. \ No newline at end of file