fix some types and add code block colorization.

senakicir · Feb 21, 2018 · 97b591e · 97b591e
1 parent f53a578
commit 97b591e
Showing 1 changed file with 22 additions and 23 deletions.
diff --git a/docs/image_apis.md b/docs/image_apis.md
@@ -6,7 +6,7 @@ Here's a sample code to get a single image. Below returned value is bytes of png
 
 ### C++
 
-```
+```cpp
 #include "vehicles/multirotor/api/MultirotorRpcLibClient.hpp"
 
 int getOneImage() 
@@ -24,7 +24,7 @@ int getOneImage()
 
 ### Python
 
-```
+```cpp
 from AirSimClient import *
 
 # for car use CarClient() 
@@ -40,7 +40,7 @@ The `simGetImages` API which is slightly more complex to use than `simGetImage`
 
 ### C++
 
-```
+```cpp
 int getStereoAndDepthImages() 
 {
     using namespace std;
@@ -71,7 +71,7 @@ int getStereoAndDepthImages()
 
 ### Python
 
-```
+```python
 from AirSimClient import *
 
 # for car use CarClient() 
@@ -92,7 +92,7 @@ responses = client.simGetImages([
 
 If you plan to use numpy for image manipulation, you should get uncompressed RGBA image and then convert to numpy like this:
 
-```
+```python
 responses = client.simGetImages([ImageRequest(0, AirSimImageType.Scene, False, False)])
 response = responses[0]
 
@@ -137,7 +137,7 @@ You can use AirSim in so-called "Computer Vision" mode. In this mode, physics en
 
 To active this mode, edit [settings.json](settings.json) that you can find in your `Documents\AirSim` folder (or `~/Documents/AirSim` on Linux) and make sure following values exist at root level:
 
-```
+```json
 {
   "SettingsVersion": 1.0,
   "UsageScenario": "ComputerVision"
@@ -166,7 +166,7 @@ Please see [example usage](https://github.com/Microsoft/AirSim/blob/master/Pytho
 ## Changing Resolution and Camera Parameters
 To change resolution, FOV etc, you can use [settings.json](settings.md). For example, below is the complete content of settings.json that 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.
 
-```
+```json
 {
   "CaptureSettings": [
     {
@@ -183,11 +183,11 @@ To change resolution, FOV etc, you can use [settings.json](settings.md). For exa
 ```
 
 ### Getting Camera Parameters
-The `getCameraInfo(camera_id)` API call retuns pose (in world frame, NED coordinates, SI units) and FOV (in degrees) of specified camera. Camera ID is zer-based [index of camera](#available-cameras). Please see [example usage](https://github.com/Microsoft/AirSim/blob/master/PythonClient/cv_mode.py).
+The `getCameraInfo(camera_id)` API call returns pose (in world frame, NED coordinates, SI units) and FOV (in degrees) of specified camera. Camera ID is zero-based [index of camera](#available-cameras). Please see [example usage](https://github.com/Microsoft/AirSim/blob/master/PythonClient/cv_mode.py).
 
 ## What Does Pixel Values Mean in Different Image Types?
 ### Available ImageType
-```
+```cpp
   Scene = 0, 
   DepthPlanner = 1, 
   DepthPerspective = 2,
@@ -199,35 +199,35 @@ The `getCameraInfo(camera_id)` API call retuns pose (in world frame, NED coordin
 ```                
 
 ### DepthPlanner and DepthPerspective
-You normally want retrieve depth image as float (i.e. set `pixels_as_float = true`) and specify `ImageType = DepthPlanner` or `ImageType = DepthPerspective` in `ImageRequest`. For `ImageType = DepthPlanner`, you get depth in camera plan, i.e., all points that are in plan parallel to camera have same depth. For `ImageType = DepthPerspective`, you get depth from camera using a project ray that hits that pixel. Depending on your use case, planner depth or perspective depth may be the ground truth image that you want. For example, you may be able to feed perspective depth to ROS package such as `depth_image_proc` to generate point cloud. Or planner depth may be more compatible with estimated depth image generated by stereo algorithms such as SGM.
+You normally want to retrieve the depth image as float (i.e. set `pixels_as_float = true`) and specify `ImageType = DepthPlanner` or `ImageType = DepthPerspective` in `ImageRequest`. For `ImageType = DepthPlanner`, you get depth in camera plan, i.e., all points that are in plan parallel to camera have same depth. For `ImageType = DepthPerspective`, you get depth from camera using a projection ray that hits that pixel. Depending on your use case, planner depth or perspective depth may be the ground truth image that you want. For example, you may be able to feed perspective depth to ROS package such as `depth_image_proc` to generate a point cloud. Or planner depth may be more compatible with estimated depth image generated by stereo algorithms such as SGM.
 
 ### DepthVis
-When you specify `ImageType = DepthVis` in `ImageRequest`, you get image that helps depth visualization. In this case, each pixel value is interpolated from red to green depending on depth in camera plane in meters. The pixels with pure green means depth of 100m or more while pure red means depth of 0 meters.
+When you specify `ImageType = DepthVis` in `ImageRequest`, you get an image that helps depth visualization. In this case, each pixel value is interpolated from red to green depending on depth in camera plane in meters. The pixels with pure green means depth of 100m or more while pure red means depth of 0 meters.
 
 ### DisparityNormalized
-You normally want retrieve disparity image as float (i.e. set `pixels_as_float = true` and specify `ImageType = DisparityNormalized` in `ImageRequest`) in which case each pixel is `(Xl - Xr)/Xmax`, valued from 0 to 1.
+You normally want to retrieve disparity image as float (i.e. set `pixels_as_float = true` and specify `ImageType = DisparityNormalized` in `ImageRequest`) in which case each pixel is `(Xl - Xr)/Xmax`, which is thereby normalized to values between 0 to 1.
 
 ### Segmentation
-When you specify `ImageType = Segmentation` in `ImageRequest`, you get image that gives you ground truth segmentation of the scene. At the starup, AirSim assigns value 0 to 255 to each mesh available in environment. This value is than mapped to a specific color in [the pallet](../Unreal/Plugins/AirSim/Content/HUDAssets/seg_color_pallet.png). Thr RGB values for each object ID can be found in [this file](seg_rgbs.txt).
+When you specify `ImageType = Segmentation` in `ImageRequest`, you get an image that gives you ground truth segmentation of the scene. At the startup, AirSim assigns value 0 to 255 to each mesh available in environment. This value is than mapped to a specific color in [the pallet](../Unreal/Plugins/AirSim/Content/HUDAssets/seg_color_pallet.png). The RGB values for each object ID can be found in [this file](seg_rgbs.txt).
 
-You can assign a specific value to specific mesh using APIs. For example, below Python code sets the object ID for the mesh called "Ground" to 20 in Blocks environment and hence changes its color in Segmentation view:
+You can assign a specific value (limited to the range 0-255) to a specific mesh using APIs. For example, below Python code sets the object ID for the mesh called "Ground" to 20 in Blocks environment and hence changes its color in Segmentation view:
 
-```
+```python
 success = client.simSetSegmentationObjectID("Ground", 20);
 ```
 
-The return value is boolean type that lets you know if the mesh was found.
+The return value is a boolean type that lets you know if the mesh was found.
 
-Notice that typical Unreal environment like Blocks usually have many other meshes that comprises of same object, for example, "Ground_2", "Ground_3" and so on. As it is tedious to set object ID for all of these meshes, AirSim also supports regular expressions. For example, below code sets all meshes which have names starting with "ground" (ignoring case) to 21 with just one line:
+Notice that typical Unreal environments, like Blocks, usually have many other meshes that comprises of same object, for example, "Ground_2", "Ground_3" and so on. As it is tedious to set object ID for all of these meshes, AirSim also supports regular expressions. For example, the code below sets all meshes which have names starting with "ground" (ignoring case) to 21 with just one line:
 
-```
+```python
 success = client.simSetSegmentationObjectID("ground[\w]*", 21, True);
 ```
 
 The return value is true if at least one mesh was found using regular expression matching.
 
-We recommand getting uncompressed image using API like this to make sure you get precise RGB values for segmentation image:
-```
+It is recommended that you request uncompressed image using this API to ensure you get precise RGB values for segmentation image:
+```python
 responses = client.simGetImages([ImageRequest(0, AirSimImageType.Segmentation, False, False)])
 img1d = np.fromstring(response.image_data_uint8, dtype=np.uint8) #get numpy array
 img_rgba = img1d.reshape(response.height, response.width, 4) #reshape array to 4 channel image array H X W X 4
@@ -245,7 +245,7 @@ A complete ready-to-run example can be found in [segmentation.py](https://github
 An object's ID can be set to -1 to make it not show up on the segmentation image.
 
 #### How to Find Mesh Names?
-To get desired ground truth segmentation you will need to know names of the meshes in your Unreal environment that you are interested in. To do this, you will need to open up Unreal Environment in Unreal Editor and then inspect the names of the meshes you are interested in the World Outliner. For example, below we see the meshe names for he ground in Blocks environment in right panel in the editor:
+To get desired ground truth segmentation you will need to know the names of the meshes in your Unreal environment. To do this, you will need to open up Unreal Environment in Unreal Editor and then inspect the names of the meshes you are interested in using the World Outliner. For example, below we see the mesh names for he ground in Blocks environment in right panel in the editor:
 
 ![record screenshot](images/unreal_editor_blocks.png)
 
@@ -254,12 +254,11 @@ If you don't know how to open Unreal Environment in Unreal Editor then try follo
 Once you decide on the meshes you are interested, note down their names and use above API to set their object IDs.
 
 #### Changing Colors for Object IDs
-At present color for each object ID is fixed as in [this pallet](../Unreal/Plugins/AirSim/Content/HUDAssets/seg_color_pallet.png). We will be adding ability to change colors for object IDs to desired values shortly. In the mean time it might be easier just to open the segmentation image in some image editor and get the RGB values you are interested in. 
+At present the color for each object ID is fixed as in [this pallet](../Unreal/Plugins/AirSim/Content/HUDAssets/seg_color_pallet.png). We will be adding ability to change colors for object IDs to desired values shortly. In the meantime you can open the segmentation image in your favorite image editor and get the RGB values you are interested in.
 
 #### Startup Object IDs
 At the start, AirSim assigns object ID to each mesh. To do this, it takes first 3 letters of mesh name, converts them to int, sums them and modulo 255 generates the object ID. In other words, all object with first same 3 letters will get same object ID at the start. This heuristic is simple and effective for many Unreal environments but may not be what you want. In that case, please use above APIs to change object IDs to your desired values.
 
-
 #### Getting Object ID for Mesh
 The `simGetSegmentationObjectID` API allows you get object ID for given mesh name.