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

sergi-e/asset-import (#2690) 

* First draft

* First iteration B comments

* Added bottom links to forum

* Intermediate iteration

* middle iteration

* Idle iteration

* New draft with separated tutorials

* Links fixed.

* New recast executable described

* Fixed spacing

* Last iteration B comments

* New iteration with auto json

* New modifications on B PR

* New iteration with ped. nav.

* New iteration on B final review
This commit is contained in:
sergi.e 2020-04-15 01:55:18 +02:00 committed by GitHub
parent 4d448fc49c
commit 8ebb8a12a1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 864 additions and 721 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Docs/core_map.md
View File

@ -153,7 +153,7 @@ info_map = map.to_opendrive()
So far there are seven different maps available. Each one has unique features and is useful for different purposes. Hereunder is a brief sum up on them.
!!! Note
Users can [customize a map](tuto_A_map_customization.md) or even [create a new map](tuto_A_map_creation.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.md) to be used in CARLA.
<table class ="defTable">
<thead>

14
Docs/index.md
View File

@ -110,14 +110,16 @@ CARLA forum</a>
## Tutorials — Assets
<p style="padding-left:30px;line-height:1.8">
[__Import new assets__](tuto_A_import_assets.md)
— Use personal assets in CARLA.
[__Map creation__](tuto_A_map_creation.md)
— Create a new map following simple guidelines.
[__Add a new map__](tuto_A_add_map.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.
[__Map customization__](tuto_A_map_customization.md)
— Edit an existing map.
[__Standalone asset packages__](tuto_A_standalone_packages.md)
— Import assets into UE and set them for package distribution.
[__Use Epic's Automotive materials__](tuto_A_epic_automotive_materials.md)
— Apply Epic's set of Automotive materials to vehicles.
[__Vehicle modelling__](tuto_A_vehicle_modelling.md)

14
Docs/start_quickstart.md
View File

@ -5,6 +5,7 @@
* __[CARLA installation](#carla-installation)__
* a) deb CARLA installation
* b) GitHub repository installation
* __[Import additional assets](#import-addditional-assets)__
* __[Running CARLA](#running-carla)__
* Command-line options
* __[Updating CARLA](#updating-carla)__
@ -110,16 +111,23 @@ cd /opt/carla/bin
The repository contains the different versions of the simulator available. _Development_ and _stable_ sections list the packages for the different official releases. The later the version the more experimental it is. The _nightly build_ is the current development version as today and so, the most unstable.
There may be many files per release. The package is a compressed file named as __CARLA_version.number__. Other elements such as __Town06_0.9.5.tar.gz__ are additional assets.
There may be many files per release. The package is a compressed file named as __CARLA_version.number__. Other elements such as __Town06_0.9.5.tar.gz__ are additional maps.
Download and extract the release file. It contains a precompiled version of the simulator, the Python API module and some scripts to be used as examples.
Move any additional assets to the _Import_ folder in the release and extract them. The script _ImportAssets_ in the main CARLA folder should extract these automatically.
Download and extract the release file. It contains a precompiled version of the simulator, the Python API module and some scripts to be used as examples.
---
## Import additional assets
Additional assets are distributed in CARLA under a compressed package file. For instance, some releases come with [__additional maps__](https://github.com/carla-simulator/carla/blob/master/Docs/download.md) as mentioned previously. In order to use them in CARLA, download and move the package to the _Import_ folder, and run the following script to extract them.
```sh
> cd ~/carla
> ./ImportAssets.sh
```
!!! Note
On Windows, directly extract the package on the root folder.
---
## Running CARLA

529
Docs/tuto_A_add_map.md Normal file
View File

@ -0,0 +1,529 @@
# 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. There is a trial version available at their [site](https://www.vectorzero.io/), 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
python 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 are some optional steps that can be done before that.
* __Create new spawning points.__ These will be used in scripts such as `spawn_npc.py`. Place the spawning point 2 to 3 meters above the ground, and a Route Planner's trigger box below it. Orient both in the same direction. When the vehicle falls into the trigger box, the autopilot will be enabled, and the vehicle will be registered to a Traffic Manager.
![ue_vehicle_spawnpoint](img/ue_vehicle_spawnpoint.png)
* __Add the map to the Unreal packaging system.__ This will include the map along with the rest if a CARLA package is created.
`Edit > Project Settings > Project > Packaging > Show Advanced > List of maps to include...` <br>
![ue_maps_to_include](img/ue_maps_to_include.png)
### 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.png)
* __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.png)
__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).
If no `.json` is provided, the name must be `map_package`
If you don't have a .json then you don't need to specify a name unless you want to change the default map_package name. That is what I was intending to say, sorry.
* Sidewalk = `Road_Sidewalk`.
* Grass = `Road_Grass`.
![ue_meshes](img/ue_meshes.png)
__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`. There are several scripts there that are going to be used.
__6.__ Run the following script to extract the crosswalks from the OpenDRIVE. This will create a `crosswalks.obj`.
``` sh
python get_xodr_crosswalks.py -f map_file.xodr
```
__7.__ Combine `map_file.obj` and `crosswalks.obj` running the following script. After that, the `map_file.obj` should contain both.
```sh
python addOBJ.py map_file.obj crosswalks.obj
```
__8.__ Create the file describing the pedestrian navigation. A `.bin` will be generated in `Util/DockerUtils/Dist`.
```sh
./RecastBuilder.sh map_file.obj
```
__9.__ 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.png
│ ├── Asphalt1_Norm.png
│ ├── Asphalt1_Spec.png
│ ├── Grass1_Diff.png
│ ├── Grass1_Norm.png
│ ├── Grass1_Spec.png
│ ├── LaneMarking1_Diff.png
│ ├── LaneMarking1_Norm.png
│ ├── LaneMarking1_Spec.png
│ ├── 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.png)
### 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.png)
__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.png)
__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.png)
</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.png)
### 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.png)
__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.png)
__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.png)
* 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.png)
* 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.png)
### 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.png)
</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.png)
__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.png)
__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.png)
> _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.png)
__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.png)
__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.png)
__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.png)
__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>

161
Docs/tuto_A_add_props.md Normal file
View File

@ -0,0 +1,161 @@
# Add new props
Props are the assets that populate the scene, besides the map, and the vehicles. That includes streetlights, buildings, trees, and much more. The simulator can ingest new props anytime in a simple process. This is really useful to create customized environments in a map.
* [__Prepare the package__](#prepare-the-package)
* [Create the folder structure](#create-the-folder-structure)
* [Create the JSON description](#create-the-json-description)
* [__Ingestion in a CARLA package__](#ingestion-in-a-carla-package)
* [__Ingestion in a build from source__](#ingestion-in-a-build-from-source)
---
## Prepare the package
### Create the folder structure
__1. Create a folder inside `carla/Import`.__ The name of the folder is not relevant.
__2. Create the subfolders.__ There should be one general subfolder for all the props, and inside of it, as many subfolders as props to import.
__3. Move the files of each prop to the corresponding subfolder.__ A prop subfolder will contain the `.fbx` mesh, and optionally, the textures required by it.
For instance, an `Import` folder with two separate packages should have a structure similar to the one below.
```sh
Import
│
├── Package01
│ ├── Package01.json
│ └── Props
│ ├── Prop01
│ │ ├── Prop01_Diff.png
│ │ ├── Prop01_Norm.png
│ │ ├── Prop01_Spec.png
│ │ └── Prop01.fbx
│ └── Prop02
│ └── Prop02.fbx
└── Package02
├── Packag02.json
└── Props
└── Prop03
└── Prop03.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__ 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).
__Props__ need the following parameters.
* __name__ of the prop. This must be the same as the `.fbx`.
* __source__ path to the `.fbx`.
* __size__ estimation of the prop. The possible values are listed here.
* `tiny`
* `small`
* `medium`
* `big`
* `huge`
* __tag__ value for the semantic segmentation. If the tag is misspelled, it will be read as `None`.
* `None`
* `Buildings`
* `Fences`
* `Pedestrians`
* `Pole`
* `Props`
* `RailTrack`
* `Road`
* `RoadLines`
* `Sidewalk`
* `Terrain`
* `TrafficSigns`
* `Vegetation`
* `Vehicles`
* `Walls`
In the end, the `.json` should look similar to the one below.
```json
{
"maps": [
],
"props": [
{
"name": "MyProp01",
"size": "medium",
"source": "./Props/Prop01/Prop01.fbx",
"tag": "SemanticSegmentationTag01"
},
{
"name": "MyProp02",
"size": "small",
"source": "./Props/Prop02/Prop02.fbx",
"tag": "SemanticSegmentationTag02"
}
]
}
```
!!! Warning
Packages with the same name will produce an error.
---
## Ingestion in a CARLA package
This is the method used to ingest the props into a CARLA package such as CARLA 0.9.8.
A Docker image of Unreal Engine will be created. It acts as a black box that automatically imports the package into the CARLA image, and generates a ditribution 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. Run the script to cook the props.__ 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.
```sh
python docker_tools.py --input ~/path_to_package --output ~/path_for_output_assets --package=Package01
```
__3. Locate the package__. The Docker should have generated the package `Package01.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
```
!!! Note
There is an alternative on Linux. Move the package to the `Import` folder and run the script `Util/ImportAssets.sh` to extract the package.
---
## Ingestion in a build from source
This is the method to import the props into a CARLA build from source.
The JSON file will be read to place the props inside the `Content` in Unreal Engine. Furthermore, it will create a `Package1.Package.json` file inside the package's `Config` folder. This will be used to define the props in the blueprint library, and expose them in the Python API. It will also be used if the package is exported as a [standalone package](tuto_A_create_standalone.md).
When everything is ready, run the command.
```sh
make import
```
!!! Warning
Make sure that the package is inside the `Import` folder in CARLA.
---
That is all there is to know about the different ways to import new props into CARLA. If there are any doubts, 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>

101
Docs/tuto_A_add_vehicle.md Normal file
View File

@ -0,0 +1,101 @@
# Add a new vehicle
---
## Add a 4 wheeled vehicle
Follow [Art Guide][artlink] for creating the Skeletal Mesh and Physics Asset. And [Vehicles User Guide][userguide] for the rest.
[artlink]: https://docs.unrealengine.com/en-US/Engine/Physics/Vehicles/VehicleContentCreation/index.html
[userguide]: https://docs.unrealengine.com/latest/INT/Engine/Physics/Vehicles/VehicleUserGuide/
!!! important
If you want a simpler way you might copy our "General4wheeledSkeleton" from our project,
either by exporting it and copying it into your model or by creating your skelleton using
the same bone names and orientation.<br>
Bind it to your vehicle model and choose it when importing your vehicle into the editor.
This way you won't need to configure the animation, you might just use
"General4wheeledAnimation" (step 4)<br>
You also won't need to configure the bone names for your wheels
(Step 8. Be carefull, you'll still need to asign the wheel blueprints).
__1.__ Import fbx as Skelletal Mesh to its own folder inside `Content/Carla/Static/Vehicles`. A Physics asset and a Skeleton should be automatically created and linked the three together.
<br>
__2.__ Delete the automatically created ones and add boxes to the `Vehicle_Base` bone matching the shape, make sure generate hit events is enabled. Add a sphere for each wheel.
<br>
__3.__ __Tune the physics.__ In `Details/Physics`, set their "Physics Type" to __`Kinematic`__, and enable the __`Simulation generates hit events`__ option.
<br>
__4.__ Inside that folder create an "Animation Blueprint", while creating select "VehicleAnimInstance" as parent class and the skeleton of this car model as the target skeleton. Add the animation graph as shown in the links given above (or look for it in other cars' animation, like Mustang).
<br>
__5.__ Create folder `Content/Carla/Blueprints/Vehicles/<vehicle-model>`
<br>
__6.__ Inside that folder create two blueprint classes derived from "VehicleWheel" class. Call them `<vehicle-model>_FrontWheel` and `<vehicle-model>_RearWheel`. Set their "Shape Radius"
to exactly match the mesh wheel radius (careful, radius not diameter). Set their "Tire Config" to "CommonTireConfig". On the front wheel uncheck "Affected by Handbrake" and on the rear wheel set "Steer Angle" to zero.
<br>
__7.__ Inside the same folder __crate a child blueprint class__ derived from `BaseVehiclePawn` call it `<vehicle-model>`. Open it for edit and select component "Mesh", setup the "Skeletal Mesh"
and the "Anim Class" to the corresponding ones. Then select the VehicleBounds component and set the size to cover vehicle's volume as close as possible.
<br>
__8.__ Select component "VehicleMovement", under "Vehicle Setup" expand "Wheel Setups", setup each wheel
- 0: Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`Wheel_Front_Left`
- 1: Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`Wheel_Front_Right`
- 2: Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`Wheel_Rear_Left`
- 3: Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`Wheel_Rear_Right`
<br>
__9.__ Test it, go to CarlaGameMode blueprint and change "Default Pawn Class" to the newly created car blueprint.
---
## Add a 2 wheeled vehicle
Adding 2 wheeled vehicles is similar to adding a 4 wheeled one but due to the complexity of the
animation you'll need to set up aditional bones to guide the driver's animation:
As with the 4 wheeled vehicles, orient the model towards positive "x" and every bone axis towards
positive x and with the z axis facing upwards.
```yaml
Bone Setup:
- Bike_Rig: # The origin point of the mesh. Place it in the point 0 of the scenecomment
- BikeBody: # The model's body centre.
- Pedals: # If the vehicle is a bike bind the pedalier to this bone, will rotate with the bike acceleration.
- RightPedal: # Sets the driver's feet position and rotates with the pedalier if the vehicle is a bike.
- LeftPedal: # ^
- RearWheel: # Rear Wheel of the vehicle
- Handler: # Rotates with the frontal wheel of the vehicle bind the vehicle handler to it.
- HandlerMidBone: # Positioned over the front wheel bone to orient the handler with the wheel
- HandlerRight: # Sets the position of the driver's hand, no need to bind it to anything.
- HandlerLeft: # ^
- Frontwheel: # Frontal wheel of the vehicle.
- RightHelperRotator: # This four additional bones are here for an obsolete system of making the bike stable by using aditional invisible wheels
- RightHelprWheel: # ^
- LeftHelperRotator: # ^
- LeftHelperWheel: # ^
- Seat: # Sets the position of the drivers hip bone. No need to bind it to anything but place it carefully.
```
__1.__ Import fbx as Skelletal Mesh to its own folder inside `Content/Carla/Static/Vehicles/2Wheeled`. When importing select "General2WheeledVehicleSkeleton" as skelleton A Physics asset should be automatically created and linked.
__2.__ Tune the Physics asset. Delete the automatically created ones and add boxes to the `BikeBody` bone trying to match the shape as possible, make sure generate hit events is enabled.
Add a sphere for each wheel and set their "Physics Type" to "Kinematic".
__3.__ Create folder `Content/Blueprints/Vehicles/<vehicle-model>`
__4.__ Inside that folder create two blueprint classes derived from "VehicleWheel" class. Call them `<vehicle-model>_FrontWheel` and `<vehicle-model>_RearWheel`. Set their "Shape Radius" to exactly match the mesh wheel radius (careful, radius not diameter). Set their "Tire Config" to "CommonTireConfig". On the front wheel uncheck "Affected by Handbrake" and on the rear wheel set "Steer Angle" to zero.
__5.__ Inside the same folder create a blueprint class derived from `Base2WheeledVehicle` call it `<vehicle-model>`. Open it for edit and select component "Mesh", setup the "Skeletal Mesh"
and the "Anim Class" to the corresponding ones. Then select the VehicleBounds component and set the size to cover vehicle's area as seen from above.
__6.__ Select component "VehicleMovement", under "Vehicle Setup" expand "Wheel Setups", setup each wheel.
* __0:__ Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
* __1:__ Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
* __2:__ Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
* __3:__ Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
(You'll notice that we are basically placing two wheels in each bone. The vehicle class unreal provides does not support vehicles with wheel numbers different from 4 so we had to make it believe the vehicle has 4 wheels)
__7.__ Select the variable "is bike" and tick it if your model is a bike. This will activate the
pedalier rotation. Leave unmarked if you are setting up a motorbike.
__8.__ Find the variable back Rotation and set it as it fit better select the component SkeletalMesh
(The driver) and move it along x axis until its in the seat position.
__9.__ Test it, go to CarlaGameMode blueprint and change "Default Pawn Class" to the newly
created bike blueprint.

49
Docs/tuto_A_create_standalone.md Normal file
View File

@ -0,0 +1,49 @@
# Create distribution packages for assets
It is a common practice in CARLA to manage assets with standalone packages. Keeping them aside allows to reduce the size of the build. These asset packages can be easily imported into a CARLA package anytime. They also become really useful to easily distribute assets in an organized way.
* [__Export a package from the UE4 Editor__](#export-a-package-from-the-ue4-editor)
* [__Import assets into a CARLA package__](#import-assets-into-a-carla-package)
---
## Export a package from the UE4 Editor
Once assets are imported into Unreal, users can generate a __standalone package__ for them. This will be used to distribute the content to CARLA packages such as 0.9.8.
To export packages, simply run the command below.
```sh
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.
---
## Import assets into a CARLA package
A standalone package is contained in a `.tar.gz` file. The way this is extracted depends on the platform.
* __On Windows__ extract the compressed file in the main root CARLA folder.
* __On Linux__ move the compressed file to the `Import` folder and run the following script.
```sh
cd Import
./ImportAssets.sh
```
!!! 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).
---
That sumps up how to create and use standalone packages in CARLA. If there is any unexpected issue, feel free to post 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>

182
Docs/tuto_A_import_assets.md
View File

@ -1,182 +0,0 @@
# How to add assets
---
## Adding a vehicle
Follow [Art Guide][artlink] for creating the Skeletal Mesh and Physics Asset. And
[Vehicles User Guide][userguide] for the rest.
[artlink]: https://docs.unrealengine.com/en-US/Engine/Physics/Vehicles/VehicleContentCreation/index.html
[userguide]: https://docs.unrealengine.com/latest/INT/Engine/Physics/Vehicles/VehicleUserGuide/
!!! important
If you want a simpler way you might copy our "General4wheeledSkeleton" from our project,
either by exporting it and copying it into your model or by creating your skelleton using
the same bone names and orientation.<br>
Bind it to your vehicle model and choose it when importing your vehicle into the editor.
This way you won't need to configure the animation, you might just use
"General4wheeledAnimation" (step 3)<br>
You also won't need to configure the bone names for your wheels
(Step 7. Be carefull, you'll still need to asign the wheel blueprints).
1. Import fbx as Skelletal Mesh to its own folder inside `Content/Carla/Static/Vehicles`.
A Physics asset and a Skeleton should be automatically created and linked the three together.
2. Tune the Physics asset. Delete the automatically created ones and add boxes to the
`Vehicle_Base` bone matching the shape, make sure generate hit events is enabled.
Add a sphere for each wheel and set their "Physics Type" to "Kinematic".
3. Inside that folder create an "Animation Blueprint", while creating select "VehicleAnimInstance"
as parent class and the skeleton of this car model as the target skeleton.
Add the animation graph as shown in the links given above
(or look for it in other cars' animation, like Mustang).
4. Create folder `Content/Carla/Blueprints/Vehicles/<vehicle-model>`
5. Inside that folder create two blueprint classes derived from "VehicleWheel" class.
Call them `<vehicle-model>_FrontWheel` and `<vehicle-model>_RearWheel`. Set their "Shape Radius"
to exactly match the mesh wheel radius (careful, radius not diameter). Set their "Tire Config" to
"CommonTireConfig". On the front wheel uncheck "Affected by Handbrake" and on the rear wheel
set "Steer Angle" to zero.
6. Inside the same folder create a blueprint class derived from `BaseVehiclePawn`
call it `<vehicle-model>`. Open it for edit and select component "Mesh", setup the "Skeletal Mesh"
and the "Anim Class" to the corresponding ones. Then select the VehicleBounds component and set
the size to cover vehicle's volume as close as possible.
7. Select component "VehicleMovement", under "Vehicle Setup" expand "Wheel Setups", setup each wheel
- 0 : Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`Wheel_Front_Left`
- 1 : Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`Wheel_Front_Right`
- 2 : Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`Wheel_Rear_Left`
- 3 : Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`Wheel_Rear_Right`
8. Test it, go to CarlaGameMode blueprint and change "Default Pawn Class" to the newly
created car blueprint.
---
## Adding a 2 wheeled vehicle
Adding 2 wheeled vehicles is similar to adding a 4 wheeled one but due to the complexity of the
animation you'll need to set up aditional bones to guide the driver's animation:
As with the 4 wheeled vehicles, orient the model towards positive "x" and every bone axis towards
positive x and with the z axis facing upwards.
```yaml
Bone Setup:
- Bike_Rig: # The origin point of the mesh. Place it in the point 0 of the scenecomment
- BikeBody: # The model's body centre.
- Pedals: # If the vehicle is a bike bind the pedalier to this bone, will rotate with the bike acceleration.
- RightPedal: # Sets the driver's feet position and rotates with the pedalier if the vehicle is a bike.
- LeftPedal: # ^
- RearWheel: # Rear Wheel of the vehicle
- Handler: # Rotates with the frontal wheel of the vehicle bind the vehicle handler to it.
- HandlerMidBone: # Positioned over the front wheel bone to orient the handler with the wheel
- HandlerRight: # Sets the position of the driver's hand, no need to bind it to anything.
- HandlerLeft: # ^
- Frontwheel: # Frontal wheel of the vehicle.
- RightHelperRotator: # This four additional bones are here for an obsolete system of making the bike stable by using aditional invisible wheels
- RightHelprWheel: # ^
- LeftHelperRotator: # ^
- LeftHelperWheel: # ^
- Seat: # Sets the position of the drivers hip bone. No need to bind it to anything but place it carefully.
```
1. Import fbx as Skelletal Mesh to its own folder inside `Content/Carla/Static/Vehicles/2Wheeled`.
When importing select "General2WheeledVehicleSkeleton" as skelleton A Physics asset should be
automatically created and linked.
2. Tune the Physics asset. Delete the automatically created ones and add boxes to the `BikeBody`
bone trying to match the shape as possible, make sure generate hit events is enabled.
Add a sphere for each wheel and set their "Physics Type" to "Kinematic".
3. Create folder `Content/Blueprints/Vehicles/<vehicle-model>`
4. Inside that folder create two blueprint classes derived from "VehicleWheel" class. Call them
`<vehicle-model>_FrontWheel` and `<vehicle-model>_RearWheel`. Set their "Shape Radius" to exactly
match the mesh wheel radius (careful, radius not diameter).
Set their "Tire Config" to "CommonTireConfig". On the front wheel uncheck "Affected by Handbrake"
and on the rear wheel set "Steer Angle" to zero.
5. Inside the same folder create a blueprint class derived from `Base2WheeledVehicle`
call it `<vehicle-model>`. Open it for edit and select component "Mesh", setup the "Skeletal Mesh"
and the "Anim Class" to the corresponding ones. Then select the VehicleBounds component and set
the size to cover vehicle's area as seen from above.
6. Select component "VehicleMovement", under "Vehicle Setup" expand "Wheel Setups", setup each wheel
- 0 : Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
- 1 : Wheel Class=`<vehicle-model>_FrontWheel`, Bone Name=`FrontWheel`
- 2 : Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
- 3 : Wheel Class=`<vehicle-model>_RearWheel`, Bone Name=`RearWheel`
(You'll notice that we are basically placing two wheels in each bone.
The vehicle class unreal provides does not support vehicles with wheel numbers different
from 4 so we had to make it believe the vehicle has 4 wheels)
7. Select the variable "is bike" and tick it if your model is a bike. This will activate the
pedalier rotation. Leave unmarked if you are setting up a motorbike.
8. Find the variable back Rotation and set it as it fit better select the component SkeletalMesh
(The driver) and move it along x axis until its in the seat position.
9. Test it, go to CarlaGameMode blueprint and change "Default Pawn Class" to the newly
created bike blueprint.
---
## Map generation
For the road generation, the following meshes are expected to be found
```
# Enum Filepath
RoadTwoLanes_LaneLeft at "Content/Carla/Static/Road/St_Road_TileRoad_RoadL.uasset"
RoadTwoLanes_LaneRight at "Content/Carla/Static/Road/St_Road_TileRoad_RoadR.uasset"
RoadTwoLanes_SidewalkLeft at "Content/Carla/Static/SideWalk/St_Road_TileRoad_SidewalkL.uasset"
RoadTwoLanes_SidewalkRight at "Content/Carla/Static/SideWalk/St_Road_TileRoad_SidewalkR.uasset"
RoadTwoLanes_LaneMarkingSolid at "Content/Carla/Static/RoadLines/St_Road_TileRoad_LaneMarkingSolid.uasset"
RoadTwoLanes_LaneMarkingBroken at "Content/Carla/Static/RoadLines/St_Road_TileRoad_LaneMarkingBroken.uasset"
Road90DegTurn_Lane0 at "Content/Carla/Static/Road/St_Road_Curve_Road1.uasset"
Road90DegTurn_Lane1 at "Content/Carla/Static/Road/St_Road_Curve_Road2.uasset"
Road90DegTurn_Lane2 at "Content/Carla/Static/Road/St_Road_Curve_Road3.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road4.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road5.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road6.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road7.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road8.uasset"
Road90DegTurn_Lane3 at "Content/Carla/Static/Road/St_Road_Curve_Road9.uasset"
Road90DegTurn_Sidewalk0 at "Content/Carla/Static/SideWalk/St_Road_Curve_Sidewalk1.uasset"
Road90DegTurn_Sidewalk1 at "Content/Carla/Static/SideWalk/St_Road_Curve_Sidewalk2.uasset"
Road90DegTurn_Sidewalk2 at "Content/Carla/Static/SideWalk/St_Road_Curve_Sidewalk3.uasset"
Road90DegTurn_Sidewalk3 at "Content/Carla/Static/SideWalk/St_Road_Curve_Sidewalk4.uasset"
Road90DegTurn_LaneMarking at "Content/Carla/Static/Road/St_Road_Curve_LaneMarking.uasset"
RoadTIntersection_Lane0 at "Content/Carla/Static/Road/St_Road_TCross_Road1.uasset"
RoadTIntersection_Lane1 at "Content/Carla/Static/Road/St_Road_TCross_Road2.uasset"
RoadTIntersection_Lane2 at "Content/Carla/Static/Road/St_Road_TCross_Road3.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road4.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road5.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road6.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road7.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road8.uasset"
RoadTIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_TCross_Road9.uasset"
RoadTIntersection_Sidewalk0 at "Content/Carla/Static/SideWalk/St_Road_TCross_Sidewalk1.uasset"
RoadTIntersection_Sidewalk1 at "Content/Carla/Static/SideWalk/St_Road_TCross_Sidewalk2.uasset"
RoadTIntersection_Sidewalk2 at "Content/Carla/Static/SideWalk/St_Road_TCross_Sidewalk3.uasset"
RoadTIntersection_Sidewalk3 at "Content/Carla/Static/SideWalk/St_Road_TCross_Sidewalk4.uasset"
RoadTIntersection_LaneMarking at "Content/Carla/Static/RoadLines/St_Road_TCross_LaneMarking.uasset"
RoadXIntersection_Lane0 at "Content/Carla/Static/Road/St_Road_XCross_Road1.uasset"
RoadXIntersection_Lane1 at "Content/Carla/Static/Road/St_Road_XCross_Road2.uasset"
RoadXIntersection_Lane2 at "Content/Carla/Static/Road/St_Road_XCross_Road3.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road4.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road5.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road6.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road7.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road8.uasset"
RoadXIntersection_Lane3 at "Content/Carla/Static/Road/St_Road_XCross_Road9.uasset"
RoadXIntersection_Sidewalk0 at "Content/Carla/Static/SideWalk/St_Road_XCross_Sidewalk1.uasset"
RoadXIntersection_Sidewalk1 at "Content/Carla/Static/SideWalk/St_Road_XCross_Sidewalk2.uasset"
RoadXIntersection_Sidewalk2 at "Content/Carla/Static/SideWalk/St_Road_XCross_Sidewalk3.uasset"
RoadXIntersection_Sidewalk3 at "Content/Carla/Static/SideWalk/St_Road_XCross_Sidewalk4.uasset"
RoadXIntersection_LaneMarking at "Content/Carla/Static/RoadLines/St_Road_XCross_LaneMarking.uasset"
```

332
Docs/tuto_A_map_creation.md
View File

@ -1,332 +0,0 @@
![Town03](img/create_map_01.jpg)
# Create and import a map
* [__Introduction__](#introduction)
* [__Map creation with RoadRunner__](#map-creation-with-roadrunner)
* [Export the map](#export-the-map)
* [__Import a map into CARLA__](#import-a-map-into-carla)
* [__Final tips__](#final-tips)
* [__Previous ways to import a map__](#previous-ways-to-import-a-map)
---
## Introduction
In order to create a CARLA map, two elements are needed. This tutorial explains how to properly import them to CARLA.
* __`.fbx` binaries.__ The meshes needed to build the map, such as roads, lanemarkings, sidewalks, ect.
* __`.xodr` OpenDRIVE file.__ Contains the road network information necessary for vehicles to navigate the map.
In order to create them, RoadRunner is the recommended software. It is quite easy to use, and it provides plugins that make the import process much simpler. Some basic steps are provided below.
The process to import a map into CARLA is now out-of-the-box. A Docker image of Unreal Engine is used so that the user does not have neither to compile anything nor manually set the assets to fit into CARLA.
!!! Note
This tutorial creates a new map from scratch. Check these other tutorials to [customize a town](tuto_A_map_customization.md) or [import other assets](tuto_A_import_assets.md) to CARLA.
---
## Map creation with RoadRunner
RoadRunner is an accessible and powerful software from Vector Zero to create 3D scenes. There is a trial version available at their [site](https://www.vectorzero.io/), 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 the map
__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.
---
## Import a map into CARLA
This process will cook the map automatically from start to finish. Using only the .fbx and .xodr, the output will provide a fully usable CARLA map with traffic behaviour, and pedestrian navigation already implemented.
__1. Build a Docker image of Unreal Engine.__ Follow [these instructions](https://github.com/carla-simulator/carla/tree/master/Util/Docker). The process takes quite a lot of time and disk space. Around 4h and 400GB to build the Docker image. However, this is only needed the first time. Then, the process of importing a new map is out-of-the-box.
__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 cooks the map automatically. It only needs the path for the input and output files.
```sh
python docker_tools.py --input ~/path_to_input_assets --output ~/path_for_output_assets
```
__3. Move the output files__ to `Content/Carla/Maps` in case they are not already there.
---
## Final tips
* __Add and test traffic light timing.__ This are not set automatically, and will need trial and error to fit perfectly with the city.
![ue_tlsigns_example](img/ue_tlsigns_example.png)
> _Example: Traffic Signs, Traffic lights and Turn based stop._
* __Place vehicle spawn points__ 2 to 3 meters above a Route Planner's trigger box, and oriented in the same direction. When the vehicle falls into the trigger box, the autopilot takes control of it.
![ue_vehicle_spawnpoint](img/ue_vehicle_spawnpoint.png)
* __Show individual route planners.__ `Generate Routes` in Open Drive Actor generates the road network but it does not show these. In order to do so, do the following.
1. Select all `RoutePlanner` actors.
2. Move them.
3. Press `ctr + z`. They will show up on the map.
![ue_route_points](img/ue_route_points.png)
* __Modify OpenDRIVE routes.__ This can be done manually.
![ue_routeplanner_mod](img/ue_routeplanner_mod.png)
* __Add the map to the Unreal packaging system.__ Go to the following path and add the level.
`Edit > Project Settings > Project > Packaging > Show Advanced > List of maps to include...` <br>
![ue_maps_to_include](img/ue_maps_to_include.png)
* __Use CARLA materials__ contained in `Content/Carla/Static/GenericMaterials`.
* Go to the material. `Right-click on the Asset > Browse to Asset`.
* Set the actors. `Right-click on Material > Asset Actions > Select Actors Using This Asset`
---
## Previous 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 became deprecated when the Docker method was developed. However, they are explained below in case they are needed.
* __A) RoadRunner plugin import.__ This software provides specific plugins for CARLA. Get those and follow some simple steps to get the map.
* __B) Manual import.__ This process requires to go through all the process manually. From importing _.fbx_ and _.xodr_ to setting the static meshes.
<details>
<summary><h4 style="display:inline">
Deprecated tutorials to import a map
</h4></summary>
!!! Warning
These importing tutorials are deprecated. The best way to import a map into CARLA is to use the Docker as explained above.
## A- RoadRunner plugin import
### 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.png)
### 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.png)
__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.png)
__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.png)
---
## B- Manual import from files
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.png)
### 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.png)
__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.png)
__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.png)
* 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.png)
* 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.png)
### 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.png)
---
## 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.png)
__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.png)
__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.png)
> _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.
![ue_skybox_no_export](img/ue_noexport.png)
__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.png)
__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.png)
__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.png)
__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>

194
Docs/tuto_A_standalone_packages.md
View File

@ -1,194 +0,0 @@
# Creating standalone asset packages for distribution
*Please note that we will use the term *assets* for referring to **props** and also **maps**.*
The main objective for importing and exporting assets is to reduce the size of
the distribution build. This is possible since these assets will be imported as
independent packages that can be plugged in anytime inside Carla and also exported.
---
## How to import assets inside Unreal Engine
The first step is to create an empty folder inside the Carla `Import` folder and rename it with any
folder name desired. For simplifying this newly created folder structure, we recommend having
as many subfolders as maps to import and one single subfolder containing all the props to import.
Inside each subfolder, we will place all the files needed for importing.<br>
So basically, for a **map** subfolder, we will need to place the following files:
* The map itself in `.FBX` format.
* Optionally, the textures required by the map.
* Optionally, the `.xodr` OpenDrive file corresponding to that map.
And for the **props** folder, we will need the following files:
* The prop itself in `.FBX` format.
* Optionally, the textures required by the prop.
Additionally, we have to create a **JSON file inside the package** that will contain information
about its assets. The file extension must be `.json`. We recommend the JSON file to have the same
name as the package name in order to keep it organized.
**Please, keep in mind that the name of this file will used as the name of the distribution package**.
The content of this JSON file should be similar to the following:
```json
{
"maps": [
{
"name": "MyTown01",
"source": "./MapToImport01/MapToImport01.fbx",
"use_carla_materials": true,
"xodr": "./MapToImport01/MapToImport01.xodr"
},
{
"name": "MyTown02",
"source": "./MapToImport02/MapToImport02.fbx",
"use_carla_materials": false,
"xodr": "./MapToImport02/MapToImport02.xodr"
}
],
"props": [
{
"name": "MyProp01",
"size": "medium",
"source": "./AssetsToImport/PropToImport01/PropToImport01.fbx",
"tag": "SemanticSegmentationTag01"
},
{
"name": "MyProp02",
"size": "small",
"source": "./AssetsToImport/PropToImport02/PropToImport02.fbx",
"tag": "SemanticSegmentationTag02"
}
]
}
```
As you can observe in the JSON file content, we have defined a JSON array of **maps** and **props**.
Each item inside the **maps** array has the following parameters:
* **name**: The name of the map. It is possible to import the same map mesh but with a different
name and, if so, it will create separate mesh files inside Unreal for each different name.
* **source**: Source path of the map inside the package folder.
* **use_carla_materials**: If true, we will use Carla materials, otherwise, we will use RoadRunner materials.
* **xodr**: Path to the `.xodr` Opendrive file for that map.
And each item inside the **props** array has the following parameters:
* **name**: The name of the prop. It is possible to import the same prop mesh but with different
name and, if so, it will create separate mesh files inside Unreal for each different name.
* **source**: Source path of the prop inside the package folder.
* **size**: Size of the prop, possible values are:
- `tiny`
- `small`
- `medium`
- `big`
- `huge`
- **tag**: Semantic segmentation tag. Possible values are:
- `None`
- `Buildings`
- `Fences`
- `Other`
- `Pedestrians`
- `Poles`
- `RoadLines`
- `Roads`
- `Sidewalks`
- `TrafficSigns`
- `Vegetation`
- `Vehicles`
- `Walls`
Note that if the tag is not spelled correctly, it will interpret it as `None` value by default.
To sum up, the `Import` folder should have this similar structure:
```
Import
|
├── Folder01
| ├── MapToImport01
│ │ ├── Asphalt1_Diff.png
│ │ ├── Asphalt1_Norm.png
│ │ ├── Asphalt1_Spec.png
│ │ ├── Grass1_Diff.png
│ │ ├── Grass1_Norm.png
│ │ ├── Grass1_Spec.png
│ │ ├── LaneMarking1_Diff.png
│ │ ├── LaneMarking1_Norm.png
│ │ ├── LaneMarking1_Spec.png
│ │ ├── MapToImport01.fbx
│ │ └── MapToImport01.xodr
| ├── MapToImport02
│ │ ├── MapToImport02.fbx
│ │ └── MapToImport02.xodr
| ├── AssetsToImport
| │ ├── PropToImport01
│ │ │ ├── PropToImport01_Diff.png
│ │ │ ├── PropToImport01_Norm.png
│ │ │ ├── PropToImport01_Spec.png
│ │ │ └── PropToImport01.fbx
│ │ ├── PropToImport02
│ │ │ └── PropToImport02.fbx
| │ └── PropToImport03
│ │ └── PropToImport03.fbx
| └── Package1.json
└── Folder02
├── AssetsToImport
| └── PropToImport04
| └── PropToImport04.fbx
└── Package2.json
```
_Maps exported from **RoadRunner** are also supported for importing them inside_
_Carla. So, basically, once created your **RoadRunner** map, you just need to export it, take the_
_required files and place them following the structure listed above._
!!! note
**RoadRunner's** imported assets will be classified for **semantic segmentation** based on
the asset's name (`RoadNode`, `Terrain`, `MarkingNode`) and moved to `Roads`, `Terrain`
and `RoadLines` respectively, under `Content/Carla/PackageName/Static`.<br>
_If the process doesn't work due to different names or other issues, you can always move the assets_
_manually, check this [`tutorial`][importtutorial]_ (_Section 3.2.1 - 6_).
[importtutorial]: tuto_A_map_creation.md#32-importing-from-the-files
Now we have everything ready for importing assets. To do so, you just need to run the command:
```sh
make import
```
This command will read the JSON file and take each asset and place it inside the Content
in Unreal Engine. Furthermore, it will create a `Package1.Package.json` file inside the package's
`Config` folder that will be used for **defining** its props in the Carla blueprint library,
**exposing** them in the `PythonAPI` and also for **exporting** those assets if needed.
_Packages with the same name will produce an error. Delete or rename the package before importing_
_a new one with the same name._
!!! note
The imported map won't have collisions, so they should be generated manually. This
[tutorial](tuto_A_map_creation.md#3.2-importing-from-the-files) (_Section 3.2.1 - 5_) shows how to do it.
---
## How to export assets
Once imported all the packages inside Unreal, users could also generate a **cooked package**
for each of them. This last step is important in order to have all packages ready to add for
distribution versions of Carla and for any supported platform. To export the packages,
simply run the command:
```sh
make package ARGS="--packages=Package1,Package2"
```
This command will create the distribution package compressed in a `.tar.gz` file for **each**
cooked package and place it in the Carla `Dist` folder. Finally, you could import these packages
in a Carla distribution by simply moving them in the Carla `Import` folder and executing
the `ImportAssets.sh` script.

7
mkdocs.yml
View File

@ -46,10 +46,11 @@ nav:
- 'Control walker skeletons': "tuto_G_control_walker_skeletons.md"
- 'Retrieve simulation data': "tuto_G_retrieve_data.md"
- Tutorials (assets):
- 'Import new assets': 'tuto_A_import_assets.md'
- 'Create and import a map': 'tuto_A_map_creation.md'
- 'Add a new map': 'tuto_A_add_map.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'
- 'Map customization': 'tuto_A_map_customization.md'
- 'Standalone asset packages': 'tuto_A_standalone_packages.md'
- "Use Epic's Automotive materials": 'tuto_A_epic_automotive_materials.md'
- 'Vehicle modelling': 'tuto_A_vehicle_modelling.md'
- Tutorials (developers):