p71924506
/
carla
mirror of https://github.com/carla-simulator/carla.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added updated OSM documentation

This commit is contained in:
corkyw10 2021-07-29 09:27:34 +02:00 committed by bernat
parent bd36e46b39
commit f72a31a491
1 changed files with 137 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

180
Docs/tuto_G_openstreetmap.md
View File

@ -1,59 +1,85 @@
# Generate maps with OpenStreetMap
OpenStreetMap is an open license map of the world developed by contributors. Sections of these map can be exported to a `.osm` file, the OpenSreetMap format, which is essentially an XML. 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.
In this guide you will learn:
* [__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)
- How to export a map from OpenStreetMaps.
- The different formats of map that can be used in CARLA and each format's limitations.
- How to convert the native `.osm` format to `.xodr`.
- How to include traffic light information in the `.xodr` file.
- How to run the final map in a CARLA simulation.
[OpenStreetMap](https://www.openstreetmap.org) is an open data map of the world developed by thousands of contributors and licensed under the [Open Data Commons Open Database License](https://opendatacommons.org/licenses/odbl/). Sections of the map can be exported to an XML formatted `.osm` file. CARLA can convert this file to an OpenDRIVE format and ingest it using the [OpenDRIVE Standalone Mode](#adv_opendrive.md).
- [__Export a map with OpenStreetMap__](#export-a-map-with-openstreetmap)
- [__Using OpenStreetMaps in CARLA__](#using-openstreetmaps-in-carla)
- [__Convert OpenStreetMap format to OpenDRIVE format__](#convert-openstreetmap-format-to-opendrive-format)
- [Linux](#linux)
- [Windows](#windows)
- [Generate Traffic Lights](#generate-traffic-lights)
- [__Ingest into CARLA__](#ingest-into-carla)
---
## 1- Obtain a map with OpenStreetMap
## Export a map with OpenStreetMap
The first thing to do is use [OpenStreetMap](https://www.openstreetmap.org) to generate the file containing the map information.
This section explains how to export your desired map information from Open Street Map:
__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.__ Navigate to the [Open Street Map website](https://www.openstreetmap.org). You will see the map view and a panel on the right side of the window where you can configure different map layers, query different features, toggle the legend, and more.
__1.2 Search for a desired location__ and zoom in to a specific area.
__2.__ Search for your desired location and zoom in to a specific area.
![openstreetmap_view](img/tuto_g_osm_web.jpg)
!!! Warning
Due to the Unreal Engine limitations, CARLA can ingest maps of a limited size (large cities like Paris push the limits of the engine). Additionally, the bigger the map, the longer the conversion to OpenDRIVE will take.
Due to limitations in Unreal Engine, CARLA can ingest maps of limited size (large cities like Paris will push the limits of the engine). 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.
__3.__ Click on _Export_ on the upper left side of the window to open the _Export_ panel.
__1.4. Click on `Manually select a different area`__ in the __Export__ pannel.
__4.__ Click on _Manually select a different area_ in the _Export_ panel.
__1.5. Select a custom area__ by dragging the corners of the square area in the viewport.
__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 `.osm` file.
__6.__ Click the _Export_ button in the _Export_ panel and save the map information of the selected area as a `.osm` file.
![openstreetmap_area](img/tuto_g_osm_area.jpg)
---
## 2- Convert to OpenDRIVE format
## Using OpenStreetMaps in CARLA
CARLA can read a the content in the `.osm` file generated with OpenStreetMap, and convert it to OpenDRIVE format so that it can be ingested as a CARLA map. This can be done using the following classes in the PythonAPI.
Open Street Map data can be used in CARLA via three different methods. The method you use will depend on if the data is in the original `.osm` format or if you convert the file to `.xodr` using the conversion method explained in the following sections. Keeping the file in `.osm` is the most restrictive method as it does not allow for settings customization.
* __[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 False)* — Determines whereas the map should be generated with an offset, thus moving the origin from the center according to that offset.
* `offset_x` *(default 0.0)* — Offset in the X axis.
* `offset_y` *(default 0.0)* — Offset in the Y axis.
* `default_lane_width` *(default 4.0)* — Determines the width that lanes should have in the resulting XODR file.
* `elevation_layer_height` *(default 0.0)* — Determines the height separating elements in different layers, used for overlapping elements. Read more on [layers](https://wiki.openstreetmap.org/wiki/Key:layer).
__Options available for `.xodr` format:__
- Generate the map in your own script. __This method allows parameterization.__
- Pass the file as a parameter to CARLA's `config.py`. __This method does not allow parameterization.__
__Options available for `.osm` format:__
- Pass the file as a parameter to CARLA's `config.py`. __This method does not allow parameterization.__
The following sections will provide more detail on the options listed above.
---
## Convert OpenStreetMap format to OpenDRIVE format
This section demonstrates how to use the Python API to convert the `.osm` file we exported in the previous section to `.xodr` format so that it is ready for use in CARLA.
The [carla.Osm2OdrSettings](python_api.md#carla.Osm2OdrSettings) class is used to configure conversion settings such as offset values, traffic light generation, origin coordinates, and more. The full list of configurable parameters is found in the Python API [documentation](python_api.md#carla.Osm2OdrSettings). The [carla.Osm2Odr](python_api.md#carla.Osm2Odr) class uses these settings to parse the `.osm` data and output it in `.xodr` format.
In Windows, the `.osm` file must be encoded to `UTF-8`. This is not necessary in Linux. Below are example code snippets that show how to perform the file conversion depending on your operating system:
##### Linux
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.
```py
# Read the .osm data
f = open("path/to/osm/file", 'r') # Windows will need to encode the file in UTF-8. Read the note below.
f = open("path/to/osm/file", 'r')
osm_data = f.read()
f.close()
# Define the desired settings. In this case, default values.
settings = carla.Osm2OdrSettings()
# Set OSM road types to export to OpenDRIVE
settings.set_osm_way_types(["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "tertiary_link", "unclassified", "residential"])
# Convert to .xodr
xodr_data = carla.Osm2Odr.convert(osm_data, settings)
@ -63,21 +89,72 @@ f.write(xodr_data)
f.close()
```
!!! Note
To read the OSM file in Windows, import `io` at the beginning of the script and change the open line to `f = io.open("test", mode="r", encoding="utf-8")`.
##### Windows
```py
import io
The resulting file contains the road information in OpenDRIVE format.
# Read the .osm data
f = io.open("test", mode="r", encoding="utf-8")
osm_data = f.read()
f.close()
# Define the desired settings. In this case, default values.
settings = carla.Osm2OdrSettings()
# Set OSM road types to export to OpenDRIVE
settings.set_osm_way_types(["motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "tertiary_link", "unclassified", "residential"])
# Convert to .xodr
xodr_data = carla.Osm2Odr.convert(osm_data, settings)
# save opendrive file
f = open("path/to/output/file", 'w')
f.write(xodr_data)
f.close()
```
<br>
---
## 3- Import into CARLA
### Generate Traffic Lights
Finally, the OpenDRIVE file can be easily ingested in CARLA using the [OpenDRIVE Standalone Mode](adv_opendrive.md).
Open Street Map data can define which junctions are controlled with traffic lights. To use this traffic light data in CARLA, you need to enable it in the OSM map settings via the Python API before converting the `.osm` file to `.xodr` format:
__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.
```py
# Define the desired settings. In this case, default values.
settings = carla.Osm2OdrSettings()
# enable traffic light generation from OSM data
settings.generate_traffic_lights = True
# Convert to .xodr
xodr_data = carla.Osm2Odr.convert(osm_data, settings)
```
Traffic light data quality can vary depending on the region from which you extract data. Some traffic light information may be missing completely. To work within these limitations, you can use the Python API to configure all junctions to be controlled with traffic lights:
```py
settings.all_junctions_with_traffic_lights = True
```
You can also exclude certain roads, e.g., motorway links, from generating traffic lights:
```
settings.set_traffic_light_excluded_way_types(["motorway_link"])
```
---
## Ingest into CARLA
This section explains how to use the different options available to ingest your Open Street Map information into CARLA using the [OpenDRIVE Standalone Mode](adv_opendrive.md).
There are three options available:
[__A)__](#a-use-your-own-script) Generate the map using a converted `.xodr` file in your own custom Python script. __This method allows parameterization.__
[__B)__](#b-pass-xodr-to-configpy) Pass a converted `.xodr` file as a parameter to the CARLA `config.py` script. __This method does not allow parameterization.__
[__C)__](#c-pass-osm-to-configpy) Pass the original `.osm` file as a parameter to the CARLA `config.py` script. __This method does not allow parameterization.__
###### A) Use your own script
Generate the new map and block the simulation until it is ready by calling [`client.generate_opendrive_world()`](python_api.md#carla.Client.generate_opendrive_world). Use the [carla.OpendriveGenerationParameters](python_api.md#carla.OpendriveGenerationParameters) class to configure the mesh generation. See below for an example:
```py
vertex_distance = 2.0 # in meters
max_road_length = 500.0 # in meters
wall_height = 0.0 # in meters
@ -93,31 +170,48 @@ world = client.generate_opendrive_world(
```
!!! Note
`wall_height = 0.0` is strongly recommended. OpenStreetMap defines lanes in opposing directions as different roads. If walls are generated, this result in wall overlapping and undesired collisions.
`wall_height = 0.0` is strongly recommended. OpenStreetMap defines lanes in opposing directions as different roads. If walls are generated, this will result in wall overlapping and undesired collisions.
__b) Using `config.py`__ — The script can load an OpenStreetMap file directly into CARLA using a new argument.
###### B) Pass `.xodr` to `config.py`
After you have started a CARLA server, run the following command in a separate terminal to load your Open Street Map:
```sh
cd PythonAPI/util
python3 config.py -x=/path/to/xodr/file
```
[Default parameters](python_api.md#carla.OpendriveGenerationParameters) will be used.
###### C) Pass `.osm` to `config.py`
After you have started a CARLA server, run the following command in a separate terminal to load your Open Street Map:
```sh
cd PythonAPI/util
python3 config.py --osm-path=/path/to/OSM/file
```
!!! Important
[client.generate_opendrive_world()](python_api.md#carla.Client.generate_opendrive_world) requires the __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.
[Default parameters](python_api.md#carla.OpendriveGenerationParameters) will be used.
Regardless of the method used, the map will be ingested into CARLA and the result should be similar to the image below:
![opendrive_meshissue](img/tuto_g_osm_carla.jpg)
<div style="text-align: right"><i>Outcome of the CARLA map generation using OpenStreetMap.</i></div>
<br>
!!! Warning
The roads generated end abruptly in the borders of the map. This will cause the TM to crash when vehicles are not able to find the next waypoint. To avoid this, the OSM mode is set to __True__ by default ([set_osm_mode()](python_api.md#carlatrafficmanager)). This will show a warning, and destroy vehicles when necessary.
The roads generated end abruptly at the borders of the map. This will cause the Traffic Manager to crash when vehicles are not able to find the next waypoint. To avoid this, the OSM mode in the Traffic Manager is set to __True__ by default ([`set_osm_mode()`](python_api.md#carlatrafficmanager)). This will show a warning and destroy vehicles when necessary.
---
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.
Any issues and doubts related with this topic can be posted in the CARLA forum.
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>
</div>