Rewrite getting started documentation

Docs/getting_started.md

@@ -10,59 +10,84 @@
 Welcome to CARLA! This tutorial provides the basic steps for getting started
 using CARLA.
 
+CARLA consists mainly of two modules, the **CARLA Simulator** and the **CARLA
+Python API** module. The simulator does most of the heavy work, controls the
+logic, physics, and rendering of all the actors and sensors in the scene; it
+requires a machine with a dedicated GPU to run. The CARLA Python API is a module
+that you can import into your Python scripts and provides and interface for
+controlling the simulator and retrieving data. Through this Python API you can
+for instance control any vehicle in the simulation, attach sensors to it, and
+read back the data these sensors generate. Most of the aspects of the simulation
+are accessible from our Python API, and more will be in future releases.
+
+<h2>How to run CARLA</h2>
+
+First of all, download the latest release from our GitHub page and extract all
+the contents of the package in a folder of your choice.
+
 <!-- Latest release button -->
 <p align="middle"><a href="https://github.com/carla-simulator/carla/blob/master/Docs/download.md" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release"><span class="icon icon-github"></span> Get the latest release</a></p>
 
-Download the latest release from our GitHub page and extract all the contents of
-the package in a folder of your choice.
-
-The release package contains the following
-
-  * The CARLA simulator.
-  * The "carla" Python API module.
-  * A few Python scripts with usage examples.
-
-The simulator can be started by running `CarlaUE4.sh` on Linux, or
-`CarlaUE4.exe` on Windows. Unlike previous versions, now the simulator
-automatically starts in "server mode". That is, you can already start connecting
-your Python scripts to control the actors in the simulation.
-
-CARLA requires two available TCP ports on your computer, by default 2000 and
-2001. Make sure you don't have a firewall or another application blocking those
-ports. Alternatively, you can manually change the port CARLA uses by launching
-the simulator with the command-line argument `-carla-port=N`, the second port
-will be automatically set to `N+1`.
-
-!!! tip
-    You can launch the simulator in windowed mode by using the argument
-    `-windowed`, and control the window size with `-ResX=N` and `-ResY=N`.
-
-#### Running the example script
-
-Run the example script with
+The release package contains a precompiled version of the simulator, the Python
+API module, and some Python scripts with usage examples. In order to run our
+usage examples, you may need to install the following Python modules
 
 ```sh
-python example.py
+pip install --user pygame numpy
 ```
 
-If everything went well you should start seeing cars appearing in the scene.
-
-_We strongly recommend taking a look at the example code to understand how it
-works, and modify it at will. We'll have soon tutorials for writing your own
-scripts, but for now the examples is all we have._
-
-#### Changing the map
-
-By default, the simulator starts up in our _"Town01"_ map. The second map can be
-started by passing the path to the map as first argument when launching the
-simulator
+Let's start by running the simulator. Launch a terminal window and go to the
+folder you extracted CARLA to. Start the simulator with the following command
 
 ```sh
-# On Linux
-$ ./CarlaUE4.sh /Game/Carla/Maps/Town02
+# Linux
+./CarlaUE4.sh
 ```
 
 ```cmd
-rem On Windows
-> CarlaUE4.exe /Game/Carla/Maps/Town02
+rem Windows
+CarlaUE4.exe
 ```
+
+this launches a window with a view over the city. This is the "spectator"
+view, you can fly around the city using the mouse and WASD keys, but you cannot
+interact with the world in this view. The simulator is now running as a server,
+waiting for a client app to connect and interact with the world.
+
+!!! note
+    CARLA requires two available TCP ports on your computer, by default 2000 and
+    2001. Make sure you don't have a firewall or another application blocking
+    those ports. Alternatively, you can manually change the port by launching
+    the simulator with the command-line argument `-carla-port=N`, the second
+    port will be automatically set to `N+1`.
+
+Let's add now some live to the city, open a new terminal window and execute
+
+```sh
+python spawn_npc.py -n 80
+```
+
+This adds 80 vehicles to the world driving in "autopilot" mode. Back to the
+simulator window we should see these vehicles driving around the city. They will
+keep driving randomly until we stop the script. Let's leave them there for now.
+
+Now, it's nice and sunny in CARLA, but that's not a very interesting driving
+condition. One of the cool features of CARLA is that you can control the weather
+and lighting conditions of the world. We'll launch now a script that dynamically
+controls the weather and time of the day, open yet another terminal window and
+execute
+
+```sh
+python dynamic_weather.py
+```
+
+The city is now ready for us to drive, we can finally run
+
+```sh
+python manual_control.py
+```
+
+This should open a new window with a 3rd person view of a car, you can drive
+this car with the WASD/arrow keys. Press 'h' to see all the options available.
+
+![manual_control.py](img/manual_control.png)