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

Corkyw10/maps documentation (#4233) 

* Restructured maps docs layout and fixed affected URLs

* Updated RoadRunner map generation doc. Includes link for Leaderboard license

* Updated package ingestion doc so it is located in the main navigation bar. All relative links have been fixed.

* Moved customization information to separate tutorial. Added next steps

* Moved manual preparation of json package to separate tutorial.

* Added how to add traffic light and signs documentation. Updated nav with approriate page name. Cropped photo to show an updated view of UE editor

* Redraft of the weather and landscape tutorial

* Updated tutorial for using the road painter. Typo fix in other tutorials for map customization

* Added tutorial to add levels to maps

* Added images for maps tutorials

* Minor syntax changes to manual package prep

* Full drafts of map documentation

* Added images and corrected names for building shaders

* [NO_BUILD] First draft of Large Maps docs (#4396)

* Drafting large map docs

* Changed name of spawn_npc script

* Syntax changes

* Corrected hybrid mode dormant behavior, added code for setting ego vehicle, removed expensive note about map calls

* Added section for roadrunner large maps

* Added images to roadrunner docs and rearranged nav bar and titles.

* Added corrections to import of large maps and standard map nomenclature

Co-authored-by: bernat <bernatx@gmail.com>

* Made corrections to spawn points and additional fbx folder information

* Fixed mentions of normal maps to standard maps

Co-authored-by: bernat <bernatx@gmail.com>
This commit is contained in:
Corinne 2021-07-30 11:20:23 +02:00 committed by GitHub
parent d1debd9a20
commit bd36e46b39
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
41 changed files with 1748 additions and 1015 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
Docs/core_map.md
View File

@ -2,72 +2,92 @@
After discussing about the world and its actors, it is time to put everything into place and understand the map and how do the actors navigate it.
* [__The map__](#the-map)
* [Changing the map](#changing-the-map)
* [Landmarks](#landmarks)
* [Lanes](#lanes)
* [Junctions](#junctions)
* [Waypoints](#waypoints)
* [Environment Objects](#environment-objects)
* [__Navigation in CARLA__](#navigation-in-carla)
* [Navigating through waypoints](#navigating-through-waypoints)
* [Generating a map navigation](#generating-a-map-navigation)
* [__CARLA maps__](#carla-maps)
* [Non-layered maps](#non-layered-maps)
* [Layered maps](#layered-maps)
- [__The map__](#the-map)
- [Changing the map](#changing-the-map)
- [Landmarks](#landmarks)
- [Lanes](#lanes)
- [Junctions](#junctions)
- [Waypoints](#waypoints)
- [Environment Objects](#environment-objects)
- [__Navigation in CARLA__](#navigation-in-carla)
- [Navigating through waypoints](#navigating-through-waypoints)
- [Generating a map navigation](#generating-a-map-navigation)
- [__CARLA maps__](#carla-maps)
- [Non-layered maps](#non-layered-maps)
- [Layered maps](#layered-maps)
---
## The map
A map includes both the 3D model of a town and its road definition. Every map is based on an OpenDRIVE file describing the road layout fully annotated. The way the [OpenDRIVE standard 1.4](http://www.opendrive.org/docs/OpenDRIVEFormatSpecRev1.4H.pdf) defines roads, lanes, junctions, etc. is extremely important. It determines the possibilities of the API and the reasoning behind decisions made.
A map includes both the 3D model of a town and its road definition. A map's road definition is based on an OpenDRIVE file, a standarized, annotated road definition format. The way the [OpenDRIVE standard 1.4](http://www.opendrive.org/docs/OpenDRIVEFormatSpecRev1.4H.pdf) defines roads, lanes, junctions, etc. determines the functionality of the Python API and the reasoning behind decisions made.
The Python API makes for a high level querying system to navigate these roads. It is constantly evolving to provide a wider set of tools.
The Python API acts as a high level querying system to navigate these roads. It is constantly evolving to provide a wider set of tools.
### Changing the map
__To change the map, the world has to change too__. Everything will be rebooted and created from scratch, besides the Unreal Editor itself. There are two ways to do so.
__To change the map, the world has to change too__. The simulation will be recreated from scratch. You can either restart with the same map in a new world or you can change both the map and the world:
* `reload_world()` creates a new instance of the world with the same map.
* `load_world()` changes the current map and creates a new world.
- `reload_world()` creates a new instance of the world with the same map.
- `load_world()` changes the current map and creates a new world.
```py
world = client.load_world('Town01')
```
The client can get a list of available maps. Each map has a `name` attribute that matches the name of the currently loaded city, e.g. _Town01_.
Each map has a `name` attribute that matches the name of the currently loaded city, e.g. _Town01_. To get a list of the available maps:
```py
print(client.get_available_maps())
```
### Landmarks
The traffic signs defined in the OpenDRIVE file are translated into CARLA as landmark objects that can be queried from the API. In order to facilitate their manipulation, there have been several additions to it.
Traffic signs defined in the OpenDRIVE file are translated to CARLA as landmark objects that can be queried from the API. The following methods and classes can be used to manipulate and work with landmark objects:
* __[carla.Landmark](https://carla.readthedocs.io/en/latest/python_api/#carla.Landmark)__ objects represent the OpenDRIVE signals. The attributes and methods describe the landmark, and where it is effective.
* [__carla.LandmarkOrientation__](https://carla.readthedocs.io/en/latest/python_api/#carla.LandmarkOrientation) states the orientation of the landmark with regards of the road's geometry definition.
* [__carla.LandmarkType__](https://carla.readthedocs.io/en/latest/python_api/#carla.LandmarkType) contains some common landmark types, to ease translation to OpenDRIVE types.
* A __[carla.Waypoint](https://carla.readthedocs.io/en/latest/python_api/#carla.Waypoint)__ can get landmarks located a certain distance ahead of it. The type of landmark can be specified.
* The __[carla.Map](https://carla.readthedocs.io/en/latest/python_api/#carla.Map)__ retrieves sets of landmarks. It can return all the landmarks in the map, or those having an ID, type or group in common.
* The __[carla.World](https://carla.readthedocs.io/en/latest/python_api/#carla.World)__ acts as intermediary between landmarks, and the *carla.TrafficSign* and *carla.TrafficLight* that embody them in the simulation.
- __[`carla.Landmark`](https://carla.readthedocs.io/en/latest/python_api/#carla.Landmark)__ objects represent OpenDRIVE signals. The attributes and methods of this class describe the landmark and its area of influence.
- [`carla.LandmarkOrientation`](https://carla.readthedocs.io/en/latest/python_api/#carla.LandmarkOrientation) states the orientation of the landmark with regard to the road's geometry definition.
- [`carla.LandmarkType`](https://carla.readthedocs.io/en/latest/python_api/#carla.LandmarkType) contains common landmark types to facilitate translation to OpenDRIVE types.
- __[`carla.Waypoint`](https://carla.readthedocs.io/en/latest/python_api/#carla.Waypoint)__ can get landmarks located a certain distance ahead of it. The landmark type to get can be specified.
- __[`carla.Map`](https://carla.readthedocs.io/en/latest/python_api/#carla.Map)__ retrieves sets of landmarks. It can return all landmarks in the map, or those which have a common ID, type or group.
- __[`carla.World`](https://carla.readthedocs.io/en/latest/python_api/#carla.World)__ acts as intermediary between landmarks and the `carla.TrafficSign` and `carla.TrafficLight` that represent them in the simulation.
```py
my_waypoint.get_landmarks(200.0,True)
```
### Lanes
### Waypoints
The lane types defined by [OpenDRIVE standard 1.4](http://www.opendrive.org/docs/OpenDRIVEFormatSpecRev1.4H.pdf) are translated to the API in [__carla.LaneType__](python_api.md#carla.LaneType) as a series of enum values.
A [`carla.Waypoint`](python_api.md#carla.Waypoint) is a 3D-directed point in the CARLA world corresponding to an OpenDRIVE lane. Everything related to waypoints happens on the client-side; communication with the server is only needed once to get the [map object](python_api.md#carlamap) containing the waypoint information.
The lane markings surrounding a lane can be accessed through [__carla.LaneMarking__](python_api.md#carla.LaneMarking). These are defined with a series of variables.
Each waypoint contains a [`carla.Transform`](python_api.md#carla.Transform) which states its location on the map and the orientation of the lane containing it. The variables `road_id`,`section_id`,`lane_id` and `s` correspond to the OpenDRIVE road. The `id` of the waypoint is constructed from a hash combination of these four values.
* [__carla.LaneMarkingType__](python_api.md#carla.LaneMarkingType) are enum values according to OpenDRIVE standards.
* [__carla.LaneMarkingColor__](python_api.md#carla.LaneMarkingColor) are enum values to determine the color of the marking.
* __width__ to state thickness of the marking.
* [__carla.LaneChange__](python_api.md#carla.LaneChange) to state permissions to perform lane changes.
!!! Note
Waypoints closer than __2cm within the same road__ share the same `id`.
Waypoints use these to aknowledge traffic permissions.
A waypoint holds information about the __lane__ containing it. This information includes the lane's left and right __lane markings__, a boolean to determine if it's inside a junction, the lane type, width, and lane changing permissions.
```py
# Get the lane type where the waypoint is.
# Access lane information from a waypoint
inside_junction = waypoint.is_junction()
width = waypoint.lane_width
right_lm_color = waypoint.right_lane_marking.color
```
### Lanes
The lane types defined by [OpenDRIVE standard 1.4](http://www.opendrive.org/docs/OpenDRIVEFormatSpecRev1.4H.pdf) are translated to the API in [`carla.LaneType`](python_api.md#carla.LaneType) as a series of enum values.
The lane markings surrounding a lane are accessed through [`carla.LaneMarking`](python_api.md#carla.LaneMarking). Lane markings are defined by a series of variables:
- __color:__ [`carla.LaneMarkingColor`](python_api.md#carla.LaneMarkingColor) are enum values that define the marking's color.
- __lane_change:__ [`carla.LaneChange`](python_api.md#carla.LaneChange) states if the lane permits turning left, right, both or none.
- __type:__ [`carla.LaneMarkingType`](python_api.md#carla.LaneMarkingType) are enum values that define the type of marking according to the OpenDRIVE standard.
- __width:__ defines the marking's thickness.
The below example shows to get information about the lane type, lane markings, and lane change permissions at a specific waypoint:
```py
# Get the lane type of the waypoint
lane_type = waypoint.lane_type
# Get the type of lane marking on the left.
@ -79,32 +99,14 @@ lane_change = waypoint.lane_change
### Junctions
A [carla.Junction](python_api.md#carla.Junction) represents an OpenDRIVE junction. This class provides for a bounding box to state whereas lanes or vehicles are inside of it.
A [`carla.Junction`](python_api.md#carla.Junction) represents an OpenDRIVE junction. This class encompasses a junction with a bounding box to identify lanes or vehicles within it.
The most remarkable method of this class returns a pair of waypoints per lane inside the junction. Each pair is located at the starting and ending point of the junction boundaries.
The `carla.Junction` class contains the `get_waypoints` method which returns a pair of waypoints for every lane within the junction. Each pair is located at the start and end points of the junction boundaries.
```py
waypoints_junc = my_junction.get_waypoints()
```
### Waypoints
A [__carla.Waypoint__](python_api.md#carla.Waypoint) is a 3D-directed point. These are prepared to mediate between the world and the openDRIVE definition of the road. Everything related with waypoints happens on the client-side, so there no communication with the server is needed.
Each waypoint contains a [carla.Transform](python_api.md#carla.Transform). This states its location on the map and the orientation of the lane containing it. The variables `road_id`,`section_id`,`lane_id` and `s` translate this transform to the OpenDRIVE road. These combined, create the `id` of the waypoint.
!!! Note
Due to granularity, waypoints closer than __2cm within the same road__ share the same `id`.
A waypoint also contains some information regarding the __lane__ containing it. Specifically its left and right __lane markings__, and a boolean to determine if it is inside a junction.
```py
# Examples of a waypoint accessing to lane information
inside_junction = waypoint.is_junction()
width = waypoint.lane_width
right_lm_color = waypoint.right_lane_marking.color
```
### Environment Objects
Every object on a CARLA map has a set of associated variables which can be found [here][env_obj]. Included in these variables is a [unique ID][env_obj_id] that can be used to [toggle][toggle_env_obj] that object's visibility on the map. You can use the Python API to [fetch][fetch_env_obj] the IDs of each environment object based on their [semantic tag][semantic_tag]:
@ -137,69 +139,70 @@ See an example of distinct objects being toggled:
---
## Navigation in CARLA
Navigation in CARLA is managed via the waypoint API. This consists of a summary of methods in [carla.Waypoint](python_api.md#carla.Waypoint) and [carla.Map](python_api.md#carla.Map).
All the queries happen on the client-side. The client only communicates with the server when retrieving the map object that will be used for the queries. There is no need to retrieve the map (`world.get_map()`) more than once.
Navigation in CARLA is managed via the Waypoint API, a combination of methods from [`carla.Waypoint`](python_api.md#carla.Waypoint) and [`carla.Map`](python_api.md#carla.Map).
The client must initially communicate with the server to retrieve the map object containing the waypoint information. This is only required once, all subsequent queries are performed on the client side.
### Navigating through waypoints
Waypoints have a set of methods to connect with others and create a road flow. All of these methods follow traffic rules to determine only places where the vehicle can go.
The Waypoint API exposes methods that allow waypoints to connect to each other and construct a path along a road for vehicles to navigate:
- `next(d)` creates a list of waypoints within an approximate distance, `d`, __in the direction of the lane__. The list contains one waypoint for each possible deviation.
- `previous(d)` creates a list of waypoints waypoint within an approximate distance, `d`, __in the opposite direction of the lane__. The list contains one waypoint for each possible deviation.
- `next_until_lane_end(d)` and `previous_until_lane_start(d)` return a list of waypoints a distance `d` apart. The lists go from the current waypoint to the end and beginning of its lane, respectively.
- `get_right_lane()` and `get_left_lane()` return the equivalent waypoint in an adjacent lane, if one exists. A lane change maneuver can be made by finding the next waypoint to the one on its right/left lane, and moving to it.
* `next(d)` creates a list of waypoints at an approximate distance `d` __in the direction of the lane__. The list contains one waypoint for each deviation possible.
* `previous(d)` creates a list of waypoints waypoint at an approximate distance `d` __on the opposite direction of the lane__. The list contains one waypoint for each deviation possible.
* `next_until_lane_end(d)` and `previous_until_lane_start(d)` returns a list of waypoints a distance `d` apart. The list goes from the current waypoint to the end and start of its lane, respectively.
* `get_right_lane()` and `get_left_lane()` return the equivalent waypoint in an adjacent lane, if any. A lane change maneuver can be made by finding the next waypoint to the one on its right/left lane, and moving to it.
```py
# Disable physics, in this example the vehicle is teleported.
vehicle.set_simulate_physics(False)
while True:
# Find next waypoint 2 meters ahead.
waypoint = random.choice(waypoint.next(2.0))
# Teleport the vehicle.
vehicle.set_transform(waypoint.transform)
waypoint = waypoint.next(2.0)
```
### Generating a map navigation
### Generating map navigation
The instance of the map is provided by the world. It will be useful to create routes and make vehicles roam around the city and reach goal destinations.
The client needs to make a request to the server to get the `.xodr` map file and parse it to a [`carla.Map`](python_api.md#carla.Map) object. This only needs to be done once.
The following method asks the server for the XODR map file, and parses it to a [carla.Map](python_api.md#carla.Map) object. It only needs to be calle once. Maps can be quite heavy, and successive calls are unnecessary and expensive.
To get the map object:
```py
map = world.get_map()
```
* __Get recommended spawn points for vehicles__ pointed by developers. There is no ensurance that these spots will be free.
The map object contains __recommended spawn points__ for the creation of vehicles. You can get a list of these spawn points, each one containing a [`carla.Transform`](python_api.md#carlatransform), using the method below. Bear in mind that the spawn points may be occupied already, resulting in failed creation of vehicles due to collisions.
```py
spawn_points = world.get_map().get_spawn_points()
```
* __Get the closest waypoint__ to a specific location or to a certain `road_id`, `lane_id` and `s` in OpenDRIVE.
You can get started with waypoints by __[getting](python_api.md#carla.Map.get_waypoint) the closest waypoint__ to a specific location or to a particular `road_id`, `lane_id` and `s` value in the map's OpenDRIVE definition:
```py
# Nearest waypoint on the center of a Driving or Sidewalk lane.
# Nearest waypoint in the center of a Driving or Sidewalk lane.
waypoint01 = map.get_waypoint(vehicle.get_location(),project_to_road=True, lane_type=(carla.LaneType.Driving | carla.LaneType.Sidewalk))
#Nearest waypoint but specifying OpenDRIVE parameters.
waypoint02 = map.get_waypoint_xodr(road_id,lane_id,s)
```
* __Generate a collection of waypoints__ to visualize the city lanes. Creates waypoints all over the map, for every road and lane. All of them will be an approximate distance apart.
The below example shows how to __generate a collection of waypoints__ to visualize the city lanes. This will create waypoints all over the map, for every road and lane. All of them will approximately 2 meters apart:
```py
waypoint_list = map.generate_waypoints(2.0)
```
* __Generate road topology__. Returns a list of pairs (tuples) of waypoints. For each pair, the first element connects with the second one and both define the starting and ending point of each lane in the map.
To __generate a minimal graph of road topology__, use the example below. This will return a list of pairs (tuples) of waypoints. The first element in each pair connects with the second element and both define the start and end points of each lane in the map. More information on this method is found in the [PythonAPI](python_api.md#carla.Map.get_topology).
```py
waypoint_tuple_list = map.get_topology()
```
* __Convert simulation point to geographical coordinates.__ Transforms a certain location to a [carla.GeoLocation](python_api.md#carla.GeoLocation) with latitude and longitude values.
The example below __converts a `carla.Transform` to geographical latitude and longitude coordinates,__ in the form of a [`carla.GeoLocation`](python_api.md#carla.GeoLocation):
```py
my_geolocation = map.transform_to_geolocation(vehicle.transform)
```
* __Save road information.__ Converts the road information to OpenDRIVE format, and saves it to disk.
Use the following example to __save road information__ in OpenDRIVE format to disk:
```py
info_map = map.to_opendrive()
```
@ -228,7 +231,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_overview.md) to be used in CARLA.
Users can [customize a map](tuto_A_map_customization.md) or even [create a new map](tuto_M_custom_map_overview.md) to be used in CARLA.
| Town | Summary |
| -----------| ------ |
@ -261,7 +264,6 @@ See an example of all layers being loaded and unloaded in sequence:
![map-layers](img/sublevels.gif)
<br>
---
That is a wrap as regarding maps and navigation in CARLA. The next step takes a closer look into sensors types, and the data they retrieve.

7
Docs/extra.css
View File

@ -12,6 +12,13 @@
text-align: center;
}
/************************* NAV BAR **************************/
.caption {
/* background-color: #d6d6d6;
color: #404040; */
text-decoration: underline;
}
/************************* DEFAULT TABLES **************************/

BIN
Docs/img/EmissiveIntensity.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 973 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 962 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 275 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.4 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 16 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.9 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.7 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 149 KiB

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.4 KiB

BIN
Docs/img/ue_tl_group.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 174 KiB

After

Width:  |  Height:  |  Size: 102 KiB

12
Docs/index.md
View File

@ -77,8 +77,16 @@ CARLA forum</a>
[__RLlib Integration__](tuto_G_rllib_integration.md) — Find out how to run your own experiment using the RLlib library.
[__Scenic__](tuto_G_scenic.md) — Follow an example of defining different scenarios using the Scenic library.
## Tutorials — Maps
[__Overview of custom maps__](tuto_M_custom_map_overview.md)
[__Create a map in RoadRunner__](tuto_M_generate_map.md)
[__Import map in CARLA package__](tuto_M_add_map_package.md)
[__Import map in CARLA source build__](tuto_M_add_map_source.md)
[__Manually prepare map package__](tuto_M_manual_map_package.md)
[__Alternative map section__](tuto_M_add_map_alternative.md)
[__Generate pedestrian navigation__](tuto_M_generate_pedestrian_navigation.md) — Obtain the information needed for walkers to move around.
## Tutorials — Assets
[__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.
@ -91,8 +99,6 @@ CARLA forum</a>
[__Create semantic tags__](tuto_D_create_semantic_tags.md) — Define customized tags for semantic segmentation.
[__Customize vehicle suspension__](tuto_D_customize_vehicle_suspension.md) — Modify the suspension system of a vehicle.
[__Generate detailed colliders__](tuto_D_generate_colliders.md) — Create detailed colliders for vehicles.
[__Make a release__](tuto_D_make_release.md) — For developers who want to publish a release.
[__Generate pedestrian navigation__](tuto_D_generate_pedestrian_navigation.md) — Obtain the information needed for walkers to move around.
## Contributing
[__Contribution guidelines__](cont_contribution_guidelines.md) — The different ways to contribute to CARLA.

150
Docs/large_map_import.md Normal file
View File

@ -0,0 +1,150 @@
# Import/Package a Large Map
Large maps generated in RoadRunner can be imported into the source build of CARLA and packaged for distribution and usage in a CARLA standalone package. The process is very simlar to that of standard maps with the addition of specific nomenclature for tiles and batch importing.
- [__Files and folders__](#files-and-folders)
- [__Create the JSON description (Optional)__](#create-the-json-description-optional)
- [__Making the import__](#making-the-import)
- [__Package a large map__](#package-a-large-map)
---
## Files and folders
All files to be imported should be placed in the `Import` folder of the root CARLA directory. These files should include:
- The mesh of the map in multiple `.fbx` files representing different tiles of the map.
- The OpenDRIVE definition in a single `.xodr` file.
!!! Warning
You cannot import large maps and standard maps at the same time.
The naming convention of map tiles is very important. Each map tile should be named according to the following convention:
```
<mapName>_Tile_<x-coordinate>_<y-coordinate>.fbx
```
Be aware that a more positive __y coordinate__ refers to a tile lower on the y-axis. For example,`Map01_Tile_0_1` would sit just below `Map01_Tile_0_0`.
>>>>>>>>![map_tiles](../img/map_tiles.png)
A resulting `Import` folder with a package containing a large map made of four tiles should have a structure similar to the one below:
```sh
Import
│
└── Package01
├── Package01.json
├── Map01_Tile_0_0.fbx
├── Map01_Tile_0_1.fbx
├── Map01_Tile_1_0.fbx
├── Map01_Tile_1_1.fbx
└── Map01.xodr
```
!!! Note
The `package.json` file is not strictly necessary. If there is no `package.json` file created, the automated import process will create one. Find out more about to structure your own `package.json` in the next section.
---
## Create the JSON description (Optional)
The `.json` description is created automatically during the import process, but there is also the option to create one manually. An existing `.json` description will override any values passed as arguments in the import process.
The `.json` file should be created in the root folder of the package. The file name will be the package distribution name. The content of the file describes a JSON array of __maps__ and __props__ with basic information for each one.
__Maps__ need the following parameters:
- __name:__ Name of the map. This must be the same as the `.fbx` and `.xodr` files.
- __xodr:__ Path to the `.xodr` file.
- __use_carla_materials:__ If __True__, the map will use CARLA materials. Otherwise, it will use RoadRunner materials.
- __tile_size:__ The size of the tiles. Default value is 2000 (2kmx2km).
- __tiles:__ A list of the `.fbx` tile files that make up the entire map.
__Props__ are not part of this tutorial. Please see [this](tuto_A_add_props.md) tutorial for how to add new props.
The resulting `.json` file should resemble the following:
```json
{
"maps": [
{
"name": "Map01",
"xodr": "./Map01.xodr",
"use_carla_materials": true,
"tile_size": 2000,
"tiles": [
"./Map01_Tile_0_0.fbx",
"./Map01_Tile_0_1.fbx",
"./Map01_Tile_1_0.fbx",
"./Map01_Tile_1_1.fbx"
]
}
],
"props": []
}
```
</details>
<br>
---
## Making the import
When all files have been placed in the `Import` folder, run the following command in the root CARLA folder:
```sh
make import
```
Depending on your system, Unreal Engine may consume too much memory to be able to import all files at once. You can choose to import the files in batches of MB by running the command:
```sh
make import ARGS="--batch-size=200"
```
Two more flags exist for the `make import` command:
- `--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__. Use this flag by running the command:
```sh
make import ARGS="--package=<package_name>"
```
- `--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_M_manual_map_package.md). Any value in the `.json` file will override this flag. Use this flag by running the command:
```sh
make import ARGS="--no-carla-materials"
```
All files will be imported and prepared to be used in the Unreal Editor. The map package will be created in `Unreal/CarlaUE4/Content`. A base map tile, `<mapName>`, will be created as a streaming level for all the tiles. The base tile will contain the sky, weather, and large map actors and will be ready for use in a simulation.
!!! Note
It is currently not recommended to use the customization tools provided for standard maps in the Unreal Editor, e.g., road painter, procedural buildings, etc.
---
## Package a large map
To package your large map so it can be used in the CARLA standalone package, run the following command:
```sh
make package ARGS="--packages=<mapPackage>"
```
This will create a standalone package compressed in a `.tar.gz` file. The files will be saved in the `Dist` folder on Linux, and `/Build/UE4Carla/` on Windows. They can then be distributed and packaged to use in standalone CARLA packages.
---
If you have any questions about the large map import and packaging process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

86
Docs/large_map_overview.md Normal file
View File

@ -0,0 +1,86 @@
# Large maps overview
- [__Large maps overview__](#large-maps-overview)
- [__Tile streaming__](#tile-streaming)
- [__Dormant actors__](#dormant-actors)
---
## Large maps overview
The large map feature in CARLA allows users to perform simulations at a vast scale. In CARLA, large maps are divided into square tiles no larger than 2kmx2km. Tiles are streamed in and out of the server based on their proximity (streaming distance) to the ego vehicle. Other actors on the map are also managed according to their streaming distance from the ego vehicle.
---
## Tile streaming
The ego vehicle is integral to the loading and unloading of map tiles. Tiles are streamed in and out of the server based on the value of the streaming distance from the ego vehicle. For example, tiles located outside the streaming distance will not be rendered in the simulation, and tiles within the streaming distance will be rendered. The rendered tiles will change as the hero vehicle moves.
To set a vehicle as ego, use the [`set_attribute`](python_api.md#carla.ActorBlueprint.set_attribute) method as shown below:
```py
blueprint.set_attribute('role_name', 'hero' )
world.spawn_actor(blueprint, spawn_point)
```
Use the code snippet below to set the streaming distance so tiles will be loaded within a 2km radius of the ego vehicle:
```py
settings = world.get_settings()
settings.tile_stream_distance = 2000
world.apply_settings(settings)
```
You can also set the streaming distance using `config.py`:
```sh
cd PythonAPI/util
python3 config.py --tile-stream-distance 2000
```
!!! Note
Large maps currently supports only one ego vehicle at a time.
---
## Dormant actors
The large map feature introduces the concept of dormant actors to CARLA. Dormant actors exist within the context of large maps only. Dormant actors are non-ego-vehicle actors in the simulation that are located outside of the __actor active distance__ of the ego vehicle, e.g., vehicles far from the ego vehicle. The actor active distance can be equal to or less than the streaming distance.
If an actor finds itself outside of the actor active distance of the ego vehicle, it will become dormant. The actor will still exist, but it will not be rendered. Physics will not be calculated (unless running in hybrid mode via the traffic manager), although [location](python_api.md#carla.Actor.set_location) and [transformation](python_api.md#carla.Actor.set_transform) can still be set. Once the dormant actor comes within actor active distance of the ego vehicle again, it will wake up, and its rendering and physics will resume as normal.
Actors controlled by the Traffic Manager have distinct behaviors that can be configured when operating within a large map. Read more in the [Traffic Manager documentation](adv_traffic_manager.md#traffic-manager-in-large-maps) to find out about how this works.
An actor will become dormant or wake up on a [`world.tick()`](python_api.md#carla.World.tick).
To set the actor active distance to a 2 km radius around the ego vehicle:
```py
settings = world.get_settings()
settings.actor_active_distance = 2000
world.apply_settings(settings)
```
You can also set the actor active distance using `config.py`:
```sh
cd PythonAPI/util
python3 config.py --actor-active-distance 2000
```
To check if an actor is dormant, you can use the Python API:
```py
actor.is_dormant
```
---
If you have any questions about large maps, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

107
Docs/large_map_roadrunner.md Normal file
View File

@ -0,0 +1,107 @@
# Create a Large Map in RoadRunner
RoadRunner is the recommended software to create large maps to be imported into CARLA. This guide outlines what RoadRunner is, things to consider when building the large map and how to export custom large maps ready for importing into CARLA.
- [__Introduction to RoadRunner__](#introduction-to-roadrunner)
- [__Before you start__](#before-you-start)
- [__Build a large map in RoadRunner__](#build-a-large-map-in-roadrunner)
- [__Export a large map in RoadRunner__](#export-a-large-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. It can be used to create road layouts and accompanying OpenDRIVE and geometry information. Find out more about RoadRunner [here][rr_home].
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.
A license for RoadRunner is also available to everyone participating in the CARLA Leaderboard. Click [here][rr_leaderboard] for more information.
[rr_home]: https://www.mathworks.com/products/roadrunner.html
[rr_trial_version]: https://www.mathworks.com/products/roadrunner.html
[rr_eligibility]: https://www.mathworks.com/academia/tah-support-program/eligibility.html
[rr_leaderboard]: https://www.mathworks.com/academia/student-competitions/carla-autonomous-driving-challenge.html
---
## Before you start
You will need to 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
---
## Build a large map in RoadRunner
The specifics of how to build a large map in RoadRunner go beyond the scope of this guide, however, there are video tutorials available in the [RoadRunner documentation][rr_tutorials].
If you are building a large map with elevation, the recommended largest size of the map is 20km by 20km. Maps larger than this may cause RoadRunner to crash on export.
[rr_tutorials]: https://www.mathworks.com/support/search.html?fq=asset_type_name:video%20category:roadrunner/index&page=1&s_tid=CRUX_topnav
---
## Export a large map in RoadRunner
Below is a basic guideline to export your custom large map from RoadRunner.
[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 road layout 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`.
Make sure the full map is selected for export by clicking on the [_World settings tool_](https://www.mathworks.com/help/roadrunner/ref/worldsettingstool.html) and dragging the edges of the blue boundary box to encompass the full area you would like to export. when it's ready, click on _Apply World Changes_.
![world_bounds_settings](img/rr_world_settings.png)
When you are ready to export:
__1.__ Export the `.fbx`:
- In the main toolbar, select `File` -> `Export` -> `Firebox (.fbx)`
__2.__ In the window that pops up:
>- Check the following options:
- _Split by Segmentation_: Divides the mesh by semantic segmentation and imroves pedestrian navigation.
- _Power of Two Texture Dimensions_: Improves performance.
- _Embed Textures_: Ensures textures are embedded in the mesh.
- _Export to Tiles_: Choose the size of the tiles. The maximum size that can be used by CARLA is 2000 x 2000.
- _Export Individual Tiles_: Generates the individual tiles needed for streaming large maps in CARLA.
>>>>>>![export_large_map_fbx](../img/large_map_export_fbx.png)
__3.__ Export the `.xodr`:
- In the main toolbar, select `File` -> `Export` -> `OpendDRIVE (.xodr)`
!!! 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. See the [__Import a Large Map__](large_map_import.md) guide for more details.
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

306
Docs/tuto_A_add_map/add_map_alternative.md
View File

@ -1,306 +0,0 @@
# 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://github.com/carla-simulator/carla/discussions/).

92
Docs/tuto_A_add_map/add_map_source.md
View File

@ -1,92 +0,0 @@
# 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://github.com/carla-simulator/carla/discussions/) 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
View File

@ -1,84 +0,0 @@
# 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
View File

@ -1,59 +0,0 @@
# 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.
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

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_overview.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_M_custom_map_overview.md).
__Props__ need the following parameters.

2
Docs/tuto_A_create_standalone.md
View File

@ -54,7 +54,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_overview.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_M_custom_map_overview.md) or [vehicles](tuto_A_add_vehicle.md).
---

178
Docs/tuto_A_map_customization.md
View File

@ -1,178 +0,0 @@
# Map customization tools
There are several tools provided by the CARLA team that allow users to edit maps at will from the Unreal Editor. This tutorial introduces the most relevant tools, according to their purpose.
* [__Serial meshes__](#add-serial-meshes)
* [BP_RepSpline](#bp_repspline)
* [BP_Spline](#bp_spline)
* [BP_Wall](#bp_wall)
* [BP_SplinePowerLine](#bp_splinepowerline)
* [__Procedural buildings__](#add-serial-meshes)
* [Building structure](#building-structure)
* [Structure modifications](#structure-modifications)
* [__Weather customization__](#weather-customization)
* [BP_Weather](#bp_weather)
* [BP_Sky](#bp_sky)
!!! Important
This tutorial only applies to users that work with a build from source, and have access to the Unreal Editor.
---
## Add serial meshes
There is a series of blueprints in `Carla/Blueprints/LevelDesign` that are useful to add props aligned in one direction. All of them use a series of meshes, and a Bezier curve that establishes the path where the props are placed.
There are differences between them, that make them fit specific purposes. However, the all work the same way. Only the parametrization presents differences.
* __Initialize the series__. The blueprints need a __Static Mesh__ that will be repeated. Initially, only one element will appear, standing on the starting point of a Bezier curve with two nodes, beginning and ending.
* __Define the path__. Press __Alt__ over one of the nodes, to create a new one and modify the curve. A new mesh will appear on every node of the curve, and the space between nodes will be filled with elements __separated by a distance__ measure. Adjust the curve using the weights on every node.
* __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/add_map_source.md#generate-pedestrian-navigation) after doing these changes.
### BP_RepSpline
The blueprint __BP_RepSpline__ adds __individual__ elements along the path defined by a Bezier curve. There are some specificic parameters that change the serialization.
* __Distance between__ — Set the distance between elements.
* __Offset rotation__ — Set a fixed rotation for the different axis.
* __Random rotation__ — Set a range of random rotations for the different axis.
* __Offset translation__ — Set a range of random locations along the different axis.
* __Max Number of Meshes__ — Set the maximum amount of elements that will be place between nodes of the curve.
* __World aligned ZY__ — If selected, the elements will be vertically aligned regarding the world axis.
* __EndPoint__ — If selected, an element will be added in the ending node of the curve.
* __Collision enabled__ — Set the type of collisions enabled for the meshes.
![bp_repspline_pic](img/map_customization/BP_Repspline.jpg)
<div style="text-align: right"><i>BP_RepSpline example.</i></div>
### BP_Spline
The blueprint __BP_Spline__ adds __connected__ elements __strictly__ following the path defined by a Bezier curve. The mesh will be warped to fit the path created.
* __Gap distance__ — Add a separation between elements.
![bp_spline_pic](img/map_customization/BP_Spline.jpg)
<div style="text-align: right"><i>BP_Spline example.</i></div>
### BP_Wall
The blueprint __BP_Wall__ adds __connected__ elements along the path defined by a Bezier curve. The mesh will not be warped to fit the curve, but the nodes will be respected.
* __Distance between__ — Set the distance between elements.
* __Vertically aligned__ — If selected, the elements will be vertically aligned regarding the world axis.
* __Scale offset__ — Scale the length of the mesh to round out the connection between elements.
![bp_wall_pic](img/map_customization/BP_Wall.jpg)
<div style="text-align: right"><i>BP_Wall example.</i></div>
### BP_SplinePowerLine
The blueprint __BP_SplinePowerLine__ adds __electricity poles__ along the path defined by a Bezier curve, and __connects them with power lines__.
This blueprint can be found in `Carla/Static/Pole`. This blueprint allows to set an __array of meshes__ to repeat, to provide variety.
![bp_splinepowerline_pic](img/map_customization/BP_Splinepowerline.jpg)
<div style="text-align: right"><i>BP_SplinePowerLine example.</i></div>
The power line that connects the pole meshes can be customized.
* __Choose the mesh__ that will be used as wire.
* __Edit the tension__ value. If `0`, the power lines will be staight. The bigger the value, the looser the connection.
* __Set the sockets__. Sockets are empty meshes that represent the connection points of the power line. A wire is created form socket to socket between poles. The amount of sockets can be changed inside the pole meshes.
![bp_powerline_socket_pic](img/map_customization/BP_Splinepowerline_Sockets.jpg)
<div style="text-align: right"><i>Visualization of the sockets for BP_SplinePowerLine.</i></div>
!!! Important
The amount of sockets and their names should be consistent between poles. Otherwise, visualization issues may arise.
---
## Procedural buildings
The blueprint __BP_Procedural_Building__ in `Content/Carla/Blueprints/LevelDesign` creates a realistic building using key meshes that are repeated along the structure. For each of them, the user can provide an array of meshes that will be used at random for variety. The meshes are only created once, and the repetitions will be instances of the same to save up costs.
!!! Note
Blueprints can be used instead of meshes, to allow more variety and customization for the building. Blueprints can use behaviour trees to set illumination inside the building, change the materials used, and much more.
### Building structure
The key meshes will be updated everytime a change is made, and the building will disappear. Enable `Create automatically` or click on `Create Building` to see the new result.
These key meshes can be percieved as pieces of the building's structure. They can be grouped in four categories.
* __Base__ — The ground floor of the building.
* __Body__ — The middle floors of the building.
* __Top__ — The highest floor of the building.
* __Roof__ — Additional mesh that used to fill the spaces in the middle of the top floor.
For each of them, except the __Roof__, there is a mesh to fill the center of the floor, and a __Corner__ mesh that will be placed on the sides of the floor. The following picture represents the global structure.
![bp_procedural_building_visual](img/map_customization/BP_Procedural_Building_Visual.jpg)
<div style="text-align: right"><i>Visualization of the building structure.</i></div>
The __Base parameters__ set the dimensions of the building.
* __Num Floors__ — Floors of the building. Repetitions of the __Body__ meshes.
* __Length X and Length Y__ — Area of the building. Repetitions of the central meshes for each side of the building.
![bp_procedural_building_full](img/map_customization/BP_Procedural_Building_Full.jpg)
<div style="text-align: right"><i>Example of BP_Procedural_Building.</i></div>
### Structure modifications
There are some additional options to modify the general structure of the building.
* __Disable corners__ — If selected, no corner meshes will be used.
* __Use full blocks__ — If selected, the structure of the building will use only one mesh per floor. No corners nor repetitions will appear in each floor.
* __Doors__ — Meshes that appear in the ground floor, right in front of the central meshes. The amount of dloors and their location can be set. `0` is the initial position, `1` the next base repetition, and so on.
* __Walls__ — Meshes that substitute one or more sides of the building. For example, a plane mesh can be used to paint one side of the building.
![bp_procedural_building_extras](img/map_customization/BP_Procedural_Building_Extras.jpg)
<div style="text-align: right"><i>On the left, a building with no cornes and one door. <br> On the right, a building with a wall applied to one side of the building. The wall is a texture with no fire escape.</i></div>
---
## Weather customization
The weather can be easily customized by the users in CARLA using the PythonAPI. However, there is some configuration that users can do in order to set the default weather for a map. The weather parameters available for configuration by the following blueprints, are the same accessible from the API. These are described [here](https://carla.readthedocs.io/en/latest/python_api/#carlaweatherparameters).
### BP_Weather
This blueprint is loaded into the world when the simulation starts. It contains the default weather parameters for every map, and these can be modified at will.
__1. Open the BP_Weather__ in `Content/Carla/Blueprints/Weather`.
__2. Go to the Weather group__ in the blueprint.
__3. Choose the desired town__ and modify the parameters.
![bp_weather_pic](img/map_customization/BP_Weather.jpg)<br>
<div style="text-align: right">
<i>Array containing default weather parameters for every CARLA map. Town01 opened.</i></div>
### BP_Sky
This blueprint groups all the weather parameters. It can be loaded into the scene when there is no CARLA server running, and used to ea test different configurations before setting a new default weather.
__1. Find the BP_Sky__ in `Content/Carla/Blueprints/Weather`.
__2. Load the blueprint in the scene.__ Drag it into the scene view.
__3. Edit the weather parameters.__ The weather in the scene will be updated accordingly.
!!! Important
If more than one blueprint is loaded into the scene, the weather will be duplicated with weird results, such as having two suns.
---
That is all there is so far, regarding the different map customization tools available in CARLA.
Open CARLA and mess around for a while. If there are any doubts, feel free to post these in the forum.
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

140
Docs/tuto_A_material_customization.md
View File

@ -5,12 +5,8 @@ The CARLA team prepares every asset to run under certain default settings. Howev
* [__Car materials__](#car-materials)
* [__Customize car materials__](#customize-car-materials)
* [Exterior properties](#exterior-properties)
* [__Building material__](#building-material)
* [__Building materials__](#building-materials)
* [__Customize a building material__](#customize-a-building-material)
* [__Customize the road__](#customize-the-road)
* [Create a group material](#create-a-group-material)
* [Change the appearance of the road](#change-the-appearance-of-the-road)
* [Update the appearance of lane markings](#update-the-appearance-of-lane-markings)
!!! Important
This tutorial only applies to users that work with a build from source, and have access to the Unreal Editor.
@ -112,6 +108,8 @@ The materials applied to buildings are made of four basic textures that are comb
* `RGB` — Channels with the base colors.
* `Alpha` — This channel defines a mask that allows to modify the color of the portions in white. This is useful to create some variations from the same material.
![building_diffuse_alpha](img/building_diffuse_alpha.png)
* __ORME__ — Maps different properties of the material using specific channels.
* `Ambient occlusion` — Contained in the `R` channel.
* `Roughness` — Contained in the `G` channel.
@ -124,16 +122,22 @@ The materials applied to buildings are made of four basic textures that are comb
* __Emissive__ — If applicable, this texture is used to set the emissive base colors of the texture.
* `RGB` — Color information for the emissive elements in the texture.
![emissive](img/EmissiveIntensity.gif)
---
## Customize a building material
Similarly to car materials, a building material can be greatly changed if desired, but it is only recommended if the user has some expertise with Unreal Engine. However, there is some customization available for the two main shaders that buildings use.
* __Glass shader__ — `M_CarWindows_Master`.
![building_material](img/building_material.png)
* __Glass shader__ — `M_GlassMaster`.
* `Opacity` — Enable color changes on the white area on the __Diffuse__ `Alpha` texture.
* `Color` — Tint to be applied based on the white area on the __Diffuse__ `Alpha` texture.
* __Building shader__ — `M_Building_Master`
* __Building shader__ — `M_MaterialMaster`
* `Change Color` — Enable color changes on the white area on the __Diffuse__ `Alpha` texture.
* `Color` — Tint to be applied based on the white area on the __Diffuse__ `Alpha` texture.
* `Emissive Texture` — Enable the usage of an __Emissive__ texture.
@ -143,128 +147,6 @@ Similarly to car materials, a building material can be greatly changed if desire
* `MetallicCorrection` — Changes the intensity of the metallic map.
* `NormalFlatness` — Changes the intensity of the normal map.
---
## Customize the road
__RoadPainter__ is a tool that uses OpenDRIVE information to paint roads. To be able to do so, a blueprint is used, which uses a master material, a render target of the road as canvas, and additional decals and meshes. The master material grous a collection of materials that will be used by the blueprint, using brushes to blend their application.
This makes for an easy way to change drastically the appearence of the road. The initial geometry of the road is painted like a canvas. There is no need to apply photometry techniques nor consider the UVs of the geometry. The result is achieved simply by blending textures and creating masks.
### Create a group material
First of all, a group material will be created. This will contain the instances of the materials the road will be painted with.
__1. Create an instance of the RoadMaster material.__ It can be found in `Game/Carla/Static/GenericMaterials/RoadPainterMaterials`.
![materials_RoadMaster_Materials](img/material_customization/Materials_RoadMaster.jpg)
<div style="text-align: right"><i>Panel to set materials to be applied on the road.</i></div>
__2. Set the `RenderTarget`.__ [Create a render target](https://docs.unrealengine.com/en-US/Engine/Rendering/RenderTargets/BlueprintRenderTargets/HowTo/CreatingTextures/index.html) for the road map that is being used. In `Texture Parameter Values` enable `Texture mask` and add the texture.
![materials_RoadMaster_RenderTarget](img/material_customization/Materials_RenderTarget.jpg)
<div style="text-align: right"><i>Panel where the Render Target should be set.</i></div>
__3. Set the map size.__ In `Scalar Parameter Values` the field `Map units (CM)`. If the size is not known, use a temporary value. The real size of the map can be retrieved later, when using the blueprint.
__4. Choose the materials to be applied.__ There is space for one base material and three additional materils that will be used to paint over the base one. The painting information will be stored in the RGB channels of a RenderTarget, one channel per material. Add them to the fields `Base Material`, `Material 1`, `Material 2`, and `Material 3`.
### Change the appearance of the road
The appearence of the road is changed using a blueprint provided by CARLA. The blueprint will paint the road using the materials passed, combined with some brush settings. Additionally, decals and meshes can be added so that the final result is more detailed. This tool takes into account road information and will paint the elements using the orientation of the lane, unless an offset is stated.
!!! Note
This tool does not interfere with the weather settings that change the road's appearence, such as wetness or precipitation.
__1. Create an instance of the RoadPainter blueprint.__ It can be found in `Carla/Blueprints/LevelDesign`. This blueprint determines how is the road being painted, and how are the materials in `RoadMaster` being used.
__2. Set the `RenderTarget` and the `Map size`.__ In the `Paint` category. These must be the same as in the __RoadMaster__ material.
![materials_RoadPaint_MatchSize](img/material_customization/Materials_Road_Matchsize.jpg)
<div style="text-align: right"><i>Panels in group material and road blueprint where the Render Target and Map Size values should match.</i></div>
!!! Note
The `Z-size` option in the `Default` panel will give you the exact size of the map. Increase this by a little and make sure both, the blueprint and the master material have the same value.
__3. Apply the group material.__ Select all the road meshes and apply the instance.
__4. For each material, set the brush to be used.__ There are different brushes available in `GenericMaterials/RoadStencil/Alphas`. The materials will be applied over the road using the brush and parameters stated here.
* `Stencil size` — Size of the brush.
* `Brush strength` — Roughness of the outline.
* `Spacebeween Brushes` — Distance between strokes.
* `Max Jitter` — Size variation of the brush between strokes.
* `Stencil` — The brush to be used.
* `Rotation` — Rotation applied to the stroke.
![materials_roadpaint_brushes](img/material_customization/Materials_Brush.jpg)
<div style="text-align: right"><i>Brush panel.</i></div>
![materials_roadpaint_typesofbrushes](img/material_customization/Materials_Road_Typesofbrushes.jpg)
<div style="text-align: right"><i>Different types of brushes.</i></div>
__5. For each material, apply it to the desired portions of the road.__ In the `Default` section, there is a series of buttons to choose how materials are applied.
* `Paint all roads` — Applies the brush to all the road.
* `Paint by actor` — Paints a specific actor being selected.
* `Paint over circle` — Paints using a circular pattern, useful to provide variation.
* `Paint over square` — Paints using a square pattern, useful to provide variation.
This section also contains options to erase the changes applied.
* `Clear all` — Erases all the painting applied by the blueprint.
* `Clear materials` — Remove the materials currently active.
* `Clear material by actor` — Removes material closest to the actor selected.
![materials_roadpaint_brushes](img/material_customization/Materials_RoadPainter_Default.jpg)
<div style="text-align: right"><i>Different painting and erasing options.</i></div>
!!! Note
Move the editor view a little for the changes to be visible.
__5. Add decals and meshes.__ Add the elements to the corresponding array and set some basic parameters for how should these be spawned over the road.
* `Decal/Mesh Scale` — Scale of the decal/mesh per axis.
* `Fixed Decal/Mesh Offset` — Deviation from the center of the lane per axis.
* `Decal/Mesh Random Offset` — Max deviation from the center of the lane per axis.
* `Decal/Mesh Random Yaw` — Max random yaw rotation.
* `Decal/Mesh Min Scale` — Minimum random scale applied to the decal/mesh.
* `Decal/Mesh Max Scale` — Max random scale applied to the decal/mesh.
![materials_](img/material_customization/Materials_DecalsMeshes.jpg)
<div style="text-align: right"><i>Decals and Meshes panels.</i></div>
__6. Spawn the decals and meshes.__ Use the buttons `Spawn decals` and `Spawn meshes` to do so.
__7. Play around.__ Try different settings, materials and brushes to obtain completely different results. This tool allows to create different presets for the road appearence and changing between them simply by changing the group material and updating a few settings.
Here is an example of the how the appearence of the road changes along the previous steps.
![materials_roadpaint_mat00](img/material_customization/Materials_Road_MaterialBase.jpg)
<div style="text-align: right"><i>Example of base road material.</i></div>
![materials_roadpaint_mat01](img/material_customization/Materials_Road_Material1.jpg)
<div style="text-align: right"><i>Example after material 1 is applied.</i></div>
![materials_roadpaint_mat02](img/material_customization/Materials_Road_Material2.jpg)
<div style="text-align: right"><i>Example after material 2 is applied.</i></div>
![materials_roadpaint_mat03](img/material_customization/Materials_Road_Material3.jpg)
<div style="text-align: right"><i>Example after material 3 is applied.</i></div>
![materials_roadpaint_mat03](img/material_customization/Materials_Road_Decals.jpg)
<div style="text-align: right"><i>Example after decals are applied.</i></div>
![materials_roadpaint_mat03](img/material_customization/Materials_Road_Meshes.jpg)
<div style="text-align: right"><i>Example after meshes are applied.</i></div>
### Update the appearance of lane markings
After the road's appearance has been customized, the lane markings should be updated accordingly to get a realistic look. The process to do so, is really simple.
__1. Create a copy of the group material.__ This has be the same as it was for the road.
__2. Select the lane marking meshes.__
__3. Mark them as lane markings.__ In `Static Switch Parameter Values` enable `LaneMark`. This will update the lane markings to be consistent to the painting applied to the road.
__4. Choose the color of the lane marking.__ In `Texture` set the `LaneColor` to the value desired. This will set the lane markings selected to have a base paint of the stated color.
---
That is a wrap on the most remarkable ways users can customize the materials of vehicles and buildings.

68
Docs/tuto_D_generate_pedestrian_navigation.md
View File

@ -1,68 +0,0 @@
# How to generate the pedestrian navigation info
The pedestrians to walk need information about the map in a specific format. That file that describes the map for navigation is a binary file with extension `.BIN`, and they are saved in the **Nav** folder of the map. Each map needs a `.BIN` file with the same name that the map, so automatically can be loaded with the map.
This `.BIN` file is generated from the Recast & Detour library and has all the information that allows pathfinding and crow management.
If we need to generate this `.BIN` file for a custom map, we need to follow this process:
* Export the map meshes
* Rebuild the `.BIN` file with RecastBuilder
* Copy the `.BIN` file in a `Nav/` folder with the map
---
## Export meshes
We have several types of meshes for navigation. The meshes need to be identified as one of those types, using specific nomenclature.
| Type | Start with | Description |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Ground | `Road_Sidewalk` | Pedestrians can walk over these meshes freely (sidewalks...). |
| Grass | `Road_Crosswalk` | Pedestrians can walk over these meshes but as a second option if no ground is found. |
| Road | `Road_Grass` | Pedestrians won't be allowed to walk on it unless we specify some percentage of pedestrians that will be allowed. |
| Crosswalk | `Road_Road`, `Road_Curb`, `Road_Gutter`, `Road_Marking` | Pedestrians can cross the roads only through these meshes. |
| Block | Any other name | Pedestrians will avoid these meshes always (are obstacles like traffic lights, trees, houses...). |
<br>
For instance, all road meshes need to start with `Road_Road` e.g: `Road_Road_Mesh_1`, `Road_Road_Mesh_2`...
This nomenclature is used by RoadRunner when it exports the map, so we are just following the same.
Also, we don't need to export meshes that are not of interest by the navigation system, like landscapes where pedestrians will not walk, or UE4's _sky domes_, rivers, lakes and so on.
We can **tag** any mesh with the name **NoExport** and then the exporter will ignore that mesh.
Once we have all meshes with the proper nomenclature and tagged the ones that we want to ignore, we can call the Carla Exporter that is found under the `File > Actors > Carla Exporter`:
![Carla Exporter](img/tuto_D_pedestrian_CarlaExporter.jpg)
The `.OBJ` file will be saved with the name of the map with extension OBJ in the **CarlaUE4/Saved** folder of UE4.
---
## Rebuild the navigation binary
With Recast & Detour library comes an executable file that needs to be used to generate the final `.BIN` file.
The executable uses by default the parameters to work on Carla, and you only need to pass as parameter the `.OBJ` you exported above, and the `.BIN` will be created.
You can find the executable, on the `Carla/Build/recast-{version}-install/bin/` folder, already compiled when Carla was installed.
Run:
```sh
$ RecastBuilder test.object
```
And it will create a `test.bin` file, that needs to be copied to the map folder, inside the `Nav/` folder.
For example, this would be the structure of files of a Test map:
```
Test/
├─ Test.umap
├─ Nav/
│ └─ Test.bin
└─ OpenDrive/
└─ Test.xodr
```

171
Docs/tuto_M_add_map_alternative.md Normal file
View File

@ -0,0 +1,171 @@
# Alternative methods to import maps
This guide describes alternative methods to import maps into CARLA. These methods involve more manual steps than the processes described in the [package](tuto_M_add_map_package.md) and [source](tuto_M_add_map_source.md) import guides. First we will describe the RoadRuner plugin and then the manual import method.
- [__RoadRunner plugin import__](#roadrunner-plugin-import)
- [__Manual import__](#manual-import)
---
## 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.
---
## 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)
---
## Next steps
You will now be able to open your map in the Unreal Editor and run simulations. From here, you will be able to customize the map and generate the pedestrian navigation data. We recommend generating the pedestrian navigation after all customization has finished, so there is no chance of obstacles blocking the pedestrian paths.
CARLA provides several tools and guides to help with the customization of your maps:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
It is recommended to use the automated processes for importing maps detailed in the guides for [CARLA packages](tuto_M_add_map_package.md) and [CARLA source build](tuto_M_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://github.com/carla-simulator/carla/discussions).

14
Docs/tuto_A_add_map/add_map_package.md → Docs/tuto_M_add_map_package.md
View File

@ -14,16 +14,16 @@ This process is only available for Linux systems. The import process involves ru
- 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
- Minimum 700 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
[source_ingest]: tuto_M_add_map_source.md
[import_map_package]: tuto_M_add_map_package.md
[rr_generate_map]: tuto_M_generate_map.md
---
## Map ingestion in a CARLA package
@ -44,7 +44,7 @@ __3.__ Create an `input_folder`. This is where you will put the files to be imp
```
> !!! Note
This is not necessary if the package is [prepared manually](add_map_deprecated.md#manual-package-preparation), and contains a `.json` file already.
This is not necessary if the package is [prepared manually](tuto_M_manual_map_package.md), 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.
@ -74,4 +74,8 @@ __7.__ To run a simulation with the new map, run CARLA and then change the map u
---
<<<<<<< HEAD:Docs/tuto_M_add_map_package.md
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://github.com/carla-simulator/carla/discussions) 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.
=======
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://github.com/carla-simulator/carla/discussions/) 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.
>>>>>>> ae0ba81b9fb32ac8a09adf1a1ad77564f3174a15:Docs/tuto_A_add_map/add_map_package.md

71
Docs/tuto_M_add_map_source.md Normal file
View File

@ -0,0 +1,71 @@
# 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]: tuto_M_add_map_package.md
- [__Before you begin__](#before-you-begin)
- [__Map ingestion__](#map-ingestion)
- [__Next steps__](#next-steps)
---
## 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]: tuto_M_add_map_package.md
[rr_generate_map]: tuto_M_generate_map.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
```
__Note that there are two optional 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__. Use this flag by running the command:
```sh
make import ARGS="--package=<package_name>"
```
- `--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_M_manual_map_package.md). Any value in the `.json` file will override this flag. Use this flag by running the command:
```sh
make import ARGS="--no-carla-materials"
```
A folder will be created in `Unreal/CarlaUE4/Content` with the name of your map package. It will contain config files, overdrive information, static asset information and navigation information.
---
## Next steps
You will now be able to open your map in the Unreal Editor and run simulations. From here, you will be able to customize the map and generate the pedestrian navigation data. We recommend generating the pedestrian navigation after all customization has finished, so there is no chance of obstacles blocking the pedestrian paths.
CARLA provides several tools and guides to help with the customization of your maps:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).

63
Docs/tuto_M_custom_add_tl.md Normal file
View File

@ -0,0 +1,63 @@
# Customizing maps: Traffic Lights and Signs
This guide explains how to add traffic lights and signs to your custom map, configure the area of influence of each one, and how to configure traffic lights as a group at junctions. This option is only available to users who have access to the Unreal Engine editor.
- [__Traffic Lights__](#traffic-lights)
- [__Traffic signs__](#traffic-signs)
- [__Next steps__](#next-steps)
---
## Traffic lights
To add traffic lights to your new map:
__1.__ From the _Content Browser_, navigate to `Content/Carla/Static/TrafficLight/StreetLights_01`. You will find several different traffic light blueprints to choose from.
__2.__ Drag the traffic lights into the scene and position them in the desired location. Press the space bar on your keyboard to toggle between positioning, rotation, and scaling tools.
__3.__ Adjust the [`trigger volume`][triggerlink] for each traffic light by selecting the _BoxTrigger_ component in the _Details_ panel and adjusting the values in the _Transform_ section. This will determine the traffic light's area of influence.
>>![ue_trafficlight](../img/ue_trafficlight.jpg)
__4.__ For junctions, drag the `BP_TrafficLightGroup` actor into the level. Assign all the traffic lights in the junction to the traffic light group by adding them to the _Traffic Lights_ array in the _Details_ panel.
>>![ue_tl_group](../img/ue_tl_group.jpg)
__5.__ Traffic light timing is only configurable through the Python API. See the documentation [here](core_actors.md#traffic-signs-and-traffic-lights) for more information.
>>![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
---
## Traffic signs
To add traffic lights to your new map:
__1.__ From the _Content Browser_, navigate to `Content/Carla/Static/TrafficSign`. You will find several different traffic light blueprints to choose from.
__2.__ Drag the traffic lights into the scene and position them in the desired location. Press the space bar on your keyboard to toggle between positioning, rotation, and scaling tools.
__3.__ Adjust the [`trigger volume`][triggerlink] for each traffic sign by selecting the _BoxTrigger_ component in the _Details_ panel and adjusting the values in the _Transform_ section. This will determine the traffic light's area of influence. Not all traffic signs have a trigger volume. Those that do, include the yield, stop and speed limit signs.
---
## Next steps
Continue customizing your map using the tools and guides below:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).

78
Docs/tuto_M_custom_buildings.md Normal file
View File

@ -0,0 +1,78 @@
# Customizing Maps: Procedural Buildings
- [__Procedural buildings__](#add-serial-meshes)
- [Building structure](#building-structure)
- [Structure modifications](#structure-modifications)
- [__Next steps__](#next-steps)
---
## Procedural buildings
The procedural building tool allows you to create rectangular buildings composed of different levels. Each level is built using a configurable array of meshes or a single blueprint. If an array of meshes is used, each mesh will be repeated along the level at random to provide variety. The meshes are created once and each repition will be an instance of that mesh. This improves performance of your map.
### Building structure
To get started on your building:
1. In the _Content Browser_ of the Unreal Engine editor, navigate to `Content/Carla/Blueprints/LevelDesign`.
2. Drag the `BP_Procedural_Building` into the scene.
In the _Details_ panel, you will see all the options available to customize your building. Every time a change is made here, the building will disappear from the scene view, as the key meshes are updated. Click on _Create Building_ to see the new result, or enable _Create automatically_ to avoid having to repeat this step.
The key meshes are pieces of the building's structure. They fall into four categories:
- __Base:__ The ground floor.
- __Body:__ The middle floors.
- __Top:__ The highest floor.
- __Roof:__ The roof that covers the top floor.
For each of them, except the __Roof__, there is a mesh to fill the center of the floor, and a __Corner__ mesh that will be placed on the sides of the floor. The following picture represents the global structure.
![bp_procedural_building_visual](../img/map_customization/BP_Procedural_Building_Visual.jpg)
<div style="text-align: right"><i>Visualization of the building structure.</i></div>
The __Base parameters__ set the dimensions.
- __Num Floors:__ Floors of the building. Repetitions of the __Body__ meshes.
- __Length X and Length Y:__ Length and breadth of the building. Repetitions of the central meshes for each side of the building.
![bp_procedural_building_full](../img/map_customization/BP_Procedural_Building_Full.jpg)
<div style="text-align: right"><i>Example of BP_Procedural_Building.</i></div>
### Structure modifications
There are some additional options to modify the general structure of the building.
- __Disable corners:__ If selected, no corner meshes will be used.
- __Use full blocks:__ If selected, the structure of the building will use only one mesh per floor. No corners nor repetitions will appear in each floor.
- __Doors:__ Meshes that appear in the ground floor, right in front of the central meshes. The amount of doors and their location can be set. `0` is the initial position, `1` the next base repetition, and so on.
- __Walls:__ Meshes that substitute one or more sides of the building. For example, a plane mesh can be used to paint one side of the building.
![bp_procedural_building_extras](../img/map_customization/BP_Procedural_Building_Extras.jpg)
<div style="text-align: right"><i>On the left, a building with no cornes and one door. <br> On the right, a building with a wall applied to one side of the building. The wall is a texture with no fire escape.</i></div>
---
## Next steps
Continue customizing your map using the tools and guides below:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

89
Docs/tuto_M_custom_layers.md Normal file
View File

@ -0,0 +1,89 @@
# Customizing Maps: Layered Maps
Utilizing levels in your custom map enables multiple people to work on a single map concurrently. It also allows you to use the Python API to load and unload layers on your map during a simulation, just like the [layered CARLA maps](core_map.md#layered-maps).
This guide will explain how to add a new level, how to add assets to a level, and how to configure a level to be always loaded or not.
- [__Add a new level__](#add-a-new-level)
- [__Add assets to a level__](#add-assets-to-a-level)
- [__Configure level loading options__](#configure-level-loading-options)
- [__Next steps__](#next-steps)
---
## Add a new level
All new levels in your map will be nested within the parent level, known as the _Persistent Level_. To create a new level:
__1. Open the levels panel.__
1. In the Unreal Engine editor, open _Window_ from the menu bar.
2. Click on _Levels_.
__2. Create a new level.__
1. In the _Levels_ panel, click on _Levels_ and select _Create New..._.
2. Choose _Empty Level_.
3. Save the level in `Content/Carla/Maps/Sublevels/<map_name>/`. To integrate the level with the CARLA Python API, use the naming convention `<map_name>_<layer_name>`, e.g., `TutorialMap_Buildings`. For a list of available layers, check [here](core_map.md#carla-maps).
>>>>>>![create new level](/img/new_level.png)
---
## Add assets to a level
__1. Select the level to which you want to add assets__.
In the _Levels_ panel, double-click the level to which you would like to add assets. Make sure the level is unlocked by toggling the lock icon.
__2. Select the assets to add.__
1. Select all the assets you would like to add to the level.
2. Right-click and go to _Level_.
3. Click on _Move Selection to Current Level_.
__3. Save the level.__
If a level has pending changes to save, you will see a pencil icon next to it in the _Levels_ panel. Click this to save the changes.
![moving assets](/img/move_assets.png)
---
## Configure level loading options
Levels can be configured to be able to be toggled or to be always loaded. To configure the level for either option:
1. Right-click the level in the _Levels_ panel and go to _Change Streaming Method_.
2. Choose the desired setting:
1. _Always Loaded_: The level __will not be able__ to be toggled via the Python API.
2. _Blueprint_: The level __will be able__ to be toggled via the Python API. A blue dot will appear beside the level name.
Regardless of the setting, you will still be able to toggle the level in the editor by pressing the eye icon.
>>>>>>![levels](/img/levels.png)
---
## Next steps
Continue customizing your map using the tools and guides below:
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

80
Docs/tuto_M_custom_map_overview.md Normal file
View File

@ -0,0 +1,80 @@
# 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 whether you are using a packaged version of CARLA or a version built from source. This section gives an overview of what you need to start the process, the different options available to import, and customization and pedestrian navigation tools available.
- [__Overview__](#overview)
- [__Generation__](#generation)
- [__Importation__](#importation)
- [__Customization__](#customization)
- [__Generate pedestrian navigation__](#generate-pedestrian-navigation)
---
## Overview
Using custom maps in CARLA involves four main processes:
1. Generation
2. Importation
3. Customization
4. Pedestrian Navigation
Read on further for additional general information on each process.
---
## Generation
CARLA requires map geometry information in `.fbx` format and OpenDRIVE information in `.xodr` format. The current recommended software to generate these files is RoadRunner.
__[This guide](tuto_M_generate_map.md) explains how to use RoadRunner to generate the map information.__
---
## Importation
There are several ways to import your map into CARLA.
If you are using a __package version__ of CARLA, you will import your map using Docker. This option is only available in Linux, and you will not have the ability to customize the map using the Unreal Editor. __You will find the guide [here](tuto_M_add_map_package.md).__
If you are using a __source build__ version of CARLA, there are three methods available to import your map:
1. Using the automatic `make import` process (recommended). __You will find the guide [here](tuto_M_add_map_source.md).__
2. Using the RoadRunner plugin. __You will find the guide [here](tuto_M_add_map_alternative.md#roadrunner-plugin-import).__
3. Manually importing the map into Unreal Engine. __You will find the guide [here](tuto_M_add_map_alternative.md#manual-import).__
The following video explains some of the methods available to import maps into CARLA:
<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>
---
## Customization
As well as hundreds of static meshes ready to be added to the landscape, CARLA provides several tools and guides to help you customize your map:
- __Add sub-levels:__ Sub-levels will allow multiple people to work on the same map at the same time. They will also allow you to toggle layers of your map with the Python API, just like the CARLA layered maps. __You will find the guide [here](tuto_M_custom_layers.md).__
- __Set default weather:__ Experiment with different weather presets, and when you find the right combination, set the default weather for your map. __You will find the guide [here](tuto_M_custom_weather_landscape.md#weather-customization).__
- __Populate landscape:__ Use blueprints to populate the landscape with repeating meshes such as street lights, power lines, and walls. __You will find the guide [here](tuto_M_custom_weather_landscape.md#add-serial-meshes).__
- __Paint the roads:__ Paint the roads with a master material that blends different textures. Add decals and meshes such as fallen leaves, cracks, or manholes. __You will find the guide [here](tuto_M_custom_road_painter.md).__
- __Add procedural buildings:__ Add buildings with a custom size, amount of floors, and variable mesh combinations using the procedural building blueprint. __You will find the guide [here](tuto_M_custom_buildings.md).__
- __Add traffic lights and signs:__ Add traffic lights and signs and configure their area of influence. Group traffic lights at junctions. __You will find the guide [here](tuto_M_custom_add_tl.md).__
---
## Generate pedestrian navigation
For pedestrians to be spawned and navigate the map, you need to generate the pedestrian navigation information using the tool provided by CARLA. Pedestrian navigation should be generated after you complete the customization of your map so that obstacles are not created over the top of navigation paths. __You can find the guide [here](tuto_M_generate_pedestrian_navigation.md).__
---
If you have any questions about the above process, feel free to post these in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

240
Docs/tuto_M_custom_road_painter.md Normal file
View File

@ -0,0 +1,240 @@
# Customizing Maps: Road Painter
This guide explains what the road painter tool is, how to use it to customize the appearance of the road by combining different textures, how to add decals and meshes and how to update the appearance of lane markings according to the road texture.
- [__What is the road painter?__](#what-is-the-road-painter)
- [__Before you begin__](#before-you-begin)
- [__Establish the road painter, master material and render target__](#establish-the-road-painter-master-material-and-render-target)
- [__Prepare the master material__](#prepare-the-master-material)
- [__Paint the road__](#paint-the-road)
- [__Update the appearance of lane markings__](#update-the-appearance-of-lane-markings)
- [__Next steps__](#next-steps)
---
## What is the road painter?
The Road Painter tool is a blueprint that uses OpenDRIVE information to paint roads quickly. It takes a master material and applies it to a render target of the road to use as a canvas. The master material is made up of a collection of materials that can be blended using brushes and applied as masks. There is no need to apply photometry techniques nor consider the UVs of the geometry.
---
## Before you begin
The road painter uses the OpenDRIVE information to paint the roads. Make sure that your `.xodr` file has the same name as your map for this to work correctly.
---
## Establish the road painter, master material and render target
__1. Create the `RoadPainter` actor.__
1. In the _Content Browser_, navigate to `Content/Carla/Blueprints/LevelDesign`.
2. Drag the `RoadPainter` into the scene.
__2. Create the Render Target.__
1. In the _Content Browser_, navigate to `Content/Carla/Blueprints/LevelDesign/RoadPainterAssets`.
2. Right-click on the `RenderTarget` file and select `Duplicate`.
3. Rename to `Tutorial_RenderTarget`.
__3. Create the master material instance.__
1. In the _Content Browser_, navigate to `Game/Carla/Static/GenericMaterials/RoadPainterMaterials`.
2. Right-click on `M_RoadMaster` and select _Create Material Instance_.
3. Rename to `Tutorial_RoadMaster`.
__4. Re-calibrate the _Map Size (Cm)_ so that it is equal to the actual size of the map.__
1. Select the `RoadPainter` actor in the scene.
2. Go to the _Details_ panel and press the _Z-Size_ button. You will see the value in _Map Size (Cm)_ change.
>>>>>![map size](/img/map_size.png)
__5. Synchronize the map size between the `RoadPainter` and `Tutorial_RoadMaster`.__
1. In the _Content Browser_, open `Tutorial_RoadMaster`.
2. Copy the value _Map Size (Cm)_ from the previous step and paste it to _Global Scalar Parameter Values -> Map units (CM)_ in the `Tutorial_RoadMaster` window.
3. Press save.
>>>>>>![img](/img/map_size_sync.png)
__6. Create the communication link between the road painter and the master material.__
The `Tutorial_RenderTarget` will be the communication link between the road painter and `Tutorial_RoadMaster`.
1. In the `Tutorial_RoadMaster` window, apply the `Tutorial_RenderTarget` to _Global Texture Parameter Values -> Texture Mask_.
2. Save and close.
3. In the main editor window, select the road painter actor, go to the _Details_ panel and apply the `Tutorial_RenderTarget` to _Paint -> Render Target_.
---
## Prepare the master material
The `Tutorial_RoadMaster` material you created holds the base material, extra material information, and parameters that will be applied via your `Tutorial_RenderTarget`. You can configure one base material and up to three additional materials.
>>![master materials](/img/master_material.png)
To configure the materials, double-click the `Tutorial_RoadMaster` file. In the window that appears, you can select and adjust the following values for each material according to your needs:
- Brightness
- Hue
- Saturation
- AO Intensity
- NormalMap Intensity
- Roughness Contrast
- Roughness Intensity
You can change the textures for each material by selecting the following values and searching for a texture in the search box:
- Diffuse
- Normal
- ORMH
Explore some of the CARLA textures available in `Game/Carla/Static/GenericMaterials/Asphalt/Textures`.
---
### Paint the road
__1. Create the link between the road painter and the roads.__
1. In the main editor window, search for `Road_Road` in the _World Outliner_ search box.
2. Press `Ctrl + A` to select all the roads.
3. In the _Details_ panel, go to the _Materials_ section and apply `Tutorial_RoadMaster` to _Element 0_, _Element 1_, _Element 2_, and _Element 3_.
__2. Choose the material to customize.__
Each of the materials we added to `Tutorial_RoadMaster` are applied to the roads separately and application is configured with the _Brush_ tool. To apply and customize a material:
1. Select the road painter actor
2. In the _Details_ panel, select the material to work with in the _Mask Color_ dropdown menu.
>>>>>>![choose material](/img/choose_material.png)
__3. Set the brush and stencil parameters.__
There are a variety of stencils to choose from in `GenericMaterials/RoadStencil/Alphas`. The stencil is used to paint the road according to your needs and can be adjusted using the following values:
- _Stencil size_ — Size of the brush.
- _Brush strength_ — Roughness of the outline.
- _Spacebeween Brushes_ — Distance between strokes.
- _Max Jitter_ — Size variation of the brush between strokes.
- _Stencil_ — The brush to use.
- _Rotation_ — Rotation applied to the stroke.
>>>>>>![materials_roadpaint_brushes](../img/material_customization/Materials_Brush.jpg)
<div style="text-align: right"><i>Brush panel.</i></div>
<br>
![materials_roadpaint_typesofbrushes](../img/material_customization/Materials_Road_Typesofbrushes.jpg)
<div style="text-align: right"><i>Different types of brushes.</i></div>
<br>
__4. Apply each material to the desired portions of the road.__
Choose where to apply the selected material via the buttons in the _Default_ section of the _Details_ panel:
* _Paint all roads_ — Paint all the roads.
* _Paint by actor_ — Paint a specific, selected actor.
* _Paint over circle_ — Paint using a circular pattern, useful to provide variation.
* _Paint over square_ — Paint using a square pattern, useful to provide variation.
This section also contains options to erase the applied changes.
* _Clear all_ — Erase all the painted material.
* _Clear materials_ — Remove the currently active materials.
* _Clear material by actor_ — Remove the material closest to the selected actor.
>>>>>>![materials_roadpaint_brushes](../img/material_customization/Materials_RoadPainter_Default.jpg)
<div style="text-align: right"><i>Different painting and erasing options.</i></div>
<br>
__5. Add decals and meshes.__
You can explore the available decals and meshes in `Content/Carla/Static/Decals` and `Content/Carla/Static`. Add them to road painter by extending and adding to the _Decals Spawn_ and _Meshes Spawn_ arrays. For each one you can configure the following parameters:
- _Number of Decals/Meshes_ - The amount of each decal or mesh to paint.
- _Decal/Mesh Scale_ — Scale of the decal/mesh per axis.
- _Fixed Decal/Mesh Offset_ — Deviation from the center of the lane per axis.
- _Random Offset_ — Max deviation from the center of the lane per axis.
- _Decal/Mesh Random Yaw_ — Max random yaw rotation.
- _Decal/Mesh Min Scale_ — Minimum random scale applied to the decal/mesh.
- _Decal/Mesh Max Scale_ — Max random scale applied to the decal/mesh.
>>>>>>![materials_](../img/decals_meshes.png)
<div style="text-align: right"><i>Decals and Meshes panels.</i></div>
<br>
Once you have configured your meshes and decals, spawn them by pressing `Spawn decals` and `Spawn meshes`.
!!! Note
Make sure that meshes and decals do not have collisions enabled that can interfere with cars on the road and lower any bounding boxes to the level of the road.
__7. Experiment to get your desired appearance.__
Experiment with different materials, textures, settings, decals, and meshes to get your desired look. Below are some example images of how the appearance of the road changes during the process of painting each material.
![materials_roadpaint_mat00](../img/material_customization/Materials_Road_MaterialBase.jpg)
<div style="text-align: right"><i>Example of base road material.</i></div>
<br>
![materials_roadpaint_mat01](../img/material_customization/Materials_Road_Material1.jpg)
<div style="text-align: right"><i>Example after material 1 is applied.</i></div>
<br>
![materials_roadpaint_mat02](../img/material_customization/Materials_Road_Material2.jpg)
<div style="text-align: right"><i>Example after material 2 is applied.</i></div>
<br>
![materials_roadpaint_mat03](../img/material_customization/Materials_Road_Material3.jpg)
<div style="text-align: right"><i>Example after material 3 is applied.</i></div>
<br>
![materials_roadpaint_mat03](../img/material_customization/Materials_Road_Decals.jpg)
<div style="text-align: right"><i>Example after decals are applied.</i></div>
<br>
![materials_roadpaint_mat03](../img/material_customization/Materials_Road_Meshes.jpg)
<div style="text-align: right"><i>Example after meshes are applied.</i></div>
<br>
---
## Update the appearance of lane markings
After you have painted the roads, you can update the appearance of the road markings by following these steps:
__1. Make a copy of the master material.__
1. In the _Content Browser_, navigate to `Game/Carla/Static/GenericMaterials/RoadPainterMaterials`.
2. Right-click on `Tutorial_RoadMaster` and select _Create Material Instance_.
3. Rename to `Tutorial_LaneMarkings`.
__2. Configure the lane marking material.__
1. In the _Content Browser_, double-click on `Tutorial_LaneMarkings`.
2. In the _Details_ panel, go to the _Global Static Switch Parameter Values_ section and check the boxes on the left and right of _LaneMark_.
3. Go to the _Texture_ section and check the boxes for _LaneColor_ and _Uv Size_.
4. Choose your preferred color for the lane markings in _LaneColor_.
5. _Save_ and close.
__3. Select the road marking meshes.__
Drag the material onto the lane markings you wish to color. Repeat the whole process for different colors of lane markings if required.
---
## Next steps
Continue customizing your map using the tools and guides below:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the weather](tuto_M_custom_weather_landscape.md#weather-customization)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

174
Docs/tuto_M_custom_weather_landscape.md Normal file
View File

@ -0,0 +1,174 @@
# Customizing maps: Weather and Landscape
CARLA provides several blueprints to help ease the creation of default weather settings for your maps and to populate the lanscape with serial meshes such as street lights, power lines, etc.
This guide will explain where each one of these blueprints are located and how to use and configure them.
- [__Weather customization__](#weather-customization)
- [BP_Sky](#bp_sky)
- [BP_Weather](#bp_weather)
- [__Serial meshes__](#add-serial-meshes)
- [BP_RepSpline](#bp_repspline)
- [BP_Spline](#bp_spline)
- [BP_Wall](#bp_wall)
- [BP_SplinePoweLine](#bp_splinepoweline)
- [__Next steps__](#next-steps)
!!! Important
This tutorial only applies to users that work with a build from source, and have access to the Unreal Editor.
---
## Weather customization
This section explains how to experiment with different weather parameters before setting your map's default weather, and once you are happy with the settings, how to configure the default weather parameters for your map.
### BP_Sky
The `BP_Sky` blueprint is neccessary to bring light and weather to your map. It can also be used to test different weather configurations before deciding on your default weather parameters.
It is likely the `BP_Sky` blueprint will already be loaded in your map. If not you can add it by dragging it into the scene from `Content/Carla/Blueprints/Weather`.
To try out different weather parameters, go to the _Details_ panel of the `BP_Sky` actor, and play with the values in the _Parameters_ section.
!!! Important
If more than one `BP_Sky` blueprint is loaded into the scene, the weather will be duplicated with undesirable results, e.g, having two suns.
### BP_Weather
The default weather for your map is defined in the `BP_Weather` blueprint. This blueprint allows you to set the same parameters as are available through the Python API. These parameters are described [here](https://carla.readthedocs.io/en/latest/python_api/#carlaweatherparameters).
To set the default weather for your map:
__1. Open the `BP_Weather` blueprint.__
In the _Content Browser_, navigate to `Content/Carla/Blueprints/Weather` and double-click on `BP_Weather`.
__2. Add your town.__
In the _Details_ panel of the `BP_Weather` window, go to the _Weather_ section and add your town to the _Default Weathers_ array.
__3. Configure your default weather parameters.__
For each weather parameter, set your desired value. When you are finished, press _Compile_ then _Save_ and close.
>>>>>![bp_weather_pic](../img/map_customization/BP_Weather.jpg)<br>
<div style="text-align: right">
<i>Array containing default weather parameters for every CARLA map. Town01 opened.</i></div>
<br>
---
## Add serial meshes
There are four blueprints available to add props aligned in one direction, e.g., walls, powerlines, street lights. These blueprints use a series of meshes distributed along a Bezier curve. Each one is initialized in the same way:
__1. Initialize the series.__
Drag the blueprint into the scene. You will see one element standing at the starting point of a Bezier curve with two nodes marking the beginning and ending.
__2. Define the path.__
Select the direction arrow of the element and press __Alt__ while dragging the element in the direction you want to go. This will create a new element which can be used to define the curve. As you drag, a new mesh will appear either on every node of the curve or every time you press `Alt` while dragging, depending on the blueprint.
__3. Customize the pattern.__
The following sections will describe the different customization parameters available to each blueprint.
### BP_RepSpline
The `BP_RepSpline` blueprint is found in `Carla/Blueprints/LevelDesign`. It is used to add __individual__ elements along a path defined by a Bezier curve.
The serialization is customized via the following values:
- _Distance between_ — Set the distance between elements.
- _Offset rotation_ — Set a fixed rotation for the different axis.
- _Random rotation_ — Set a range of random rotations for the different axis.
- _Offset translation_ — Set a range of random locations along the different axis.
- _Max Number of Meshes_ — Set the maximum amount of elements that will be place between nodes of the curve.
- _World aligned ZY_ — If selected, the elements will be vertically aligned regarding the world axis.
- _EndPoint_ — If selected, an element will be added at the end node of the curve.
- _Collision enabled_ — Set the type of collisions enabled for the meshes.
![bp_repspline_pic](../img/map_customization/BP_Repspline.jpg)
<div style="text-align: right"><i>BP_RepSpline example.</i></div>
### BP_Spline
The `BP_Spline` blueprint is found in `Carla/Blueprints/LevelDesign`. It adds __connected__ elements that __strictly__ follow a path defined by a Bezier curve. The mesh will be warped to fit the path created.
The blueprint can be customized using the following value:
- _Gap distance_ — Add a separation between elements.
![bp_spline_pic](../img/map_customization/BP_Spline.jpg)
<div style="text-align: right"><i>BP_Spline example.</i></div>
### BP_Wall
The `BP_Wall` blueprint is found in `Carla/Blueprints/LevelDesign`. It adds __connected__ elements along a path defined by a Bezier curve. The mesh will not be warped to fit the curve, but the nodes will be respected.
- _Distance between_ — Set the distance between elements.
- _Vertically aligned_ — If selected, the elements will be vertically aligned regarding the world axis.
- _Scale offset_ — Scale the length of the mesh to round out the connection between elements.
![bp_wall_pic](../img/map_customization/BP_Wall.jpg)
<div style="text-align: right"><i>BP_Wall example.</i></div>
### BP_SplinePoweLine
The __BP_SplinePoweLine__ blueprint is found in `Carla/Static/Pole/PoweLine`. It adds __electricity poles__ along a path defined by a Bezier curve and __connects them with power lines__.
To provide variety, you can provide the blueprint with an array of powerline meshes to populate the path. To do this:
1. Double-click the __BP_SplinePoweLine__ blueprint in the _Content Browser_.
2. In the _Details_ panel, go to the _Default_ section.
3. Expand the _Array Meshes_ and add to or change it according to your needs.
4. Press _Compile_, then save and close the window.
![bp_splinepowerline_pic](../img/map_customization/BP_Splinepowerline.jpg)
<div style="text-align: right"><i>BP_SplinePowerLine example.</i></div>
To alter the line tension of the power lines:
1. Select the blueprint actor in the editor scene and go to the _Details_ panel.
2. Go to the _Default_ section.
3. Adjust the value in _Tension_. `0` indicates that the lines will be straight.
To increase the amount of wires:
1. In the _Content Browser_, double-click on one of the pole meshes.
2. Go to the _Socket Manager_ panel.
3. Configure existing sockets or add new ones by clicking _Create Socket_. Sockets are empty meshes that represent the connection points of the power line. A wire is created form socket to socket between poles.
![bp_powerline_socket_pic](../img/map_customization/BP_Splinepowerline_Sockets.jpg)
<div style="text-align: right"><i>Visualization of the sockets for BP_SplinePowerLine.</i></div>
<br>
!!! Important
The amount of sockets and their names should be consistent between poles. Otherwise, visualization issues may arise.
---
## Next steps
Continue customizing your map using the tools and guides below:
- [Implement sub-levels in your map.](tuto_M_custom_layers.md)
- [Add and configure traffic lights and signs.](tuto_M_custom_add_tl.md)
- [Add buildings with the procedural building tool.](tuto_M_custom_buildings.md)
- [Customize the road with the road painter tool.](tuto_M_custom_road_painter.md)
- [Customize the landscape with serial meshes.](tuto_M_custom_weather_landscape.md#add-serial-meshes)
Once you have finished with the customization, you can [generate the pedestrian navigation information](tuto_M_generate_pedestrian_navigation.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

107
Docs/tuto_M_generate_map.md Normal file
View File

@ -0,0 +1,107 @@
# Generating Maps in RoadRunner
RoadRunner is the recommended software to create maps to be imported into CARLA. This guide outlines what RoadRunner is, things to consider when building the map and how to export custom maps ready for importing into CARLA.
- [__Introduction to RoadRunner__](#introduction-to-roadrunner)
- [__Before you start__](#before-you-start)
- [__Build a map in RoadRunner__](#build-a-map-in-roadrunner)
- [__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. It can be used to create road layouts and accompanying OpenDRIVE and geometry information. Find out more about RoadRunner [here][rr_home].
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.
A license for RoadRunner is also available to everyone participating in the CARLA Leaderboard. Click [here][rr_leaderboard] for more information.
[rr_home]: https://www.mathworks.com/products/roadrunner.html
[rr_trial_version]: https://www.mathworks.com/products/roadrunner.html
[rr_eligibility]: https://www.mathworks.com/academia/tah-support-program/eligibility.html
[rr_leaderboard]: https://www.mathworks.com/academia/student-competitions/carla-autonomous-driving-challenge.html
---
## Before you start
You will need to 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
---
## Build a map in RoadRunner
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].
__Keep in mind that a map heavy with props can slow the import process significantly.__ This is because Unreal Engine needs to convert every mesh to an Unreal asset. If you plan to import your map into a source build version of CARLA, we highly recommend that you only create the road layout in RoadRunner and leave any customization until after the map has been imported into Unreal Engine. CARLA provides several tools that you can use in the Unreal Engine editor to simplify the customization process.
---
## Export a map in RoadRunner
[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 basic 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 road layout 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`.
When you are ready to export:
__1.__ Export the scene using the CARLA option:
- In the main toolbar, select `File` -> `Export` -> `CARLA (.fbx, .xodr, .rrdata.xml)`
__2.__ In the window that pops up:
>- 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.__ Choose 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__](tuto_M_add_map_source.md).
* __For users of a packaged (binary) version of CARLA__, follow the guide [__here__](tuto_M_add_map_package.md).
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

90
Docs/tuto_M_generate_pedestrian_navigation.md Normal file
View File

@ -0,0 +1,90 @@
# Generate Pedestrian Navigation
To allow pedestrians to navigate a map, you will need to generate a pedestrian navigation file. This guide details what meshes to use and how to generate the file.
- [__Before you begin__](#before-you-begin)
- [__Pedestrian navigable meshes__](#pedestrian-navigable-meshes)
- [__Optional pedestrian navigation options__](#optional-pedestrian-navigation-options)
- [__Generate the pedestrian navigation__](#generate-the-pedestrian-navigation)
---
## Before you begin
Map customization (adding buildings, painting the road, adding landscape features, etc.) 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.
---
## Pedestrian navigable meshes
Pedestrians can only navigate specific meshes. You need to name the meshes you want to include in pedestrian navigation according to the nomenclature in the table below:
| Type | Name includes | Description |
|------|------------|-------------|
| Ground | `Road_Sidewalk` or `Roads_Sidewalk` | Pedestrians will walk over these meshes freely. |
| Crosswalk | `Road_Crosswalk` or `Roads_Crosswalk` | Pedestrians will walk over these meshes as a second option if no ground is found. |
| Grass | `Road_Grass` or `Roads_Grass` | Pedestrians won't walk on this mesh unless you specify a percentage of them to do so. |
| Road | `Road_Road` or `Roads_Road` <br> `Road_Curb` or `Roads_Curb` <br> `Road_Gutter` or `Roads_Gutter` <br> `Road_Marking` or `Roads_Marking` | Pedestrians will only cross roads through these meshes. |
<br>
---
## Optional pedestrian navigation options
The following step is not necessary for generating a pedestrian navigation, but allows you to customize pedestrian activity to a certain extent.
- __Generate new crosswalks__.
Avoid doing this if the crosswalk is already defined the `.xodr` file as this will lead to duplication:
1. Create a plane mesh that extends a bit over two sidewalks that you want to connect.
2. Place the mesh overlapping the ground and disable it's physics and rendering.
3. Change the name of the mesh to `Road_Crosswalk` or `Roads_Crosswalk`.
![ue_crosswalks](../img/ue_crosswalks.jpg)
---
## Generate the 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.
__7.__ Test the pedestrian navigation by starting a simulation and running the example script `generate_traffic.py` in `PythonAPI/examples`.
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

99
Docs/tuto_M_manual_map_package.md Normal file
View File

@ -0,0 +1,99 @@
# Manual package preparation
A map package follows a certain folder structure and must contain a `.json` file describing that structure. Our automatic map import processes create this `.json` file automatically, but you also have the option to prepare it yourself. Including your own `.json` file will overwrite any arguments passed to the `make import` command.
- [__Standard Maps__](#standard-maps)
- [Create the folder structure for the standard maps](#create-the-folder-structure-for-the-standard-maps)
- [Create the JSON description for the standard maps](#create-the-json-description-for-the-standard-maps)
- [__Large Maps__](#large-maps)
- [Create the folder structure for the large maps](#create-the-folder-structure-for-the-large-maps)
- [Create the JSON description for the large maps](#create-the-json-description-for-the-large-maps)
---
## Standard maps
### Create the folder structure for the standard maps
__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 for the standard maps
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>
---
If you have any questions about the process, then you can ask in the [forum](https://github.com/carla-simulator/carla/discussions).
<div class="build-buttons">
<p>
<a href="https://github.com/carla-simulator/carla/discussions" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>
</p>
</div>

22
mkdocs.yml
View File

@ -47,9 +47,26 @@ nav:
- 'carlaviz — web visualizer': 'plugins_carlaviz.md'
- ROS bridge:
- 'ROS bridge documentation': 'ros_documentation.md'
- Custom Maps:
- 'Overview of custom maps in CARLA': 'tuto_M_custom_map_overview.md'
- 'Create a map in RoadRunner': 'tuto_M_generate_map.md'
- 'Import map in CARLA package': 'tuto_M_add_map_package.md'
- 'Import map in CARLA source build': 'tuto_M_add_map_source.md'
- 'Alternative ways to import maps': 'tuto_M_add_map_alternative.md'
- 'Manually prepare map package': 'tuto_M_manual_map_package.md'
- 'Customizing maps: Layered maps': 'tuto_M_custom_layers.md'
- 'Customizing maps: Traffic lights and signs': 'tuto_M_custom_add_tl.md'
- 'Customizing maps: Road painter': 'tuto_M_custom_road_painter.md'
- 'Customizing maps: Procedural Buildings': 'tuto_M_custom_buildings.md'
- 'Customizing maps: Weather and landscape': 'tuto_M_custom_weather_landscape.md'
- 'Generate pedestrian navigation': 'tuto_M_generate_pedestrian_navigation.md'
- Large Maps:
- 'Large maps overview': 'large_map_overview.md'
- 'Create a large map in RoadRunner': 'large_map_roadrunner.md'
- 'Import/Package a large map': 'large_map_import.md'
- Tutorials (general):
- 'Add friction triggers': "tuto_G_add_friction_triggers.md"
- 'Control and monitor vehicle physics': "tuto_G_control_vehicle_physics.md"
- 'Control vehicle physics': "tuto_G_control_vehicle_physics.md"
- 'Control walker skeletons': "tuto_G_control_walker_skeletons.md"
- 'Generate maps with OpenStreetMap': 'tuto_G_openstreetmap.md'
- 'Retrieve simulation data': "tuto_G_retrieve_data.md"
@ -59,11 +76,9 @@ nav:
- 'Chrono Integration': 'tuto_G_chrono.md'
- 'Build Unreal and CARLA in Docker': 'build_docker_unreal.md'
- Tutorials (assets):
- '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'
- 'Map customization tools': 'tuto_A_map_customization.md'
- "Material customization": 'tuto_A_material_customization.md'
- Tutorials (developers):
- 'Contribute assets': 'tuto_D_contribute_assets.md'
@ -72,7 +87,6 @@ nav:
- 'Customize vehicle suspension': 'tuto_D_customize_vehicle_suspension.md'
- 'Generate detailed colliders': 'tuto_D_generate_colliders.md'
- 'Make a release': 'tuto_D_make_release.md'
- 'Generate pedestrian navigation': 'tuto_D_generate_pedestrian_navigation.md'
- Contributing:
- 'Contribution guidelines': 'cont_contribution_guidelines.md'
- 'Code of conduct': 'cont_code_of_conduct.md'