Merge branch 'dev'

Author: bernatx

.gitignore

@@ -7,6 +7,9 @@ Util/Build
 Install
 Plugins
 !Unreal/CarlaUE4/Plugins
+Unreal/CarlaUE4/Plugins/Streetmap
+Unreal/CarlaUE4/Plugins/HoudiniEngine
+
 
 /ExportedMaps
 /Import/*

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Required
+
+version: 2
+
+# Set the version of Python and other tools you might need
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.7"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+
+python:
+  install:
+  - requirements: Docs/requirements.txt

.readthedocs.yml

@@ -1,3 +1,31 @@
+## CARLA 0.9.15
+
+  * Added Digital Twins feature version 0.1. Now you can create your own map based on OpenStreetMaps
+  * Added compatibility with SymReady Assets, using NVIDIA Omniverse
+  * Added new maps: Town13 (is a large map) and Town15
+  * The spectator will be used to load tiles and actor in Large Maps when no other actors with the rolename 'ego_vehicle' or 'hero' are present. Added the `spectator_as_ego` to the `carla.WorldSettings()` to allow users to disable this behavior.
+  * Add keyword arguments for `carla.TrafficManager` Python API functions
+  * Added build support for VS2022 and Ninja for LibCarla and osm2odr on Windows
+  * Added empty actor
+  * Restored gamma value to 2.2 instead of 2.4
+  * CarlaExporter tool now exports the box collider and convex collider of the object if it has one, otherwise the mesh
+  * Pedestrians with AI or in replayer are now faster around 10x. They have collisions disabled until they hit a vehicle.
+  * Added API function to avoid replaying the spectator
+    * `Client.set_replayer_ignore_spectator(bool)`
+    * `start_replaying.py` using flag `--move-spectator`
+  * Surface non-unity build mode by passing ARGS=--no-unity to make; allows IWYU-type errors to be unmasked and fixed.
+  * Added maps, vehicles, pedestrians and props catalogues to the documentation
+  * Collisions detected by the CollisionSensor no longer generate more than one event per frame.
+  * Added API function to load a map only if it is different from the current one.
+  * Fixed a bug in the TrafficManager causing vehicles that reached an ending lane to have abnormal behavior while lane changing.
+  * Fixed bug causing the TM's unstuck logic to incorrectly remove the vehicles in some situations.
+  * Fixed the extra data in Directx textures, so we need to copy row by row on Windows to remove extra bytes on images
+  * Fixed vertices of big meshes (more than 65k vertices) in CarlaExporter
+  * Fixed sensors to check for the stream to be ready (race condition)
+  * Fixed bug causing the `FPixelReader::SavePixelsToDisk(PixelData, FilePath)` function to crash due to pixel array not set correctly.
+  * Fixed segfaults in Python API due to incorrect GIL locking under Python 3.10.
+  * Fixed the import script, where could use any other TilesInfo.txt if the destination folder has many
+
 ## CARLA 0.9.14
 
   * Fixed tutorial for adding a sensor to CARLA.
@@ -29,6 +57,7 @@
   * Python agents now accept a carla.Map and GlobalRoutePlanner instances as inputs, avoiding the need to recompute them.
   * Python agents now have a function to lane change.
   * Python agents now detect vehicle in adjacent lanes if invaded due to the offset.
+  * Python agents now have the offset exposed.
   * Fixed bug causing the python agents to sometimes not detect a blocking actor if there were severral actors around it.
   * Improved Python agents performance for large maps.
   * Fix a bug at `Map.get_topology()`, causing lanes with no successors to not be part of it.

CHANGELOG.md

@@ -0,0 +1,87 @@
+!!! note
+	The __Digital Twin Tool__ is currently an __experimental feature__ and is not considered *production ready* at this stage. Some parts of maps may be undecorated or untextured. Hence it should only be used for experimental research projects.
+
+# Digital Twin Tool
+
+![digital_twin_pipeline](img/pipeline.jpg)
+
+- [__Downloading and preparing OSM map data__](#downloading-and-preparing-osm-map-data)
+- [__OpenStreetMap browser__](#openstreetmap-browser)
+- [__Procedural environment generation__](#procedural-environment-generation)
+	- [Road decoration](#overview)
+	- [Buildings](#alsm)
+- [__Generate the map__](#generate-the-map)
+- [__Save the map__](#save-the-map)
+
+The __Digital Twin Tool__ enables procedural generation of unique 3D environments based on road networks derived from the [OpenStreetMap](https://www.openstreetmap.org) (OSM) service. Through the Digital Twin Tool interface in CARLA's Unreal Engine editor a user can select a region of map from OSM and download the road network as the basis for a new CARLA map. The tool then fills the spaces between the roads with procedurally generated 3D buildings that adjust to the layout of the road, creating a realistic 3D road environment with high variability.
+
+## Building the OSM renderer
+
+If you are using Linux, you have the option of using the OSM renderer in the CARLA interface to navigate a large OSM map region that you have downloaded. You first need to build the OSM renderer. Run `make osmrenderer` inside the CARLA root directory. You may need to upgrade your version of CMake to v3.2 or above in order for this to work. This will create two folders in your build directory called `libosmcout-source` and `libosmcout-build`. Windows users do not have the option of using the OSM renderer and must use directly a URL. 
+
+## Downloading and preparing OSM map data
+
+![osm_website](img/osm_export.png)
+
+In a web-browser, go to the [OpenStreetMap website](https:/www.openstreetmap.org) and choose an area of the map which you would like to use. Define your region and then export the data as an `.osm` file, or you can use a URL, as explained later. Alternatively, you could use other tools based on the OpenStreetMap service such as [GeoFabrik](https://download.geofabrik.de/), which allows specific map regions such as states or territories to be extracted from the OSM data.
+
+There are two ways to use the OSM data. Using a URL or downloading an OSM file: 
+
+### Using a URL
+
+In the [OpenStreetMap website](https:/www.openstreetmap.org) website, navigate to an area of interest, then press `Export`, you may also want to use the `Manually select a different area` option. Then, right click on `Overpass API` and select `Copy link` from the context menu. You must ensure that the file will be no bigger than 1 Gb. Take this link and paste it into the URL field of the interface.
+
+### Downloading an OSM file and navigating in the interface
+
+This option is only available to Linux users. You may download a larger region of map, for example an entire state or territory, then use the OSM interface in CARLA to navigate the map using the arrow and zoom buttons. Download your desired region of OSM data as a `.osm` file, then place this file in the `{CARLA_ROOT}/Build/libosmcout-source/maps/` folder. Open a terminal inside this folder and run the following command:
+
+```sh
+cd {CARLA_ROOT}/Build/libosmcout-source/maps/
+./build.sh <path_to_osm_file>
+```
+
+## OpenStreetMap browser
+
+To open the OSM browser, open the content browser and navigate to `CarlaToolsContent/OnroadMapGenerator`. Right click on *UW_OnRoadMainWidget* and select *Launch Editor Utility Widget* from the context menu. This will open the tool's interface. 
+
+![osm_interface_open](img/digital_twins_widget.png)
+
+The interface enables browsing of a region of OSM map that has been downloaded from the OSM database and baked. First, you should enter the directory location where you stored the processed OSM data in the previous step in the *Select OSM Database* field in the interface. If you are using a URL directly, paste it into the `OSM URL` field, you will not be able to use the navigator in this case. 
+
+![osm_interface](img/digital_twins_interface.png)
+
+Use the directional arrows and the zoom icons to navigate the map and find a part of the road network you want to turn into a CARLA map. The square region you see in the preview will be the extent of your map. Enter an appropriate name in the `File Name` field and then press *generate* to start the procedural generation process. The map generation process may take several minutes, or more if you are using a large region.
+
+## Procedural environment generation
+
+### Road decoration
+
+The tool extracts the road network from the OSM data as the basis of the map. The road surface is decorated with realistic surface irregularities, road markings and textures. 
+
+![road_markings](img/road_surface.jpg)
+
+### Buildings
+
+The empty spaces between the roads are populated with buildings or open areas that will adjust their shape and dimensions to fill the space between the roads. 
+
+![procedural_buildings](img/procedural_building_generation.jpg)
+
+The procedural generation tool extracts the building footprints and height information from the OSM data to generate virtual buildings with similar dimensions. Detailed cladding is applied to simulate windows, doors and balconies. Different decoration styles are applied depending upon the dimensions of the building, with the tallest buildings having an office style, smaller buildings have a commercial or residential style applied according to the area of the building footprint.
+
+![procedural_cities](img/digital_twins_vegetation.jpg)
+
+Vegetation is also added to the pavements in the next step step for additional detail.
+
+![residential_building_style](img/digital_twins_buildings.jpg)
+*Digital Twin Tool building styles*
+
+The buildings are in a variety of styles that are randomly distributed throughout the city, the architectural style of an area is chosen based on the characteristic dimensions of the buildings extracted from the OSM data.
+
+## Generate the map
+
+The generation step will take around 10 minutes for a 2x2 km<sup>2</sup> region, larger regions will take longer. Once the generation process has finished, you can examine the map in 3D in the Unreal Engine editor. 
+
+## Save the map
+
+If you are satisfied with the generated map then you can press *Save Map* button to save the map. __This step will take a significant amount of time__, it may take over an hour and could take several. You should prepare to leave your computer running for several hours while this step is completed. Once this step is completed, the map will be available through the Unreal Engine editor or through the CARLA API, the same as any other map. 
+

Docs/adv_digital_twin.md

@@ -0,0 +1,153 @@
+!!! note
+	The __Procedural Building Tool__ is currently an __experimental feature__ and is not considered *production ready* at this stage. Hence it should only be used for experimental research projects.
+
+# Procedural Building Tool
+
+The __Procedural Building Tool__ facilitates the generation of virtual 3D buildings for which the dimensions and decoration styles can be modulated to create a near infinite array of variations through a simple interface. The footprint dimensions and height in stories can be chosen through the interface. Then users can select a variety of styles for the building lobby, the body and the top floor or penthouse. A variety of facia element styles can be chosen for features such as corners windows and balconies from the CARLA asset library. 
+
+- [__Opening the tool__](#opening-the-procedural-building-tool)
+- [__Base parameters__](#base-parameters)
+- [__Mesh parameters__](#mesh-parameters)
+- [__Mesh elements__](#mesh-elements)
+	- [Sockets](#sockets)
+- [__Facade materials__](#facade-materials)
+- [__Cooking__](#cooking)
+
+## Opening the Procedural Building Tool
+
+Firstly, you need to add a procedural building actor to the scene. Navigate to `Content>Carla>Blueprints>LevelDesign` and drag the *BP_ProceduralBuilding* blueprint into your map. Move the asset to the position where you wish to visualize the building. Choose a place where you have space so you can see the result clearly. Then to open the tool, launch the Procedural Building tool by right clicking on the *WD_ProceduralBuilding* widget and selecting *Run editor utility widget* from the context menu. This will open the tool's interface. 
+
+![open_pb_tool](img/open_pb_tool.png)
+
+!!! note
+	You must complete this step before opening the tool, an instance of the *BP_ProceduralBuilding* blueprint must exist in the map before the tool can function. You must also ensure that the *BP_ProceduralBuilding* entity is selected in the *World outliner* before proceeding.
+
+## Base parameters
+
+![base_parameters](img/pb_base_parameters.png)
+
+In the base parameters section you select the fundamental properties of your building, such as the footprint and the height in floors.
+
+!!! note
+	Until you have selected mesh pieces in the [mesh parameters](#mesh-parameters) section, you will not see any changes in the Unreal Engine viewport when you adjust the base parameters
+
+The available parameters are as follows:
+
+- __Seed__: sets the random seed for the procedural generation, this enables variations on the building with the same settings.
+- __Num floors__: sets the number of stories or floors the building will have, and henceforth defines the height of the building.
+- __Length X/Y__: defines the size of the footprint of the building in the X and Y dimensions. These are unitless, the number denotes the number repeating sections, each section is a column of windows.
+- __Create automatically__: if this option is selected, the building will automatically update in the viewport so you can see the effect of your adjustments.
+- __Corners__: allows corner pieces to be added to the building, you can choose these pieces in the Mesh Parameters section.
+- __Walls__: replace the middle pieces of the left/right/front/back of the building with alternate pieces that can be selected using the [Mesh parameters](#mesh-parameters) menu.
+- __Doors__: array allowing the placement of a door in the lobby level. The door is placed at the chosen index position.
+
+## Mesh parameters
+
+![mesh_parameters](img/pb_mesh_parameters.png)
+
+In the Mesh Parameters tab in the interface, we choose the mesh pieces that will be used to clad the exterior of the building. There are 5 categories of mesh pieces for different parts of the building:
+
+- __Lobby__: mesh pieces to decorate the lobby of the building.
+- __Midsection__: mesh pieces to decorate the midsection of the building, every floor between the lobby and the top floor.
+- __Penthouse__: mesh pieces to decorate the penthouse level.
+- __Doors__: mesh pieces to add doors to the lobby
+- __Walls__: mesh pieces to decorate the walls of the building
+
+In each category you will find numerous options for mesh pieces. Click on one or more such that they turn red, these will be added to the respective section of your building. If you choose more than one, the tool will randomly alternate between the choices. As you select the mesh pieces for each section of your building, if you have *Create automatically* selected in the base parameters section, you will see the building taking shape in the editor viewport.
+
+![building_parts](img/pb_building_parts.png)
+
+## Mesh elements
+
+![mesh_elements](img/pb_mesh_elements.png)
+
+In this section you can select the more detailed elements of the building such as windows, columns, plant pots, air conditioning units and antennas. Each type of decoration has slightly different properties.
+
+There are numerous types of decoration for details of the building:
+
+- __Vertical/Horizontal window meshes__: these mesh pieces define the style of the window frames in the building. Vertical window meshes will occupy the window spaces that are taller than their width, while horizontal window meshes will occupy the window spaces that are wider than their height. If you select multiple options, they will alternate. 
+
+- __Column meshes__: these simulate brickwork column details that span the height of the building
+
+- __Top/Bottom window details__: these meshes decorate the top of the windows with lintels and sunshades and the bottom of the windows with window sills and plant boxes.
+
+- __Window columns__: brickwork columns that separate windows
+
+- __Curtain meshes__: curtains and blinds to go inside the windows
+
+- __Pot meshes__: plant pots that are added to window sills and plant boxes at specified socket points
+
+- __Air conditioner meshes__: air conditioning units that are added to the windows at specified socket points
+
+- __Pipe meshes__: pipes that descend the building vertically mimicking drainage pipes for the roof
+
+- __Wire meshes__: wires that descend the building vertically mimicking TV aerial extensions and lightning grounding wires
+
+- __Antenna meshes__: TV antennas that protrude from the windows
+
+![mesh_variations](img/pb_detail_variations.webp)
+
+ The parameters work as follows:
+
+ __Common parameters__:
+
+* __Percentage__: controls the amount pieces that will be placed on the building, 100% means all available spaces will be occupied
+* __Offset__: spacial offset of the piece from the body of the building
+
+__Blinds and curtains__:
+
+* __Min/Max size__: selects the min/max length of the blinds or curtains with random variation between the values. 1.0 is fully shut, 0.0 is fully open.
+
+__Pipes and wires__:
+
+* __Index__: defines the face of the building where the pipe will be placed
+* __Offset side/front__: adds a spatial offset to the piece from the center of the face of the building
+
+!!! note
+	You may find in some cases that when you choose detail mesh pieces such as plant pots, antennas and air conditioning units, you don't see any change in the building. This is most likely because the pieces you are using don't have the appropriate sockets needed to add the pieces you chose. Refer to the [sockets section](#sockets) to learn how to use sockets
+
+### Sockets
+
+![socket_details](img/pb_detail_section.png)
+
+Sockets are anchor points which define where to place detail meshes on another mesh piece. To add sockets to the mesh pieces in the procedural building, with the procedural building selected, go to the *details panel*, normally on the right hand side of the UE editor interface. In there, you will find the *Meshes* and *Detail meshes* panels. Open the relevant section to open the mesh piece where you wish to place the socket.
+
+![mesh_details](img/pb_mesh_details.png)
+
+Find the mesh on which you want to place a socket and double click the icon to open it in the editor. Click *create socket* to add a socket and name it using the following convention:
+
+* Air conditioning unit: aa_*
+* Antennas: ant_*
+* Plant pots: pot_*
+
+Replace the asterisk with an index, depending upon how many sockets you have, i.e. aa_0, aa_2, aa_3...
+
+![socket_details](img/pb_add_socket.png)
+
+When you click *Create socket* the socket will be instantiated in the editor with a 3D handle. Drag the socket to the desired position on the mesh, this is where your detail piece will appear attached to the unit. 
+
+## Facade materials
+
+![facade_materials](img/pb_facade_materials.png)
+
+In the facade materials tab, you can browse and preview the material that you want to decorate the walls of your building.
+
+![facade_changes](img/pb_facade_changes.webp)
+
+## Cooking
+
+In the cooking tab, you initiate the combination of all the mesh pieces and materials you've selected into a single static mesh with associated materials and textures. An LOD texture of the building will also be created for the LOD. Specify a folder name in the interface where the assets for your new building will be saved.
+
+Once you have cooked your building, you will then be able to place instances of the building in the map just like any other CARLA assets.
+
+
+
+
+
+
+
+
+
+
+
+