New draft with parameters. Pending questions.

Docs/adv_opendrive.md

@@ -2,9 +2,9 @@
 
 This feature allows users to ingest any OpenDRIVE file as a CARLA map out-of-the-box. In order to do so, the simulator will automatically generate a road mesh for actors to navigate through.  
 
-*	[__Overview__](#overview)  
+*   [__Overview__](#overview)  
-*	[__Run a standalone map__](#run-a-standalone-map)  
+*   [__Run a standalone map__](#run-a-standalone-map)  
-*	[__Mesh generation__](#mesh-generation)  
+*   [__Mesh generation__](#mesh-generation)  
 
 ---
 ## Overview
@@ -13,15 +13,15 @@ This mode runs a full simulation using only an OpenDRIVE file, without the need
 
 The resulting mesh describes the road definition in a minimalistic manner. All the elements will correspond with the OpenDRIVE file, but besides that, there will be only void. In order to prevent vehicles from falling off the road, two measures have been taken. 
 
-*	Lanes are a bit wider at junctions, where the flow of vehicles is most complex.  
+*   Lanes are a bit wider at junctions, where the flow of vehicles is most complex.  
-*	Visible walls are created at the boundaries of the road, to act as a last safety measure. 
+*   Visible walls are created at the boundaries of the road, to act as a last safety measure. 
 
 Traffic lights, stops and yields will be generated on the fly, as happens when using any map. Pedestrians will navigate over the sidewalks and crosswalks that appear in the map. All of these elements, and every detail on the road, are based on the OpenDRIVE file. As the standalone mode uses the `.xodr` directly, any issues in it will propagate to the simulation. This could be an issue especially at junctions, where many lanes are mixed.
 
-*	OpenDRIVE maps created with RoadRunner present some issues related to tilted junction ??
+*   OpenDRIVE maps created with RoadRunner present some issues related to tilted junction ??
-*	Lateral slope for roads is not supported yet ??
+*   Lateral slope for roads is not supported yet ??
-*	The sidewalks height is currently hardcoded. This ensures collisions with them are detected even if the map definition does not include this field ??
+*   The sidewalks height is currently hardcoded. This ensures collisions with them are detected even if the map definition does not include this field ??
-*	What .xml ??
+*   What .xml ??
 
 !!! Important
     It is especially important to double check the OpenDRIVE file. Any issues in it will propagate when running the simulation.
@@ -31,12 +31,26 @@ Traffic lights, stops and yields will be generated on the fly, as happens when u
 ---
 ## Run a standalone map
 
-In order to test this feature, the `config.py` script in `PythonAPI/util/` has a new argument, `-x` or `--xodr-path`. This argument contains a string with the path to the `.xodr` file. The script calls a client method, [`client.generate_opendrive_world()`](python_api.md#carla.Client.generate_opendrive_world). This will block the simulation, as [`load_world()`](python_api.md#carla.World.load_world) would do, until the new map is active.
+In order to open an OpenDRIVE file, the Python API includes now the method [`client.generate_opendrive_world()`](python_api.md#carla.Client.generate_opendrive_world). This will block the simulation until the new one is ready. The method needs for two parameters.  
 
+*   __`opendrive`__ is the content of the OpenDRIVE file parsed as a string.  
+*   __`parameters`__ is a [carla.OpendriveGenerationParameters](python_api.md#carla.OpendriveGenerationParameters) containing settings for the generation of the mesh. 
+	*   `vertex_distance` is the distance between the vertices of the mesh. --> The bigger the more inaccuracies?? The smallest, the more detailed but heavier ??
+	*   `max_road_length` 
+	*   `wall_height` states the height of the additional walls created on the boundaries of the road. These prevent vehicles from falling to the void.  
+	*   `additional_width` is an small width increment applied to the junction lanes. This is a safety measure to prevent vehicles from falling.  
+	*   `smooth_junctions` if __True__, the mesh at junctions will be smoothed, to prevent some inaccuracies that may occur when various lanes meet.  --> And why can I choose to disable them?? 
+	*   `enable_mesh_visibility` if __True__, the mesh will be rendered. --> If False? Vehicles rendered, no rendering mode or what?  
+
+
+In order to easily test this feature, the `config.py` script in `PythonAPI/util/` has a new argument, `-x` or `--xodr-path`. This argument contains a string with the path to the `.xodr` file. If the mesh is generated with this script, the parameters used will always be the default ones. 
 ```sh
 python3 config.py -x path/to/some/file.xodr
 ```
 
+!!! Important
+    __[carla.OpendriveGenerationParameters](python_api.md#carla.OpendriveGenerationParameters)__ uses __content of the OpenDRIVE file parsed as string__. On the contrary, __`config.py`__ script needs __the path to the `.xodr` file__.
+
 ---
 ## Mesh generation
 

Docs/adv_sumo.md

@@ -2,11 +2,11 @@
 
 CARLA has developed a co-simulation feature with SUMO. This allows to distribute the tasks at will, and exploit the capabilities of each simulation in favour of the user.  
 
-*	[__Requisites__](#requisites)  
+*   [__Requisites__](#requisites)  
-	*	[Prepare a SUMO environment](#prepare-a-sumo-environment)
+	*   [Prepare a SUMO environment](#prepare-a-sumo-environment)
-*	[__Run the co-simulation__](#run-the-co-simulation)  
+*   [__Run the co-simulation__](#run-the-co-simulation)  
-	*	[Spawn vehicles](#spawn-vehicles)
+	*   [Spawn vehicles](#spawn-vehicles)
-*	[__Spawn NPCs with SUMO__](#spawn-npcs-with-sumo)  
+*   [__Spawn NPCs with SUMO__](#spawn-npcs-with-sumo)  
 
 ---
 ## Requisites
@@ -35,12 +35,12 @@ Everything related with this feature can be found in `Co-Simulation/Sumo`. Sever
 
 Use one of this examples, or any other SUMO file, to start the co-simulation. There are some optional arguments that can be set.  
 
-*	__`--tls-manager <string>`__ chooses which simulator will change the state of the traffic lights. The other will update them accordingly.  
+*   __`--tls-manager <string>`__ chooses which simulator will change the state of the traffic lights. The other will update them accordingly.  
-	*	`carla` to put CARLA in charge of the traffic lights.  
+	*   `carla` to put CARLA in charge of the traffic lights.  
-	*	`sumo` to put SUMO in charge of the traffic lights. 
+	*   `sumo` to put SUMO in charge of the traffic lights. 
-	*	`none` to disable the synchronization of traffic lights. Vehicles do not take them into consideration --> None of them, or only one? 
+	*   `none` to disable the synchronization of traffic lights. Vehicles do not take them into consideration --> None of them, or only one? 
 
-*	__`--sumo-gui`__ will create a window to visualize the SUMO simulation. By default SUMO runs off-screen. 
+*   __`--sumo-gui`__ will create a window to visualize the SUMO simulation. By default SUMO runs off-screen. 
 
 ```sh
 python run_synchronization.py examples/TestTLS.sumocfg --tls-manager carla --sumo-gui

Docs/python_api.md

@@ -328,11 +328,11 @@ Executes a list of commands on a single simulation step, blocks until the comman
         - `commands` (_list_) – A list of commands to execute in batch. The commands available are listed right above, in the function **<font color="#7fb800">apply_batch()</font>**.  
         - `due_tick_cue` (_bool_) – A boolean parameter to specify whether or not to perform a [carla.World.tick](#carla.World.tick) after applying the batch in _synchronous mode_. It is __False__ by default.  
     - **Return:** _list(command.Response)_  
-- <a name="carla.Client.generate_opendrive_world"></a>**<font color="#7fb800">generate_opendrive_world</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**opendrive**</font>, <font color="#00a6ed">**parameters**</font>)  
+- <a name="carla.Client.generate_opendrive_world"></a>**<font color="#7fb800">generate_opendrive_world</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**opendrive**</font>, <font color="#00a6ed">**parameters**=(2.0, 50.0, 1.0, 0.6, true, true)</font>)  
 Loads a new world with a basic 3D topology generated from the content of an OpenDRIVE file. This content is passed as a `string` parameter. It is similar to `client.load_world(map_name)` but allows for custom OpenDRIVE maps in server side. Cars can drive around the map, but there are no graphics besides the road and sidewalks.  
     - **Parameters:**
-        - `opendrive` (_str_) – Content of an OpenDRIVE file as `string` (**NOT** the path of the `.xodr` file!).  
+        - `opendrive` (_str_) – Content of an OpenDRIVE file as `string`, __not the path to the `.xodr`__.  
-        - `parameters` (_[carla.OpendriveGenerationParameters](#carla.OpendriveGenerationParameters)_) – Parameters used when generating a world using an OpenDRIVE file.  
+        - `parameters` (_[carla.OpendriveGenerationParameters](#carla.OpendriveGenerationParameters)_) – Additional settings for the mesh generation. If none are provided, default values will be used.  
 - <a name="carla.Client.load_world"></a>**<font color="#7fb800">load_world</font>**(<font color="#00a6ed">**self**</font>, <font color="#00a6ed">**map_name**</font>)  
 Creates a new world with default settings using `map_name` map. All actors in the current world will be destroyed.  
     - **Parameters:**
@@ -1078,17 +1078,17 @@ This class defines the parameters used when generating a world using an OpenDRIV
 
 <h3>Instance Variables</h3>
 - <a name="carla.OpendriveGenerationParameters.vertex_distance"></a>**<font color="#f8805a">vertex_distance</font>** (_float_)  
-The distance between vertices when generating the world mesh from OpenDRIVE.  
+Distance between vertices of the mesh generated. __Default is `2.0`__.  
 - <a name="carla.OpendriveGenerationParameters.max_road_length"></a>**<font color="#f8805a">max_road_length</font>** (_float_)  
-Max road length for a single mesh portion.  
+Max road length for a single mesh portion. The mesh of the map is divided into portions, in order to avoid propagating issues. __Default is `50.0`__.  
 - <a name="carla.OpendriveGenerationParameters.wall_height"></a>**<font color="#f8805a">wall_height</font>** (_float_)  
-Defines the height of walls added to roads to prevent vehicles from falling.  
+Height of walls created on the boundaries of the road. These prevent vehicles from falling off the road. __Default is `1.0`__.  
 - <a name="carla.OpendriveGenerationParameters.additional_width"></a>**<font color="#f8805a">additional_width</font>** (_float_)  
-Additional with to junction lanes to prevent vehicles from falling.  
+Additional with applied junction lanes. Complex situations tend to occur at junctions, and a little increase can prevent vehicles from falling off the road.  __Default is `0.6`__.  
 - <a name="carla.OpendriveGenerationParameters.smooth_junctions"></a>**<font color="#f8805a">smooth_junctions</font>** (_bool_)  
-When this variable is `True` the generated junctions will be smoothed to prevent roads from blocking other roads.  
+If __True__, the mesh at junctions will be smoothed to prevent issues where roads blocked other roads. __Default is `True`__.  
 - <a name="carla.OpendriveGenerationParameters.enable_mesh_visibility"></a>**<font color="#f8805a">enable_mesh_visibility</font>** (_bool_)  
-This variable indicates whether the mesh should be rendered to reduce the rendering overhead.  
+If __True__, the road mesh will be rendered. Setting this to __False__ should reduce the rendering overhead.  __Default is `True`__.  
 
 ---
 

PythonAPI/docs/client.yml

@@ -65,11 +65,12 @@
       - param_name: opendrive
         type: str
         doc: >
-          Content of an OpenDRIVE file as `string` (**NOT** the path of the `.xodr` file!).
+          Content of an OpenDRIVE file as `string`, __not the path to the `.xodr`__.
       - param_name: parameters
         type: carla.OpendriveGenerationParameters
+        default: (2.0, 50.0, 1.0, 0.6, true, true)
         doc: >
-           Parameters used when generating a world using an OpenDRIVE file.
+           Additional settings for the mesh generation. If none are provided, default values will be used. 
       doc: >
         Loads a new world with a basic 3D topology generated from the content of an OpenDRIVE file. This content is passed as a `string` parameter.
         It is similar to `client.load_world(map_name)` but allows for custom OpenDRIVE maps in server side.
@@ -425,24 +426,24 @@
     - var_name: vertex_distance
       type: float
       doc: >
-        The distance between vertices when generating the world mesh from OpenDRIVE.
+        Distance between vertices of the mesh generated. __Default is `2.0`__.
     - var_name: max_road_length
       type: float
       doc: >
-        Max road length for a single mesh portion.
+        Max road length for a single mesh portion. The mesh of the map is divided into portions, in order to avoid propagating issues. __Default is `50.0`__.
     - var_name: wall_height
       type: float
       doc: >
-        Defines the height of walls added to roads to prevent vehicles from falling.
+        Height of walls created on the boundaries of the road. These prevent vehicles from falling off the road. __Default is `1.0`__.
     - var_name: additional_width
       type: float
       doc: >
-        Additional with to junction lanes to prevent vehicles from falling.
+        Additional with applied junction lanes. Complex situations tend to occur at junctions, and a little increase can prevent vehicles from falling off the road.  __Default is `0.6`__.
     - var_name: smooth_junctions
       type: bool
       doc: >
-        When this variable is `True` the generated junctions will be smoothed to prevent roads from blocking other roads.
+        If __True__, the mesh at junctions will be smoothed to prevent issues where roads blocked other roads. __Default is `True`__.
     - var_name: enable_mesh_visibility
       type: bool
       doc: >
-        This variable indicates whether the mesh should be rendered to reduce the rendering overhead.
+        If __True__, the road mesh will be rendered. Setting this to __False__ should reduce the rendering overhead.  __Default is `True`__.