diff --git a/Docs/img/tuto_g_osm_area.jpg b/Docs/img/tuto_g_osm_area.jpg
new file mode 100644
index 000000000..e0a4dd16e
Binary files /dev/null and b/Docs/img/tuto_g_osm_area.jpg differ
diff --git a/Docs/img/tuto_g_osm_carla.jpg b/Docs/img/tuto_g_osm_carla.jpg
new file mode 100644
index 000000000..94063f4b2
Binary files /dev/null and b/Docs/img/tuto_g_osm_carla.jpg differ
diff --git a/Docs/img/tuto_g_osm_web.jpg b/Docs/img/tuto_g_osm_web.jpg
new file mode 100644
index 000000000..e0f577933
Binary files /dev/null and b/Docs/img/tuto_g_osm_web.jpg differ
diff --git a/Docs/tuto_G_openstreetmap.md b/Docs/tuto_G_openstreetmap.md
index 4d41c0de7..d1ccafb53 100644
--- a/Docs/tuto_G_openstreetmap.md
+++ b/Docs/tuto_G_openstreetmap.md
@@ -1,78 +1,100 @@
# Generate reality-based 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 XODR and automatically ingest it as any other CARLA map using the [OpenDRIVE Standalone Mode](#adv_opendrive.md). The process is quite straightforward.
+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.
-* [__1- Create a map with OpenStreetMap__](#1-create-a-map-with-openstreetmap)
-* [__2- Convert to XODR file__](#2-convert-to-xodr-file)
-* [__3- Import into CARLA__](#3-import-into-carla)
+* [__1- Obtain a map with OpenStreetMap__](#1-obtain-a-map-with-openstreetmap)
+* [__2- Convert to OpenDRIVE format__](#2-convert-to-OpenDRIVE-format)
+* [__3- Import into CARLA__](#3-import-into-carla)
---
-## 1- Create a map with OpenStreetMap
+## 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](#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](openstreetmap.org)__.
-__1.2 Search for a desired location__ and zoom in to a specific area.
-
+__1.2 Search for a desired location__ and zoom in to a specific area.
+
!!! Important
- Maps larger than __Limit??__ will probably create issues when ingested in CARLA. Additionally, the bigger the map, the longer the conversion to XODR will take.
+ 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.
-If visualization is not proper, go to the pannel on the right and change between layers to update the map.
-
+__1.3.Click on `Export`__ in the upper left side of the window. The __Export__ pannel will open.
-__1.3.Click on `Export`__ in the upper left side of the window. The __Export__ pannel will open.
+__1.4. Click on `Manually select a different area`__ in the __Export__ pannel.
-__1.4. Click on `Manually select a different area`__ in the __Export__ pannel.
-
+__1.5. Select a custom area__ by dragging the corners of the square area in the viewport.
-__1.5. Select a custom area__ by dragging the corners of the square area in the viewport.
-
+__1.6. Click the `Export` button__ in the __Export__ pannel, and save the map information of the selected area as a XML file.
-__1.6. Click the `Export` button__ in the __Export__ pannel, and save the map information of the selected area as a XML file.
-
+
---
-## 2- Convert to XODR file
+## 2- Convert to OpenDRIVE format
-CARLA can take an XML file generated with OpenStreetMaps, and convert it to an XODR file that can be ingested as a CARLA map. In order to do so??...
+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:
+```
+# load osm data
+f = open(path/to/osm/file, 'r')
+osm_xml = f.read()
+f.close()
-* __`paramA`__ *(default )* — Description??...
-* __`paramB`__ *(default )* — Description??...
-* __`paramC`__ *(default )* — Description??...
+# convert to opendrive
+settings = carla.Osm2OdrSettings()
+# set desired settings
+xodr_xml = carla.osm2odr.convert(osm_xml, settings)
+
+# save opendrive file
+f = open(path/to/output/file, 'w')
+f.write(xodr_xml)
+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.
---
## 3- Import into CARLA
-The resulting XODR map 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 an example script__ — The `config.py` script in `PythonAPI/util/` has a new argument, `-x` or `--xodr-path`. This argument expects a string with the path to the `.xodr` file.
+__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.
-```sh
-# Go to the folder containing the example scripts
-cd PythonAPI/examples
-# Run the script
-python3 config.py -x opendrive/TownBig.xodr
```
+vertex_distance = 2.0 # in meters
+max_road_length = 500.0 # in meters
+wall_height = 0.0 # in meters
+extra_width = 0.6 # in meters
+world = client.generate_opendrive_world(
+ xodr_xml, carla.OpendriveGenerationParameters(
+ vertex_distance=vertex_distance,
+ max_road_length=max_road_length,
+ wall_height=wall_height,
+ additional_width=extra_width,
+ 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.
-!!! Important
- The ingestion of the map allows for some parameterization. However, using the `config.py`, parameters will always be the default ones.
-
-__b) 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.
-
+__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__.
-Either way, the map should be ingested automatically in CARLA and the result should be similar to this.
-
+```
+!!! Important
+ The ingestion of the map allows for some parameterization. However, using the `config.py` parameters will always be the default ones.
+
+
+Either way, the map should be ingested automatically in CARLA and the result should be similar to this.
+
Outcome.
---
-That is all there is to know about how to use OpenStreetMap to generate CARLA maps.
+That is all there is to know about how to use OpenStreetMap to generate CARLA maps.
-For issues and doubts related with this topic can be posted in the CARLA forum.
+For issues and doubts related with this topic can be posted in the CARLA forum.