Minimal documentation of the new API

Docs/CONTRIBUTING.md

@@ -76,11 +76,11 @@ usually offers that make it very affordable.
 
 #### What should I know before I get started?
 
-Check out the ["CARLA Design"](carla_design.md) document to get an idea on the
+Check out the ["CARLA Design"](index.md)<!-- @todo --> document to get an idea
-different modules that compose CARLA, and chose the most appropriate one to hold
+on the different modules that compose CARLA, and chose the most appropriate one
-the new feature. We are aware the developers documentation is still scarce,
+to hold the new feature. We are aware the developers documentation is still
-please ask us in case of doubt, and of course don't hesitate to improve the
+scarce, please ask us in case of doubt, and of course don't hesitate to improve
-current documentation if you feel confident enough.
+the current documentation if you feel confident enough.
 
 #### Are there any examples in CARLA to see how Unreal programming works?
 

Docs/benchmark_creating.md

@@ -13,7 +13,7 @@ In this tutorial we show:
 ![Benchmark_structure](img/benchmark_diagram_small.png)
 
 The driving benchmark is associated with other two modules.
-The *agent* module, that is a controller which performs in 
+The *agent* module, that is a controller which performs in
 another module: the *experiment suite*.
 Both modules are abstract classes that must be redefined by
 the user.
@@ -54,11 +54,11 @@ Let's start by deriving a simple forward agent:
 
     from carla.agent.agent import Agent
     from carla.client import VehicleControl
-    
+
     class ForwardAgent(Agent):
 
 
-To have its performance evaluated, the ForwardAgent derived class _must_ 
+To have its performance evaluated, the ForwardAgent derived class _must_
 redefine the *run_step* function as it is done in the following excerpt:
 
     def run_step(self, measurements, sensor_data, directions, target):
@@ -71,18 +71,18 @@ redefine the *run_step* function as it is done in the following excerpt:
 
 
 This function receives the following parameters:
- 
+
- * [Measurements](measurements.md): the entire state of the world received
+ * [Measurements](index.md)<!-- @todo -->: the entire state of the world received
  by the client from the CARLA Simulator. These measurements contains agent position, orientation,
  dynamic objects information, etc.
- * [Sensor Data](cameras_and_sensors.md): The measured data from defined sensors, 
+ * [Sensor Data](cameras_and_sensors.md): The measured data from defined sensors,
  such as Lidars or RGB cameras.
  * Directions: Information from the high level planner. Currently the planner sends
  a high level command from the follwoing set: STRAIGHT, RIGHT, LEFT, NOTHING.
  * Target Position: The position and orientation of the target.
- 
+
- With all this information, the *run_step* function is expected 
+ With all this information, the *run_step* function is expected
- to return a [vehicle control message](measurements.md), containing:
+ to return a [vehicle control message](index.md)<!-- @todo -->, containing:
  steering value, throttle value, brake value, etc.
 
 
@@ -108,12 +108,12 @@ as in the following code excerpt:
     from carla.agent_benchmark.experiment import Experiment
     from carla.sensor import Camera
     from carla.settings import CarlaSettings
-    
+
     from .experiment_suite import ExperimentSuite
-    
+
-    
+
     class BasicExperimentSuite(ExperimentSuite):
-    
+
 ##### Define test and train weather conditions
 
 The user must select the weathers to be used. One should select the set
@@ -126,7 +126,7 @@ class property as in the following example:
     @property
     def test_weathers(self):
         return [1]
-        
+
 
 ##### Building Experiments
 
@@ -134,15 +134,15 @@ The [experiments are composed by a *task* that is defined by a set of *poses*](b
 Let's start by selecting poses for one of the cities, let's take Town01, for instance.
 First of all, we need to see all the possible positions, for that, with
 a CARLA simulator running in a terminal, run:
-    
+
     python view_start_positions.py
- 
+
  ![town01_positions](img/town01_positions.png)
-  
+
-  
+
 Now let's choose, for instance, 140 as start position and 134
 as the end position. This two positions can be visualized by running:
-    
+
     python view_start_positions.py --pos 140,134 --no-labels
 
  ![town01_positions](img/town01_140_134.png)
@@ -165,7 +165,7 @@ the number of dynamic objects for each of these tasks and repeat
 the arbitrary position task to have it also defined with dynamic
 objects. In the following code excerpt we show the final
 defined positions and the number of dynamic objects for each task:
-    
+
     # Define the start/end position below as tasks
     poses_task0 = [[7, 3]]
     poses_task1 = [[138, 17]]
@@ -212,7 +212,7 @@ vector as we show in the following code excerpt:
 
 
 
-            
+
 The full code could be found at [basic_experiment_suite.py](https://github.com/carla-simulator/carla/blob/master/PythonClient/carla/driving_benchmark/experiment_suites/basic_experiment_suite.py)
 
 
@@ -228,7 +228,7 @@ For that you should run the CARLA simulator as:
 The example presented in this tutorial can be executed  for Town01 as:
 
     ./driving_benchmark_example.py -c Town01
- 
+
 You should expect these results: [town01_basic_forward_results](benchmark_basic_results_town01)
 
 For Town02:

Docs/cameras_and_sensors.md

@@ -1,5 +1,11 @@
 <h1>Cameras and sensors</h1>
 
+!!! important
+    This document still refers to the 0.8.X API (stable version). The
+    proceedings stated here may not apply to latest versions, 0.9.0 or later.
+    Latest versions introduced significant changes in the API, we are still
+    working on documenting everything, sorry for the inconvenience.
+
 !!! important
     Since version 0.8.0 the positions of the sensors are specified in meters
     instead of centimeters. Always relative to the vehicle.

Docs/carla_settings.md

@@ -2,6 +2,12 @@
 
 > _This document is a work in progress and might be incomplete._
 
+!!! important
+    This document still refers to the 0.8.X API (stable version). The
+    proceedings stated here may not apply to latest versions, 0.9.0 or later.
+    Latest versions introduced significant changes in the API, we are still
+    working on documenting everything, sorry for the inconvenience.
+
 CarlaSettings.ini
 -----------------
 
@@ -14,7 +20,7 @@ hierarchy overriding earlier values.
 
   1. `{CarlaFolder}/Unreal/CarlaUE4/Config/CarlaSettings.ini`.
   2. File provided by command-line argument `-carla-settings="Path/To/CarlaSettings.ini"`.
-  3. Other command-line arguments as `-carla-server` or `-world-port`.
+  3. Other command-line arguments like `-carla-port`.
   4. Settings file sent by the client on every new episode.
 
 Take a look at the [CARLA Settings example][settingslink].
@@ -54,8 +60,6 @@ WeatherId=6
 Simulator command-line options
 ------------------------------
 
-  * `-carla-server` Launches CARLA as server, the execution hangs until a client connects.
   * `-carla-settings="Path/To/CarlaSettings.ini"` Load settings from the given INI file. See Example.CarlaSettings.ini.
-  * `-carla-world-port=N` Listen for client connections at port N, agent ports are set to N+1 and N+2 respectively. Activates server.
+  * `-carla-port=N` Listen for client connections at port N, streaming port is set to N+1.
   * `-carla-no-hud` Do not display the HUD by default.
-  * `-carla-no-networking` Disable networking. Overrides `-carla-server` if present.

Docs/coding_standard.md

@@ -26,11 +26,11 @@ C++
 ---
 
   * Compilation should not give any error or warning
-    (`clang++ -Wall -Wextra -std=C++14`).
+    (`clang++ -Wall -Wextra -std=C++14 -Wno-missing-braces`).
   * Unreal C++ code (CarlaUE4 and Carla plugin) follow the
     [Unreal Engine's Coding Standard][ue4link] with the exception of using
     spaces instead of tabs.
-  * CarlaServer uses [Google's style guide][googlelink].
+  * LibCarla uses a variation of [Google's style guide][googlelink].
 
 [ue4link]: https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/
 [googlelink]: https://google.github.io/styleguide/cppguide.html

Docs/configuring_the_simulation.md

@@ -40,6 +40,8 @@ run the simulation at a fixed time-step of 0.2 seconds we execute
 It is important to note that this mode can only be enabled when launching the
 simulator since this is actually a feature of Unreal Engine.
 
+<!-- Disabled for now...
+
 Synchronous vs Asynchronous mode
 --------------------------------
 
@@ -83,3 +85,4 @@ settings.set(SynchronousMode=True)
 [CARLA/Server]
 SynchronousMode=true
 ```
+ -->

Docs/getting_started.md

@@ -2,6 +2,11 @@
 
 ![Welcome to CARLA](img/welcome.png)
 
+!!! important
+    This tutorial refers to the latest development versions of CARLA, 0.9.0 or
+    later. For the documentation of the stable version please switch to the
+    [stable branch](https://carla.readthedocs.io/en/stable/getting_started/).
+
 Welcome to CARLA! This tutorial provides the basic steps for getting started
 using CARLA.
 
@@ -14,17 +19,50 @@ the package in a folder of your choice.
 The release package contains the following
 
   * The CARLA simulator.
-  * The "carla" Python module.
+  * The "carla" Python API module.
-  * Some Python client examples.
+  * An "example.py" script.
 
-For now we will focus on the simulator only. The simulator can be run in two
+The simulator can be started by running `CarlaUE4.sh` on Linux, or
-different modes
+`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.
 
-  * **Server mode:** The simulator is controlled by a client application that
+CARLA requires two available TCP ports on your computer, by default 2000 and
-    collects data and sends driving instructions. In this mode the simulator
+2001. Make sure you don't have a firewall or another application blocking those
-    hangs until a client starts a connection.
+ports. Alternatively, you can manually change the port CARLA uses by launching
-  * **Standalone mode:** The simulator starts in sort of _video-game mode_ in
+the simulator with the command-line argument `-carla-port=N`, the second port
-    which you can control the vehicle with the keyboard.
+will be automatically set to `N+1`.
 
-In the next item in this tutorial we will run the **standalone mode** to take a
+!!! tip
-first look into CARLA.
+    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
+
+```sh
+python example.py
+```
+
+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
+
+```sh
+# On Linux
+$ ./CarlaUE4.sh /Game/Carla/Maps/Town02
+```
+
+```cmd
+rem On Windows
+> CarlaUE4.exe /Game/Carla/Maps/Town02
+```

Docs/index.md

@@ -1,12 +1,17 @@
 <h1>CARLA Documentation</h1>
 
+!!! important
+    This documentation refers to the latest development versions of CARLA, 0.9.0
+    or later. For the documentation of the stable version please switch to the
+    [stable branch](https://carla.readthedocs.io/en/stable/).
+
 <h3>Quick start</h3>
 
   * [Getting started](getting_started.md)
-  * [Running the simulator](running_simulator_standalone.md)
+  <!-- * [Running the simulator](running_simulator_standalone.md) -->
-  * [Connecting a Python client](connecting_the_client.md)
+  <!-- * [Connecting a Python client](connecting_the_client.md) -->
   * [Configuring the simulation](configuring_the_simulation.md)
-  * [Measurements](measurements.md)
+  <!-- * [Measurements](measurements.md) -->
   * [Cameras and sensors](cameras_and_sensors.md)
   * [F.A.Q.](faq.md)
 
@@ -25,7 +30,8 @@
 <h3>Advanced topics</h3>
 
   * [CARLA settings](carla_settings.md)
-  * [Simulator keyboard input](simulator_keyboard_input.md)
+  * [Python API](python_api.md)
+  <!-- * [Simulator keyboard input](simulator_keyboard_input.md) -->
   * [Running without display and selecting GPUs](carla_headless.md)
   * [How to link Epic's Automotive Materials](epic_automotive_materials.md)
 
@@ -39,6 +45,6 @@
 
   * [Map customization](map_customization.md)
   * [How to add assets](how_to_add_assets.md)
-  * [CARLA design](carla_design.md)
+  <!-- * [CARLA design](carla_design.md) -->
-  * [CarlaServer documentation](carla_server.md)
+  <!-- * [CarlaServer documentation](carla_server.md) -->
   * [Build system](build_system.md)

Docs/python_api.md

@@ -0,0 +1,117 @@
+<h1>Python API</h1>
+
+!!! important
+    Versions prior to 0.9.0 have a very different API. For the documentation of
+    the stable version please switch to the
+    [stable branch](https://carla.readthedocs.io/en/stable/).
+
+## `carla.Client`
+
+- `Client(host, port, worker_threads=0)`
+- `set_timeout(milliseconds)`
+- `get_client_version()`
+- `get_server_version()`
+- `ping()`
+- `get_world()`
+
+## `carla.World`
+
+- `get_blueprint_library()`
+- `spawn_actor(blueprint, transform, attach_to=None)`
+- `try_spawn_actor(blueprint, transform, attach_to=None)`
+
+## `carla.BlueprintLibrary`
+
+- `find(id)`
+- `filter(wildcard_pattern)`
+- `__getitem__(pos)`
+- `__len__()`
+- `__iter__()`
+
+## `carla.ActorBlueprint`
+
+- `id`
+- `tags`
+- `contains_tag(tag)`
+- `match_tags(wildcard_pattern)`
+- `contains_attribute(key)`
+- `get_attribute(key)`
+- `set_attribute(key, value)`
+
+## `carla.ActorAttribute`
+
+- `is_modifiable`
+- `type`
+- `recommended_values`
+- `as_bool()`
+- `as_int()`
+- `as_float()`
+- `as_str()`
+- `as_color()`
+- `__eq__()`
+- `__ne__()`
+- `__nonzero__()`
+- `__bool__()`
+- `__int__()`
+- `__float__()`
+- `__str__()`
+
+## `carla.Actor`
+
+- `id`
+- `type_id`
+- `get_world()`
+- `get_location()`
+- `get_transform()`
+- `set_location(location)`
+- `set_transform(transform)`
+- `destroy()`
+
+## `carla.Vehicle(carla.Actor)`
+
+- `apply_control(vehicle_control)`
+- `set_autopilot(enabled=True)`
+
+## `carla.Sensor(carla.Actor)`
+
+- `listen(callback_function)`
+
+## `carla.Image`
+
+- `frame_number`
+- `width`
+- `height`
+- `type`
+- `fov`
+- `raw_data`
+
+## `carla.VehicleControl`
+
+- `throttle`
+- `steer`
+- `brake`
+- `hand_brake`
+- `reverse`
+
+## `carla.Location`
+
+- `x`
+- `y`
+- `z`
+
+## `carla.Rotation`
+
+- `pitch`
+- `yaw`
+- `roll`
+
+## `carla.Transform`
+
+- `location`
+- `rotation`
+
+## `carla.Color`
+
+- `r`
+- `g`
+- `b`

PythonAPI/source/libcarla/Blueprint.cpp

@@ -113,23 +113,22 @@ void export_blueprint() {
     .add_property("id", +[](const cc::ActorBlueprint &self) -> std::string {
       return self.GetId();
     })
+    .add_property("tags", &cc::ActorBlueprint::GetTags)
     .def("contains_tag", &cc::ActorBlueprint::ContainsTag)
     .def("match_tags", &cc::ActorBlueprint::MatchTags)
-    .def("get_tags", &cc::ActorBlueprint::GetTags)
     .def("contains_attribute", &cc::ActorBlueprint::ContainsAttribute)
     .def("get_attribute", +[](const cc::ActorBlueprint &self, const std::string &id) -> cc::ActorAttribute {
       return self.GetAttribute(id);
     })
     .def("set_attribute", &cc::ActorBlueprint::SetAttribute)
-    .def("match_tags", &cc::ActorBlueprint::MatchTags)
     .def(self_ns::str(self_ns::self))
   ;
 
   class_<cc::BlueprintLibrary, boost::noncopyable, boost::shared_ptr<cc::BlueprintLibrary>>("BlueprintLibrary", no_init)
-    .def("filter", &cc::BlueprintLibrary::Filter)
     .def("find", +[](const cc::BlueprintLibrary &self, const std::string &key) -> cc::ActorBlueprint {
       return self.at(key);
     })
+    .def("filter", &cc::BlueprintLibrary::Filter)
     .def("__getitem__", +[](const cc::BlueprintLibrary &self, size_t pos) -> cc::ActorBlueprint {
       return self.at(pos);
     })

Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Settings/CarlaSettings.cpp

@@ -198,6 +198,7 @@ void UCarlaSettings::LoadSettings()
     }
     uint32 Value;
     if (FParse::Value(FCommandLine::Get(), TEXT("-world-port="), Value) ||
+        FParse::Value(FCommandLine::Get(), TEXT("-carla-port="), Value) ||
         FParse::Value(FCommandLine::Get(), TEXT("-carla-world-port="), Value)) {
       WorldPort = Value;
       bUseNetworking = true;

mkdocs.yml

@@ -7,10 +7,10 @@ pages:
 - Home: 'index.md'
 - Quick start:
   - 'Getting started': 'getting_started.md'
-  - 'Running the simulator': 'running_simulator_standalone.md'
+  # - 'Running the simulator': 'running_simulator_standalone.md'
-  - 'Connecting a Python client': 'connecting_the_client.md'
+  # - 'Connecting a Python client': 'connecting_the_client.md'
   - 'Configuring the simulation': 'configuring_the_simulation.md'
-  - 'Measurements': 'measurements.md'
+  # - 'Measurements': 'measurements.md'
   - 'Cameras and sensors': 'cameras_and_sensors.md'
   - 'F.A.Q.': 'faq.md'
 - Driving Benchmark:
@@ -23,7 +23,8 @@ pages:
   - 'How to build on Windows': 'how_to_build_on_windows.md'
 - Advanced topics:
   - 'CARLA Settings': 'carla_settings.md'
-  - 'Simulator keyboard input': 'simulator_keyboard_input.md'
+  - 'Python API': 'python_api.md'
+  # - 'Simulator keyboard input': 'simulator_keyboard_input.md'
   - 'Running without display and selecting GPUs': 'carla_headless.md'
   - "How to link Epic's Automotive Materials": 'epic_automotive_materials.md'
 - Contributing:
@@ -33,8 +34,8 @@ pages:
 - Development:
   - 'Map customization': 'map_customization.md'
   - 'How to add assets': 'how_to_add_assets.md'
-  - 'CARLA design': 'carla_design.md'
+  # - 'CARLA design': 'carla_design.md'
-  - 'CarlaServer documentation': 'carla_server.md'
+  # - 'CarlaServer documentation': 'carla_server.md'
   - 'Build system': 'build_system.md'
 - Appendix:
   - 'Driving Benchmark Sample Results Town01': 'benchmark_basic_results_town01.md'