Docs finalized

README.md

@@ -1,78 +1,60 @@
 # Welcome to AirSim
 
-AirSim is a simulator for drones (and soon other vehicles) built on Unreal Engine. It is open-source, cross platform and supports hardware-in-loop 
-with popular flight controllers such as Pixhawk for physically and visually realistic simulations. It is developed as an Unreal plugin that can 
-simply be dropped in to any Unreal environment you want. 
+AirSim is a simulator for drones (and soon other vehicles) built on Unreal Engine. It is open-source, cross platform and supports hardware-in-loop with popular flight controllers such as Pixhawk for physically and visually realistic simulations. It is developed as an Unreal plugin that can simply be dropped in to any Unreal environment you want.
 
-Our goal is to develop AirSim as a platform for AI research to experiment with deep learning, computer vision and reinforcement learning algorithms 
-for autonomous vehicles. For this purpose, AirSim also exposes APIs to retrieve data and control vehicles in a platform independent way.
+Our goal is to develop AirSim as a platform for AI research to experiment with deep learning, computer vision and reinforcement learning algorithms for autonomous vehicles. For this purpose, AirSim also exposes APIs to retrieve data and control vehicles in a platform independent way.
 
 **Check out the quick 1.5 minute demo**
 
 [![AirSim Demo Video](docs/images/demo_video.png)](https://youtu.be/-WfTr1-OBGQ)
 
-## Development Status
-
-This project is under heavy development. The current release is in beta and all APIs are subject to change. The next major features currently in works are standalone mode, 
-several API enhancements and Python client support. We welcome contributions!
-
 ## How to Get It
-### Prerequisites
-To get the best experience you will need Pixhawk or compatible device and a RC controller. This enables the "hardware-in-loop simulation" for 
-more realistic experience. [Follow these instructions](docs/prereq.md) on how to get it, set it up and other alternatives.
 
-### Windows
-There are two ways to get AirSim working on your machine. Click on below links and follow the instructions.
+* [Build it on Windows](docs/build_windows.md)
+* [Build it on Linux](docs/build_linux.md)
 
-1.  [Build it and use it with Unreal](docs/build.md)
-2.  [Use the precompiled binaries](docs/use_precompiled.md)
+## How to Use It
 
-### Linux
-[Build AirSim on Ubuntu 16.04](docs/linux_build.md)
+### Manual flights
 
+If you have remote control (RC) as shown below, you can manually control the vehicle in the simulator.
 
-## How to Use It
+[More details](docs/remote_control.md)
 
-### Video Tutorials
-- [Walkthrough Demo Video](https://youtu.be/HNWdYrtw3f0)
-- [AirSim Setup  Video](https://youtu.be/1oY8Qu5maQQ) (shows you all the setup steps)
+![record screenshot](docs/images/DroneGIF-03.gif)
 
-### Manual flights
-If you have a Pixhawk flight controller (or compatible device) and a remote control you can manually control the drones in the simulator 
-and fly around.
+### Programmatic control
 
-![record screenshot](docs/images/DroneGIF-03.gif)
+AirSim exposes APIs so you can interact with vehicle in the simulation programmatically. You can use these APIs to retrieve images, get state, control the vehicle and so on. The APIs are exposed through RPC and accessible via variety of languages including C++, Python, C# and Java.
+
+These APIs are also available as a part of a separate independent cross-platform library so you can deploy them on an companion computer on your vehicle. This way you can write and test your code in simulator and later execute it on the real drones. Transfer learning and related research is one of our focus areas.
 
-[More details](docs/manual_flight.md)
+[More details](docs/apis.md)
 
 ### Gathering training data
-There are two ways you can generate training data from AirSim for deep learning. The easiest way is to simply press the record button on the lower right corner. 
-This will start writing pose and images for each frame. 
 
-![record screenshot](docs/images/record_data.png)
+There are two ways you can generate training data from AirSim for deep learning. The easiest way is to simply press the record button on the lower right corner. This will start writing pose and images for each frame. The data logging code is pretty simple and you can modify it to your heart's desire.
 
-If you would like more data logging capabilities and other features, [file a feature request](https://github.com/Microsoft/AirSim/issues) or contribute changes. 
-The data logging code is pretty simple and you can modify it to your heart's desire.
+![record screenshot](docs/images/record_data.png)
 
-A more complex way to generate training data is by writing client code that uses our APIs. This allows you to be in full control of how, what, where and when you want to log data. See the next section for more details.
+A better way to generate training data exactly the way you want is by accessing the APIs. This allows you to be in full control of how, what, where and when you want to log data. 
 
-For MavLink enabled drones, you can also use our [Log Viewer](docs/log_viewer.md) to visualize the streams of data.
+### Computer Vision mode
 
-You can also [playback recorded logs](docs/playback.md) for side-by-side comparison between real drone and the simulator.
+Yet another way to use AirSim is so-called "Computer Vision" mode. In this mode, you don't have vehicle physics and dynamics but you can use keyboard to move around and use APIs to position vehicle in any arbitrary pose and get images such as depth, disparity, surface normals or object segmentation. 
 
-### Programmatic control
-The AirSim exposes easy to use APIs in order to retrieve data from the drones that includes ground truth, sensor data as well as various images. It also exposes 
-APIs to control the drones in a platform independent way. This allows you to use your code to control different drones platforms, for example, Pixhawk or DJI Matrice, 
-without making changes as well as without having to learn internal protocols details. 
+[More details](image_apis.md)
 
-These APIs are also available as a part of a separate independent cross-platform library so you can deploy them on an offboard computer on your vehicle. 
-This way you can write and test your code in simulator and later execute it on the real drones. Transfer learning and related research is one of our focus areas.  See [custom drones](docs/custom_drone.md).
+### Video Tutorials
 
-[More details](docs/apis.md)
+- [Setting up AirSim with Pixhawk Tutorial](https://youtu.be/1oY8Qu5maQQ) 
+- [Using AirSim with Pixhawk Tutorial](https://youtu.be/HNWdYrtw3f0)
 
 ## Participate
+
 ### Paper
-You can get additional technical details in [our paper (preprint)](https://arxiv.org/abs/1705.05065). Please cite this as:
+
+More technical details are available in [AirSim paper (FSR 2017 Conference)](https://arxiv.org/abs/1705.05065). Please cite this as:
 ```
 @inproceedings{airsim2017fsr,
   author = {Shital Shah and Debadeepta Dey and Chris Lovett and Ashish Kapoor},
@@ -85,18 +67,21 @@ You can get additional technical details in [our paper (preprint)](https://arxiv
 ```
 
 ### Contribute
+
 We welcome contributions to help advance research frontiers. 
 
-- [More on our design](docs/design.md)
-- [More on our code structure](docs/code_structure.md)
-- [Contribution Guidelines](docs/contributing.md)
+* [More on AirSim design](docs/design.md)
+* [More on code structure](docs/code_structure.md)
+* [Contribution Guidelines](docs/contributing.md)
 
 ### Contact
+
 Join the [AirSim group at Facebook](https://www.facebook.com/groups/1225832467530667/) to stay up to date or ask any questions.
 
 ### FAQ
 
 If you run into problems, check the [FAQ](docs/faq.md) and feel free to post issues on the [AirSim github](https://github.com/Microsoft/AirSim/issues).
 
 ### License
+
 This project is released under MIT License. Please review [License file](LICENSE) for more details.

Unreal/Environments/Blocks/update_from_git.sh

@@ -7,6 +7,8 @@ pushd "$SCRIPT_DIR" >/dev/null
 set -e
 set -x
 
+./clean.sh
+
 rsync -a  --exclude 'temp' --delete ../../Plugins/AirSim Plugins/AirSim
 rsync -a  --exclude 'temp' --delete ../../../AirLib Plugins/AirSim/Source/AirLib
 

build.cmd

@@ -10,19 +10,19 @@ git submodule update --init --recursive
 REM //---------- if cmake doesn't exist then install it ----------
 WHERE cmake >nul 2>nul
 IF %ERRORLEVEL% NEQ 0 (
-	call :installcmake
+    call :installcmake
 )
 
 REM //---------- get Eigen library ----------
 IF NOT EXIST AirLib\deps mkdir AirLib\deps
 IF NOT EXIST AirLib\deps\eigen3 (
-	powershell -command "& { iwr http://bitbucket.org/eigen/eigen/get/3.3.2.zip -OutFile eigen3.zip }"
-	powershell -command "& { Expand-Archive -Path eigen3.zip -DestinationPath AirLib\deps }"
-	move AirLib\deps\eigen* AirLib\deps\del_eigen
-	mkdir AirLib\deps\eigen3
-	move AirLib\deps\del_eigen\Eigen AirLib\deps\eigen3\Eigen
+    powershell -command "& { iwr http://bitbucket.org/eigen/eigen/get/3.3.2.zip -OutFile eigen3.zip }"
+    powershell -command "& { Expand-Archive -Path eigen3.zip -DestinationPath AirLib\deps }"
+    move AirLib\deps\eigen* AirLib\deps\del_eigen
+    mkdir AirLib\deps\eigen3
+    move AirLib\deps\del_eigen\Eigen AirLib\deps\eigen3\Eigen
     rmdir /S /Q AirLib\deps\del_eigen
-	del eigen3.zip
+    del eigen3.zip
 )
 IF NOT EXIST AirLib\deps\eigen3 goto :buildfailed
 
@@ -60,7 +60,7 @@ robocopy /MIR MavLinkCom\lib %MAVLINK_TARGET_LIB%
 
 REM //---------- all our output goes to Unreal/Plugin folder ----------
 if NOT exist Unreal\Plugins\AirSim\Source\AirLib mkdir Unreal\Plugins\AirSim\Source\AirLib
-robocopy /MIR AirLib Unreal\Plugins\AirSim\Source\AirLib  /XD temp
+robocopy /MIR AirLib Unreal\Plugins\AirSim\Source\AirLib  /XD temp *. /njh /njs /ndl /np
 
 REM //---------- done building ----------
 goto :eof

build.sh

@@ -87,7 +87,7 @@ echo "If you are using your own environment, update plugin using,"
 echo "rsync -t -r Unreal/Plugins path/to/MyUnrealProject"
 echo ""
 echo "For help see:"
-echo "https://github.com/Microsoft/AirSim/blob/master/docs/linux_build.md"
+echo "https://github.com/Microsoft/AirSim/blob/master/docs/build_linux.md"
 echo "=================================================================="
 
 

cmake/build.sh

@@ -2,7 +2,7 @@
 # You should NOT use this with Unreal.
 # If you want bits that work in Unreal you need to use ../build.sh
 # For pre-requisite tools needed to run this script see
-# https://github.com/Microsoft/AirSim/blob/master/docs/linux_build.md
+# https://github.com/Microsoft/AirSim/blob/master/docs/build_linux.md
 
 # First get the location of this script, it is assumed you already cloned "main" and you are running the
 # script from that repo.  It will then put everything else in a ROS workspace at "../catkin_ws"

cmake/gcc_build.sh

@@ -2,7 +2,7 @@
 # You should NOT use this with Unreal.
 # If you want bits that work in Unreal you need to use ../build.sh
 # For pre-requisite tools needed to run this script see
-# https://github.com/Microsoft/AirSim/blob/master/docs/linux_build.md
+# https://github.com/Microsoft/AirSim/blob/master/docs/build_linux.md
 
 # First get the location of this script, it is assumed you already cloned "main" and you are running the
 # script from that repo.  It will then put everything else in a ROS workspace at "../catkin_ws"

docs/apis.md

@@ -1,9 +1,9 @@
+#AirSim APIs
 ## Introduction
-AirSim offers APIs to interact with vehicles. You can use these APIs to retrieve images, get state, command the vehicle and so on. The APIs use [msgpack-rpc protocol](https://github.com/msgpack-rpc/msgpack-rpc) which has bindings available in variety of languages including C++, C#, Python, Java etc.
+AirSim exposes APIs so you can interact with vehicle in the simulation programmatically. You can use these APIs to retrieve images, get state, control the vehicle and so on. The APIs use [msgpack-rpc protocol](https://github.com/msgpack-rpc/msgpack-rpc) over TCP/IP which allows you to use variety of programming languages including C++, C#, Python, Java etc.
 
 ## Hello Drone
-Here's very quick overview of how to use AirSim APIs using C++ (see also [Python doc](python.md)):
-See also  if you prefer that language.
+Here's very quick overview of how to use AirSim APIs using C++ (see also [Python example](python.md)):
 
 ```
 #include <iostream>
@@ -14,18 +14,18 @@ int main()
     using namespace std;
     msr::airlib::RpcLibClient client;
 
+    cout << "Press Enter to use offboard control" << endl; cin.get();
+    client.setOffboardMode(true);
+
     cout << "Press Enter to arm the drone" << endl; cin.get();
     client.armDisarm(true);
 
     cout << "Press Enter to takeoff" << endl; cin.get();
-    client.takeoff(60);
+    client.takeoff(5);
 
-    cout << "Press Enter to use offboard control" << endl; cin.get();
-    client.requestControl();
-
-    cout << "Press Enter to move 5 meters in x direction with 1 m/s velocity" << endl; cin.get();    
+    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.moveToPosition(position.x() + 5, position.y(), position.z(), 1, 5*1);
+    client.moveToPosition(position.x() + 5, position.y(), position.z(), 1);
 
     cout << "Press Enter to land" << endl; cin.get();
     client.land();
@@ -35,25 +35,41 @@ int main()
 
 ```
 
-You can find a ready to run project in HelloDrone folder in the repository. Read more about [Hello Drone](hello_drone.md).
+You can find a ready to run project in HelloDrone folder in the repository. See more about [Hello Drone](hello_drone.md).
 
 ## Image / Computer Vision and Collision APIs
-AirSim offers comprehensive images APIs to retrieve synchronized images from multiple cameras along with ground truth including depth and vision. You can set the resolution, FOV, motion blur etc parameters in [settings.json](settings.md). There is also API for detecting collison state. In addition, AirSim also includes complete examples of how to generate stereo images along with ground truth depth images.
+AirSim offers comprehensive images APIs to retrieve synchronized images from multiple cameras along with ground truth including depth, disparity, surface normals and vision. You can set the resolution, FOV, motion blur etc parameters in [settings.json](settings.md). There is also API for detecting collision state. See also [complete code](../Examples/StereoImageGenerator.hpp) that generates specified number of stereo images and ground truth depth with normalization to camera plan, computation of disparity image and saving it to pfm format.
 
-More on [image APIs](image_apis.md).
+More on [image APIs and Computer Vision mode](image_apis.md).
 
-## Note on Timing Related Parameters
+### APIs for Multirotors
+Multirotor can be controlled by specifying angles, velocity vector, destination position or some combination of these. There are corresponding `move*` APIs for this purpose. When doing position control, we need to use some path following algorithm. By default AirSim uses carrot following algorithm. This is often referred to as "high level control" because you just need to specify very high level goal and the firmware takes care of the rest. Currently lowest level control available in AirSim is moveByAngle API however we will be adding more lower level controls soon as well.
 
-Many API methods has parameters named `float duration` or: `float max_wait_seconds`.
+## Often Encountered Parameters
+### duration and max_wait_seconds
+Many API methods has parameters named `duration` or: `max_wait_seconds`.
 
-Methods that take `float duration`, like `moveByVelocit`y return control immediately. So you can therefore choose to sleep for this duration, or you can change their mind and call something else which will automatically cancel the `moveByVelocity`.
+Methods that take `float duration`, like `moveByVelocity`y return control immediately. So you can therefore choose to sleep for this duration, or you can change their mind and call something else which will automatically cancel the `moveByVelocity`.
 
 Methods that take `float max_wait_seconds`, like `takeoff`, `land`, `moveOnPath`, `moveToPosition`, `moveToZ`, and so will block this amount of time waiting for command to be successfully completed. If the command completes before the max_wait_seconds they will return True, otherwise
 if the `max_wait_seconds` times out they will return `false`.  If you want to wait for ever pass a big number. But if you want to be able to interrupt even these commands pass 0 and you can do something else or sleep in a loop while checking the drone position, etc. We would not recommend interrupting takeoff/land on a real drone, of course, as the results may be unpredictable.
 
+### drivetrain
+Many APIs take `drivetrain` parameter which specifies how vehicle is oriented while it moves. For example, a quadrotor may move in West direction while its front is pointing towards North. In fact, quad rotors can move in all 3 axis while its front is pointing to any direction. In this mode of movement, vehicle uses its maximum degree of freedom. In forward-only mode, vehicle move only in the direction its pointing to. So if quadrotor is pointing to North and if we want it to move along West then we must reorient it. This mode is useful if we have only one sensor in the front.
+
+### yaw_mode
+Many APIs take `yaw_mode` parameter which specifies where vehicle should be pointing to. For example, you may want to move quadrotor while its front is pointing to North-East which means you will set `YawMode::is_rate = false` and `YawMode::yaw_or_rate = 90` (angle unit is degrees for Yaw). In some weired world, you might want your vehicle to continuously rotate at, say 20-degrees/sec, while it moves. YawMode allows you to specify that by setting  `YawMode::is_rate = true` and `YawMode::yaw_or_rate = 20`. However in more sane scenarios, you just don't want yaw to change which you can do by setting yaw rate of 0. The shothand for this is `YawMode::Zero()`. 
+
+### lookahead and adaptive_lookahead
+When you ask vehicle to follow a path, AirSim uses "carrot following" algorithm. This algorithm operates by looking ahead on path and adjusting its velocity vector. The parameters for this algorithm is specified by `lookahead` and `adaptive_lookahead`. For most of the time you want algorithm to auto-decide the values by simply setting `lookahead = -1` and `adaptive_lookahead = 0`.
+
 ## Using APIs on Real Vehicles
-We want to be able to run *same code* that runs in simulation as on real vehicle. The AirLib is self-contained library that you can put on an offboard computing module such as the Gigabyte barebone Mini PC. This module then can talk to the flight controllers such as Pixhawk using exact same code and MavLink protocol (or DJI protocol). The code you write for testing in the simulator remains unchanged! 
-See [AirLib on custom drones](https://github.com/Microsoft/AirSim/blob/master/docs/custom_drone.md).
+We want to be able to run *same code* that runs in simulation as on real vehicle. This allows you to test your code in simulator and deploy to real vehicle. 
+
+Generally speaking, APIs therefore shouldn't allow you to do something that cannot be done on real vehicle (for example, getting the ground truth). But, of course, simulator has much more information and it would be useful in applications that may not care about running things on real vehicle. For this reason, we clearly delineate between sim-only APIs by attaching `sim` prefix and we recommend that you don't use these APIs if you do care about real vehicle deployment.
+
+The AirLib is self-contained library that you can put on an offboard computing module such as the Gigabyte barebone Mini PC. This module then can talk to the flight controllers such as Pixhawk using exact same code and flight controller protocol. The code you write for testing in the simulator remains unchanged. See [AirLib on custom drones](/custom_drone.md).
+
 
 ## References and Examples