new iteration. Missing default values, API docs, and wall height note.

Docs/tuto_G_openstreetmap.md

@@ -1,4 +1,4 @@
-# Generate reality-based maps with OpenStreetMap
+# Generate maps with OpenStreetMap
 
 OpenStreetMap is an open license map of the world developed by contributors. Sections of these map can be exported to an XML file. CARLA can convert this file to OpenDRIVE format and ingest it as any other OpenDRIVE map using the [OpenDRIVE Standalone Mode](#adv_opendrive.md). The process is quite straightforward.
 
@@ -9,14 +9,14 @@ OpenStreetMap is an open license map of the world developed by contributors. Sec
 ---
 ## 1- Obtain a map with OpenStreetMap
 
-The first thing to do is using [OpenStreetMap](#openstreetmap.org) to generate an XML file containing the map information.
+The first thing to do is using [OpenStreetMap](https://www.openstreetmap.org) to generate an XML file containing the map information.
 
-__1.1. Go to [openstreetmap.org](openstreetmap.org)__.
+__1.1. Go to [openstreetmap.org](https://www.openstreetmap.org)__. If the map is not properly visualized, try changing the layer in the righ pannel.  
 
 __1.2 Search for a desired location__ and zoom in to a specific area.
 ![openstreetmap_view](img/tuto_g_osm_web.jpg)
 
-!!! Important
+!!! Warning
     Due to the Unreal Engine limitations, CARLA can ingest maps of a limited size (large cities like Paris pushes the limits of the engine). Additionally, the bigger the map, the longer the conversion to OpenDRIVE will take.
 
 __1.3.Click on `Export`__ in the upper left side of the window. The __Export__ pannel will open.
@@ -32,29 +32,42 @@ __1.6. Click the `Export` button__ in the __Export__ pannel, and save the map in
 ---
 ## 2- Convert to OpenDRIVE format
 
-CARLA can read a XML file generated with OpenStreetMaps, and convert it to OpenDRIVE format that can be ingested as a CARLA map. This can be done through the PythonAPI using an script as in this example:
+CARLA can read a XML file generated with OpenStreetMaps, and convert it to OpenDRIVE format that can be ingested as a CARLA map. This can be done through the PythonAPI using the following classes.  
+
+*   __[carla.osm2odr](python_api.md#carla.osm2odr)__ – The class that does the conversion. It takes the content of the `.osm` parsed as strind, and returns a string containing the resulting `.xodr`.  
+	*   `osm_file` — The content of the initial `.osm` file parsed as string.  
+	*   `settings` — A [carla.Osm2OdrSettings](python_api.md#carla.Osm2OdrSettings) object containing the settings to parameterize the conversion.  
+*   __[carla.Osm2OdrSettings](python_api.md#carla.Osm2OdrSettings)__ – Helper class that contains different parameters used during the conversion.  
+	*   `use_offsets` *(default ???)* — Determines whereas the map should be generated with an offset, thus moving the origin from the center according to that offset.  
+	*   `offset_x` *(default ???)* — Offset in the X axis.  
+	*   `offset_y` *(default ???)* — Offset in the Y axis.  
+	*   `default_lane_width` *(default ???)* — Determines the width that lanes should have in the resulting XODR file.  
+	*   `elevation_layer_height` *(default ???)* — Determines the height separating elements in different layers, used for overlapping elements. Read more on [layers](https://wiki.openstreetmap.org/wiki/Key:layer).  
+
+
+The input and output of the conversion are not the `.osm` and `.xodr` files itself, but their content. For said reason, the code should be similar to the following.  
 ```
-# load osm data
-f = open(path/to/osm/file, 'r')
-osm_xml = f.read()
+# Read the .osm data
+f = open("path/to/osm/file", 'r')
+osm_data = f.read()
 f.close()
 
-# convert to opendrive
+# Define the desired settings. In this case, default. 
 settings = carla.Osm2OdrSettings()
-# set desired settings
-xodr_xml = carla.osm2odr.convert(osm_xml, settings)
+# Convert to .xodr
+xodr_data = carla.osm2odr.convert(osm_data, settings)
 
 # save opendrive file
-f = open(path/to/output/file, 'w')
-f.write(xodr_xml)
+f = open("path/to/output/file", 'w')
+f.write(xodr_data)
 f.close()
 ```
-The resulting file contains the road information in OpenDRIVE format. In the API documentation you can find more information regarding the settings that can be adjusted when converting the OSM file.
+The resulting file contains the road information in OpenDRIVE format.  
 
 ---
 ## 3- Import into CARLA
 
-Finally, the OpenDRIVE file can be easily ingested in CARLA using the [OpenDRIVE Standalone Mode](#adv_opendrive.md).
+Finally, the OpenDRIVE file can be easily ingested in CARLA using the [OpenDRIVE Standalone Mode](#adv_opendrive.md).  
 
 __a) Using your own script__ — Call for [`client.generate_opendrive_world()`](python_api.md#carla.Client.generate_opendrive_world) through the API. This will generate the new map, and block the simulation until it is ready. Use the [carla.OpendriveGenerationParameters](python_api.md#carla.OpendriveGenerationParameters) class to set the parameterization of the mesh generation.
 
@@ -72,23 +85,21 @@ world = client.generate_opendrive_world(
         smooth_junctions=True,
         enable_mesh_visibility=True))
 ```
-We recommend to run the standalone mode with `wall_height = 0.0` in the `carla.OpendriveGenerationParameters` settings to launch the standalone mode.
+
+!!! Note
+    `wall_height = 0.0` is strongly recommended.
 
 __b) Using config.py__ — We also provide the means to load an OpenStreetMaps file directly to Carla using the `config.py` script provided with Carla:
 ```
 config.py --osm-file=/path/to/OSM/file
 ```
 !!! Warning
-    [client.generate_opendrive_world()](python_api.md#carla.Client.generate_opendrive_world) uses __content of the OpenDRIVE file parsed as string__. On the contrary, __`config.py`__ script needs __the path to the `.xodr` file__.
-
-```
-!!! Important
-    The ingestion of the map allows for some parameterization. However, using the `config.py` parameters will always be the default ones.
+    [client.generate_opendrive_world()](python_api.md#carla.Client.generate_opendrive_world) uses __content of the OpenDRIVE file parsed as string__, and allows parameterization. On the contrary, __`config.py`__ script needs __the path to the `.xodr` file__ and always uses default parameters.
 
 
 Either way, the map should be ingested automatically in CARLA and the result should be similar to this.
 ![opendrive_meshissue](img/tuto_g_osm_carla.jpg)
-<div style="text-align: right"><i>Outcome.</i></div>
+<div style="text-align: right"><i>Outcome of the CARLA map generation using OpenStreetMap.</i></div>
 
 ---
 

mkdocs.yml

@@ -49,7 +49,7 @@ nav:
   - 'Add friction triggers': "tuto_G_add_friction_triggers.md"
   - 'Control vehicle physics': "tuto_G_control_vehicle_physics.md"
   - 'Control walker skeletons': "tuto_G_control_walker_skeletons.md"
-  - 'Generate reality-based maps with OpenStreetMap': 'tuto_G_openstreetmap.md'
+  - 'Generate maps with OpenStreetMap': 'tuto_G_openstreetmap.md'
   - 'Retrieve simulation data': "tuto_G_retrieve_data.md"
 - Tutorials (assets):
   - 'Add a new map': 'tuto_A_add_map.md'