Make Python as default for docs, relative URLs, better build instruct…

…ions, suggestions from microsoft#1191
VegaVK · Jun 23, 2018 · f910350 · f910350
1 parent dbb14a8
commit f910350
Show file tree

Hide file tree

Showing 10 changed files with 322 additions and 266 deletions.
diff --git a/docs/apis.md b/docs/apis.md
diff --git a/docs/apis_cpp.md b/docs/apis_cpp.md
@@ -0,0 +1,91 @@
+# Using C++ APIs for AirSim
+
+Please read [general API doc](apis.md) first if you haven't already. This document describes C++ examples and other C++ specific details.
+
+## Quick Start
+Fastest way to get started is to open AirSim.sln in Visual Studio 2017. You will see [Hello Car](../HelloCar) and [Hello Drone](../HelloDrone) examples in the solution. These examples will show you the include paths and lib paths you will need to setup in your VC++ projects. If you are using Linux then you will specify these paths either in your [cmake file](../cmake/HelloCar/CMakeLists.txt) or on compiler command line.
+
+#### Include and Lib Folders
+* Include folders: `$(ProjectDir)..\AirLib\deps\rpclib\include;include;$(ProjectDir)..\AirLib\deps\eigen3;$(ProjectDir)..\AirLib\include`
+* Dependencies: `rpc.lib`
+* Lib folders: `$(ProjectDir)\..\AirLib\deps\MavLinkCom\lib\$(Platform)\$(Configuration);$(ProjectDir)\..\AirLib\deps\rpclib\lib\$(Platform)\$(Configuration);$(ProjectDir)\..\AirLib\lib\$(Platform)\$(Configuration)`
+
+## Hello Car
+
+Here's how to use AirSim APIs using Python to control simulated car (see also [Python example](apis.md#hello_car)):
+
+```cpp
+
+// ready to run example: https://github.com/Microsoft/AirSim/blob/master/HelloCar/main.cpp
+
+#include <iostream>
+#include "vehicles/car/api/CarRpcLibClient.hpp"
+
+int main() 
+{
+    msr::airlib::CarRpcLibClient client;
+    client.enableApiControl(true); //this disables manual control
+    CarControllerBase::CarControls controls;
+
+    std::cout << "Press enter to drive forward" << std::endl; std::cin.get();
+    controls.throttle = 1;
+    client.setCarControls(controls);
+
+    std::cout << "Press Enter to activate handbrake" << std::endl; std::cin.get();
+    controls.handbrake = true;
+    client.setCarControls(controls);
+
+    std::cout << "Press Enter to take turn and drive backward" << std::endl; std::cin.get();
+    controls.handbrake = false;
+    controls.throttle = -1;
+    controls.steering = 1;
+    client.setCarControls(controls);
+
+    std::cout << "Press Enter to stop" << std::endl; std::cin.get();
+    client.setCarControls(CarControllerBase::CarControls());
+
+    return 0;
+}
+```
+
+## Hello Drone
+
+Here's how to use AirSim APIs using Python to control simulated car (see also [Python example](apis.md#hello_drone)):
+
+```cpp
+
+// ready to run example: https://github.com/Microsoft/AirSim/blob/master/HelloDrone/main.cpp
+
+#include <iostream>
+#include "vehicles/multirotor/api/MultirotorRpcLibClient.hpp"
+
+int main() 
+{
+    using namespace std;
+    msr::airlib::MultirotorRpcLibClient client;
+
+    cout << "Press Enter to enable API control" << endl; cin.get();
+    client.enableApiControl(true);
+
+    cout << "Press Enter to arm the drone" << endl; cin.get();
+    client.armDisarm(true);
+
+    cout << "Press Enter to takeoff" << endl; cin.get();
+    client.takeoffAsync(5)->waitOnLastTask();
+
+    cout << "Press Enter to move 5 meters in x direction with 1 m/s velocity" << endl; cin.get();  
+    auto position = client.getPosition(); // from current location
+    client.moveToPositionAsync(position.x() + 5, position.y(), position.z(), 1)->waitOnLastTask();
+
+    cout << "Press Enter to land" << endl; cin.get();
+    client.landAync()->waitOnLastTask();
+
+    return 0;
+}
+```
+
+## See Also
+* [Examples](../Examples) of how to use internal infrastructure in AirSim in your other projects
+* [DroneShell](../DroneShell) app shows how to make simple interface using C++ APIs to control drones
+* [Python APIs](apis.md)
+
diff --git a/docs/build_linux.md b/docs/build_linux.md
@@ -25,15 +25,27 @@ It's super simple: 1-2-3!
    ./build.sh
    ```
 
-## Setup Remote Control
+
+## Build Unreal Environment
+
+Finally, you will need an Unreal project that hosts the environment for your vehicles. AirSim comes with a built-in "Blocks Environment" which you can use, or you can create your own. Please see [setting up Unreal Environment](unreal_proj.md).
+
+## Setup Remote Control (Multirotor Only)
 
 A remote control is required if you want to fly manually. See the [remote control setup](remote_control.md) for more details.
 
 Alternatively, you can use [APIs](apis.md) for programmatic control or use the so-called [Computer Vision mode](image_apis.md) to move around using the keyboard.
 
-## Setup Unreal Environment
+## How to Use AirSim
 
-Finally, you will need an Unreal project that hosts the environment for your vehicles. AirSim comes with a built-in "Blocks Environment" which you can use, or you can create your own. Please see [setting up Unreal Environment](unreal_proj.md).
+Once AirSim is set up by following above steps, you can,
+
+1. Go to `UnrealEngine` folder and start Unreal by running `UnrealEngine/Engine/Binaries/Linux/UE4Editor`.
+2. When Unreal Engine prompts for opening or creating project, select Browse and choose `AirSim/Unreal/Environments/Blocks` (or your [custom](unreal_custenv.md) Unreal project).
+3. If you get prompts to convert project, look for More Options or Convert-In-Place option. If you get prompted to build, chose Yes. If you get prompted to disable AirSim plugin, choose No.
+4. After Unreal Editor loads, press Play button. Tip: go to 'Edit->Editor Preferences', in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked.
+
+See [Using APIs](apis.md) and [settings.json](settings.md) for various options available.
 
 ## FAQ
 

diff --git a/docs/build_windows.md b/docs/build_windows.md
@@ -13,15 +13,25 @@
   2. Start `x64 Native Tools Command Prompt for VS 2017`. Create a folder for the repo and run `git clone https://github.com/Microsoft/AirSim.git`.
   3. Run `build.cmd` from the command line. This will create ready to use plugin bits in the `Unreal\Plugins` folder that can be dropped into any Unreal project.
 
-## Setup Remote Control
+## Build Unreal Project
+
+Finally, you will need an Unreal project that hosts the environment for your vehicles. AirSim comes with a built-in "Blocks Environment" which you can use, or you can create your own. Please see [setting up Unreal Environment](unreal_proj.md).
+
+## Setup Remote Control (Multirotor only)
 
 A remote control is required if you want to fly manually. See the [remote control setup](remote_control.md) for more details.
 
 Alternatively, you can use [APIs](apis.md) for programmatic control or use the so-called [Computer Vision mode](image_apis.md) to move around using the keyboard.
 
-## Setup Unreal Environment
+## How to Use AirSim
 
-Finally, you will need an Unreal project that hosts the environment for your vehicles. AirSim comes with a built-in "Blocks Environment" which you can use, or you can create your own. Please see [setting up Unreal Environment](unreal_proj.md).
+Once AirSim is set up by following above steps, you can,
+
+1. Double click on .sln file to load the Blocks project in `Unreal\Environments\Blocks` (or .sln file in your own [custom](unreal_custenv.md) Unreal project). If you don't see .sln file then you probably haven't completed steps in Build Unreal Project section above.
+2. Select your Unreal project as Start Up project (for example, Blocks project) and make sure Build config is set to "Develop Editor" and x64.
+3. After Unreal Editor loads, press Play button. Tip: go to 'Edit->Editor Preferences', in the 'Search' box type 'CPU' and ensure that the 'Use Less CPU when in Background' is unchecked.
+
+See [Using APIs](apis.md) and [settings.json](settings.md) for various options available.
 
 ## FAQ
 
@@ -36,7 +46,7 @@ By default, AirSim uses its own built-in firmware called [simple_flight](simple_
 Sometimes the Unreal + VS build system doesn't recompile if you make changes to only header files. To ensure a recompile, make some Unreal based cpp file "dirty" like AirSimGameMode.cpp.
 
 #### Unreal still uses VS2015 or I'm getting some link error
-Running serveral versions of VS can lead to issues when compiling UE projects. One problem that may arise is that UE will try to compile with an older version of VS which may or may not work. There are two settings in Unreal, one for for the engine and one for the project, to adjust the version of VS to be used.
+Running several versions of VS can lead to issues when compiling UE projects. One problem that may arise is that UE will try to compile with an older version of VS which may or may not work. There are two settings in Unreal, one for for the engine and one for the project, to adjust the version of VS to be used.
 1. Edit -> Editor preferences -> General -> Source code
 2. Edit -> Project Settings -> Platforms -> Windows -> Toolchain ->CompilerVersion
 

diff --git a/docs/image_apis.md b/docs/image_apis.md
@@ -1,27 +1,11 @@
 # Image APIs
 
+Please read [general API doc](apis.md) first if you are not familiar with AirSim APIs.
+
 ## Getting a Single Image
 
 Here's a sample code to get a single image from camera named "0". The returned value is bytes of png format image. To get uncompressed and other format as well as available cameras please see next sections.
 
-### C++
-
-```cpp
-#include "vehicles/multirotor/api/MultirotorRpcLibClient.hpp"
-
-int getOneImage() 
-{
-    using namespace std;
-    using namespace msr::airlib;
-
-    //for car use CarRpcLibClient
-    msr::airlib::MultirotorRpcLibClient client;
-
-    vector<uint8_t> png_image = client.simGetImage("0", VehicleCameraBase::ImageType::Scene);
-    //do something with images
-}
-```
-
 ### Python
 
 ```python
@@ -34,41 +18,28 @@ png_image = client.simGetImage("0", airsim.AirSimImageType.Scene)
 # do something with image
 ```
 
-## Getting Images with More Flexibility
-
-The `simGetImages` API which is slightly more complex to use than `simGetImage` API, for example, you can get left camera view, right camera view and depth image from left camera in a single API call. The `simGetImages` API also allows you to get uncompressed images as well as floating point single channel images (instead of 3 channel (RGB), each 8 bit).
-
 ### C++
 
 ```cpp
-int getStereoAndDepthImages() 
+#include "vehicles/multirotor/api/MultirotorRpcLibClient.hpp"
+
+int getOneImage() 
 {
     using namespace std;
     using namespace msr::airlib;
 
-    typedef VehicleCameraBase::ImageRequest ImageRequest;
-    typedef VehicleCameraBase::ImageResponse ImageResponse;
-    typedef VehicleCameraBase::ImageType ImageType;
-
-    //for car use
-    //msr::airlib::CarRpcLibClient client;
+    //for car use CarRpcLibClient
     msr::airlib::MultirotorRpcLibClient client;
 
-    //get right, left and depth images. First two as png, second as float16.
-    vector<ImageRequest> request = { 
-        //png format
-        ImageRequest("0", ImageType::Scene),
-        //uncompressed RGBA array bytes
-        ImageRequest("1", ImageType::Scene, false, false),       
-        //floating point uncompressed image  
-        ImageRequest("1", ImageType::DepthPlanner, true) 
-    };
-
-    const vector<ImageResponse>& response = client.simGetImages(request);
-    //do something with response which contains image data, pose, timestamp etc
+    vector<uint8_t> png_image = client.simGetImage("0", VehicleCameraBase::ImageType::Scene);
+    //do something with images
 }
 ```
 
+## Getting Images with More Flexibility
+
+The `simGetImages` API which is slightly more complex to use than `simGetImage` API, for example, you can get left camera view, right camera view and depth image from left camera in a single API call. The `simGetImages` API also allows you to get uncompressed images as well as floating point single channel images (instead of 3 channel (RGB), each 8 bit).
+
 ### Python
 
 ```python
@@ -112,18 +83,58 @@ img_rgba[:,:,1:2] = 100
 airsim.write_png(os.path.normpath(filename + '.greener.png'), img_rgba) 
 ```
 
-## Ready to Run Complete Examples
+#### Quick Tips
+- The API `simGetImage` returns `binary string literal` which means you can simply dump it in binary file to create a .png file. However if you want to process it in any other way than you can handy function `airsim.string_to_uint8_array`. This converts binary string literal to NumPy uint8 array.
+
+- The API `simGetImages` can accept request for multiple image types from any cameras in single call. You can specify if image is png compressed, RGB uncompressed or float array. For png compressed images, you get `binary string literal`. For float array you get Python list of float64. You can convert this float array to NumPy 2D array using
+    ```
+    airsim.list_to_2d_float_array(response.image_data_float, response.width, response.height)
+    ```
+    You can also save float array to .pfm file (Portable Float Map format) using `airsim.write_pfm()` function.
 
 ### C++
 
-For a more complete ready to run sample code please see [sample code in HelloDrone project](../HelloDrone/main.cpp) for multirotors or [HelloCar project](../HelloCar/main.cpp). 
+```cpp
+int getStereoAndDepthImages() 
+{
+    using namespace std;
+    using namespace msr::airlib;
+    
+    typedef VehicleCameraBase::ImageRequest ImageRequest;
+    typedef VehicleCameraBase::ImageResponse ImageResponse;
+    typedef VehicleCameraBase::ImageType ImageType;
 
-See also [other example code](../Examples/StereoImageGenerator.hpp) that generates specified number of stereo images along with ground truth depth and disparity and saving it to [pfm format](pfm.md).
+    //for car use
+    //msr::airlib::CarRpcLibClient client;
+    msr::airlib::MultirotorRpcLibClient client;
+
+    //get right, left and depth images. First two as png, second as float16.
+    vector<ImageRequest> request = { 
+        //png format
+        ImageRequest("0", ImageType::Scene),
+        //uncompressed RGBA array bytes
+        ImageRequest("1", ImageType::Scene, false, false),       
+        //floating point uncompressed image  
+        ImageRequest("1", ImageType::DepthPlanner, true) 
+    };
+
+    const vector<ImageResponse>& response = client.simGetImages(request);
+    //do something with response which contains image data, pose, timestamp etc
+}
+```
+
+## Ready to Run Complete Examples
 
 ### Python
 
 For a more complete ready to run sample code please see [sample code in AirSimClient project](../PythonClient/multirotor/hello_drone.py) for multirotors or [HelloCar sample](../PythonClient/car/hello_car.py). This code also demonstrates simple activities such as saving images in files or using `numpy` to manipulate images.
 
+### C++
+
+For a more complete ready to run sample code please see [sample code in HelloDrone project](../HelloDrone/main.cpp) for multirotors or [HelloCar project](../HelloCar/main.cpp). 
+
+See also [other example code](../Examples/StereoImageGenerator.hpp) that generates specified number of stereo images along with ground truth depth and disparity and saving it to [pfm format](pfm.md).
+
 ## Available Cameras
 ### Car
 The cameras on car can be accessed by following names in API calls: `front_center`, `front_right`, `front_left`, `fpv` and `back_center`. Here FPV camera is driver's head position in the car.
@@ -148,15 +159,15 @@ To active this mode, edit [settings.json](settings.md) that you can find in your
 }
 ```
 
-[Here's the Python code example](https://github.com/Microsoft/AirSim/blob/master/PythonClient/computer_vision/cv_mode.py) to move camera around and capture images.
+[Here's the Python code example](../PythonClient/computer_vision/cv_mode.py) to move camera around and capture images.
 
 This mode was inspired from [UnrealCV project](http://unrealcv.org/).
 
 ### Setting Pose in Computer Vision Mode
 To move around the environment using APIs you can use `simSetVehiclePose` API. This API takes position and orientation and sets that on the invisible vehicle where the front-center camera is located. All rest of the cameras move along keeping the relative position. If you don't want to change position (or orientation) then just set components of position (or orientation) to floating point nan values. The `simGetVehiclePose` allows to retrieve the current pose. You can also use `simGetGroundTruthKinematics` to get the quantities kinematics quantities for the movement. Many other non-vehicle specific APIs are also available such as segmentation APIs, collision APIs and camera APIs.
 
 ## Camera APIs
-The `simGetCameraInfo` returns the pose (in world frame, NED coordinates, SI units) and FOV (in degrees) for the specified camera. Please see [example usage](https://github.com/Microsoft/AirSim/blob/master/PythonClient/computer_vision/cv_mode.py).
+The `simGetCameraInfo` returns the pose (in world frame, NED coordinates, SI units) and FOV (in degrees) for the specified camera. Please see [example usage](../PythonClient/computer_vision/cv_mode.py).
 
 The `simSetCameraOrientation` sets the orientation for the specified camera as quaternion in NED frame. The handy `airsim.to_quaternion()` function allows to convert pitch, roll, yaw to quaternion. For example, to set camera-0 to 15-degree pitch, you can use:
 ```
@@ -166,7 +177,7 @@ client.simSetCameraOrientation(0, airsim.toQuaternion(0.261799, 0, 0)); #radians
 ### Gimbal
 You can set stabilization for pitch, roll or yaw for any camera [using settings](settings.md#gimbal).
 
-Please see [example usage](https://github.com/Microsoft/AirSim/blob/master/PythonClient/computer_vision/cv_mode.py).
+Please see [example usage](../PythonClient/computer_vision/cv_mode.py).
 
 ## Changing Resolution and Camera Parameters
 To change resolution, FOV etc, you can use [settings.json](settings.md). For example, below addition in settings.json sets parameters for scene capture and uses "Computer Vision" mode described above. If you omit any setting then below default values will be used. For more information see [settings doc](settings.md). If you are using stereo camera, currently the distance between left and right is fixed at 25 cm.
@@ -244,7 +255,7 @@ print(np.unique(img_rgba[:,:,1], return_counts=True)) #green
 print(np.unique(img_rgba[:,:,2], return_counts=True)) #blue  
 ```
 
-A complete ready-to-run example can be found in [segmentation.py](https://github.com/Microsoft/AirSim/blob/master/PythonClient/computer_vision/segmentation.py).
+A complete ready-to-run example can be found in [segmentation.py](../computer_vision/segmentation.py).
 
 #### Unsetting object ID
 An object's ID can be set to -1 to make it not show up on the segmentation image.
@@ -270,8 +281,5 @@ The `simGetSegmentationObjectID` API allows you get object ID for given mesh nam
 ### Infrared
 Currently this is just a map from object ID to grey scale 0-255. So any mesh with object ID 42 shows up with color (42, 42, 42). Please see [segmentation section](#segmentation) for more details on how to set object IDs. Typically noise setting can be applied for this image type to get slightly more realistic effect. We are still working on adding other infrared artifacts and any contributions are welcome.
 
-## Collision API
-The collision information can be obtained using `simGetCollisionInfo` API. This call returns a struct that has information not only whether collision occurred but also collision position, surface normal, penetration depth and so on.
-
 ## Example Code
 A complete example of setting vehicle positions at random locations and orientations and then taking images can be found in [GenerateImageGenerator.hpp](../Examples/StereoImageGenerator.hpp). This example generates specified number of stereo images and ground truth disparity image and saving it to [pfm format](pfm.md).
diff --git a/docs/pfm.md b/docs/pfm.md
@@ -4,4 +4,4 @@ Pfm (or Portable FloatMap) image format stores image as floating point pixels an
 
 One of the good viewer to view this file format is [PfmPad](https://sourceforge.net/projects/pfmpad/). We don't recommend Maverick photo viewer because it doesn't seem to show depth images properly.
 
-AirSim has code to write pfm file for [C++](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/common/common_utils/Utils.hpp#L637) and read as well as write for [Python](https://github.com/Microsoft/AirSim/blob/master/PythonClient/airsim/utils.py#L122).
+AirSim has code to write pfm file for [C++](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/common/common_utils/Utils.hpp#L637) and read as well as write for [Python](../PythonClient/airsim/utils.py#L122).
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,4 +4,4 @@ Pfm (or Portable FloatMap) image format stores image as floating point pixels an

		One of the good viewer to view this file format is [PfmPad](https://sourceforge.net/projects/pfmpad/). We don't recommend Maverick photo viewer because it doesn't seem to show depth images properly.

		AirSim has code to write pfm file for [C++](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/common/common_utils/Utils.hpp#L637) and read as well as write for [Python](https://github.com/Microsoft/AirSim/blob/master/PythonClient/airsim/utils.py#L122).
		AirSim has code to write pfm file for [C++](https://github.com/Microsoft/AirSim/blob/master/AirLib/include/common/common_utils/Utils.hpp#L637) and read as well as write for [Python](../PythonClient/airsim/utils.py#L122).