From ee77b3afa683a4366d84e788afb9c76bf7b71642 Mon Sep 17 00:00:00 2001 From: corkyw10 Date: Mon, 11 Jan 2021 17:08:30 +0100 Subject: [PATCH] CarSim tutorial refactoring and name change to bring in line with other tutorials --- Docs/carsim_integration.md | 129 --------------------------- Docs/tuto_G_carsim_integration.md | 143 ++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 3 files changed, 144 insertions(+), 130 deletions(-) delete mode 100644 Docs/carsim_integration.md create mode 100644 Docs/tuto_G_carsim_integration.md diff --git a/Docs/carsim_integration.md b/Docs/carsim_integration.md deleted file mode 100644 index 0bdd0c998..000000000 --- a/Docs/carsim_integration.md +++ /dev/null @@ -1,129 +0,0 @@ -# CARSIM Integration (Beta) - -This integration allows CARLA to forward all vehicle controls to CarSim in order to make all -the physics calculations of the vehicle and send back the new state of the vehicle to CARLA. - -* [__Requisites__](#requisites) -* [__Setup Carsim__](#set-up-carsim) - * [__SIM file__](#sim-file) - * [__On Windows__](#on-windows) - * [__On Ubuntu__](#on-ubuntu) - * [__Vehicle Sizes__](#vehicle-sizes) -* [__Run Simulation__](#run-simulation) - ---- -## Requisites - -* [CarSim](https://www.carsim.com/products/carsim/index.php) software + licence -* Unreal 4.24 plugin (version 2020.0): [Vehicle dynamics](https://www.unrealengine.com/marketplace/en-US/product/carsim-vehicle-dynamics) -* CARLA compiled with flag **--carsim** (CARLA packages are CarSim ready) - -It is necessary to have a licence for CarSim software set up and running. - -For the communication with Unreal it is necessary to install the free plugin in UE called [**vehicle -dynamics**](https://www.unrealengine.com/marketplace/en-US/product/carsim-vehicle-dynamics). -* **For Ubuntu** only: - 1) Download the plugin version 2020.0 from [here](https://www.carsim.com/users/unreal_plugin/unreal_plugin_2020_0.php) - 2) After downloading the plugin replace the file **CarSim.Build.cs** with the one [here](https://carla-releases.s3.eu-west-3.amazonaws.com/Backup/CarSim.Build.cs). We added the proper solver to use. - -If you use CARLA from source, then you need to compile the server with the **--carsim** flag: -```sh -make CarlaUE4Editor ARGS="--carsim" -``` -All packages are already compiled with the **--carsim** flag, so they are ready to use with CarSim. - -## Set Up CarSim -#### SIM File - -You need to generate the .sim file that describes the simulation to run in both CARLA and -CarSim. The CarSim plugin needs this file to know about the simulation to run. - -##### On Windows - -You can use the GUI to generate the file once you have all the parameters configured. - -![generate .sim file](img/carsim_generate.jpg) - -For Windows systems, a **.sim** file looks like this: - -``` -SIMFILE - -SET_MACRO $(ROOT_FILE_NAME)$ Run_dd7a828d-4b14-4c77-9d09-1974401d6b25 -SET_MACRO $(OUTPUT_PATH)$ D:\carsim\Data\Results -SET_MACRO $(WORK_DIR)$ D:\carsim\Data\ -SET_MACRO $(OUTPUT_FILE_PREFIX)$ $(WORK_DIR)$Results\Run_dd7a828d-4b14-4c77-9d09-1974401d6b25\LastRun - -FILEBASE $(OUTPUT_FILE_PREFIX)$ -INPUT $(WORK_DIR)$Results\$(ROOT_FILE_NAME)$\Run_all.par -INPUTARCHIVE $(OUTPUT_FILE_PREFIX)$_all.par -ECHO $(OUTPUT_FILE_PREFIX)$_echo.par -FINAL $(OUTPUT_FILE_PREFIX)$_end.par -LOGFILE $(OUTPUT_FILE_PREFIX)$_log.txt -ERDFILE $(OUTPUT_FILE_PREFIX)$.vs -PROGDIR D:\carsim\ -DATADIR D:\carsim\Data\ -GUI_REFRESH_V CarSim_RefreshEvent_7760 -RESOURCEDIR D:\carsim\\Resources\ -PRODUCT_ID CarSim -PRODUCT_VER 2020.0 -ANIFILE D:\carsim\Data\runs\animator.par -VEHICLE_CODE i_i -EXT_MODEL_STEP 0.00050000 -PORTS_IMP 0 -PORTS_EXP 0 - -DLLFILE D:\carsim\Programs\solvers\carsim_64.dll -END -``` -##### On Ubuntu -For Ubuntu there is no way to create these files via GUI. You need to generate them in Windows and -move the related .par, .txt, .vs files to Ubuntu. You then need to modify the .sim file so that the -variables `INPUT`, `INPUTARCHIVE`, `LOGFILE`, etc point towards the same files in your Ubuntu -system. Finally, you need to replace the `DLLFILE` line to point towards the CarSim solver which -in the default installation will be `SOFILE /opt/carsim_2020.0/lib64/libcarsim.so.2020.0`. Your .sim -file should be similar to this: - -``` -SIMFILE - -FILEBASE /path/to/LastRun -INPUT /path/to/Run_all.par -INPUTARCHIVE /path/to/LastRun_all.par -ECHO /path/to/LastRun_echo.par -FINAL /path/to/LastRun_end.par -LOGFILE /path/to/LastRun_log.txt -ERDFILE /path/to/LastRun.vs -PROGDIR /opt/carsim_2020.0/lib64/ -DATADIR . -PRODUCT_ID CarSim -PRODUCT_VER 2020.0 -VEHICLE_CODE i_i - -SOFILE /opt/carsim_2020.0/lib64/libcarsim.so.2020.0 -END -``` -#### Vehicle Sizes - -Care needs to be taken regarding the sizes of vehicles. CarSim lets you specify the dimensions of -the vehicle to use, but currently there is no correlation between a CarSim vehicle and a CARLA -vehicle. That means that the vehicles in both parts have different dimensions, and the CARLA vehicle is only used as a placeholder in the simulation. - -![carsim vehicle sizes](img/carsim_vehicle_sizes.jpg) - -## Run Simulation - -You only need to spawn a CARLA vehicle and enable CarSim on it with the Python API function - -```sh -vehicle.enable_carsim() -``` - -Now all input controls sent to the vehicle will be forwarded to CarSim, which will update the -physics and send back the status of the vehicle (the transform) to the CARLA vehicle. - -Once the simulation has finished you can analyze all the data in CarSim as usual. - -![carsim analysis](img/carsim_analysis.jpg) - - diff --git a/Docs/tuto_G_carsim_integration.md b/Docs/tuto_G_carsim_integration.md new file mode 100644 index 000000000..f2d35bde8 --- /dev/null +++ b/Docs/tuto_G_carsim_integration.md @@ -0,0 +1,143 @@ +# CarSim Integration (Beta) + +CARLA's integration with CarSim allows vehicle controls in CARLA to be forwarded to CarSim. CarSim will do all required physics calculations of the vehicle and return the new state to CARLA. + +This page shows you how to generate a `.sim` file, explains how vehicle dimensions relate between CARLA and CarSim and how to run a simulation on CARLA using the CarSim integration. + +!!! Warning + This feature is in beta release. This means that development of the feature is ongoing and some aspects of the feature may not work as expected. If you come across any problems feel free to open an issue on [GitHub](https://github.com/carla-simulator/carla). + +* [__Before you begin__](#before-you-begin) +* [__Set up CarSim__](#set-up-carsim) + * [__Generate the .sim file__](#generate-the-sim-file) + * [__On Windows__](#on-windows) + * [__On Ubuntu__](#on-ubuntu) + * [__Vehicle sizes__](#vehicle-sizes) +* [__Run the simulation__](#run-the-simulation) + +--- +## Before you begin + +1. You will need a license for CarSim and to have the software up and running. If you don't currently have a license for CarSim, you can contact the team [here](https://www.carsim.com/forms/additional_information.php) for information. +2. To allow communication with Unreal Engine you will need to install the VehicleSim Dynamics plugin (version 2020.0) for Unreal Engine 4.24. For information on finding specific versions of the plugin, check this [link](https://www.carsim.com/products/supporting/unreal/index.php). Installation of the plugin will depend on your operating system: + + __For Windows__: + + Get the plugin [here](https://www.unrealengine.com/marketplace/en-US/product/carsim-vehicle-dynamics). + + __For Ubuntu__: + + 1. Download the plugin [here](https://www.carsim.com/users/unreal_plugin/unreal_plugin_2020_0.php). + 2. Replace the file `CarSim.Build.cs` with the file found [here](https://carla-releases.s3.eu-west-3.amazonaws.com/Backup/CarSim.Build.cs) in order to use the correct solver for Ubuntu. + +3. If you have built CARLA from source then you will need to compile the server with the `--carsim` flag. This step can be skipped if you are using the packaged version of CARLA. The packaged version has already been compiled using this flag. + + To compile the server with the `--carsim` flag in the source version of CARLA, run the following command: + +```sh + make launch ARGS="--carsim" +``` + +## Set up CarSim + +The following section details how to generate the `.sim` file which is required to run the simulation. There is also important information detailed regarding the relationship of vehicle sizes between CARLA and CarSim. + +#### Generate the .sim file + +The `.sim` file describes the simulation to be run in both CARLA and CarSim. This file is required by the plugin to run the simulation. There is currently no way to generate this file on Ubuntu, however we will describe below how to use a previously generated file to run the simulation on Ubuntu. + +##### On Windows + +After you have configured all the parameters on CarSim, use the GUI to generate the `.sim` file as highlighted below: + +![generate .sim file](img/carsim_generate.jpg) + +The resulting `.sim` file should look something like this: + +``` +SIMFILE + +SET_MACRO $(ROOT_FILE_NAME)$ Run_dd7a828d-4b14-4c77-9d09-1974401d6b25 +SET_MACRO $(OUTPUT_PATH)$ D:\carsim\Data\Results +SET_MACRO $(WORK_DIR)$ D:\carsim\Data\ +SET_MACRO $(OUTPUT_FILE_PREFIX)$ $(WORK_DIR)$Results\Run_dd7a828d-4b14-4c77-9d09-1974401d6b25\LastRun + +FILEBASE $(OUTPUT_FILE_PREFIX)$ +INPUT $(WORK_DIR)$Results\$(ROOT_FILE_NAME)$\Run_all.par +INPUTARCHIVE $(OUTPUT_FILE_PREFIX)$_all.par +ECHO $(OUTPUT_FILE_PREFIX)$_echo.par +FINAL $(OUTPUT_FILE_PREFIX)$_end.par +LOGFILE $(OUTPUT_FILE_PREFIX)$_log.txt +ERDFILE $(OUTPUT_FILE_PREFIX)$.vs +PROGDIR D:\carsim\ +DATADIR D:\carsim\Data\ +GUI_REFRESH_V CarSim_RefreshEvent_7760 +RESOURCEDIR D:\carsim\\Resources\ +PRODUCT_ID CarSim +PRODUCT_VER 2020.0 +ANIFILE D:\carsim\Data\runs\animator.par +VEHICLE_CODE i_i +EXT_MODEL_STEP 0.00050000 +PORTS_IMP 0 +PORTS_EXP 0 + +DLLFILE D:\carsim\Programs\solvers\carsim_64.dll +END +``` +##### On Ubuntu + +There is no way to create the `.sim` file via GUI on Ubuntu. In order to proceed you will need to follow these steps: + +1. Generate the `.sim` file in Windows +2. Move the related `.par`, `.txt` and `.vs` files to Ubuntu. +3. Modify the `.sim` file so the variables `INPUT`, `INPUTARCHIVE`, `LOGFILE` and so on point towards the corresponding files in your Ubuntu +system. +4. Replace the `DLLFILE` line to point towards the CarSim solver which, in the default installation, will be `SOFILE /opt/carsim_2020.0/lib64/libcarsim.so.2020.0`. + +The resulting file should be similar to this: + +``` +SIMFILE + +FILEBASE /path/to/LastRun +INPUT /path/to/Run_all.par +INPUTARCHIVE /path/to/LastRun_all.par +ECHO /path/to/LastRun_echo.par +FINAL /path/to/LastRun_end.par +LOGFILE /path/to/LastRun_log.txt +ERDFILE /path/to/LastRun.vs +PROGDIR /opt/carsim_2020.0/lib64/ +DATADIR . +PRODUCT_ID CarSim +PRODUCT_VER 2020.0 +VEHICLE_CODE i_i + +SOFILE /opt/carsim_2020.0/lib64/libcarsim.so.2020.0 +END +``` +#### Vehicle sizes + +Although CarSim lets you specify the dimensions of the vehicle to use in the simulation, there is currently no correlation between a CarSim vehicle and a CARLA +vehicle. This means that the vehicles in both programmes will have different dimensions. The role of the CARLA vehicle is only to act as a placeholder during the simulation. + +![carsim vehicle sizes](img/carsim_vehicle_sizes.jpg) + +!!! Note + There is no correlation between vehicle size in CARLA and CarSim. The CARLA vehicle is only a simulation placeholder. + +## Run the simulation + +All that is needed when running the simulation is to enable CarSim when you spawn a vehicle. This can be done by passing the path to the `.sim` file to the following [method](https://carla.readthedocs.io/en/latest/python_api/#carla.Vehicle.enable_carsim) of the Python API: + +```sh +vehicle.enable_carsim() +``` + +All input controls sent to the vehicle will be forwarded to CarSim. CarSim will update the +physics and send back the status of the vehicle (the transform) to the CARLA vehicle. + +Once the simulation has finished you can analyze all the data in CarSim as usual. + +![carsim analysis](img/carsim_analysis.jpg) + + diff --git a/mkdocs.yml b/mkdocs.yml index 8dd37b5c9..59d3f69cc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,7 +50,7 @@ nav: - 'Control walker skeletons': "tuto_G_control_walker_skeletons.md" - 'Generate maps with OpenStreetMap': 'tuto_G_openstreetmap.md' - 'Retrieve simulation data': "tuto_G_retrieve_data.md" - - 'CarSim Integration (Beta)': "carsim_integration.md" + - 'CarSim Integration (Beta)': "tuto_G_carsim_integration.md" - Tutorials (assets): - 'Add a new map': 'tuto_A_add_map.md' - 'Add a new vehicle': 'tuto_A_add_vehicle.md'