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

Corkyw10/import maps tutorial (#3875) 

* restructured tutorial layout to avoid confusion between the three different methods available

* Beginnings of new layout of maps tutorial

* updatng docker and make import sections

* Final first draft of map import guide refactor. Links to the guide have been changed in the rest of the documentation

* Removed windows import option from package map import doc

* Clarified that package import otpion with Docker only works on Linux

* Deleted deprecated section. Removed reference to creating crosswalk meshes unless users want to add new ones. Removed part about packages needing unique name and moved this to 'before you begin' to say that map names should be unique'

* Added more information about how to export from road runner. Removed another line referring to the deprecated methods to import maps.

* Add a structure of the .json file to the overview and added to --use-carla-materials flag that it is only necessary if you do not provide a .json file yourself

* Clarified that .json values will override flag values

* Alternative import methods

* Added alternative section to overview and added images for manual import

* Summary section added to alternative methods

* Added image to show render disable for pedestrian mesh
This commit is contained in:
Corinne 2021-03-23 10:00:18 +01:00 committed by GitHub
parent 5a9159b14b
commit b4b50cc48a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
18 changed files with 625 additions and 524 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Docs/core_map.md
View File

@ -228,7 +228,7 @@ There are eight towns in the CARLA ecosystem and each of those towns have two ki
Non-layered maps are shown in the table below (click the town name to see an overhead image of the layout). All of the layers are present at all times and cannot be toggled on or off in these maps. Up until CARLA 0.9.11, these were the only kinds of map available.
!!! Note
Users can [customize a map](tuto_A_map_customization.md) or even [create a new map](tuto_A_add_map.md) to be used in CARLA.
Users can [customize a map](tuto_A_map_customization.md) or even [create a new map](tuto_A_add_map_overview.md) to be used in CARLA.
| Town | Summary |
| -----------| ------ |

BIN
Docs/img/disable_rendering.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 626 KiB

BIN
Docs/img/roadrunner_export.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.8 KiB

BIN
Docs/img/ue_duplicate_basemap.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
Docs/img/ue_generate_routes.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
Docs/img/ue_import_asset.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
Docs/img/ue_noexport.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB

2
Docs/index.md
View File

@ -76,7 +76,7 @@ CARLA forum</a>
[__Retrieve simulation data__](tuto_G_retrieve_data.md) — A step by step guide to properly gather data using the recorder.
## Tutorials — Assets
[__Add a new map__](tuto_A_add_map.md) — Create and ingest a new map.
[__Add a new map__](tuto_A_add_map_overview.md) — Create and ingest a new map.
[__Add a new vehicle__](tuto_A_add_vehicle.md) — Prepare a vehicle to be used in CARLA.
[__Add new props__](tuto_A_add_props.md) — Import additional props into CARLA.
[__Create standalone packages__](tuto_A_create_standalone.md) — Generate and handle standalone packages for assets.

517
Docs/tuto_A_add_map.md
View File

@ -1,517 +0,0 @@
# Add a new map
Users can create their own maps, and run CARLA using these. The creation of the map object is quite independent from CARLA. Nonetheless, the process to ingest it has been refined to be automatic. Thus, the new map can be used in CARLA almost out-of-the-box.
* [__Introduction__](#introduction)
* [__Create a map with RoadRunner__](#create-a-map-with-roadrunner)
* [Export from RoadRunner](#export-from-roadrunner)
* [__Map ingestion in a CARLA package__](#map-ingestion-in-a-carla-package)
* [__Map ingestion in a build from source__](#map-ingestion-in-a-build-from-source)
* [Modify pedestrian navigation](#modify-pedestrian-navigation)
* [__Deprecated ways to import a map__](#deprecated-ways-to-import-a-map)
---
## Introduction
RoadRunner is the recommended software to create a map due to its simplicity. Some basic steps on how to do it are provided in [the next section](#create-a-map-with-roadrunner). The resulting map should consist of a `.fbx` and a `.xodr` with the mesh and road network informtion respectively.
The process of the map ingestion has been simplified to minimize the users' intervention. For said reason, there are certains steps have been automatized.
* __Package `.json` file and folder structure__. Normally packages need a certain folder structure and a `.json` file describing them to be imported. However, as regards the map ingestion, this can be created automatically during the process.
* __Traffic signs and traffic lights.__ The simulator will generate the traffic lights, stops, and yields automatically when running. These will be creatd according to their `.xodr` definition. The rest of landmarks present in the road map will not be physically on scene, but they can be queried using the API.
* __Pedestrian navigation.__ The ingestion will generate a `.bin` file describing the pedestrian navigation. It is based on the sidewalks and crosswalks that appear in the OpenDRIVE map. This can only be modified if working in a build from source.
!!! Important
If a map contains additional elements besides the `.fbx` and `.xodr`, the package has to be [prepared manually](#prepare-the-package-manually).
The map ingestion process differs, depending if the package is destined to be in a CARLA package (e.g., 0.9.9) or a build from source.
There are other ways to import a map into CARLA, which are now deprecated. They require the user to manually set the map ready. Nonetheless, as they may be useful for specific cases when the user wants to customize a specific setting, they are listed in the [last section](#deprecated-ways-to-import-a-map) of this tutorial.
---
## Create a map with RoadRunner
RoadRunner is an accessible and powerful software from Vector Zero to create 3D scenes. Since the release of R2020b (16th September 2020), it has been added to the MATLAB Campus Wide Licenses, so many universities can provide unlimited academic access. [Check](https://www.mathworks.com/academia/tah-support-program/eligibility.html) if your university has access. Reach out to *automated-driving@mathworks.com* for any question or trouble regarding accessibility. Additionally, there is a [trial version](https://es.mathworks.com/products/roadrunner.html) available, and an [installation guide][rr_docs].
[rr_docs]: https://tracetransit.atlassian.net/wiki/spaces/VS/pages/740622413/Getting+Started
The process is quite straightforward, but there are some things to take into account.
* __Center the map__ in (0,0).
* __Create the map definition.__ Take a look at the [official tutorials](https://www.youtube.com/channel/UCAIXf4TT8zFbzcFdozuFEDg/playlists).
* __Check the map validation.__ Take a close look at all connections and geometries.
![CheckGeometry](img/check_geometry.jpg)
Once the map is ready, click on the `OpenDRIVE Preview Tool` button to visualize the OpenDRIVE road network. Give one last check to everything. Once the map is exported, it cannot be modified.
![checkopen](img/check_open.jpg)
!!! note
_OpenDrive Preview Tool_ makes it easier to test the integrity of the map. If there is any error with junctions, click on `Maneuver Tool`, and `Rebuild Maneuver Roads`.
### Export from RoadRunner
__1. Export the scene using the CARLA option.__ `File/Export/CARLA(.fbx+.xml+.xodr)`
__2. Leave `Export individual Tiles` unchecked.__ This will generate only one _.fbx_ with all the pieces. It makes easier to keep track of the map.
__3. Click `Export`.__
This will generate a `mapname.fbx` and `mapname.xodr` files within others. There is more detailed information about how to export to CARLA in [VectorZero's documentation][exportlink].
[exportlink]: https://tracetransit.atlassian.net/wiki/spaces/VS/pages/752779356/Exporting+to+CARLA
!!! Warning
Make sure that the .xodr and the .fbx files have the same name.
---
## Map ingestion in a CARLA package
This is the recommended method to import a map into a CARLA package. It will run a Docker image of Unreal Engine to import the files, and export them as a standalone package. The Docker image takes 4h and 400GB to be built. However, this is only needed the first time.
__1. Build a Docker image of Unreal Engine.__ Follow [these instructions](https://github.com/carla-simulator/carla/tree/master/Util/Docker) to build the image.
__2. Change permissions on the input folder.__ If no `.json` file is provided, the Docker will try to create it on the input folder. To be successful, said folder must have all permissions enabled for others.
```sh
#Go to the parent folder, where the input folder is contained
chmod 777 input_folder
```
!!! Note
This is not necessary if the package is [prepared manually](#prepare-the-package-manually), and contains a `.json` file.
__2. Run the script to cook the map.__ In the folder `~/carla/Util/Docker` there is a script that connects with the Docker image previously created, and makes the ingestion automatically. It only needs the path for the input and output files, and the name of the package to be ingested. If no `.json` is provided, the name must be `map_package`.
```sh
python3 docker_tools.py --input ~/path_to_input_folder --output ~/path_to_output_folder --packages map_package
```
!!! Warning
If the argument `--package <package_name>` is not provided, the Docker will make a package of CARLA.
__3. Locate the package__. The Docker should have generated the package `map_package.tar.gz` in the output path. This is the standalone package for the assets.
__4. Import the package into CARLA.__
* __On Windows__ extract the package in the `WindowsNoEditor` folder.
* __On Linux__ move the package to the `Import` folder, and run the script to import it.
```sh
cd Util
./ImportAssets.sh
```
__5. Change the name of the package folder__. Two packages cannot have the same name in CARLA. Go to `Content` and find the package. Change the name if necessary, to use one that identifies it.
---
## Map ingestion in a build from source
This is method is meant to be used if working with the source version of CARLA. Place the maps to be imported in the `Import` folder. The script will make the ingestion, but the pedestrian navigation will have to be generated after that. Make sure that the name of the `.xodr` and `.fbx` files are the same for each of the maps being imported. Otherwise, the script will not recognize them as a map.
There are two parameters to be set.
* __Name of the package.__ By default, the script ingest the map or maps in a package named `map_package`. This could lead to error the second time an ingestion is made, as two packages cannot have the same name. __It is highly recommended to change the name of the package__.
```sh
ARGS="--package package_name"
```
* __Usage of CARLA materials.__ By default, the maps imported will use CARLA materials, but this can be changed using a flag.
```sh
ARGS="--no-carla-materials"
```
Check that there is an `.fbx` and a `.xodr` for each map in the `Import` folder, and make the ingestion.
```sh
make import ARGS="--package package_name --no-carla-materials"
```
After the ingestion, only the pedestrian navigation is yet to be generated. However there is an optional step that can be done before that.
* __Create new spawning points.__ Place them a over the road, around 0.5/1m so the wheels do not collide with the ground. These will be used in scripts such as `spawn_npc.py`.
### Generate pedestrian navigation
The pedestrian navigation is managed using a `.bin`. However, before generating it, there are two things to be done.
* __Add crosswalk meshes.__ Crosswalks defined inside the `.xodr` remain in the logic of the map, but are not visible. For each of them, create a plane mesh that extends a bit over both sidewalks connected. __Place it overlapping the ground, and disable its physics and rendering__.
!!! Note
To generate new crosswalks, change the name of the mesh to `Road_Crosswalk`. Avoid doing so if the crosswalk is in the `.xodr`. Otherwise, it will be duplicated.
![ue_crosswalks](img/ue_crosswalks.jpg)
* __Customize the map.__ In is common to modify the map after the ingestion. Props such as trees, streetlights or grass zones are added, probably interfering with the pedestrian navigation. Make sure to have the desired result before generating the pedestrian navigation. Otherwise, it will have to be generated again.
Now that the version of the map is final, it is time to generate the pedestrian navigation file.
__1.__ Select the __Skybox object__ and add a tag `NoExport` to it. Otherwise, the map will not be exported, as the size would be too big.
![ue_skybox_no_export](img/ue_noexport.jpg)
__2.__ Check the name of the meshes. By default, pedestrians will be able to walk over sidewalks, crosswalks, and grass (with minor influence over the rest).
* Sidewalk = `Road_Sidewalk`.
* Crosswalk = `Road_Crosswalk`.
* Grass = `Road_Grass`.
![ue_meshes](img/ue_meshes.jpg)
__3.__ Name these planes following the common format `Road_Crosswalk_mapname`.
__4.__ Press `G` to deselect everything, and export the map. `File > Export CARLA...`. A `map_file.obj` file will be created in `Unreal/CarlaUE4/Saved`.
__5.__ Move the `map_file.obj` and the `map_file.xodr` to `Util/DockerUtils/dist`.
__6.__ Run the following command to generate the navigation file.
* __Windows__
```sh
build.bat map_file # map_file has no extension
```
* __Linux__
```sh
./build.sh map_file # map_file has no extension
```
__7.__ Move the `.bin` into the `Nav` folder of the package that contains the map.
---
## Deprecated ways to import a map
There are other ways to import a map used in previous CARLA releases. These required to manually cook the map and prepare everything, so they are now deprecated. However, they are explained below in case they are needed.
### Prepare the package manually
A package needs to follow a certain folder structure and contain a `.json` file describing it. This steps can be saved under certains circumstances, but doing it manually will always work.
<details>
<summary> Read how to prepare the folder structure and .json file
</h4></summary>
#### Create the folder structure
__1. Create a folder inside `carla/Import`.__ The name of the folder is not relevant.
__2. Create different subfolders__ for each map to import.
__3. Move the files of each map to the corresponding subfolder.__ A subfolder will contain a specific set of elements.
* The mesh of the map in a `.fbx`.
* The OpenDRIVE definition in a `.xodr`.
* Optionally, the textures required by the asset.
For instance, an `Import` folder with one package containing two maps should have a structure similar to the one below.
```sh
Import
│
└── Package01
├── Package01.json
├── Map01
│ ├── Asphalt1_Diff.jpg
│ ├── Asphalt1_Norm.jpg
│ ├── Asphalt1_Spec.jpg
│ ├── Grass1_Diff.jpg
│ ├── Grass1_Norm.jpg
│ ├── Grass1_Spec.jpg
│ ├── LaneMarking1_Diff.jpg
│ ├── LaneMarking1_Norm.jpg
│ ├── LaneMarking1_Spec.jpg
│ ├── Map01.fbx
│ └── Map01.xodr
└── Map02
└── Map02.fbx
```
#### Create the JSON description
Create a `.json` file in the root folder of the package. Name the file after the package. Note that this will be the distribution name. The content of the file will describe a JSON array of __maps__ and __props__ with basic information for each of them.
__Maps__ need the following parameters.
* __name__ of the map. This must be the same as the `.fbx` and `.xodr` files.
* __source__ path to the `.fbx`.
* __use_carla_materials__. If __True__, the map will use CARLA materials. Otherwise, it will use RoadRunner materials.
* __xodr__ Path to the `.xodr`.
__Props__ are not part of this tutorial. The field will be left empty. There is another tutorial on how to [add new props](tuto_A_add_props.md).
In the end, the `.json` should look similar to the one below.
```json
{
"maps": [
{
"name": "Map01",
"source": "./Map01/Map01.fbx",
"use_carla_materials": true,
"xodr": "./Map01/Map01.xodr"
},
{
"name": "Map02",
"source": "./Map02/Map02.fbx",
"use_carla_materials": false,
"xodr": "./Map02/Map02.xodr"
}
],
"props": [
]
}
```
</details>
<br>
### RoadRunner plugin import
This software provides specific plugins for CARLA. Get those and follow some simple steps to get the map.
<details>
<summary> Read RoadRunner plugin import guide
</h4></summary>
!!! Warning
These importing tutorials are deprecated. There are new ways to [ingest a map](#map-ingestion) to simplify the process.
### Plugin installation
These plugins will set everything ready to be used in CARLA. It makes the import process more simple.
__1. Locate the plugins__ in RoadRunner's installation folder
`/usr/bin/VectorZero/Tools/Unreal/Plugins`.
__2. Copy those folders__ to the CarlaUE4 plugins directory `/carla/Unreal/CarlaUE4/Plugins/`.
__3. Rebuild the plugin__ following the instructions below.
* __a) Rebuild on Windows.__
* Right-click the `.uproject` file and `Generate Visual Studio project files`.
* Open the project and build the plugins.
* __b) Rebuild on Linux.__
* Run the following command.
```sh
> UE4_ROOT/GenerateProjectFiles.sh -project="carla/Unreal/CarlaUE4/CarlaUE4.uproject" -game -engine
```
__4. Restart Unreal Engine.__ Make sure the checkbox is on for both plugins `Edit > Plugins`.
![rr_ue_plugins](img/rr-ue4_plugins.jpg)
### Import map
__1. Import the _mapname.fbx_ file__ to a new folder under `/Content/Carla/Maps` with the `Import` button.
![ue_import](img/ue_import_mapname.jpg)
__2. Set `Scene > Hierarchy Type`__ to _Create One Blueprint Asset_ (selected by default).
__3. Set `Static Meshes > Normal Import Method`__ to _Import Normals_.
![ue_import_options](img/ue_import_options.jpg)
__4. Click `Import`.__
__5. Save the current level__ `File > Save Current As...` > _mapname_.
The new map should now appear next to the others in the Unreal Engine _Content Browser_.
![ue_level_content](img/ue_level_content.jpg)
</details>
!!! Note
The tags for semantic segmentation will be assigned by the name of the asset. And the asset moved to the corresponding folder in `Content/Carla/PackageName/Static`. To change these, move them manually after imported.
### Manual import
This process requires to go through all the process manually. From importing _.fbx_ and _.xodr_ to setting the static meshes.
<details>
<summary> Read manual import guide
</summary>
!!! Warning
These importing tutorials are deprecated. There are new ways to [ingest a map](#map-ingestion) to simplify the process.
This is the generic way to import maps into Unreal Engine using any _.fbx_ and _.xodr_ files. As there is no plugin to ease the process, there are many settings to be done before the map is available in CARLA.
__1. Create a new level__ with the **Map** name in Unreal `Add New > Level` under `Content/Carla/Maps`.
__2. Copy the illumination folder and its content__ from the BaseMap `Content/Carla/Maps/BaseMap`, and paste it in the new level. Otherwise, the map will be in the dark.
![ue_illumination](img/ue_illumination.jpg)
### Import binaries
__1. Import the _mapname.fbx_ file__ to a new folder under `/Content/Carla/Maps` with the `Import` button. __Make sure the following options are unchecked.__
* Auto Generate Collision
* Combine Meshes
* Force Front xAxis
* Normal Import Method - _To import normals_
__2. Check the following options.__
* Convert Scene Unit
* _To import materials and textures._
* Material Import Method - _To create new materials_
* Import Textures
![ue_import_file](img/ue_import_file.jpg)
__3. Check that the static meshes have appeared__ in the chosen folder.
__4. Drag the meshes__ into the level.
![ue_meshes](img/ue_drag_meshes.jpg)
__5. Center the meshes at point (0,0,0)__ when Unreal finishes loading.
![Transform_Map](img/transform.jpg)
__6. Generate collisions__. Otherwise, pedestrians and vehicles will fall into the abyss.
* Select the meshes meant to have colliders.
* Right-click `Asset Actions > Bulk Edit via Property Matrix...`.
![ue_selectmesh_collision](img/ue_selectmesh_collision.jpg)
* Search for _collision_ in Property's Matrix search box.
* Change `Collision complexity` from `Project Default` to `Use Complex Collision As Simple`.
![ue_collision_complexity](img/ue_collision_complexity.jpg)
* Go to `File > Save All`.
__7. Move the static meshes__ from `Content/Carla/Maps/mapfolder` to the corresponding `Carla/Static` subsequent folder. This will be meaningful for the semantic segmentation ground truth.
* `Terrain/mapname`
* `Road/mapname`
* `RoadLines/mapname`
```sh
Content
└── Carla
├── Blueprints
├── Config
├── Exported Maps
├── HDMaps
├── Maps
└── Static
├── Terrain
│ └── mapname
│ └── Static Meshes
│
├── Road
│ └── mapname
│ └── Static Meshes
│
├── RoadLines
| └── mapname
| └── Static Meshes
└── Sidewalks
└── mapname
└── Static Meshes
```
![ue__semantic_segmentation](img/ue_ssgt.jpg)
### Import OpenDRIVE files
__1. Copy the `.xodr` file__ inside the `Content/Carla/Maps/OpenDrive` folder.
__2. Open the Unreal level.__ Drag the _Open Drive Actor_ inside the level. It will read the level's name. Search the Opendrive file with the same name and load it.
![ue_opendrive_actor](img/ue_opendrive_actor.jpg)
</details>
<br>
### Set traffic and pedestrian behaviour
This software provides specific plugins for CARLA. Get those and follow some simple steps to get the map.
<details>
<summary>Read traffic and pedestrian setting guide</summary>
!!! Warning
These importing tutorials are deprecated. There are new ways to [ingest a map](#map-ingestion) to simplify the process.
### Set traffic behavior
Once everything is loaded into the level, it is time to create traffic behavior.
__1. Click on the _Open Drive Actor_.__
__2. Check the following boxes in the same order.__
* Add Spawners.
* _(Optional for more spawn points)_ On Intersections.
* Generate Routes.
This will generate a series of _RoutePlanner_ and _VehicleSpawnPoint_ actors. These are used for vehicle spawning and navigation.
### Traffic lights and signs
Traffic lights and signs must be placed all over the map.
__1. Drag traffic light/sign actors__ into the level and place them.
__2. Adjust the [`trigger volume`][triggerlink]__ for each of them. This will determine their area of influence.
[triggerlink]: python_api.md#carla.TrafficSign.trigger_volume
![ue_trafficlight](img/ue_trafficlight.jpg)
__3. In junctions, drag a traffic light group actor__ into the level. Assign to it all the traffic lights involved and configure their timing. Make sure to understand [how do traffic lights work](http://127.0.0.1:8000/core_actors/#traffic-signs-and-traffic-lights).
![ue_tl_group](img/ue_tl_group.jpg)
__4. Test traffic light timing and traffic trigger volumes.__ This may need trial and error to fit perfectly.
![ue_tlsigns_example](img/ue_tlsigns_example.jpg)
> _Example: Traffic Signs, Traffic lights and Turn based stop._
---
### Add pedestrian navigation
In order to prepare the map for pedestrian navigation, there are some settings to be done before exporting it.
__1.__ Select the __Skybox object__ and add a tag `NoExport` to it. Otherwise, the map will not be exported, as the size would be too big. Any geometry that is not involved or interfering in the pedestrian navigation can be tagged also as `NoExport`.
![ue_skybox_no_export](img/ue_noexport.jpg)
__2.__ Check the name of the meshes. By default, pedestrians will be able to walk over sidewalks, crosswalks, and grass (with minor influence over the rest).
![ue_meshes](img/ue_meshes.jpg)
__3.__ Crosswalks have to be manually created. For each of them, create a plane mesh that extends a bit over both sidewalks connected. __Place it overlapping the ground, and disable its physics and rendering__.
![ue_crosswalks](img/ue_crosswalks.jpg)
__4.__ Name these planes following the common format `Road_Crosswalk_mapname`.
__5.__ Press `G` to deselect everything, and export the map. `File > Export CARLA...`.
__6.__ Run RecastDemo `./RecastDemo`.
* Select `Solo Mesh` from the `Sample` parameter's box.
* Select the _mapname.obj_ file from the `Input Mesh` parameter's box.
![recast_example](img/recast_example.jpg)
__7.__ Click on the `Build` button.
__8.__ Once the build has finished, click on the `Save` button.
__9.__ Change the **filename** of the binary file generated at `RecastDemo/Bin` to `mapname.bin`.
__10.__ Drag the _mapname.bin_ file into the `Nav` folder under `Content/Carla/Maps`.
</details>
<br>
---
That comprises the process to create and import a new map into CARLA. If during the process any doubts arise, feel free to post these in the forum.
<div class="build-buttons">
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

306
Docs/tuto_A_add_map/add_map_alternative.md Normal file
View File

@ -0,0 +1,306 @@
# Alternative methods to import maps
This section describes how to prepare a map package manually and details methods to import maps alternative to the processes described in the guides [__Import into source build version of CARLA__](add_map_source.md) and [__Import into package version of CARLA__](add_map_package.md). The methods described in this section involve more manual steps than the processes explained in those guides.
- [__RoadRunner plugin import__](#roadrunner-plugin-import)
- [__Manual import__](#manual-import)
- [__Set traffic and pedestrian behaviour__](#set-traffic-and-pedestrian-behaviour)
- [__Manual package preparation__](#manual-package-preparation)
---
## RoadRunner plugin import
The RoadRunner software from MathWorks provides plugins for Unreal Engine to help ease the import process of maps into CARLA.
#### Plugin installation
__1.__ The plugins are available for download from the [MathWorks website](https://www.mathworks.com/help/roadrunner/ug/Downloading-Plugins.html). MathWorks also has a [full tutorial](https://www.mathworks.com/help/roadrunner/ug/Exporting-to-CARLA.html), similar to this one, on how to import maps to CARLA using the plugins.
__2.__ Extract the contents of the downloaded folder and move the folders `RoadRunnerImporter`, `RoadRunnerCarlaIntegration` and `RoadRunnerMaterials` to `<carla>/Unreal/CarlaUE4/Plugins/`.
__3.__ Rebuild the plugin following the instructions below:
* __On Windows.__
* Right-click the `.uproject` file in `<carla>/Unreal/CarlaUE4` and select `Generate Visual Studio project files`.
* In the root folder of CARLA, run the command:
```sh
make launch
```
* __On Linux.__
* Run the following command:
```sh
UE4_ROOT/GenerateProjectFiles.sh -project="carla/Unreal/CarlaUE4/CarlaUE4.uproject" -game -engine
```
__4.__ In the Unreal Engine window, make sure the checkbox is selected for both plugins `Edit > Plugins`.
![rr_ue_plugins](../img/rr-ue4_plugins.jpg)
### Import map
__1.__ Import the `<mapName>.fbx` file to a new folder under `/Content/Carla/Maps` with the `Import` button.
![ue_import](../img/ue_import_mapname.jpg)
__2.__ Set `Scene > Hierarchy Type` to _Create One Blueprint Asset_ (selected by default).
__3.__ Set `Static Meshes > Normal Import Method` to _Import Normals_.
![ue_import_options](../img/ue_import_options.jpg)
__4.__ Click `Import`.
__5.__ Save the current level `File` -> `Save Current As...` -> `<mapname>`.
The new map should now appear next to the others in the Unreal Engine _Content Browser_.
![ue_level_content](../img/ue_level_content.jpg)
</details>
!!! Note
The tags for semantic segmentation will be assigned according to the name of the asset. The asset will be moved to the corresponding folder in `Content/Carla/PackageName/Static`. To change these, move them manually after importing.
__6.__ The pedestrian navigation will still need to be generated. See the section ["Add pedestrian navigation"](#add-pedestrian-navigation) for more information.
---
## Manual import
This method of importing maps can be used with generic `.fbx` and `.xodr` files. If you are using RoadRunner, you should use the export method `Firebox (.fbx)`, `OpenDRIVE (.xodr)` or `Unreal (.fbx + .xml)`. Do not use the `Carla Exporter` option because you will run into compatibility issues with the `.fbx` file.
To import a map manually to Unreal Engine:
__1.__ In your system's file explorer, copy the `.xodr` file to `<carla-root>/Unreal/CarlaUE4/Content/Carla/Maps/OpenDrive`.
__2.__ Open the Unreal Engine editor by running `make launch` in the carla root directory. In the _Content Browser_ of the editor, navigate to `Content/Carla/Maps/BaseMap` and duplicate the `BaseMap`. This will provide a blank map with the default sky and lighting objects.
>>![ue_duplicate_basemap](../img/ue_duplicate_basemap.png)
__3.__ Create a new folder with the name of your map package in the `Content/Carla/Maps` directory and save the duplicated map there with the same name as your `.fbx` and `.xodr` files.
__4.__ In the _Content Browser_ of the Unreal Engine editor, navigate back to `Content/Carla/Maps`. Right click in the grey area and select `Import to /Game/Carla/Maps...` under the heading _Import Asset_.
>>![ue_import_asset](../img/ue_import_asset.png)
__5.__ In the configuration window that pops up, make sure:
>- These options are unchecked:
* Auto Generate Collision
* Combine Meshes
* Force Front xAxis
- In the following drop downs, the corresponding options are selected:
* Normal Import Method - _Import Normals_
* Material Import Method - _Create New Materials_
- These options are checked:
* Convert Scene Unit
* Import Textures
>>![ue_import_file](../img/ue_import_file.jpg)
__6.__ Click `Import`.
__7.__ The meshes will appear in the _Content Browser_. Select the meshes and drag them into the scene.
>>![ue_meshes](../img/ue_drag_meshes.jpg)
__8.__ Center the meshes at 0,0,0.
>>![Transform_Map](../img/transform.jpg)
__9.__ In the _Content Browser_, select all the meshes that need to have colliders. This refers to any meshes that will interact with pedestrians or vehicles. The colliders prevent them from falling into the abyss. Right-click the selected meshes and select `Asset Actions > Bulk Edit via Property Matrix...`.
>>![ue_selectmesh_collision](../img/ue_selectmesh_collision.jpg)
__10.__ Search for _collision_ in the search box.
__11.__ Change `Collision Complexity` from `Project Default` to `Use Complex Collision As Simple` and close the window.
>>![ue_collision_complexity](../img/ue_collision_complexity.jpg)
__12.__ Confirm the collision setting has been applied correctly by pressing `Alt + c`. You will see a black web over the meshes.
__13.__ To create the ground truth for the semantic segmentation sensor, move the static meshes to the corresponding `Carla/Static/<segment>` folder following the structure below:
Content
└── Carla
├── Blueprints
├── Config
├── Exported Maps
├── HDMaps
├── Maps
└── Static
├── Terrain
│ └── mapname
│ └── Static Meshes
│
├── Road
│ └── mapname
│ └── Static Meshes
│
├── RoadLines
| └── mapname
| └── Static Meshes
└── Sidewalks
└── mapname
└── Static Meshes
__14.__ In the _Modes_ panel, search for the __Open Drive Actor__ and drag it into the scene.
>>![ue_opendrive_actor](../img/ue_opendrive_actor.jpg)
__15.__ In the _Details_ panel, check `Add Spawners` and then click on the box beside `Generate Routes`. This will find the `.xodr` file with the same map name in the `<carla-root>/Unreal/CarlaUE4/Content/Carla/Maps/OpenDrive` directory and use it to generate a series of _RoutePlanner_ and _VehicleSpawnPoint_ actors.
>>![ue_generate_routes](../img/ue_generate_routes.png)
__18.__ To add pedestrian navigation capabilities, see the section [Add pedestrian navigation](#add-pedestrian-navigation).
__17.__ Save your map and press _Play_ to run a simulation on your new map.
#### Traffic lights and signs
To add traffic lights and signs to your new map:
__1.__ From the _Content Browser_, navigate to `Content/Carla/Static` to find the folders that contain traffic lights and traffic signs.
__2.__ Drag the signs and/or lights into the scene.
__3.__ Adjust the [`trigger volume`][triggerlink] for each of them by selecting the _BoxTrigger_ component and adjusting the values of _Scale_ in the _Transform_ section of the _Details_ menu. This will determine their area of influence.
>>![ue_trafficlight](../img/ue_trafficlight.jpg)
__4.__ For junctions, drag a traffic light group actor into the level. Assign all the traffic lights involved to it and configure their timing. Make sure to understand [how traffic lights work](../core_actors.md#traffic-signs-and-traffic-lights).
>>![ue_tl_group](../img/ue_tl_group.jpg)
__5.__ Test traffic light timing and traffic trigger volumes. This may require some trial and error to get right.
>>![ue_tlsigns_example](../img/ue_tlsigns_example.jpg)
> _Example: Traffic Signs, Traffic lights and Turn based stop._
[triggerlink]: ../python_api.md#carla.TrafficSign.trigger_volume
#### Add pedestrian navigation
To allow pedestrians to navigate the new map, you will need to generate a pedestrian navigation file. Follow the steps below to generate the file:
__1.__ Generate new crosswalks if needed. Avoid doing this if the crosswalk is already defined in the `.xodr` file as this will lead to duplication:
- Create a plane mesh that extends a bit over two sidewalks that you want to connect.
- Place the mesh overlapping the ground and disable it's physics and rendering.
>>![disable_rendering](../img/disable_rendering.png)
- Change the name of the mesh to `Road_Crosswalk` or `Roads_Crosswalk`.
__2.__ To prevent the map being too large to export, select the __BP_Sky object__ and add a tag `NoExport` to it. If you have any other particularly large meshes that are not involved in the pedestrian navigation, add the `NoExport` tag to them as well.
>>![ue_skybox_no_export](../img/ue_noexport.png)
__3.__ Double check your mesh names. Mesh names should start with any of the appropriate formats listed below in order to be recognized as areas where pedestrians can walk. By default, pedestrians will be able to walk over sidewalks, crosswalks, and grass (with minor influence over the rest):
* Sidewalk = `Road_Sidewalk` or `Roads_Sidewalk`
* Crosswalk = `Road_Crosswalk` or `Roads_Crosswalk`
* Grass = `Road_Grass` or `Roads_Grass`
>>![ue_meshes](../img/ue_meshes.jpg)
__4.__ Press `ctrl + A` to select everything and export the map by selecting `File` -> `Carla Exporter`. A `<mapName>.obj` file will be created in `Unreal/CarlaUE4/Saved`.
__5.__ Copy the `<mapName>.obj` and the `<mapName>.xodr` to `Util/DockerUtils/dist`.
__6.__ Run the following command to generate the navigation file:
* __Windows__
```sh
build.bat <mapName> # <mapName> has no extension
```
* __Linux__
```sh
./build.sh <mapName> # <mapName> has no extension
```
__7.__ A `<mapName>.bin` file will be created. This file contains the information for pedestrian navigation on your map. Move this file to the `Nav` folder of the package that contains your map.
---
## Manual package preparation
A map package needs to follow a certain folder structure and must contain a `.json` file describing that folder structure. These steps can be saved under certain circumstances, but doing it manually will always work.
#### Create the folder structure
__1. Create a folder inside `carla/Import`.__ The name of the folder is not important.
__2. Create different subfolders__ for each map to be imported.
__3. Move the files of each map to the corresponding subfolder.__ A subfolder will contain a specific set of elements:
* The mesh of the map in a `.fbx` file.
* The OpenDRIVE definition in a `.xodr` file.
* Optionally, the textures required by the asset.
For instance, an `Import` folder with one package containing two maps should have a structure similar to the one below.
```sh
Import
│
└── Package01
├── Package01.json
├── Map01
│ ├── Asphalt1_Diff.jpg
│ ├── Asphalt1_Norm.jpg
│ ├── Asphalt1_Spec.jpg
│ ├── Grass1_Diff.jpg
│ ├── Grass1_Norm.jpg
│ ├── Grass1_Spec.jpg
│ ├── LaneMarking1_Diff.jpg
│ ├── LaneMarking1_Norm.jpg
│ ├── LaneMarking1_Spec.jpg
│ ├── Map01.fbx
│ └── Map01.xodr
└── Map02
└── Map02.fbx
```
#### Create the JSON description
Create a `.json` file in the root folder of the package. Name the file after the package. Note that this will be the distribution name. The content of the file will describe a JSON array of __maps__ and __props__ with basic information for each of them.
__Maps__ need the following parameters:
* __name__ of the map. This must be the same as the `.fbx` and `.xodr` files.
* __source__ path to the `.fbx` file.
* __use_carla_materials__. If __True__, the map will use CARLA materials. Otherwise, it will use RoadRunner materials.
* __xodr__ Path to the `.xodr` file.
__Props__ are not part of this tutorial. The field will be left empty. There is another tutorial on how to [add new props](../tuto_A_add_props.md).
The resulting `.json` file should resemble the following:
```json
{
"maps": [
{
"name": "Map01",
"source": "./Map01/Map01.fbx",
"use_carla_materials": true,
"xodr": "./Map01/Map01.xodr"
},
{
"name": "Map02",
"source": "./Map02/Map02.fbx",
"use_carla_materials": false,
"xodr": "./Map02/Map02.xodr"
}
],
"props": [
]
}
```
</details>
<br>
---
It is recommended to use the automated processes for importing maps detailed in the guides for [CARLA packages](add_map_package.md) and [CARLA source build](add_map_source.md), however the methods listed in this section can be used if required. If you encounter any issues with the alternative methods, feel free to post in the [forum](https://forum.carla.org/).

77
Docs/tuto_A_add_map/add_map_package.md Normal file
View File

@ -0,0 +1,77 @@
# Ingesting Maps in a CARLA package
This section describes the process of ingesting maps into __a package (binary) version of CARLA__. If you are using a version of CARLA that has been built from source to ingest maps then follow the guidelines [here][source_ingest] instead.
This process is only available for Linux systems. The import process involves running a Docker image of Unreal Engine to import the relevant files and then export them as a standalone package which can then be configured to be used in CARLA. The Docker image takes around 4h and 600-700 GB to be built. This is only needed the first time the image is built.
- [__Before you begin__](#before-you-begin)
- [__Map ingestion in a CARLA package__](#map-ingestion-in-a-carla-package)
---
## Before you begin
- You will need to fulfill the following system requirements:
- 64-bit version of [Docker](https://docs.docker.com/engine/install/) in Ubuntu 16.04+
- Minimum 8GB of RAM
- Minimum 600 GB available disk space for building container images
- [Git](https://git-scm.com/downloads) version control
- Ensure you are using a package (binary) version of CARLA. If you are using a version of CARLA that has been built from source to ingest maps then follow the guidelines [here][source_ingest] instead.
- You should have at least two files, `<mapName>.xodr` and `<mapName>.fbx` that have been [generated][rr_generate_map] from a map editor such as RoadRunner.
- These files should have the same value for `<mapName>` in order to be recognised as the same map.
[source_ingest]: add_map_source.md
[import_map_package]: add_map_package.md
[rr_generate_map]: generate_map_roadrunner.md
---
## Map ingestion in a CARLA package
__1.__ CARLA provides all the utilities to build Unreal Engine in a Docker image and to compile CARLA using that image. The tools are found in the source code available in GitHub. Clone the repository using the following command:
```sh
git clone https://github.com/carla-simulator/carla
```
__2.__ Build the Docker image of Unreal Engine by following [these instructions](https://github.com/carla-simulator/carla/tree/master/Util/Docker).
__3.__ Create an `input_folder`. This is where you will put the files to be imported. Docker will automatically create a `.json` file describing the package folder structure. Change permissions on the `input_folder` for this to be created successfully:
```sh
#Go to the parent folder, where the input folder is contained
chmod 777 input_folder
```
> !!! Note
This is not necessary if the package is [prepared manually](add_map_deprecated.md#manual-package-preparation), and contains a `.json` file already.
__4.__ Create an `output_folder`. This is where the Docker image will write the output files after it has cooked the map.
__5.__ Navigate to `~/carla/Util/Docker`. This is where the ingestion script is located. The script requires the path for the `input_folder` and `output_folder` and the name of the package to be ingested. If a `.json` file is provided, the name of that file is the package name, if no `.json` is provided, the name must be `map_package`:
```sh
python3 docker_tools.py --input ~/path_to_input_folder --output ~/path_to_output_folder --packages map_package
```
> !!! Warning
If the argument `--packages map_package` is not provided, the Docker image will make a package of CARLA.
__6.__ The package will be generated in the `output_folder` as `<map_package>.tar.gz`. This is the standalone package that is now ready to be imported into CARLA. Move the package to the `Import` folder in the CARLA root directory (of the package/binary version where you will be using the map), and run the following script from the root directory to import it:
```sh
./ImportAssets.sh
```
__7.__ To run a simulation with the new map, run CARLA and then change the map using the `config.py` file:
```sh
cd PythonAPI/util
python3 config.py --map <mapName>
```
<br>
---
Your map is now ready to run simulations in CARLA. If you have any questions about the process then you can ask in the [forum](https://forum.carla.org/) or you can try running some of our [example scripts](https://github.com/carla-simulator/carla/tree/master/PythonAPI/examples) on your new map to test it out.

92
Docs/tuto_A_add_map/add_map_source.md Normal file
View File

@ -0,0 +1,92 @@
# Ingesting Maps in CARLA Built From Source
This section describes the process of ingesting maps into __CARLA that has been built from source__. If you are using a package (binary) version of CARLA to ingest maps then follow the guidelines [here][package_ingest] instead.
The ingestion process involves importing the relevant map files by compiling them into a package. This package can then be opened in the Unreal Engine editor and customized before generating the pedestrian navigation file and finally adding it to the package.
[package_ingest]: add_map_package.md
- [__Before you begin__](#before-you-begin)
- [__Map ingestion__](#map-ingestion)
- [Customize the map](#customize-the-map)
- [Generate pedestrian navigation](#generate-pedestrian-navigation)
---
## Before you begin
- Ensure you are using a version of CARLA that has been built from source. If you are using a packaged (binary) version of CARLA then follow the tutorial [here][import_map_package].
- You should have at least two files, `<mapName>.xodr` and `<mapName>.fbx` that have been [generated][rr_generate_map] from a map editor such as RoadRunner.
- These files should have the same value for `<mapName>` in order to be recognised as the same map.
- You can ingest multiple maps into the same package. Each map should have a unique name.
[import_map_package]: add_map_package.md
[rr_generate_map]: generate_map_roadrunner.md
---
## Map ingestion
__1.__ Place the map files to be imported in the `Import` folder found in the CARLA root directory.
__2.__ Run the command below to ingest the files:
```sh
make import ARGS="--package <package_name> --no-carla-materials"
```
__Note that there are two parameter flags that can be set__:
- `--package <package_name>` specifies the name of the package. By default, this is set to `map_package`. Two packages cannot have the same name, so using the default value will lead to errors on a subsequent ingestion. __It is highly recommended to change the name of the package__.
- `--no-carla-materials` specifies that you do not want to use the default CARLA materials (road textures etc). You will use the RoadRunner materials instead. This flag is only required if you are not providing your own [`.json` file](../tuto_A_add_map_overview.md#ingest-the-map-in-carla). Any value in the `.json` file will override this flag.
### Customize the map
Before generating the pedestrian navigation, you may want to customize the map in the editor. Props such as trees, streetlights or grass zones can be added. Customization should be completed before generating the pedestrian navigation in order to avoid interference or collisions between the two, resulting in the need to generate the pedestrian navigation a second time.
* __Create new spawning points__. These spawning points will be used in scripts such as [`spawn_npc.py`](https://github.com/carla-simulator/carla/blob/master/PythonAPI/examples/spawn_npc.py):
- In the editor, go to the `Modes` panel and search for "spawn" in the `Search Classes` search bar.
- Choose the type of spawning point you would like to create and drag it on to the map.
- Place the spawn point about 0.5-1m above the ground to prevent collisions with the road.
* __Generate new crosswalks__. Avoid doing this if the crosswalk is already defined the `.xodr` file as this will lead to duplication:
- Create a plane mesh that extends a bit over two sidewalks that you want to connect.
- Place the mesh overlapping the ground and disable it's physics and rendering.
- Change the name of the mesh to `Road_Crosswalk` or `Roads_Crosswalk`.
![ue_crosswalks](../img/ue_crosswalks.jpg)
### Generate pedestrian navigation
__1.__ To prevent the map being too large to export, select the __BP_Sky object__ and add a tag `NoExport` to it. If you have any other particularly large meshes that are not involved in the pedestrian navigation, add the `NoExport` tag to them as well.
![ue_skybox_no_export](../img/ue_noexport.png)
__2.__ Double check your mesh names. Mesh names should start with any of the appropriate formats listed below in order to be recognized as areas where pedestrians can walk. By default, pedestrians will be able to walk over sidewalks, crosswalks, and grass (with minor influence over the rest):
* Sidewalk = `Road_Sidewalk` or `Roads_Sidewalk`
* Crosswalk = `Road_Crosswalk` or `Roads_Crosswalk`
* Grass = `Road_Grass` or `Roads_Grass`
![ue_meshes](../img/ue_meshes.jpg)
__3.__ Press `ctrl + A` to select everything and export the map by selecting `File` -> `Carla Exporter`. A `<mapName>.obj` file will be created in `Unreal/CarlaUE4/Saved`.
__4.__ Move the `<mapName>.obj` and the `<mapName>.xodr` to `Util/DockerUtils/dist`.
__5.__ Run the following command to generate the navigation file:
* __Windows__
```sh
build.bat <mapName> # <mapName> has no extension
```
* __Linux__
```sh
./build.sh <mapName> # <mapName> has no extension
```
__6.__ A `<mapName>.bin` file will be created. This file contains the information for pedestrian navigation on your map. Move this file to the `Nav` folder of the package that contains the map.
---
Your map is now ready to run simulations in CARLA. If you have any questions about the process then you can ask in the [forum](https://forum.carla.org/) or you can try running some of our [example scripts](https://github.com/carla-simulator/carla/tree/master/PythonAPI/examples) on your new map to test it out.

84
Docs/tuto_A_add_map/generate_map_roadrunner.md Normal file
View File

@ -0,0 +1,84 @@
# Generating Maps in RoadRunner
RoadRunner is the recommended software to create maps to be imported into CARLA. This guide will give an outline of what RoadRunner is and how to export customs maps that are ready for importing into CARLA.
- [__Introduction to Roadrunner__](#introduction-to-roadrunner)
- [__Before you start__](#before-you-start)
- [__Export a map in RoadRunner__](#export-a-map-in-roadrunner)
- [__Next steps__](#next-steps)
---
## Introduction to RoadRunner
RoadRunner is an interactive editor that lets you design 3D scenes for simulating and testing automated driving systems. You can customize roadway scenes by creating region-specific road signs and markings. You can insert signs, signals, guardrails, and road damage, as well as foliage, buildings, and other 3D models. RoadRunner provides tools for setting and configuring traffic signal timing, phases, and vehicle paths at intersections. the Asset Library lets you quickly populate your 3D scenes with a large set of realistic and visually consistent 3D models.
RoadRunner is part of the MATLAB Campus Wide Licenses, so many universities can provide unlimited academic access. [Check][rr_eligibility] if your university has access. Reach out to *automated-driving@mathworks.com* for any questions or troubles regarding accessibility. There is also a [trial version][rr_trial_version] available.
[rr_trial_version]: https://www.mathworks.com/products/roadrunner.html
[rr_eligibility]: https://www.mathworks.com/academia/tah-support-program/eligibility.html
---
## Before you start
__1.__ Install RoadRunner. You can follow the [installation guide][rr_docs] at the Mathworks website.
[rr_docs]: https://www.mathworks.com/help/roadrunner/ug/install-and-activate-roadrunner.html
---
## Export a map in RoadRunner
!!! Note
The specifics of how to build a map in RoadRunner go beyond the scope of this guide, however there are video tutorials available in the [RoadRunner documentation][rr_tutorials].
[rr_tutorials]: https://www.mathworks.com/support/search.html?fq=asset_type_name:video%20category:roadrunner/index&page=1&s_tid=CRUX_topnav
Below is a guideline to export your custom map from RoadRunner. You can find more detailed information about how to export to CARLA in [MathWorks' documentation][exportlink].
[exportlink]: https://www.mathworks.com/help/roadrunner/ug/Exporting-to-CARLA.html
Once you have made your map in Roadrunner you will be able to export it. Be aware that __the map cannot be modified after it has been exported.__ Before exporting, ensure that:
- The map is centered at (0,0) to ensure the map can be visualized correctly in Unreal Engine.
- The map definition is correct.
- The map validation is correct, paying close attention to connections and geometries.
![CheckGeometry](../img/check_geometry.jpg)
Once the map is ready, click on the `OpenDRIVE Preview Tool` button to visualize the OpenDRIVE road network and give everything one last check.
![checkopen](../img/check_open.jpg)
!!! note
_OpenDrive Preview Tool_ makes it easier to test the integrity of the map. If there are any errors with junctions, click on `Maneuver Tool`, and `Rebuild Maneuver Roads`.
__1.__ Export the scene using the CARLA option:
- In the main toolbar, select `File` -> `Export` -> `CARLA (.fbx, .xodr, .rrdata.xml)`
__2.__ Check the following options:
- Split by Segmentation: Divides the mesh by semantic segmentation.
- Power of Two Texture Dimensions: Improves performance.
- Embed Textures: Ensures textures are embedded in the mesh.
- Export to Tiles: Choose the size of the tile or leave unchecked for only one piece.
Leave unchecked:
- `Export Individual Tiles`: Generates one `.fbx` file with all map pieces.
![roadrunner_export](/img/roadrunner_export.png)
__3.__ Chose the directory where you want to export your files and click `Export`. This will generate `<mapName>.fbx` and `<mapName>.xodr` files among others.
!!! Warning
Make sure that the `.xodr` and the `.fbx` files have the same name.
---
## Next steps
You are now ready to import your map into CARLA. The next step will depend upon the kind of CARLA installation you are using:
* __For users of CARLA built from source__, follow the guide [__here__](add_map_source.md).
* __For users of a packaged (binary) version of CARLA__, follow the guide [__here__](add_map_package.md).

59
Docs/tuto_A_add_map_overview.md Normal file
View File

@ -0,0 +1,59 @@
# Add a new map
Users of CARLA can create custom maps and use them to run simulations. There are several ways to import custom maps in CARLA. The method to be used will depend on if the map is destined to be used in a packaged version of CARLA or in a version built from source. This section serves as a guide to direct you to the correct method.
- [__Overview__](#overview)
- [Export from RoadRunner](#export-from-roadrunner)
- [Ingest the map in CARLA](#ingest-the-map-in-carla)
- [__Alternative import methods__](#alternative-import-methods)
- [__Summary__](#summary)
---
## Overview
Follow the links to go directly to the relevant guide or read on futher for a brief summary of the steps involved in the ingestion process:
1. [__Export from RoadRunner__](tuto_A_add_map/generate_map_roadrunner.md)
2. [__Import into source build version of CARLA__](tuto_A_add_map/add_map_source.md)
3. [__Import into package version of CARLA__](tuto_A_add_map/add_map_package.md)
4. [__Alternative methods to import maps__](tuto_A_add_map/add_map_alternative.md)
You can also watch the following video to see an explanation of the various methods:
<iframe width="560" height="315" src="https://www.youtube.com/embed/mHiUUZ4xC9o" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<br>
### Export from RoadRunner
RoadRunner is the recommended software to create a map due to its simplicity. We provide a [__guide__](tuto_A_add_map/generate_map_roadrunner.md) on how to export maps made in RoadRunner so they are ready for import into CARLA.
### Ingest the map in CARLA
This is where the route splits in two:
- __If you are using CARLA built from source__, follow the guide [__here__](tuto_A_add_map/add_map_source.md).
- __If you are using a packaged (binary) version of CARLA__, follow the guide [__here__](tuto_A_add_map/add_map_package.md).
Regardless of the method used, there are some common themes involved in the ingestion process:
- __Package `.json` file and folder structure__. Map packages have a particular folder structure and this structure is described in a `.json` file. This file is automatically created during the import process if it is not provided by the user. If you prefer to provide the `.json` file yourself, check the [alternative methods guide](tuto_A_add_map/add_map_alternative.md#manual-package-preparation) for an outline on how to do this.
- __Traffic signs and traffic lights.__ The simulator will generate the traffic lights, stops and yields automatically when running. These will be created according to their `.xodr` definition. Any other landmarks present in the map will not be physically on scene, but they can be queried using the API.
* __Pedestrian navigation.__ The ingestion process will generate a `.bin` file describing the pedestrian navigation. It is based on the sidewalks and crosswalks that appear in the `.xodr` definition. This can only be modified if working in a build from source.
### Alternative import methods
We provide a section that details alternative methods of importing maps to CARLA that involve the use of plugins or performing each step manually. You will find those methods [here](tuto_A_add_map/add_map_alternative.md).
---
## Summary
If you have any questions about the process to create and import a new map into CARLA, feel free to post these in the [forum](https://forum.carla.org/).
<div class="build-buttons">
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

2
Docs/tuto_A_add_props.md
View File

@ -45,7 +45,7 @@ Import
Create a `.json` file in the root folder of the package. Name the file after the package. Note that this will be the distribution name. The content of the file will describe a JSON array of __maps__ and __props__ with basic information for each of them.
__Maps__ are not part of this tutorial, so this definition will be empty. There is a specific tutorial to [__add a new map__](tuto_A_add_map.md).
__Maps__ are not part of this tutorial, so this definition will be empty. There is a specific tutorial to [__add a new map__](tuto_A_add_map_overview.md).
__Props__ need the following parameters.

4
Docs/tuto_A_create_standalone.md
View File

@ -19,7 +19,7 @@ make package ARGS="--packages=Package1,Package2"
This will create a standalone package compressed in a `.tar.gz` file for each of the packages listed. The files will be saved in `Dist` folder on Linux, and `/Build/UE4Carla/` on Windows.
!!! Note
As an alternative, the [Docker method](tuto_A_add_map.md#via-docker) will create the standalone package without the need of having Unreal Engine in the system.
As an alternative, the [Docker method](tuto_A_add_map/add_map_package.md) will create the standalone package without the need of having Unreal Engine in the system.
---
## Import assets into a CARLA package
@ -35,7 +35,7 @@ cd Import
```
!!! Note
Standalone packages cannot be directly imported into a CARLA build. Follow the tutorials to import [props](tuto_A_add_props.md), [maps](tuto_A_add_map.md) or [vehicles](tuto_A_add_vehicle.md).
Standalone packages cannot be directly imported into a CARLA build. Follow the tutorials to import [props](tuto_A_add_props.md), [maps](tuto_A_add_map_overview.md) or [vehicles](tuto_A_add_vehicle.md).
---

2
Docs/tuto_A_map_customization.md
View File

@ -29,7 +29,7 @@ There are differences between them, that make them fit specific purposes. Howeve
* __Customize the pattern__. This is where the blueprints present differences between each other.
!!! Warning
New props will probably interfere with the mesh navigation. If necessary, rebuild that as explained [here](tuto_A_add_map.md#generate-pedestrian-navigation) after doing these changes.
New props will probably interfere with the mesh navigation. If necessary, rebuild that as explained [here](tuto_A_add_map/add_map_source.md#generate-pedestrian-navigation) after doing these changes.
### BP_RepSpline

2
mkdocs.yml
View File

@ -55,7 +55,7 @@ nav:
- 'RLlib Integration': "tuto_G_rllib_integration.md"
- 'Scenic': 'tuto_G_scenic.md'
- Tutorials (assets):
- 'Add a new map': 'tuto_A_add_map.md'
- 'Add a new map': 'tuto_A_add_map_overview.md'
- 'Add a new vehicle': 'tuto_A_add_vehicle.md'
- 'Add new props': 'tuto_A_add_props.md'
- 'Create standalone packages': 'tuto_A_create_standalone.md'