release commit
[jacinto-ai/pytorch-jacinto-ai-devkit.git] / docs / Semantic_Segmentation.md
index 320c878ae65643b77d607bd18b5ee0469f7ad293..a341c860df8830271bf14525827bd2db727ca1be 100644 (file)
@@ -2,52 +2,27 @@
 
 Semantic segmentation assigns a class to each pixel of the image. It is useful for tasks such as lane detection, road segmentation etc. 
 
-Commonly used Training/Validation commands are listed in the file [run_segmentation.sh](../run_segmentation.sh). Un-commend one and run the file to start the run. 
+Commonly used Training/Validation commands are listed in the file [run_segmentation.sh](../run_segmentation.sh). Uncommend one line and run the file to start the run. 
 
-## Models
-We have defined a set of example models for all pixel to pixel tasks
+## Model Configurations
+A set of common example model configurations are defined for all pixel to pixel tasks. These models can support multiple inputs (for example image and optical flow) as well as support multiple decoders for multi-task prediction (for example semantic segmentation + depth estimation + motion segmentation)
 
-These models can support multiple inputs (for example image and optical flow) as well as support multiple decoders for multi-task prediction (for example semantic segmentation + depth estimation + motion segmentation). 
+Whether to use multiple inputs or how many decoders to use are fully configurable. This framework is also flexible to add different model architectures or backbone networks. The following model configurations are currently available:<br>
 
-Whether to use multiple inputs or how many decoders to use are fully configurable. Our framework is also flexible to add different model architectures or backbone networks if you wish to do. 
+* **deeplabv3lite_mobilenetv2_tv**: (default) This model is mostly similar to the DeepLabV3+ model [[6]] using MobileNetV2 backbone. The difference with DeepLabV3+ is that we removed the convolutions after the shortcut and kep one set of depthwise separable convolutions to generate the prediction. The ASPP module that we used is a lite-weight variant with depthwise separable convolutions (DWASPP). We found that this reduces complexity without sacrificing accuracy. Due to this we call this model DeepLabV3+(Lite) or simply  DeepLabV3Lite. (Note: The suffix "_tv" is used to indicate that our backbone model is from torchvision)<br> 
 
-The models that we support of the shelf are:<br>
+* **fpn_pixel2pixel_aspp_mobilenetv2_tv**: This is similar to Feature Pyramid Network [[3]], but adapted for pixel2pixel tasks. We stop the decoder at a stride of 4 and then upsample to the final resolution from there. We also use DWASPP module to improve the receptive field. We call this model FPNPixel2Pixel. 
 
-* **deeplabv3lite_mobilenetv2_tv**: (default) This model is mostly similar to the DeepLabV3+ model [3] using MobileNetV2 backbone. The difference with DeepLabV3+ is that we removed the convolutions after the shortcut and kep one set of depthwise separable convolutions to generate the prediction. The ASPP module that we used is a lite-weight variant with depthwise separable convolutions (DWASPP). We found that this reduces complexity without sacrificing accuracy. Due to this we call this model DeepLabV3+(Lite) or simply  DeepLabV3Lite. (Note: The suffix "_tv" is used to indicate that our backbone model is from torchvision)<br> 
-
-* **fpn_pixel2pixel_aspp_mobilenetv2_tv**: This is similar to Feature Pyramid Network [4], but adapted for pixel2pixel tasks. We stop the decoder at a stride of 4 and then upsample to the final resolution from there. We also use DWASPP module to improve the receptive field. We call this model FPNPixel2Pixel. 
+* **fpn_pixel2pixel_aspp_mobilenetv2_tv_es64**: This is also FPN, but with a larger encoder stride(64). This is a low complexity model that can be used with higher resolutions.
 
 * **fpn_pixel2pixel_aspp_resnet50**: Feature Pyramid Network (FPN) based pixel2pixel using ResNet50 backbone with DWASPP.
 
-## Datasets: Cityscapes Dataset [1]
-
-* Download the cityscapes dataset from https://www.cityscapes-dataset.com/. You will need need to register before the data can be downloaded. Unzip the data into the folder ./data/datasets/cityscapes/data. This folder should contain leftImg8bit and gtFine folders of cityscapes. 
-
-* These examples use two gpus because we use slightly higher accuracy when we restricted the number of GPUs used. 
-
-* Training can be done as follows:<br>
-    ```
-    python ./scripts/train_segmentation_main.py --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 384 768 --output_size 1024 2048 --gpus 0 1
-  ```
-
- * During the training, **validation** accuracy will also be printed. But if you want to explicitly check the accuracy again with **validation** set, it can be done:<br>
-    ```
-    python ./scripts/train_segmentation_main.py --evaluate True --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 384 768 --output_size 1024 2048 --gpus 0 1
-    ```
-  
-  * It is possible to use a different image size. For example, we trained for 1536x768 resolution by the following. (We used a smaller crop size compared to the image resize resolution to reduce GPU memory usage). <br>
-    ```
-    python ./scripts/train_segmentation_main.py --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 768 1536 --rand_crop 512 1024 --output_size 1024 2048 --gpus 0 1
-    ```
+## Datasets: Cityscapes Dataset 
 
-* Train FPNPixel2Pixel model at 1536x768 resolution (use 1024x512 crop to reduce memory usage):<br>
-    ```
-    python ./scripts/train_segmentation_main.py --model_name fpn_pixel2pixel_aspp_mobilenetv2_tv --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 768 1536 --rand_crop 512 1024 --output_size 1024 2048 --gpus 0 1
-    ```
+* Download the Cityscapes dataset [[1]] from https://www.cityscapes-dataset.com/. You will need need to register before the data can be downloaded. Unzip the data into the folder ./data/datasets/cityscapes/data. This folder should contain leftImg8bit and gtFine folders of cityscapes. 
 
-## Datasets: VOC Dataset [2]
-### Download the data
-* The dataset can be downloaded using the following:<br>
+## Datasets: VOC Dataset 
+* The PASCAL VOC dataset [[2]] can be downloaded using the following:<br>
     ```
     mkdir ./data/datasets/voc
     cd /data/datasets/voc
@@ -55,7 +30,6 @@ The models that we support of the shelf are:<br>
     wget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtrainval_06-Nov-2007.tar
     wget http://host.robots.ox.ac.uk/pascal/VOC/voc2007/VOCtest_06-Nov-2007.tar
     ```
-### Extract the data.
 * Extact the dataset files into ./data/datasets/voc/VOCdevkit
     ```
     tar -xvf VOCtrainval_11-May-2012.tar
@@ -70,28 +44,60 @@ The models that we support of the shelf are:<br>
     ls -1 SegmentationClassAug | sed s/.png// > trainaug.txt
     ```
 
-* training can be done as follows from the base folder of the repository:<br>
+## Training
+* These examples use two gpus because we use slightly higher accuracy when we restricted the number of GPUs used. 
+
+* **Cityscapes Segmentation Training** can be done as follows:<br>
+    ```
+    python ./scripts/train_segmentation_main.py --model_name deeplabv3lite_mobilenetv2_tv --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 384 768 --output_size 1024 2048 --pretrained https://download.pytorch.org/models/mobilenet_v2-b0353104.pth --gpus 0 1
+  ```
+  
+  * It is possible to use a different image size. For example, we trained for 1536x768 resolution by the following. (We used a smaller crop size compared to the image resize resolution to reduce GPU memory usage). <br>
+    ```
+    python ./scripts/train_segmentation_main.py --model_name deeplabv3lite_mobilenetv2_tv --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 768 1536 --rand_crop 512 1024 --output_size 1024 2048 --pretrained https://download.pytorch.org/models/mobilenet_v2-b0353104.pth --gpus 0 1
+    ```
+
+* Train FPNPixel2Pixel model at 1536x768 resolution (use 1024x512 crop to reduce memory usage):<br>
     ```
-    python ./scripts/train_segmentation_main.py --dataset_name voc_segmentation --data_path ./data/datasets/voc --img_resize 512 512 --output_size 512 512 --gpus 0 1
+    python ./scripts/train_segmentation_main.py --model_name fpn_pixel2pixel_aspp_mobilenetv2_tv --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 768 1536 --rand_crop 512 1024 --output_size 1024 2048 --pretrained https://download.pytorch.org/models/mobilenet_v2-b0353104.pth --gpus 0 1
+    ```
+* **VOC Segmentation Training** can be done as follows:<br>
+    ```
+    python ./scripts/train_segmentation_main.py --model_name deeplabv3lite_mobilenetv2_tv --dataset_name voc_segmentation --data_path ./data/datasets/voc --img_resize 512 512 --output_size 512 512 --pretrained https://download.pytorch.org/models/mobilenet_v2-b0353104.pth --gpus 0 1
   ```
 
+## Validation
+ * During the training, **validation** accuracy will also be printed. But to explicitly check the accuracy again with **validation** set, it can be done as follows (fill in the path to the pretrained model):<br>
+    ```
+    python ./scripts/train_segmentation_main.py --evaluate True --model_name deeplabv3lite_mobilenetv2_tv --dataset_name cityscapes_segmentation --data_path ./data/datasets/cityscapes/data --img_resize 384 768 --output_size 1024 2048 --gpus 0 1 --pretrained ?????
+    ```
+
+## Inference
+Inference can be done as follows (fill in the path to the pretrained model):<br>
+    ```
+    python ./scripts/infer_segmentation_main.py --evaluate True --model_name deeplabv3lite_mobilenetv2_tv --dataset_name cityscapes_segmentation_measure --data_path ./data/datasets/cityscapes/data --img_resize 384 768 --output_size 1024 2048 --gpus 0 1 --pretrained ?????
+    ```
+          
 ## Results
 
 ### Cityscapes Segmentation
 
-|Dataset    |Mode Architecture|Backbone Model|Model Name                         |Backbone Stride|Resolution |Complexity (GigaMACS)|MeanIoU%  |
-|---------  |----------       |-----------   |---------------------------------  |-------------- |-----------|--------             |----------|
-|Cityscapes |DeepLabV3Lite    |MobileNetV2   |deeplabv3lite_mobilenetv2_tv       |16             |768x384    |3.54                 |**69.13** |
-|Cityscapes |FPNPixel2Pixel   |MobileNetV2   |fpn_pixel2pixel_mobilenetv2_tv     |32             |768x384    |3.84                 |**70.39** |
-|Cityscapes |FPNPixel2Pixel   |MobileNetV2   |fpn_pixel2pixel_mobilenetv2_tv_es64|64             |1536x768   |3.96                 |**71.28** |
-|Cityscapes |FPNPixel2Pixel   |MobileNetV2   |fpn_pixel2pixel_mobilenetv2_tv_es64|64             |2048x1024  |7.03                 |          |
-|Cityscapes |DeepLabV3Lite    |MobileNetV2   |deeplabv3lite_mobilenetv2_tv       |16             |1536x768   |14.48                |**73.59** |
-|Cityscapes |FPNPixel2Pixel   |MobileNetV2   |fpn_pixel2pixel_mobilenetv2_tv     |32             |1536x768   |15.37                |**74.98** |
-|-
-|Cityscapes |ERFNet[5]        |              |                                   |               |1024x512   |27.705               |69.7      |
-|Cityscapes |SwiftNetMNV2[6]  |MobileNetV2   |                                   |               |2048x1024  |41.0                 |75.3      |
-|Cityscapes |DeepLabV3Plus[3] |MobileNetV2   |                                   |16             |           |21.27                |70.71     |
-|Cityscapes |DeepLabV3Plus[3] |Xception65    |                                   |16             |           |418.64               |78.79     |
+|Dataset    |Mode Architecture   |Backbone Model|Backbone Stride|Resolution |Complexity (GigaMACS)|MeanIoU%  |Model Configuration Name           |
+|---------  |----------          |-----------   |-------------- |-----------|--------             |----------|---------------------------------  |
+|Cityscapes |DeepLabV3Lite       |MobileNetV2   |16             |768x384    |3.54                 |**69.13** |deeplabv3lite_mobilenetv2_tv       |
+|Cityscapes |FPNPixel2Pixel      |MobileNetV2   |32             |768x384    |3.84                 |**70.39** |fpn_pixel2pixel_mobilenetv2_tv     |
+|Cityscapes |FPNPixel2Pixel      |MobileNetV2   |64             |1536x768   |3.96                 |**71.28** |fpn_pixel2pixel_mobilenetv2_tv_es64|
+|Cityscapes |FPNPixel2Pixel      |MobileNetV2   |64             |2048x1024  |7.03                 |          |fpn_pixel2pixel_mobilenetv2_tv_es64|
+|Cityscapes |DeepLabV3Lite       |MobileNetV2   |16             |1536x768   |14.48                |**73.59** |deeplabv3lite_mobilenetv2_tv       |
+|Cityscapes |FPNPixel2Pixel      |MobileNetV2   |32             |1536x768   |15.37                |**74.98** |fpn_pixel2pixel_mobilenetv2_tv     |
+
+|Dataset    |Mode Architecture   |Backbone Model|Backbone Stride|Resolution |Complexity (GigaMACS)|MeanIoU%  |Model Configuration Name           |
+|---------  |----------          |-----------   |-------------- |-----------|--------             |----------|---------------------------------  |
+|Cityscapes |ERFNet[[4]]         |              |               |1024x512   |27.705               |69.7      |N/A                                |
+|Cityscapes |SwiftNetMNV2[[5]]   |MobileNetV2   |               |2048x1024  |41.0                 |75.3      |N/A                                |
+|Cityscapes |DeepLabV3Plus[[6,7]]|MobileNetV2   |16             |           |21.27                |70.71     |N/A                                |
+|Cityscapes |DeepLabV3Plus[[6,7]]|Xception65    |16             |           |418.64               |78.79     |N/A                                |
 
 
 ## References
@@ -101,12 +107,14 @@ The models that we support of the shelf are:<br>
 Everingham, M., Van Gool, L., Williams, C. K. I., Winn, J. and Zisserman, A.
 International Journal of Computer Vision, 88(2), 303-338, 2010, http://host.robots.ox.ac.uk/pascal/VOC/
 
-[3] Encoder-Decoder with Atrous Separable Convolution for Semantic Image Segmentation, Liang-Chieh Chen, Yukun Zhu, George Papandreou, Florian Schroff, and Hartwig Adam, CVPR 2018, https://github.com/tensorflow/models/blob/master/research/deeplab/g3doc/model_zoo.md
+[3] Feature Pyramid Networks for Object Detection, Tsung-Yi Lin, Piotr Dollar, Ross Girshick, Kaiming He, Bharath Hariharan, Serge Belongie, CVPR 2017
+
+[4] ERFNet: Efficient Residual Factorized ConvNet for Real-time Semantic Segmentation, E. Romera, J. M. Alvarez, L. M. Bergasa and R. Arroyo, Transactions on Intelligent Transportation Systems (T-ITS), 2017
 
-[4] Feature Pyramid Networks for Object Detection, Tsung-Yi Lin, Piotr Dollar, Ross Girshick, Kaiming He, Bharath Hariharan, Serge Belongie, CVPR 2017
+[5] In Defense of Pre-trained ImageNet Architectures for Real-time Semantic Segmentation of Road-driving Images, Marin Orsic, Ivan Kreso, Petra Bevandic, Sinisa Segvic, CVPR 2019.
 
-[5] ERFNet: Efficient Residual Factorized ConvNet for Real-time Semantic Segmentation, E. Romera, J. M. Alvarez, L. M. Bergasa and R. Arroyo, Transactions on Intelligent Transportation Systems (T-ITS), 2017
+[6] Encoder-Decoder with Atrous Separable Convolution for Semantic Image Segmentation, Liang-Chieh Chen, Yukun Zhu, George Papandreou, Florian Schroff, and Hartwig Adam, CVPR 2018
 
-[6] In Defense of Pre-trained ImageNet Architectures for Real-time Semantic Segmentation of Road-driving Images, Marin Orsic, Ivan Kreso, Petra Bevandic, Sinisa Segvic, CVPR 2019.
+[7] Tensorflow/Deeplab Model Zoo, https://github.com/tensorflow/models/blob/master/research/deeplab/g3doc/model_zoo.md