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

Sergi e/p098 adv (#2619) 

* First iteration

* Backup images deleted.

* Minor modifications added.

* Changes on A review and updated to CARLA 4.22
This commit is contained in:
sergi.e 2020-03-24 10:23:02 +01:00 committed by GitHub
parent 2c6483d194
commit b62ccb1a30
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 396 additions and 297 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

303
Docs/adv_recorder.md
View File

@ -1,31 +1,31 @@
# Recorder
This is one of the advanced CARLA features. It allows to record and reenact a simulation while providing with a complete log of the events happened and a few queries to ease the trace and study of those.
To learn about the generated file and its specifics take a look at this [reference](ref_recorder_binary_file_format.md).
This feature allows to record and reenact a previous simulation. All the events happened are registered in the [recorder file](ref_recorder_binary_file_format.md). There are some high-level queries to trace and study those events.
* [__Recording__](#recording)
* [__Simulation playback__](#simulation-playback):
* Setting a time factor
* [__Recorded file__](#unreal-engine)
* [__Queries__](#queries):
* Collisions
* Blocked actors
* [__Sample Python scripts__](#sample-python-scripts)
* [__Recording__](#recording)
* [__Simulation playback__](#simulation-playback)
* Setting a time factor
* [__Recorded file__](#unreal-engine)
* [__Queries__](#queries)
* Collisions
* Blocked actors
* [__Sample Python scripts__](#sample-python-scripts)
---
## Recording
All the data is written in a binary file on the server side only. However, the recorder is managed using the [carla.Client](python_api.md#carla.Client).
To reenact the simulation, actors will be updated on every frame according to the data contained in the recorded file. Actors that appear in the simulation will be either moved or re-spawned to emulate the recording. Those that do not appear in the recording will continue their way as if nothing happened.
Actors are updated on every frame according to the data contained in the recorded file. Actors in the current simulation that appear in the recording will be either moved or re-spawned to emulate it. Those that do not appear in the recording will continue their way as if nothing happened.
!!! Important
By the end of the playback, vehicles will be set to autopilot, but __pedestrians will stop at their current location__.
By the end of the playback, vehicles will be set to autopilot, but __pedestrians will stop__.
The information registered by the recorder basically includes:
The recorder file includes information regarding actors.
* __Actors:__ Creation and destruction.
* __Traffic lights:__ State changes.
* __Vehicles and pedestrians:__ Position and orientation.
* __Actors'__ creation and destruction.
* __Traffic lights'__ state changes.
* __Vehicles and pedestrians'__ position and orientation.
To start recording there is only need for a file name. Using `\`, `/` or `:` characters in the file name will define it as an absolute path. If no path is detailed, the file will be saved in `CarlaUE4/Saved`.
@ -33,78 +33,92 @@ To start recording there is only need for a file name. Using `\`, `/` or `:` cha
client.start_recorder("/home/carla/recording01.log")
```
To stop the recording, the call is also straightforward:
To stop the recording, the call is also straightforward.
```py
client.stop_recorder()
```
!!! Note
As an estimate: 1h recording with 50 traffic lights and 100 vehicles takes around 200MB in size.
As an estimate, 1h recording with 50 traffic lights and 100 vehicles takes around 200MB in size.
---
## Simulation playback
A playback can be started at any point during a simulation only specifying the file name.
```py
client.replay_file("recording01.log")
```
Additionally, this method allows for some parameters to specify which segment of the recording is reenacted:
A playback can be started at any point during a simulation. Besides the path to the log file, this method needs some parameters.
```py
client.replay_file("recording01.log", start, duration, camera)
```
| Parameters | Description | Notes |
| ---------- | ----------------------------------------------------- | ----- |
| `start` | Recording time in seconds to start the simulation at. | If positive, time will be considered from the beginning of the recording. <br>If negative, it will be considered from the end. |
| `duration` | Seconds to playback. 0 is all the recording. | By the end of the playback, vehicles will be set to autopilot and pedestrians will stop. |
| `camera` | ID of the actor that the camera will focus on. | By default the spectator will move freely. |
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
<th>Notes</th>
</thead>
<tbody>
<td><code>start</code> </td>
<td>Recording time in seconds to start the simulation at.</td>
<td>If positive, time will be considered from the beginning of the recording. <br>If negative, it will be considered from the end.</td>
<tr>
<td><code>duration</code></td>
<td>Seconds to playback. 0 is all the recording.</td>
<td>By the end of the playback, vehicles will be set to autopilot and pedestrians will stop.</td>
<tr>
<td><code>camera</code></td>
<td>ID of the actor that the camera will focus on. </td>
<td>Set it to <code>0</code> to let the spectator move freely.</td>
</tbody>
</table>
<br>
!!! Note
These parameters allows to recall an event and then let the simulation run free, as vehicles will be set to autopilot when the recording stops.
### Setting a time factor
#### Setting a time factor
The time factor will determine the playback speed.
It can be changed any moment without stopping the playback, using the following API call:
The time factor will determine the playback speed. It can be changed any moment without stopping the playback.
```py
client.set_replayer_time_factor(2.0)
```
| Parameters | Default | Fast motion | slow motion |
| ------------- | ------- | ----------- | ----------- |
| `time_factor` | __1.0__ | __>1.0__ | __<1.0__ |
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Default</th>
<th>Fast motion</th>
<th>Slow motion</th>
</thead>
<tbody>
<td><code>time_factor</code> </td>
<td><b>1.0</b></td>
<td><b>>1.0</b></td>
<td><b> <1.0 </b></td>
</tbody>
</table>
<br>
!!! Important
Over 2.0 position interpolation is disabled and just updated. Pedestrians' animations are not affected by the time factor.
If `time_factor>2.0`, the actors' position interpolation is disabled and just updated. Pedestrians' animations are not affected by the time factor.
For instance, with a time factor of __20x__ traffic flow is easily appreciated:
When the time factor is around __20x__ traffic flow is easily appreciated.
![flow](img/RecorderFlow2.gif)
---
## Recorded file
The details of a recording can be retrieved using a simple API call. By default, it only retrieves those frames where an event was registered, but setting the parameter `show_all` would return all the information for every frame. The specifics on how the data is stored are detailed in the [recorder's reference](ref_recorder_binary_file_format.md).
The following example only would retrieve remarkable events:
The details of a recording can be retrieved using a simple API call. By default, it only retrieves those frames where an event was registered. Setting the parameter `show_all` would return all the information for every frame. The specifics on how the data is stored are detailed in the [recorder's reference](ref_recorder_binary_file_format.md).
```py
client.show_recorder_file_info("recording01.log")
# Show info for relevant frames
print(client.show_recorder_file_info("recording01.log"))
```
* __Opening information:__ map, date and time when the simulation was recorded.
* __Opening information.__ Map, date and time when the simulation was recorded.
* __Frame information:__ any event that could happen (actor spawning/destruction, collisions...). The output contains the actor's ID and some additional information.
* __Frame information.__ Any event that could happen such as actors spawning or collisions. It contains the actors' ID and some additional information.
* __Closing information:__ a summary of number of frames and total time recorded.
The output result should be similar to this one:
* __Closing information.__ Number of frames and total time recorded.
```
Version: 1
@ -136,31 +150,31 @@ Frame 2351 at 60.3057 seconds
Frames: 2354
Duration: 60.3753 seconds
```
---
## Queries
#### Collisions
### Collisions
In order to record collisions, vehicles must have a [collision detector](ref_sensors.md#collision-detector) attached. The collisions registered by the recorder can be queried using arguments to filter the type of the actors involved in the collisions. For example, `h` identifies actors whose `role_name = hero`, usually assigned to vehicles managed by the user.
Currently, the actor types that can be used in the query are:
Vehicles must have a [collision detector](ref_sensors.md#collision-detector) attached to record collisions. These can be queried, using arguments to filter the type of the actors involved in the collisions. For example, `h` identifies actors whose `role_name = hero`, usually assigned to vehicles managed by the user. There is a specific set of actor types available for the query.
* __h__ = Hero
* __v__ = Vehicle
* __w__ = Walker
* __t__ = Traffic light
* __o__ = Other
* __a__ = Any
* __h__ = Hero
* __v__ = Vehicle
* __w__ = Walker
* __t__ = Traffic light
* __o__ = Other
* __a__ = Any
!!! Note
The `manual_control.py` script automatically assigns the `role_name` of the vehicle to `hero` besides providing control over it.
The `manual_control.py` script assigns `role_name = hero` for the ego vehicle.
The API call to query collisions requires two of the previous flags to filter the collisions. The following example would show collisions registered between vehicles and any other object:
The collision query requires two flags to filter the collisions. The following example would show collisions between vehicles, and any other object.
```py
client.show_recorder_collisions("recording01.log", "v", "a")
print(client.show_recorder_collisions("recording01.log", "v", "a"))
```
The output summarizes time of the collision and type, ID and description of the actors involved. It should be similar to this one:
The output summarizes time of the collision, and type, ID and description of the actors involved.
```
Version: 1
@ -179,40 +193,51 @@ Duration: 46 seconds
As it is the `hero` or `ego` vehicle who registers the collision, this will always be `Actor 1`.
To understand how that collision happened, it could be a good idea to replay it just moments before the event:
The collision can be reenacted by using the recorder and setting it seconds before the event.
```py
client.replay_file("col2.log", 13, 0, 122)
```
In this case, the playback showed this:
In this case, the playback showed this.
![collision](img/collision1.gif)
#### Blocked actors
### Blocked actors
This query is used to detect vehicles that where stucked during the recording. An actor is considered blocked if it does not move a minimum distance in a certain time. This definition is made by the user during the query:
Detects vehicles that where stucked during the recording. An actor is considered blocked if it does not move a minimum distance in a certain time. This definition is made by the user during the query.
```py
client.show_recorder_actors_blocked("recording01.log", min_time, min_distance)
print(client.show_recorder_actors_blocked("recording01.log", min_time, min_distance))
```
| Parameters | Description | Default |
| -------------- | --------------------------------------------------------- | ----- |
| `min_time` | Minimum seconds to move `min_distance`. | 30 secs. |
| `min_distance` | Minimum centimeters to move to not be considered blocked. | 10 cm. |
<br>
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
<th>Default</th>
</thead>
<tbody>
<td><code>min_time</code> </td>
<td>Minimum seconds to move `min_distance`.</td>
<td>30secs.</td>
<tr>
<td><code>min_distance</code> </td>
<td>Minimum centimeters to move to not be considered blocked.</td>
<td>10cm.</td>
</tbody>
</table>
<br>
!!! Note
Take into account that vehicles are stopped at traffic lights sometimes for longer than expected.
Sometimes vehicles are stopped at traffic lights for longer than expected.
For the sake of comprehension, let's make an example to look for vehicles stopped (moving less than 1 meter during 60 seconds):
The following example considers that vehicles are blocked when moving less than 1 meter during 60 seconds.
```py
client.show_recorder_actors_blocked("col3.log", 60, 100)
```
The output is sorted by __duration__, which states how long it took to stop being "blocked" and move the `min_distance`:
The output is sorted by __duration__, which states how long it took to stop being "blocked" and move the `min_distance`.
```
Version: 1
@ -228,7 +253,7 @@ Frames: 6985
Duration: 374 seconds
```
In this example, the vehicle `173` was stopped for `336` seconds at time `36` seconds. To check the cause of it , it would be useful to check how it arrived to that situation by replaying a few seconds before the second `36`:
The vehicle `173` was stopped for `336` seconds at time `36` seconds. Reenact the simulation a few seconds before the second `36` to check it out.
```py
client.replay_file("col3.log", 34, 0, 173)
@ -239,61 +264,109 @@ client.replay_file("col3.log", 34, 0, 173)
---
## Sample python scripts
Some of the provided scripts in `PythonAPI/examples` facilitate the use of the recorder:
Some of the provided scripts in `PythonAPI/examples` facilitate the use of the recorder.
* __start_recording.py__: starts the recording. Optionally actors can be spawned at the beginning and duration of the recording set.
| Parameters | Description |
| -------------- | ------------ |
| `-f` | Filename. |
| `-n` <small>(optional)</small>| Vehicles to spawn. Default is 10. |
| `-t` <small>(optional)</small>| Duration of the recording. |
* __start_recording.py__ starts the recording. The duration of the recording can be set, and actors can be spawned at the beginning of it.
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
</thead>
<tbody>
<td><code>-f</code> </td>
<td>Filename.</td>
<tr>
<td><code>-n</code><small> (optional)</small></td>
<td>Vehicles to spawn. Default is 10.</td>
<tr>
<td><code>-t</code><small> (optional)</small></td>
<td>Duration of the recording.</td>
</tbody>
</table>
<br>
* __start_replaying.py__: starts the playback of a recording. Starting time, duration and actor to follow can be set.
| Parameters | Description |
| -------------- | ------------ |
| `-f` | Filename. |
| `-s` <small>(optional)</small>| Starting time. Default is 0. |
| `-d` <small>(optional)</small>| Duration. Default is all. |
| `-c` <small>(optional)</small>| ID of the actor to follow. |
* __start_replaying.py__ starts the playback of a recording. Starting time, duration, and actor to follow can be set.
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
</thead>
<tbody>
<td><code>-f</code> </td>
<td>Filename.</td>
<tr>
<td><code>-s</code><small> (optional)</small></td>
<td>Starting time. Default is 10.</td>
<tr>
<td><code>-d</code><small> (optional)</small></td>
<td>Duration. Default is all.</td>
<tr>
<td><code>-c</code><small> (optional)</small></td>
<td>IDof the actor to follow.</td>
</tbody>
</table>
<br>
* __show_recorder_file_info.py__: shows all the information in the recording file.
Two modes of detail: by default it only shows frames where some event is recorded. The second shows all information for all frames.
| Parameters | Description |
| -------------- | ------------ |
| `-f` | Filename. |
| `-s` <small>(optional)</small>| Flag to show all details. |
* __show_recorder_file_info.py__ shows all the information in the recording file. By default, it only shows frames where an event is recorded. However, all of them can be shown.
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
</thead>
<tbody>
<td><code>-f</code> </td>
<td>Filename.</td>
<tr>
<td><code>-s</code><small> (optional)</small></td>
<td>Flag to show all details.</td>
</tbody>
</table>
<br>
* __show_recorder_collisions.py__: shows recorded collisions between two actors of type __A__ and __B__ defined using a series of flags: `-t = vv` would show all collisions between vehicles.
* __show_recorder_collisions.py__ shows recorded collisions between two flags of actors of types __A__ and __B__. `-t = vv` would show all collisions between vehicles.
| Parameters | Description |
| ----------- | ------------- |
| `-f` | Filename. |
| `-t` | Flags of the actors involved: <br> `h` = hero <br> `v` = vehicle <br> `w` = walker <br> `t` = traffic light <br> `o` = other <br> `a` = any |
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
</thead>
<tbody>
<td><code>-f</code> </td>
<td>Filename.</td>
<tr>
<td><code>-t</code></td>
<td>Flags of the actors involved. <br> <code>h</code> = hero <br> <code>v</code> = vehicle <br> <code>w</code> = walker <br> <code>t</code> = traffic light <br> <code>o</code> = other <br> <code>a</code> = any</td>
</tbody>
</table>
<br>
* __show_recorder_actors_blocked.py__ lists vehicles considered blocked. Actors are considered blocked when not moving a minimum distance in a certain time.
* __show_recorder_actors_blocked.py__: shows a register for vehicles considered blocked. Actors are considered blocked when not moving a minimum distance in a certain time.
| Parameters | Description |
| --------------- | ------------ |
| `-f` | Filename. |
| `-t` <small>(optional)</small> | Time to move `-d` before being considered blocked. |
| `-d` <small>(optional)</small> | Distance to move to not be considered blocked. |
<table class ="defTable">
<thead>
<th>Parameter</th>
<th>Description</th>
</thead>
<tbody>
<td><code>-f</code> </td>
<td>Filename.</td>
<tr>
<td><code>-t</code><small> (optional)</small></td>
<td>Time to move <code>-d</code> before being considered blocked.</td>
<tr>
<td><code>-d</code><small> (optional)</small></td>
<td>Distance to move to not be considered blocked.</td>
</tbody>
</table>
<br>
---
Now it is time to experiment for a while. Use the recorder to playback a simulation, trace back events, make changes to see new outcomes. Feel free to say your word in the CARLA forum about this matter:
Now it is time to experiment for a while. Use the recorder to playback a simulation, trace back events, make changes to see new outcomes. Feel free to say your word in the CARLA forum about this matter.
<div class="build-buttons">
<!-- Latest release button -->
<p>
<a href="https://forum.carla.org/" target="_blank" class="btn btn-neutral" title="Go to the CARLA forum">
CARLA forum</a>

94
Docs/adv_rendering_options.md
View File

@ -1,55 +1,58 @@
# Rendering options
Before you start running your own experiments there are few details to take into
account at the time of configuring your simulation. In this document we cover
the most important ones.
There are few details to take into account at the time of configuring a simulation. This page covers the more important ones.
* [__Graphics quality__](#graphics-quality):
* Vulkan vs OpenGL
* Quality levels
* [__No-rendering mode__](#no-rendering-mode)
* [__Off-screen mode__](#off-screen-mode)
* Off-screen Vs no-rendering
* [__Running off-screen using a preferred GPU__](#running-off-screen-using-a-preferred-gpu):
* Docker: recommended approach
* Deprecated: emulate the virtual display
* [__Graphics quality__](#graphics-quality)
* Vulkan vs OpenGL
* Quality levels
* [__No-rendering mode__](#no-rendering-mode)
* [__Off-screen mode__](#off-screen-mode)
* Off-screen Vs no-rendering
* [__Running off-screen using a preferred GPU__](#running-off-screen-using-a-preferred-gpu)
* Docker: recommended approach
* Deprecated: emulate the virtual display
!!! Important
Some of the command options shown below are not directly equivalent when using the CARLA packaged releases. Read the [Command line options](#command-line-options) section to learn more about this.
Some of the command options below are not equivalent in the CARLA packaged releases. Read the [Command line options](start_quickstart.md#command-line-options) section to learn more about this.
---
## Graphics quality
#### Vulkan vs OpenGL
### Vulkan vs OpenGL
Vulkan is the default graphics API used by Unreal Engine and CARLA (if installed). It consumes more memory, but performs faster and makes for a better frame rate. However, it is quite experimental, especially in Linux, and it may lead to some issues.
For said reasons, there is the option to change to OpenGL simply by using a flag when running CARLA. The same flag works for both Linux and Windows:
Vulkan is the default graphics API used by Unreal Engine, and CARLA. It consumes more memory, but performs faster and makes for a better frame rate. However, it is quite experimental, especially in Linux, and it may lead to some issues.
There is the option to change to OpenGL. Use a flag when running CARLA.
```sh
cd carla && ./CarlaUE4.sh -opengl
```
When working with the build version of CARLA it is Unreal Engine the one that needs to be set to use OpenGL. [Here][UEdoc] is a documentation regarding different command line options for Unreal Engine.
When working with the build version of CARLA, Unreal Engine needs to be set to use OpenGL. [Here][UEdoc] is a documentation regarding different command line options for Unreal Engine.
[UEdoc]: https://docs.unrealengine.com/en-US/Programming/Basics/CommandLineArguments/index.html
#### Quality levels
### Quality levels
CARLA also allows for two different graphic quality levels named as __Epic__, the default, and __Low__, which disables all post-processing, shadows and the drawing distance is set to 50m instead of infinite and makes the simulation run significantly faster.
Low mode is not only used when precision is nonessential or there are technical limitations, but also to train agents under conditions with simpler data or regarding only close elements.
CARLA also allows for two different graphic quality levels. __Epic__, the default is the most detailed. __Low__ disables all post-processing and shadows, the drawing distance is set to 50m instead of infinite.
The images below show how do both modes look like and how to start the CARLA packaged release with the appropiate flag in order to set a quality level. The same flag works for both Linux and Windows. There is no equivalent option when working with the build, but the UE editor has its own quality settings in _Settings>Engine Scalability Settings_ that allow for a greater customization of the desired quality.
The simulation runs significantly faster in __Low__ mode. This is not only used when there are technical limitations or precision is nonessential. It may be useful to train agents under conditions with simpler data or regarding only close elements.
The images below compare both modes. The flag used is the same for Windows and Linux. There is no equivalent option when working with the build, but the UE editor has its own quality settings. Go to `Settings/Engine Scalability Settings` for a greater customization of the desired quality.
![](img/epic_quality_capture.png) | ![](img/low_quality_capture.png)
:-------------------------:|:-------------------------:
`./CarlaUE4.sh -quality-level=Epic` | `./CarlaUE4.sh -quality-level=Low`
<br>
!!! Important
The issue that made Epic mode show an abnormal whiteness has been fixed. If the problem persists delete `GameUserSettings.ini` as it is saving the previous settings. It will be generated again in the next run. __Ubuntu path:__ ` ~/.config/Epic/CarlaUE4/Saved/Config/LinuxNoEditor/` __Windows path:__ `<Package folder>\WindowsNoEditor\CarlaUE4\Saved\Config\WindowsNoEditor\`
The issue that made Epic mode show an abnormal whiteness has been fixed. If the problem persists, delete `GameUserSettings.ini`. It is saving previous settings, and will be generated again in the next run. __Ubuntu path:__ ` ~/.config/Epic/CarlaUE4/Saved/Config/LinuxNoEditor/` __Windows path:__ `<Package folder>\WindowsNoEditor\CarlaUE4\Saved\Config\WindowsNoEditor\`
---
## No-rendering mode
This mode completely disables rendering in the simulator, Unreal Engine will skip everything regarding graphics. This facilitates a lot simulating traffic and road behaviours at very high frequencies without the rendering overhead. To enable or disable no-rendering mode the user can either change the world settings in a script or use the provided script in `/PythonAPI/util/config.py` that does that same thing automatically.
This mode disables rendering. Unreal Engine will skip everything regarding graphics. This mode prevents rendering overheads. It facilitates a lot traffic simulation and road behaviours at very high frequencies. To enable or disable no-rendering mode, change the world settings, or use the provided script in `/PythonAPI/util/config.py`.
Here is an example on how to enable and then disable it via script.
```py
settings = world.get_settings()
@ -59,7 +62,7 @@ world.apply_settings(settings)
settings.no_rendering_mode = False
world.apply_settings(settings)
```
And here is an example on how to disable and then enable rendering using the `config.py`:
And here is an example on how to disable and then enable rendering using the `config.py`.
```sh
cd PythonAPI/util && ./config.py --no-rendering
```
@ -67,44 +70,46 @@ cd PythonAPI/util && ./config.py --no-rendering
cd PythonAPI/util && ./config.py --rendering
```
On of the example scripts in `PythonAPI/examples/no_rendering_mode.py` will enable no-rendering mode and use __Pygame__ to create an aerial view using simple graphics:
The script `PythonAPI/examples/no_rendering_mode.py` will enable no-rendering mode, and use __Pygame__ to create an aerial view using simple graphics.
```sh
cd PythonAPI/examples && ./no_rendering_mode.py
```
!!! Warning
In no-rendering mode, cameras and GPU sensors will return empty data. The GPU is not used, as Unreal Engine is not drawing any scene.
In no-rendering mode, cameras and GPU sensors will return empty data. The GPU is not used. Unreal Engine is not drawing any scene.
---
## Off-screen mode
Unreal Engine needs for a screen in order to run, but there is a workaround for this that makes possible to work on rendering for remote servers with no display or desktop users with a GPU not connected to any screen.
The simulator launches but there is no available window. However, it can be connected in the usual manner and scripts run the same way. For the sake of understanding let's sake that this mode tricks Unreal Engine into running in a fake screen.
Unreal Engine needs for a screen in order to run. However, there is a workaround for remote servers with no display, or desktop users with a GPU not connected to any screen.
The simulator launches but there is no available window. It runs in the same way as normal mode. This mode tricks Unreal Engine into running in a "fake screen".
#### Off-screen vs no-rendering
### Off-screen vs no-rendering
These may look similar but are indeed quite different. It is important to understand the disctintion them to prevent misunderstandings. In off-screen Unreal Engine is working as usual and rendering is computed as usual. The only difference is that there is no available display. In no-rendering, it is Unreal Engine the one that is said to avoid rendering and thus, graphics are not computed. For said reasons, GPU sensors return data when off-screen and no-rendering mode can be enabled at will.
It is important to understand the disctintion them to prevent misunderstandings.
#### Setting off-screen mode
* In __no-rendering__, Unreal Engine does not render anything. Graphics are not computed.
* In __off-screen__, Unreal Engine is working as usual, rendering is computed. Simply, there is no display available. GPU sensors return data when off-screen, and no-rendering mode can be enabled at will.
Right now this is __only possible in Linux while using OpenGL__ instead of Vulkan. Unreal Engine crushes when Vulkan is running off-screen, and this issue is yet to be fixed by Epic.
### Setting off-screen mode
To force the simulator run off-screen set the environment variable `DISPLAY` to empty and run CARLA using OpenGL:
This is __only possible in Linux while using OpenGL__. Unreal Engine crushes when Vulkan is running off-screen, and this issue is yet to be fixed by Epic.
To force the simulator run off-screen set the environment variable `DISPLAY` to empty and run CARLA using OpenGL.
```sh
# Linux
DISPLAY= ./CarlaUE4.sh -opengl
```
Note that this method, in multi-GPU environments, does not allow to choose the GPU that the simulator will use for rendering. To do so, read the following section.
---
## Running off-screen using a preferred GPU
#### Docker: recommended approach
### Docker: recommended approach
The best way to run a headless CARLA and select the GPU is to [__run CARLA in a Docker__](build_docker.md).
This section contains an alternative tutorial, but this method is deprecated and performance is much worse. However, it is here just in case, for those who Docker is not an option.
The best way to run a headless CARLA and select the GPU is to [__run CARLA in a Docker__](build_docker.md).
This section contains an alternative tutorial, but this method is deprecated and performance is much worse. It is here only for those who Docker is not an option.
<details>
<summary><h4 style="display:inline">
@ -124,16 +129,16 @@ __3.__ Run CARLA.
This tutorial was tested in Ubuntu 16.04 using NVIDIA 384.11 drivers.
* __[Latest Nvidia drivers](http://www.nvidia.es/Download/index.aspx)__
* __[OpenGL](https://www.khronos.org/opengl/wiki/Getting_Started)__: needed to use Virtual GL (VGL). OpenGL can be installed via apt:
* __[Latest Nvidia drivers](http://www.nvidia.es/Download/index.aspx)__
* __[OpenGL](https://www.khronos.org/opengl/wiki/Getting_Started)__: needed to use Virtual GL (VGL). OpenGL can be installed via apt:
```sh
sudo apt-get install freeglut3-dev mesa-utils
```
* __[VGL](https://virtualgl.org/vgldoc/2_2_1/#hd004001)__: redirects 3D rendering commands from Unix and Linux OpenGL to the hardware in a dedicated server.
* __[VGL](https://virtualgl.org/vgldoc/2_2_1/#hd004001)__: redirects 3D rendering commands from Unix and Linux OpenGL to the hardware in a dedicated server.
* __[TurboVNC 2.11](https://cdn.rawgit.com/TurboVNC/turbovnc/2.1.1/doc/index.html#hd005001)__: graphical desktop-sharing system to connect remotely to the server.
* __[TurboVNC 2.11](https://cdn.rawgit.com/TurboVNC/turbovnc/2.1.1/doc/index.html#hd005001)__: graphical desktop-sharing system to connect remotely to the server.
* __Extra packages__: necessary to make Unreal work.
* __Extra packages__: necessary to make Unreal work.
```sh
sudo apt install x11-xserver-utils libxrandr-dev
```
@ -186,7 +191,8 @@ To run CARLA on a certain `<gpu_number>` in a certain `$CARLA_PATH` use the foll
---
That is all there is to know about the different rendering options in CARLA.
Open CARLA and mess around for a while to make sure that everything is clear and yet, if there are any doubts, feel free to post these in the forum.
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>

134
Docs/adv_synchrony_timestep.md
View File

@ -1,105 +1,115 @@
# Synchrony and time-step
This section deals with two concepts that are fundamental to fully comprehend CARLA and gain control over it to achieve the desired results. There are different configurations that define how does time go by in the simulation and how does the server running said simulation work. The following sections will dive deep into these concepts:
This section deals with two fundamental concepts in CARLA. Their configuration defines how does time go by in the simulation, and how does the server make the simulation move forward.
* [__Simulation time-step__](#simulation-time-step)
* Variable time-step
* [__Simulation time-step__](#simulation-time-step)
* Variable time-step
* Fixed time-step
* Tips when recording the simulation
* Time-step limitations
* [__Client-server synchrony__](#client-server-synchrony)
* [__Client-server synchrony__](#client-server-synchrony)
* Setting synchronous mode
* Using synchronous mode
* [__Possible configurations__](#possible-configurations)
* Using synchronous mode
* [__Possible configurations__](#possible-configurations)
---
## Simulation time-step
The very first and essential concept to understand in this section is the difference between real time and simulation time. The simulated world has its own clock and time, conducted by the server. Between two steps of the simulation, there is the time spent to compute said steps (real time) and a time span that went by in those two moments of the simulation (simulated time). This latest is the time-step.
Just an example for the sake of comprehension: When simulating, the server can take a few miliseconds to compute two steps of a simulation, but the time-step, the time that went by in the simulated world, can be configured to be, for instance, always a second.
The time-step can be fixed or variable depending on user preferences, and CARLA can run in both modes.
There is a difference between real time, and simulation time. The simulated world has its own clock and time, conducted by the server. Computing two simulation steps takes some real time. However, there is also the time span that went by between those two simulation moments, the time-step.
To clarify, the server can take a few miliseconds to compute two steps of a simulation. However, the time-step between those two simulation moments can be configured to be, for instance, always a second.
Time-step can be fixed or variable depending on user preferences.
!!! Note
After reading this section it would be a great idea to go for the following one, __Client-server synchrony__, especially the part about synchrony and time-step. Both are related concepts and affect each other when using CARLA.
Time-step and synchrony are intertwined concepts. Make sure to read both sections to get a full understanding of how does CARLA work.
#### Variable time-step
### Variable time-step
The default mode in CARLA. The simulation time that goes by between steps will be the time that the server takes to compute these.
This is the default mode in CARLA. When the time-step is variable, the simulation time that goes by between steps will be the time that the server takes to compute these.
In order to set the simulation to a variable time-step the code could look like this:
```py
settings = world.get_settings()
settings.fixed_delta_seconds = None
settings.fixed_delta_seconds = None # Set a variable time-step
world.apply_settings(settings)
```
The provided script `PythonAPI/util/config.py` automatically sets time-step with a flag where variable time-step is zero.
`PythonAPI/util/config.py` sets the time-step using an argument. Zero equals variable time-step.
```sh
cd PythonAPI/util && ./config.py --delta-seconds 0
```
#### Fixed time-step
### Fixed time-step
Going for a fixed time-step makes the server run a simulation where the elapsed time remains constant between steps. If it is set to 0.5 seconds, there will be two frames per simulated second.
Using the same time increment on each step is the best way to gather data from the simulation, as physics and sensor data will correspond to an easy to comprehend moment of the simulation. Also, if the server is fast enough, it makes possible to simulate longer time periods in less real time.
To enable this mode set a fixed delta seconds in the world settings. For instance, to run the simulation at a fixed time-step of 0.05 seconds apply the following settings:
The elapsed time remains constant between steps. If it is set to 0.5 seconds, there will be two frames per simulated second. Using the same time increment on each step is the best way to gather data from the simulation. Physics and sensor data will correspond to an easy to comprehend moment of the simulation. Also, if the server is fast enough, it makes possible to simulate longer time periods in less real time.
Fixed delta seconds can be set in the world settings. To run the simulation at a fixed time-step of 0.05 seconds apply the following settings. In this case, the simulator will take twenty steps (1/0.05) to recreate one second of the simulated world.
```py
settings = world.get_settings()
settings.fixed_delta_seconds = 0.05
world.apply_settings(settings)
```
Thus, the simulator will take twenty steps (1/0.05) to recreate one second of the simulated world. This can also be set using the provided script `PythonAPI/util/config.py` that automatically does this with a flag.
This can also be set using the provided script `PythonAPI/util/config.py`.
```sh
cd PythonAPI/util && ./config.py --delta-seconds 0.05
```
#### Tips when recording the simulation
### Tips when recording the simulation
CARLA has a [recorder feature](adv_recorder.md) that allows a simulation to be recorded and then reenacted. However, when looking for precision, some things need to be taken into account.
If the simulation ran with a fixed time-step, reenacting it will be easy, as the server can be set to the same time-step used in the original simulation. However, if the simulation used a variable time-step, things are a bit more complicated.
Firstly, if the server reenacting the simulation also runs with a variable time-step, the time-steps will be different from the original one, as logic cycles differ from time to time. The information will then be interpolated using the recorded data.
Secondly, the server can be forced to reproduce the exact same time-steps passing them one by one. Must be mentioned though that as those time steps were the result of the original simulation running as fast as possible, as the time taken to represent this time-steps now will mostly be different, the simulation is bound to be reproduced with weird time fluctuations. The steps simulated are the same, but the real-time between them changes.
Finally there is also the float-point arithmetic error that working with a variable time-step introduces. As the simulation is running with a time-step equal to the real one, being real time a continuous and simulation one a float variable, the time-steps show decimal limitations. The time that is cropped for each step is an error that accumulates and prevents the simulation from a precise repetition of what has happened.
* With a __fixed time-step__, reenacting it will be easy. The server can be set to the same time-step used in the original simulation.
#### Time-step limitations
* With a __variable time-step__, things are a bit more complicated.
Physics must be computed within very low time steps to be precise. The more time goes by, the more variables and chaos come to place and so, the more defective the simulation will be.
* If the __server runs with a variable time-step__, the time-steps will be different from the original one, as logic cycles differ from time to time. The information will then be interpolated using the recorded data.
* If the __server is forced to reproduce the exact same time-steps__, the steps simulated will be the same, but the real time between them changes. Time-steps should be passed one by one. Those original time-steps were the result of the original simulation running as fast as possible. As the time taken to represent these will mostly be different, the simulation is bound to be reproduced with weird time fluctuations.
* There is also a __float-point arithmetic error__ that variable time-step introduces. The simulation is running with a time-step equal to the real one. Real time is a continuous variable, represented in the simulation with a `float` value, which has decimal limitations. The time that is cropped for each step accumulates, and prevents the simulation from a precise repetition of what has happened.
### Time-step limitations
Physics must be computed within very low time steps to be precise. The more time goes by, the more variables and chaos come to place, and the more defective the simulation will be.
CARLA uses up to 6 substeps to compute physics in every step, each with a maximum delta time of 0.016667s.
To know how many of these are needed, the time-step used gets divided by the maximum delta time a substep can use `number_of_substeps = time_step/0.016667`.
Being these a maximum of 6, `6*0.016667 = 0.1`. If the time-step is greater there will not be enough physical substeps and thus, the physics will not be in synchrony with the delta time.
To know how many of these are needed, the time-step used gets divided by the maximum delta time a substep can use `number_of_substeps = time_step/0.016667`. Being these a maximum of 6, `6*0.016667 = 0.1`. If the time-step is greater than `0.1``, there will not be enough physical substeps. Physics will not be in synchrony with the delta time.
!!! Warning
__Do not use a time-step greater than 0.1s.__<br>
As explained above, the physics will not be representative for the simulation. The original issue can be found here: Ref. [#695](https://github.com/carla-simulator/carla/issues/695)
As explained above, the physics will not be representative for the simulation. The original issue can be found in ref. [#695](https://github.com/carla-simulator/carla/issues/695)
---
## Client-server synchrony
CARLA is built over a client-server architecture. This has been previously stated: the server runs the simulation and the client retrieves information and demands for changes in the world. But how do these two elements communicate?
By default, CARLA runs in __asynchronous mode__, meaning that the server runs the simulation as fast as possible, without waiting for the client. On the contrary, running on __synchronous mode__ will make the server wait for a client tick, a "ready to go" message, before updating to the following simulation step.
CARLA is built over a client-server architecture. The server runs the simulation. The client retrieves information, and demands for changes in the world. This section deals with communication between client and server.
By default, CARLA runs in __asynchronous mode__. The server runs the simulation as fast as possible, without waiting for the client. On __synchronous mode__, the server waits for a client tick, a "ready to go" message, before updating to the following simulation step.
!!! Note
In a multiclient architecture, only one client should make the tick. The server would react to receiving many as if these were all coming from one client and thus, take one step per tick.
In a multiclient architecture, only one client should tick. The server reacts to every tick received as if it came from the same client. Many client ticks will make the create inconsistencies between server and clients.
#### Setting synchronous mode
### Setting synchronous mode
Changing between synchronous and asynchronous mode is just a matter of a boolean state. In the following example, there is the code to make the simulation run on synchronous mode:
Changing between synchronous and asynchronous mode is just a matter of a boolean state.
```py
settings = world.get_settings()
settings.synchronous_mode = True
settings.synchronous_mode = True # Enables synchronous mode
world.apply_settings(settings)
```
To disable synchronous mode just set the variable to false or use the provided script in `PythonAPI/util/config.py`.
To disable synchronous mode just set the variable to false or use the script `PythonAPI/util/config.py`.
```sh
cd PythonAPI/util && ./config.py --no-sync
cd PythonAPI/util && ./config.py --no-sync # Disables synchronous mode
```
Must be mentioned that synchronous mode cannot be enabled using the script, only disabled. Enabling the synchronous mode makes the server wait for a client tick, and using this script the user cannot send ticks when desired.
Synchronous mode cannot be enabled using the script, only disabled. Enabling the synchronous mode makes the server wait for a client tick. Using this script, the user cannot send ticks when desired.
#### Using synchronous mode
### Using synchronous mode
The synchronous mode becomes specially relevant when running with slow clients applications and when synchrony between different elements, such as sensors, is needed. If the client is too slow and the server does not wait for it, the amount of information received will be impossible to manage and it can easily be mixed. On a similar tune, if there are ten sensors waiting to retrieve data and the server is sending all these information without waiting for all of them to have the previous one, it would be impossible to know if all the sensors are using data from the same moment in the simulation.
As a little extension to the previous code, in the following fragment, the client creates a camera sensor that puts the image data received in the current step in a queue and sends ticks to the server only after retrieving it from the queue. A more complex example regarding several sensors can be found [here][syncmodelink].
The synchronous mode becomes specially relevant with slow client applications, and when synchrony between different elements, such as sensors, is needed. If the client is too slow and the server does not wait, there will be an overflow of information. The client will not be able to mange everything, and it will be lost or mixed. On a similar tune, with many sensors and asynchrony, it would be impossible to know if all the sensors are using data from the same moment in the simulation.
The following fragment of code extends the previous one. The client creates a camera sensor, stores the image data of the current step in a queue, and ticks the server after retrieving it from the queue. A more complex example regarding several sensors can be found [here][syncmodelink].
```py
settings = world.get_settings()
@ -118,10 +128,10 @@ while True:
!!! Important
Data coming from GPU-based sensors (cameras) is usually generated with a delay of a couple of frames when compared with CPU based sensors, so synchrony is essential here.
Data coming from GPU-based sensors, mostly cameras, is usually generated with a delay of a couple of frames. Synchrony is essential here.
The world also has asynchrony methods to make the client wait for a server tick or do something when it is received:
The world has asynchrony methods to make the client wait for a server tick, or do something when it is received.
```py
# Wait for the next tick and retrieve the snapshot of the tick.
@ -134,31 +144,43 @@ world.on_tick(lambda world_snapshot: do_something(world_snapshot))
---
## Possible configurations
The configuration of both concepts explained in this page, simulation time-step and client-server synchrony, leads for different types of simulation and results. Here is a brief summary on the possibilities and a better explanation of the reasoning behind it:
| | __Fixed time-step__ | __Variable time-step__ |
| --- | --- | --- |
| __Synchronous mode__ | Client is in total control over the simulation and its information. | Risk of non reliable simulations. |
| __Asynchronous mode__ | Good time references for information. Server runs as fast as possible. | Non easily repeatable simulations. |
The configuration of time-step and synchrony, leads for different settings. Here is a brief summary on the possibilities.
<table class ="defTable">
<thead>
<th></th>
<th><b>Fixed time-step</b></th>
<th><b>Variable time-step</b></th>
</thead>
<tbody>
<td><b>Synchronous mode</b></td>
<td>Client is in total control over the simulation and its information.</td>
<td>Risk of non reliable simulations.</td>
<tr>
<td><b>Variable time-step</b></td>
<td>Good time references for information. Server runs as fast as possible.</td>
<td>Non easily repeatable simulations.</td>
</tbody>
</table>
<br>
* __Synchronous mode + variable time-step:__ This is almost for sure a non-desirable state. Physics cannot run properly when the time-step is bigger than 0.1s and, if the server needs to wait for the client to compute the steps, this is likely to happen. Simulation time and physics then will not be in synchrony and thus, the simulation is not reliable.
* __Synchronous mode + variable time-step.__ This is almost for sure a non-desirable state. Physics cannot run properly when the time-step is bigger than 0.1s and. If the server has to wait for the client to compute the steps, this is likely to happen. Simulation time and physics will not be in synchrony. The simulation will not be reliable.
* __Aynchronous mode + variable time-step:__ This is the default CARLA state. Client and server are asynchronous but the simulation time flows according to the real time. Reenacting the simulation needs to take into account float-arithmetic error and possible differences in time steps between servers.
* __Aynchronous mode + variable time-step.__ This is the default CARLA state. Client and server are asynchronous. The simulation time flows according to the real time. Reenacting the simulation needs to take into account float-arithmetic error, and possible differences in time steps between servers.
* __Asynchronous mode + fixed time-step:__ The server will run as fast as possible, and yet, the information retrieved will be easily related with an exact moment in the simulation. This configuration makes possible to simulate long periods of time in much less real time if the server is fast enough.
* __Asynchronous mode + fixed time-step.__ The server will run as fast as possible. The information retrieved will be easily related with an exact moment in the simulation. This configuration makes possible to simulate long periods of time in much less real time, if the server is fast enough.
* __Synchronous mode + fixed time-step:__ In this mode, the client will have complete ruling over the simulation. The time step will be fixed and the server will not compute the following step until the client sends a tick saying so. This is the best mode when synchrony and precision is relevant, especially when dealing with slow clients or different elements retrieving information.
* __Synchronous mode + fixed time-step.__ The client will rule the simulation. The time step will be fixed. The server will not compute the following step until the client sends a tick. This is the best mode when synchrony and precision is relevant. Especially when dealing with slow clients or different elements retrieving information.
!!! Warning
__In synchronous mode, always use a fixed time-step__. If the server has to wait for the user to compute the following step, and it is using a variable time-step, the simulation world will use time-steps too big for the physics to be reliable. This issue is better explained in the __time-step limitations__ section.
__In synchronous mode, always use a fixed time-step__. If the server has to wait for the user, and it is using a variable time-step, time-steps will be too big. Physics will not be reliable. This issue is better explained in the __time-step limitations__ section.
---
That is all there is to know about the roles of simulation time and client-server synchrony in CARLA.
Open CARLA and mess around for a while to make sure that everything is clear and yet, if there are any doubts, feel free to post these in the forum.
Open CARLA and mess around for a while. Any suggestions or doubts are welcome in the forum.
<div class="build-buttons">
<p>

112
Docs/adv_traffic_manager.md
View File

@ -1,40 +1,41 @@
# Traffic Manager
* [__What is it?__](#what-is-it)
* [__How does it work?__](#how-does-it-work)
* Architecture
* Stages
* [__Using the Traffic Manager__](#using-the-traffic-manager)
* Parameters
* Creating a Traffic Manager
* Setting the Traffic Manager
* [__Other considerations__](#other-considerations)
* [__What is it?__](#what-is-it)
* [__How does it work?__](#how-does-it-work)
* Architecture
* Stages
* [__Using the Traffic Manager__](#using-the-traffic-manager)
* Parameters
* Creating a Traffic Manager
* Setting the Traffic Manager
* [__Other considerations__](#other-considerations)
* FPS limitations
* Multiclient management
* [__Summary__](#summary)
* [__Summary__](#summary)
---
## What is it?
The Traffic Manager, TM for short, is a module built on top of the CARLA API in C++ that is in charge of controlling vehicles inside the simulation. Its goal is to populate the simulation with realistic urban traffic conditions allowing users to customize some behaviours, for example to set specific learning circumstances. To do so, every TM controls vehicles registered to it by setting autopilot to true, and is accounting for the rest by considering them unregistered.
The Traffic Manager, TM for short, is the module in charge of controlling vehicles inside the simulation. It is built on top of the CARLA API in C++. Its goal is to populate the simulation with realistic urban traffic conditions. Users can customize some behaviours, for example to set specific learning circumstances. Every TM controls vehicles registered to it by setting autopilot to true, and is accounting for the rest by considering them unregistered.
#### Structured design
The TM is built on the client-side of the CARLA architecture, replacing the former server-side autopilot after version 0.9.7. The execution flow is divided in __stages__ with independent operations and goals, to facilitate the development of phase-related functionalities and data structures, while also improving computational efficiency. Each stage runs on a different thread and communication with the rest is managed through synchronous messaging between the stages, so the information flows only in one direction.
### Structured design
The TM is built on the client-side of the CARLA architecture. It replaces the server-side autopilot. The execution flow is divided in __stages__ with independent operations and goals. This facilitates the development of phase-related functionalities and data structures, while also improving computational efficiency. Each stage runs on a different thread. Communication with the rest is managed through synchronous messaging between the stages.The information flows only in one direction.
#### User customization
Users must have some control over the traffic flow by setting parameters that allow, force or encourage specific behaviours. Thus, users can change the traffic behaviour as they prefer, both online and offline. For example they could allow a car to ignore the speed limits or force a lane change. Being able to play around with behaviours is a must when trying to simulate reality, specially to train driving systems under specific and atypical circumstances.
### User customization
Users must have some control over the traffic flow by setting parameters that allow, force or encourage specific behaviours. Users can change the traffic behaviour as they prefer, both online and offline. For example they could allow a car to ignore the speed limits or force a lane change. Being able to play around with behaviours is a must when trying to simulate reality. It is necessary to train driving systems under specific and atypical circumstances.
---
## How does it work?
#### Architecture
The following diagram is a summary of the internal architecture of the Traffic Manager. Blue bodies represent the different stages, green ones are additional modules that work with these and the arrows represent communication between elements managed by messenger classes.
The inner structure of the TM can be easily translated to code. Each relevant element has its equivalent in the C++ code (.cpp files) found inside `LibCarla/source/carla/trafficmanager`.
### Architecture
The following diagram is a summary of the internal architecture of the Traffic Manager. Blue bodies represent the different stages. Green ones are additional modules that work with these. The arrows represent communication between elements managed by messenger classes.
The inner structure of the TM can be easily translated to code. Each relevant element has its equivalent in the C++ code (.cpp files) inside `LibCarla/source/carla/trafficmanager`.
<div style="text-align:center">
<img src="../img/traffic_manager_diagram.png">
</div>
#### Stages
### Stages
__1. Localization Stage:__ the TM stores a list of waypoints ahead for each vehicle to follow. The list of waypoints is updated each iteration, changing according to the decisions taken during the stage, such as lane changes, to modify the vehicle's trajectory. The amount of waypoints stored depends on the vehicle's speed, being greater the faster it goes. This stage contains a __spatial hashing__ which saves the position for every car __registered to the Traffic Manager in a world grid__. This is a way to roughly predict possible collisions and create a list of overlapping actors for every vehicle that will be later used by the next stage.
@ -56,7 +57,7 @@ __5. Apply Control Stage:__ receives actuation signals, such as throttle, brake,
* __Related .cpp files:__ `BatchControlStage.cpp`.
#### Additional modules
### Additional modules
__Cached map:__ in order to increase computational efficiency during the Localization stage, the map is discretized and cached as a grid of waypoints. These are included in a specific data structure designed to hold more information, such as links between them. The grids allow to easily connect the map, each of them representing sections of a road or a whole junction, by also having an ID that is used to quickly identify vehicles in nearby areas.
@ -69,7 +70,7 @@ __PID controller:__ the TM module uses a PID controller to regulate throttle, br
---
## Using the Traffic Manager
#### General considerations
### General considerations
First of all there are some general behaviour patterns the TM will generate that should be understood beforehand. These statements are inherent to the way the TM is implemented:
@ -79,40 +80,37 @@ First of all there are some general behaviour patterns the TM will generate that
The TM provides a set of possibilities so the user can establish specific behaviours. All the methods accessible from the Python API are listed in the [documentation](../python_api/#carla.TrafficManager). However, here is a brief summary of what the current possibilities are.
<table style="width:100%">
<col width="150">
<tr>
<td><b> TM creation: </b></td>
<td> <li><br>1. Get a TM instance for a client.</li> </td>
</tr>
<tr>
<td><b>Safety conditions: </b></td>
<td><br>
1. Set a minimum distance between stopped vehicles (for a vehicle or all of them). This will affect the minimum moving distance. <br>
2. Set an intended speed regarding current speed limitation (for a vehicle or all of them). <br>
3. Reset traffic lights.
<table class ="defTable">
<tbody>
<td><b>TM creation:</b> </td>
<td><br>
<b>1.</b> Get a TM instance for a client.</td>
<tr>
<td><b>Safety conditions:</b> </td>
<td><br>
<b>1.</b> Set a minimum distance between stopped vehicles (for a vehicle or all of them). This will affect the minimum moving distance. <br>
<b>2.</b> Set an intended speed regarding current speed limitation (for a vehicle or all of them). <br>
<b>3.</b> Reset traffic lights.
</td>
<tr>
<td><b>Collision managing:</b> </td>
<td><br>
<b>1.</b> Enable/Disable collisions between a vehicle and a specific actor. <br>
<b>2.</b> Make a vehicle ignore all the other vehicles. <br>
<b>3.</b> Make a vehicle ignore all the walkers. <br>
<b>4.</b> Make a vehicle ignore all the traffic lights.
</td>
<tr>
<td><b>Lane changes:</b> </td>
<td><br>
<b>1.</b> Force a lane change disregarding possible collisions. <br>
<b>2.</b> Enable/Disable lane changes for a vehicle.
</td>
</tr>
<tr>
<td><b>Collision managing: </b></td>
<td><br>
1. Enable/Disable collisions between a vehicle and a specific actor. <br>
2. Make a vehicle ignore all the other vehicles. <br>
3. Make a vehicle ignore all the walkers. <br>
4. Make a vehicle ignore all the traffic lights.
</td>
</tr>
<tr>
<td><b>Lane changes: </b></td>
<td><br>
1. Force a lane change disregarding possible collisions. <br>
2. Enable/Disable lane changes for a vehicle.
</td>
</tr>
</tbody>
</table>
<br>
#### Creating a Traffic Manager
### Creating a Traffic Manager
A TM instance can be created by any [carla.Client](python_api.md#carla.Client) specifying the port that will be used. The default port is `8000`.
@ -138,7 +136,7 @@ batch.append(SpawnActor(blueprint, transform).then(SetAutopilot(FutureActor, Tru
traffic_manager.global_percentage_speed_difference(30.0)
```
#### Setting a Traffic Manager
### Setting a Traffic Manager
The following example creates an instance of the TM and sets a dangerous behaviour for a specific car that will ignore all traffic lights, leave no safety distance with the rest and drive at 120% its current speed limit.
@ -168,7 +166,7 @@ for v in my_vehicles:
Lane changes are currently disabled in the TM due to unintended collisions causing jams. As long as this issues are not fixed, vehicles will remain in the lane they are spawned and the methods to set lane changes will be disabled.
#### Stopping a Traffic Manager
### Stopping a Traffic Manager
The TM is not an actor that needs to be destroyed, it will stop when the corresponding client does so. This is automatically managed by the API so the user does not have to take care of it.
However, it is important that when shutting down a TM, the vehicles registered to it are destroyed. Otherwise, they will stop at place, as no one will be conducting them. The script `spawn_npc.py` does this automatically.
@ -179,7 +177,7 @@ However, it is important that when shutting down a TM, the vehicles registered t
---
## Multiclient and multiTM management
#### Different Traffic Manager definitions
### Different Traffic Manager definitions
When working with different clients containing different TM, understanding inner implementation of the TM in the client-server architecture becomes specially relevant. There is one ruling these scenarios: __the port is the key__.
@ -208,7 +206,7 @@ tm04 = client04.get_trafficmanager(5000) # tm04(p=5000) --> tm02 (p=5000)
The CARLA server keeps register of all the TM instances internally by storing the port and also the client IP (hidden to the user) that link to them. Right now there is no way to check the TM instances that have been created so far. A connection will always be attempted when trying to create an instance and it will either create a new __TM-Server__ or a __TM-Client__.
#### Multiclient VS MultiTM
### Multiclient VS MultiTM
Based on the different definitions for a TM, successfully creating a TM can lead to two different results:
@ -230,14 +228,14 @@ That creates a clear distinction between having multiple clients and multiple Tr
The TM is a module constantly evolving and trying to adapt the range of possibilities that it presents. For instance, in order to get more realistic behaviours we can have many clients with different TM in charge of sets of vehicles with specific and distinct behaviours. This range of possibilities also makes for a lot of different configurations that can get really complex and specific. For such reason, here are listed of considerations that should be taken into account when working with the TM as it is by the time CARLA 0.9.8 is released:
#### FPS limitations
### FPS limitations
The TM stops working properly in asynchronous mode when the simulation is under 20fps. Below that rate, the server is going much faster than the client containing the TM and behaviours cannot be simulated properly. For said reason, under these circumstances it is recommended to work in __synchronous mode__.
!!! Important
The FPS limitations are specially relevant when working in the night mode.
#### Synchronous mode
### Synchronous mode
TM-Clients cannot tick the CARLA server in synchronous mode, __only a TM-Server can call for a tick__.
If more than one TM-Server ticks, the synchrony will fail, as the server will move forward on every tick. This is specially relevant when working with the __ScenarioRunner__, which runs a TM. In this case, the TM will be subordinated to the ScenarioRunner and wait for it.

6
Docs/build_faq.md
View File

@ -54,9 +54,9 @@ To run CARLA using `CarlaUE4.sh`, follow the [quick start installation](start_qu
Many different issues can be dragged during the build installation, and show like this. Here is a list of the most likely reasons why.
* __Run Unreal Engine 4.22.__ Something may have failed when building Unreal Engine. Try running UE editor on its own and check out that it is the 4.22 release.
* __Run Unreal Engine 4.24.__ Something may have failed when building Unreal Engine. Try running UE editor on its own and check out that it is the 4.24 release.
* __Download the assets.__ The server will not be able to run without the visual content. This step is mandatory.
* __UE4_ROOT is not defined.__ The environment variable is not set. Remember to make it persistent session-wide by adding it to the `~/.bashrc` or `~/.profile`. Otherwise it will need to be set for every new shell. Run `export UE4_ROOT=~/UnrealEngine_4.22` to set the variable this time.
* __UE4_ROOT is not defined.__ The environment variable is not set. Remember to make it persistent session-wide by adding it to the `~/.bashrc` or `~/.profile`. Otherwise it will need to be set for every new shell. Run `export UE4_ROOT=~/UnrealEngine_4.24` to set the variable this time.
* __Check dependencies.__ Make sure that everything was installed properly. Maybe one of the commands was skipped, unsuccessful or the dependencies were not suitable for the system.
* __Delete CARLA and clone it again.__ Just in case something went wrong. Delete CARLA and clone or download it again.
* __Meet system requirements.__ Ubuntu version should be 16.04 or later. CARLA needs around 15GB of disk space and a dedicated GPU (or at least one with 4GB) to run.
@ -134,7 +134,7 @@ To keep other Visual Studio versions, edit ```%appdata%\Unreal Engine\UnrealBuil
Many different issues can be dragged during the build installation, and show like this. Here is a list of the most likely reasons why.
* __Restart the computer.__ There are many going on in the Windows build. Restart and make sure that everything is updated properly.
* __Run Unreal Engine 4.22.__ Something may have failed when building Unreal Engine. Run the Editor and check that 4.22 is being used.
* __Run Unreal Engine 4.24.__ Something may have failed when building Unreal Engine. Run the Editor and check that 4.24 is being used.
* __Download the assets.__ The server will not be able to run without the visual content. This step is mandatory.
* __Visual Studio 2017.__ If there are other versions of Visual Studio installed or recently uninstalled, conflicts may arise. To completely clean Visual Studio from the computer go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`.
* __Delete CARLA and clone it again.__ Just in case something went wrong. Delete CARLA and clone or download it again.

34
Docs/build_linux.md
View File

@ -9,8 +9,8 @@
* Install git
* Link GitHub and Unreal Engine
* [__Unreal Engine__](#unreal-engine)
* Download UE4.22
* Build UE4.22
* Download UE4.24
* Build UE4.24
* [__CARLA build__](#carla-build)
* Clone repository
* Get assets
@ -60,13 +60,13 @@ sudo update-alternatives --install /usr/bin/clang clang /usr/lib/llvm-7/bin/clan
# Get a GitHub and a UE account, and link both.
# Install git.
# Build Unreal Engine 4.22.
git clone --depth=1 -b 4.22 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.22
cd ~/UnrealEngine_4.22
# Build Unreal Engine 4.24.
git clone --depth=1 -b 4.24 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.24
cd ~/UnrealEngine_4.24
./Setup.sh && ./GenerateProjectFiles.sh && make
# Open the UE Editor to check everything works properly.
cd ~/UnrealEngine_4.22/Engine/Binaries/Linux && ./UE4Editor
cd ~/UnrealEngine_4.24/Engine/Binaries/Linux && ./UE4Editor
# Clone the CARLA repository.
git clone https://github.com/carla-simulator/carla
@ -76,7 +76,7 @@ cd ~/carla
./Update.sh
# Set the environment variable.
export UE4_ROOT=~/UnrealEngine_4.22
export UE4_ROOT=~/UnrealEngine_4.24
# make the CARLA server and the CARLA client.
make launch
@ -145,18 +145,18 @@ In order to access the Unreal Engine repositories, which are set to private, cre
---
## Unreal Engine
The current version of CARLA runs on __Unreal Engine 4.22__ only. The path is irrelevant, but for the sake of this tutorial, installation will be done under `~/UnrealEngine_4.22`. If the path chosen differs, remember to change it accordingly when running the commands on terminal.
The current version of CARLA runs on __Unreal Engine 4.24__ only. The path is irrelevant, but for the sake of this tutorial, installation will be done under `~/UnrealEngine_4.24`. If the path chosen differs, remember to change it accordingly when running the commands on terminal.
!!! Note
Alternatively, there is this [guide](https://docs.unrealengine.com/en-US/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnUnrealWorkflow/index.html) to build UE on Linux. When consulting it, remember that CARLA will need the __4.22 release__, not the latest.
Alternatively, there is this [guide](https://docs.unrealengine.com/en-US/Platforms/Linux/BeginnerLinuxDeveloper/SettingUpAnUnrealWorkflow/index.html) to build UE on Linux. When consulting it, remember that CARLA will need the __4.24 release__, not the latest.
Clone the content for Unreal Engine 4.22 in a local computer.
Clone the content for Unreal Engine 4.24 in a local computer.
```sh
git clone --depth=1 -b 4.22 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.22
git clone --depth=1 -b 4.24 https://github.com/EpicGames/UnrealEngine.git ~/UnrealEngine_4.24
```
Get into said folder. Remember, this is the path where UE4.22 has been cloned.
Get into said folder. Remember, this is the path where UE4.24 has been cloned.
```sh
cd ~/UnrealEngine_4.22
cd ~/UnrealEngine_4.24
```
Make the build.
```sh
@ -165,7 +165,7 @@ Make the build.
Unreal Engine should be installed in the system. Run `Engine/Binaries/Linux/UE4Editor.sh` to open the Editor and check it out.
```sh
cd ~/UnrealEngine_4.22/Engine/Binaries/Linux && ./UE4Editor
cd ~/UnrealEngine_4.24/Engine/Binaries/Linux && ./UE4Editor
```
In case something went wrong, it is related with Unreal Engine There is not much CARLA can do about it. However, the [build documentation](https://wiki.unrealengine.com/Building_On_Linux) provided by Unreal Engine may be helpful.
@ -177,7 +177,7 @@ The system should be ready to start building CARLA. Just for clarity, a brief su
* Minimum technical requirements to run CARLA are suitable.
* Dependencies have been properly installed.
* GitHub account is ready.
* Unreal Engine 4.22 runs smooth.
* Unreal Engine 4.24 runs smooth.
!!! Note
Downloading aria2 with `sudo apt-get install aria2` will speed up the following commands.
@ -219,10 +219,10 @@ Run the script to get the assets.
### Set the environment variable
This is necessary for CARLA to find the Unreal Engine 4.22 installation folder.
This is necessary for CARLA to find the Unreal Engine 4.24 installation folder.
```sh
export UE4_ROOT=~/UnrealEngine_4.22
export UE4_ROOT=~/UnrealEngine_4.24
```
The variable should be added to `~/.bashrc` or `~/.profile` to be set persistently session-wide. Otherwise, it will only be accessible from the current shell.

10
Docs/build_windows.md
View File

@ -6,7 +6,7 @@
* [__Necessary software__](#necessary-software)
* Minor installations: CMake, git, make, Python3 x64
* Visual Studio 2017
* Unreal Engine 4.22
* Unreal Engine 4.24
* [__CARLA build__](#carla-build)
* Clone repository
* Get assets
@ -35,7 +35,7 @@ CARLA forum</a>
# Git
# Make
# Python3 x64
# Unreal Engine 4.22
# Unreal Engine 4.24
# Visual Studio 2017 with Windows 8.1 SDK and x64 Visual C++ Toolset.
# Set environment variables for the software
@ -85,12 +85,12 @@ Get the 2017 version from [here](https://developerinsider.co/download-visual-stu
!!! Important
Other Visual Studio versions may cause conflict. Even if these have been uninstalled, some registers may persist. To completely clean Visual Studio from the computer, go to `Program Files (x86)\Microsoft Visual Studio\Installer\resources\app\layout` and run `.\InstallCleanup.exe -full`
### Unreal Engine 4.22
### Unreal Engine 4.24
Go to [Unreal Engine](https://www.unrealengine.com/download) and download the _Epic Games Launcher_. In `Engine versions/Library`, download __Unreal Engine 4.22.x__. Make sure to run it in order to check that everything was properly installed.
Go to [Unreal Engine](https://www.unrealengine.com/download) and download the _Epic Games Launcher_. In `Engine versions/Library`, download __Unreal Engine 4.24.x__. Make sure to run it in order to check that everything was properly installed.
!!! Note
Having VS2017 and UE4.22 installed, a __Generate Visual Studio project files__ option should appear when doing right-click on __.uproject__ files. If this is not available, something went wrong whith the UE4.22 installation. Create a UE project to check it out and reinstall if necessary.
Having VS2017 and UE4.24 installed, a __Generate Visual Studio project files__ option should appear when doing right-click on __.uproject__ files. If this is not available, something went wrong whith the UE4.24 installation. Create a UE project to check it out and reinstall if necessary.
---
## CARLA build

BIN
Docs/img/Town01.png~
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 36 KiB

BIN
Docs/img/Town02.png~
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 32 KiB

BIN
Docs/img/Town03.png~
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 127 KiB

BIN
Docs/img/Town05.png~
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 186 KiB

BIN
Docs/img/Town07.png~
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 86 KiB