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

@@ -72,7 +72,7 @@ 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,
@@ -82,7 +82,7 @@ This function receives the following parameters:
  * Target Position: The position and orientation of the target.
 
  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.
 
 

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'