diff --git a/docs/azure.md b/docs/azure.md index 4d4f0f75d5..24ace28094 100644 --- a/docs/azure.md +++ b/docs/azure.md @@ -15,9 +15,9 @@ Use [this](https://github.com/microsoft/AirSim/blob/master/azure/azure-env-creat - When using an Azure Trial account, the default vCPU quota may not be enough to allocate the required VM to run AirSim. If that's the case, you will see an error when trying to create the VM and will have to make a support request to increase the default quota. - To avoid charges for the Virtual Machine usage while not in use, remember to deallocate its resources from the [Azure Portal](https://portal.azure.com) or use the following command from the Azure CLI: - ```bash - az vm deallocate --resource-group MyResourceGroup --name MyVMName - ``` +```bash +az vm deallocate --resource-group MyResourceGroup --name MyVMName +``` ## Code and debug from Visual Studio Code and Remote SSH - Install Visual Studio Code diff --git a/docs/build_linux.md b/docs/build_linux.md index 37519a7daf..7c7bc7a192 100644 --- a/docs/build_linux.md +++ b/docs/build_linux.md @@ -19,14 +19,14 @@ Please see instructions [here](https://github.com/Microsoft/AirSim/blob/master/d - Clone Unreal in your favorite folder and build it (this may take a while!). **Note**: We only support Unreal >= 4.22 at present. We recommend using 4.24. - ```bash - # go to the folder where you clone GitHub projects - git clone -b 4.24 https://github.com/EpicGames/UnrealEngine.git - cd UnrealEngine - ./Setup.sh - ./GenerateProjectFiles.sh - make - ``` +```bash +# go to the folder where you clone GitHub projects +git clone -b 4.24 https://github.com/EpicGames/UnrealEngine.git +cd UnrealEngine +./Setup.sh +./GenerateProjectFiles.sh +make +``` #### macOS - Download Unreal Engine @@ -41,18 +41,19 @@ Click on the `Add Versions` which should show the option to download **Unreal 4. - Clone AirSim and build it: - ```bash - # go to the folder where you clone GitHub projects - git clone https://github.com/Microsoft/AirSim.git - cd AirSim - ``` +```bash +# go to the folder where you clone GitHub projects +git clone https://github.com/Microsoft/AirSim.git +cd AirSim +``` - By default AirSim recommends using clang 8 to build the binaries as those will be compatible with UE 4.24. The setup script will install the right version of cmake, llvm, and eigen. + By default AirSim uses clang 8 to build for compatibility with UE 4.24. The setup script will install the right version of cmake, llvm, and eigen. - ```bash - ./setup.sh - ./build.sh - ``` +```bash +./setup.sh +./build.sh +# use ./build.sh --debug to build in debug mode +``` ### Build Unreal Environment diff --git a/docs/docker_ubuntu.md b/docs/docker_ubuntu.md index 67987d7291..d4aeec6dc1 100644 --- a/docs/docker_ubuntu.md +++ b/docs/docker_ubuntu.md @@ -11,12 +11,13 @@ We've two options for docker. You can either build an image for running [airsim You can specify any [NVIDIA cudagl](https://hub.docker.com/r/nvidia/cudagl/) at your own risk. `--target_image` is the desired name of your docker image. Defaults to `airsim_binary` with same tag as the base image - ``` - $ cd Airsim/docker; - $ python build_airsim_image.py \ - --base_image=nvidia/cudagl:10.0-devel-ubuntu18.04 \ - --target_image=airsim_binary:10.0-devel-ubuntu18.04 - ``` + +```bash +$ cd Airsim/docker; +$ python build_airsim_image.py \ + --base_image=nvidia/cudagl:10.0-devel-ubuntu18.04 \ + --target_image=airsim_binary:10.0-devel-ubuntu18.04 +``` - Verify you have an image by: `$ docker images | grep airsim` @@ -25,16 +26,19 @@ We've two options for docker. You can either build an image for running [airsim - Get [an unreal binary](https://github.com/Microsoft/AirSim/releases/tag/v1.2.0Linux) or package your own project in Ubuntu. Let's take the Blocks binary as an example. You can download it by running - ``` - $ cd Airsim/docker; - $ ./download_blocks_env_binary.sh - ``` + +```bash + $ cd Airsim/docker; + $ ./download_blocks_env_binary.sh +``` - Running an unreal binary inside a docker container The syntax is: - ``` - $ ./run_airsim_image_binary.sh DOCKER_IMAGE_NAME UNREAL_BINARY_SHELL_SCRIPT UNREAL_BINARY_ARGUMENTS -- headless - ``` + +```bash + $ ./run_airsim_image_binary.sh DOCKER_IMAGE_NAME UNREAL_BINARY_SHELL_SCRIPT UNREAL_BINARY_ARGUMENTS -- headless +``` + For blocks, you can do a `$ ./run_airsim_image_binary.sh airsim_binary:10.0-devel-ubuntu18.04 Blocks/Blocks.sh -windowed -ResX=1080 -ResY=720` * `DOCKER_IMAGE_NAME`: Same as `target_image` parameter in previous step. By default, enter `airsim_binary:10.0-devel-ubuntu18.04` @@ -42,11 +46,12 @@ You can download it by running * [`UNREAL_BINARY_ARGUMENTS`](https://docs.unrealengine.com/en-us/Programming/Basics/CommandLineArguments): For airsim, most relevant would be `-windowed`, `-ResX`, `-ResY`. Click on link to see all options. - * Running in Headless mode: - Suffix `-- headless` at the end: - ``` - $ ./run_airsim_image_binary.sh Blocks/Blocks.sh -- headless - ``` + * Running in Headless mode: + Suffix `-- headless` at the end: +```bash +$ ./run_airsim_image_binary.sh Blocks/Blocks.sh -- headless +``` + - [Specifying a `settings.json`](https://github.com/Microsoft/AirSim/blob/master/docs/docker_ubuntu.md#airsim_binary-docker-image) ## Source @@ -79,18 +84,22 @@ You can download it by running `--base_image`: This is image over which we'll install airsim. We've tested on `adamrehn/ue4-engine:4.19.2-cudagl10.0`. See [ue4-docker](https://adamrehn.com/docs/ue4-docker/building-images/available-container-images) for other versions. `--target_image` is the desired name of your docker image. Defaults to `airsim_source` with same tag as the base image - ``` - $ cd Airsim/docker; - $ python build_airsim_image.py \ - --source \ - ----base_image adamrehn/ue4-engine:4.19.2-cudagl10.0 \ - --target_image=airsim_source:4.19.2-cudagl10.0 - ``` + +```bash +$ cd Airsim/docker; +$ python build_airsim_image.py \ + --source \ + ----base_image adamrehn/ue4-engine:4.19.2-cudagl10.0 \ + --target_image=airsim_source:4.19.2-cudagl10.0 +``` + #### Running AirSim container * Run the airsim source image we built by: - ``` - ./run_airsim_image_source.sh airsim_source:4.19.2-cudagl10.0 - ``` + +```bash + ./run_airsim_image_source.sh airsim_source:4.19.2-cudagl10.0 +``` + Syntax is `./run_airsim_image_source.sh DOCKER_IMAGE_NAME -- headless` `-- headless`: suffix this to run in optional headless mode. @@ -103,52 +112,56 @@ You can download it by running #### [Misc] Packaging Unreal Environments in `airsim_source` containers * Let's take the Blocks environment as an example. In the following script, specify the full path to your unreal uproject file by `project` and the directory where you want the binaries to be placed by `archivedirectory` - ``` - $ /home/ue4/UnrealEngine/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun -platform=Linux -clientconfig=Shipping -serverconfig=Shipping -noP4 -cook -allmaps -build -stage -prereqs -pak -archive \ - -archivedirectory=/home/ue4/Binaries/Blocks/ \ - -project=/home/ue4/AirSim/Unreal/Environments/Blocks/Blocks.uproject - ``` + +```bash +$ /home/ue4/UnrealEngine/Engine/Build/BatchFiles/RunUAT.sh BuildCookRun -platform=Linux -clientconfig=Shipping -serverconfig=Shipping -noP4 -cook -allmaps -build -stage -prereqs -pak -archive \ +-archivedirectory=/home/ue4/Binaries/Blocks/ \ +-project=/home/ue4/AirSim/Unreal/Environments/Blocks/Blocks.uproject +``` This would create a Blocks binary in `/home/ue4/Binaries/Blocks/`. You can test it by running `/home/ue4/Binaries/Blocks/LinuxNoEditor/Blocks.sh -windowed` ### Specifying an airsim settings.json - #### `airsim_binary` docker image: +#### `airsim_binary` docker image: - We're mapping the host machine's `PATH/TO/Airsim/docker/settings.json` to the docker container's `/home/airsim_user/Documents/AirSim/settings.json`. - Hence, we can load any settings file by simply modifying `PATH_TO_YOUR/settings.json` by modifying the following snippets in * [`run_airsim_image_binary.sh`](https://github.com/Microsoft/AirSim/blob/master/docker/run_airsim_image_binary.sh) - ``` - nvidia-docker run -it \ - -v $PATH_TO_YOUR/settings.json:/home/airsim_user/Documents/AirSim/settings.json \ - -v $UNREAL_BINARY_PATH:$UNREAL_BINARY_PATH \ - -e SDL_VIDEODRIVER=$SDL_VIDEODRIVER_VALUE \ - -e SDL_HINT_CUDA_DEVICE='0' \ - --net=host \ - --env="DISPLAY=$DISPLAY" \ - --env="QT_X11_NO_MITSHM=1" \ - --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ - -env="XAUTHORITY=$XAUTH" \ - --volume="$XAUTH:$XAUTH" \ - --runtime=nvidia \ - --rm \ - $DOCKER_IMAGE_NAME \ - /bin/bash -c "$UNREAL_BINARY_COMMAND" - ``` - #### `airsim_source` docker image: + +```bash +nvidia-docker run -it \ + -v $PATH_TO_YOUR/settings.json:/home/airsim_user/Documents/AirSim/settings.json \ + -v $UNREAL_BINARY_PATH:$UNREAL_BINARY_PATH \ + -e SDL_VIDEODRIVER=$SDL_VIDEODRIVER_VALUE \ + -e SDL_HINT_CUDA_DEVICE='0' \ + --net=host \ + --env="DISPLAY=$DISPLAY" \ + --env="QT_X11_NO_MITSHM=1" \ + --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ + -env="XAUTHORITY=$XAUTH" \ + --volume="$XAUTH:$XAUTH" \ + --runtime=nvidia \ + --rm \ + $DOCKER_IMAGE_NAME \ + /bin/bash -c "$UNREAL_BINARY_COMMAND" +``` + +#### `airsim_source` docker image: * We're mapping the host machine's `PATH/TO/Airsim/docker/settings.json` to the docker container's `/home/airsim_user/Documents/AirSim/settings.json`. * Hence, we can load any settings file by simply modifying `PATH_TO_YOUR/settings.json` by modifying the following snippets in [`run_airsim_image_source.sh`](https://github.com/Microsoft/AirSim/blob/master/docker/run_airsim_image_source.sh): - ``` - nvidia-docker run -it \ - -v $(pwd)/settings.json:/home/airsim_user/Documents/AirSim/settings.json \ - -e SDL_VIDEODRIVER=$SDL_VIDEODRIVER_VALUE \ - -e SDL_HINT_CUDA_DEVICE='0' \ - --net=host \ - --env="DISPLAY=$DISPLAY" \ - --env="QT_X11_NO_MITSHM=1" \ - --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ - -env="XAUTHORITY=$XAUTH" \ - --volume="$XAUTH:$XAUTH" \ - --runtime=nvidia \ - --rm \ - $DOCKER_IMAGE_NAME - ``` + +```bash + nvidia-docker run -it \ + -v $(pwd)/settings.json:/home/airsim_user/Documents/AirSim/settings.json \ + -e SDL_VIDEODRIVER=$SDL_VIDEODRIVER_VALUE \ + -e SDL_HINT_CUDA_DEVICE='0' \ + --net=host \ + --env="DISPLAY=$DISPLAY" \ + --env="QT_X11_NO_MITSHM=1" \ + --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \ + -env="XAUTHORITY=$XAUTH" \ + --volume="$XAUTH:$XAUTH" \ + --runtime=nvidia \ + --rm \ + $DOCKER_IMAGE_NAME +``` diff --git a/docs/lidar.md b/docs/lidar.md index 3182a7e181..1c592d5787 100644 --- a/docs/lidar.md +++ b/docs/lidar.md @@ -101,8 +101,8 @@ Use `getLidarData()` API to retrieve the Lidar data. * Can be used to transform points to other frames. ### Python Examples -[drone_lidar.py](https://github.com/Microsoft/AirSim/tree/master/PythonClient//multirotor) -[car_lidar.py](https://github.com/Microsoft/AirSim/tree/master/PythonClient//car) +- [drone_lidar.py](https://github.com/Microsoft/AirSim/tree/master/PythonClient//multirotor) +- [car_lidar.py](https://github.com/Microsoft/AirSim/tree/master/PythonClient//car) ## Coming soon * Visualization of lidar data on client side. \ No newline at end of file diff --git a/docs/sensors.md b/docs/sensors.md index 5f81bf037f..5309399158 100644 --- a/docs/sensors.md +++ b/docs/sensors.md @@ -73,32 +73,32 @@ A vehicle specific sensor list can be specified in the vehicle settings part of e.g., ```json - "Vehicles": { - - "Drone1": { - "VehicleType": "SimpleFlight", - "AutoCreate": true, - ... - "Sensors": { - "MyLidar1": { - "SensorType": 6, - "Enabled" : true, - "NumberOfChannels": 16, - "PointsPerSecond": 10000, - "X": 0, "Y": 0, "Z": -1, - "DrawDebugPoints": true - }, - "MyLidar2": { - "SensorType": 6, - "Enabled" : true, - "NumberOfChannels": 4, - "PointsPerSecond": 10000, - "X": 0, "Y": 0, "Z": -1, - "DrawDebugPoints": true - } +"Vehicles": { + + "Drone1": { + "VehicleType": "SimpleFlight", + "AutoCreate": true, + ... + "Sensors": { + "MyLidar1": { + "SensorType": 6, + "Enabled" : true, + "NumberOfChannels": 16, + "PointsPerSecond": 10000, + "X": 0, "Y": 0, "Z": -1, + "DrawDebugPoints": true + }, + "MyLidar2": { + "SensorType": 6, + "Enabled" : true, + "NumberOfChannels": 4, + "PointsPerSecond": 10000, + "X": 0, "Y": 0, "Z": -1, + "DrawDebugPoints": true } } - } + } +} ``` ### Sensor specific settings @@ -146,62 +146,47 @@ Be default, the points hit by distance sensor are not drawn on the viewport. To ## Sensor APIs Jump straight to [`hello_drone.py`](https://github.com/Microsoft/AirSim/blob/master/PythonClient/multirotor/hello_drone.py) or [`hello_drone.cpp`](https://github.com/Microsoft/AirSim/blob/master/HelloDrone/main.cpp) for example usage, or see follow below for the full API. -- Barometer - - C++ - ```cpp - msr::airlib::BarometerBase::Output getBarometerData(const std::string& barometer_name, const std::string& vehicle_name); - ``` - - Python - ```python - barometer_data = client.getBarometerData(barometer_name = "", vehicle_name = "") - ``` - -- IMU - - C++ - ```cpp - msr::airlib::ImuBase::Output getImuData(const std::string& imu_name = "", const std::string& vehicle_name = ""); - ``` - - Python - ```python - imu_data = client.getImuData(imu_name = "", vehicle_name = "") - ``` - -- GPS - - C++ - ```cpp - msr::airlib::GpsBase::Output getGpsData(const std::string& gps_name = "", const std::string& vehicle_name = ""); - ``` - Python - ```python - gps_data = client.getGpsData(gps_name = "", vehicle_name = "") - ``` - -- Magnetometer - - C++ - ```cpp - msr::airlib::MagnetometerBase::Output getMagnetometerData(const std::string& magnetometer_name = "", const std::string& vehicle_name = ""); - ``` - Python - ```python - magnetometer_data = client.getMagnetometerData(magnetometer_name = "", vehicle_name = "") - ``` - -- Distance sensor - - C++ - ```cpp - msr::airlib::DistanceSensorData getDistanceSensorData(const std::string& distance_sensor_name = "", const std::string& vehicle_name = ""); - ``` - Python - ```python - distance_sensor_data = client.getDistanceSensorData(distance_sensor_name = "", vehicle_name = "") - ``` - -- Lidar - See [lidar](lidar.md) for Lidar API. +##### Barometer +```cpp +msr::airlib::BarometerBase::Output getBarometerData(const std::string& barometer_name, const std::string& vehicle_name); +``` + +```python +barometer_data = client.getBarometerData(barometer_name = "", vehicle_name = "") +``` + +##### IMU +```cpp +msr::airlib::ImuBase::Output getImuData(const std::string& imu_name = "", const std::string& vehicle_name = ""); +``` + +```python +imu_data = client.getImuData(imu_name = "", vehicle_name = "") +``` + +##### GPS +```cpp +msr::airlib::GpsBase::Output getGpsData(const std::string& gps_name = "", const std::string& vehicle_name = ""); +``` +```python +gps_data = client.getGpsData(gps_name = "", vehicle_name = "") +``` + +##### Magnetometer +```cpp +msr::airlib::MagnetometerBase::Output getMagnetometerData(const std::string& magnetometer_name = "", const std::string& vehicle_name = ""); +``` +```python +magnetometer_data = client.getMagnetometerData(magnetometer_name = "", vehicle_name = "") +``` + +##### Distance sensor +```cpp +msr::airlib::DistanceSensorData getDistanceSensorData(const std::string& distance_sensor_name = "", const std::string& vehicle_name = ""); +``` +```python +distance_sensor_data = client.getDistanceSensorData(distance_sensor_name = "", vehicle_name = "") +``` + +##### Lidar +See the [lidar page](lidar.md) for Lidar API. diff --git a/docs/unreal_custenv.md b/docs/unreal_custenv.md index d327b0b83d..b528432e22 100644 --- a/docs/unreal_custenv.md +++ b/docs/unreal_custenv.md @@ -23,7 +23,7 @@ There is no `Epic Games Launcher` for Linux which means that if you need to crea 6. Edit the `LandscapeMountains.uproject` so that it looks like this -``` +```json { "FileVersion": 3, "EngineAssociation": "4.24", @@ -108,19 +108,20 @@ In this case, create a new blank C++ project with no Starter Content and add you #### I already have my own Unreal project. How do I use AirSim with it? Copy the `Unreal\Plugins` folder from the build you did in the above section into the root of your Unreal project's folder. In your Unreal project's .uproject file, add the key `AdditionalDependencies` to the "Modules" object as we showed in the `LandscapeMountains.uproject` above. - ``` +```json "AdditionalDependencies": [ "AirSim" ] - ``` +``` + and the `Plugins` section to the top level object: - ``` - "Plugins": [ - { - "Name": "AirSim", - "Enabled": true - } - ] - ``` +```json +"Plugins": [ + { + "Name": "AirSim", + "Enabled": true + } +] +```