[doc]: add doc for pytorch2onnx (#4271)

* [doc]: add doc for pytorch2onnx

* [doc]: remove blank lines

* resolve format of doc

* refact doc for pytorch2onnx

* add space

* add to index.rst

Author: RunningLeon

docs/tutorials/index.rst

@@ -8,3 +8,4 @@
    customize_runtime.md
    customize_losses.md
    finetune.md
+   pytorch2onnx.md

docs/tutorials/pytorch2onnx.md

@@ -0,0 +1,98 @@
+# Tutorial 8: Pytorch to ONNX (Experimental)
+
+<!-- TOC -->
+
+- [Tutorial 8: Pytorch to ONNX (Experimental)](#tutorial-8-pytorch-to-onnx-experimental)
+  - [How to convert models from Pytorch to ONNX](#how-to-convert-models-from-pytorch-to-onnx)
+    - [Prerequisite](#prerequisite)
+    - [Usage](#usage)
+  - [List of supported models exportable to ONNX](#list-of-supported-models-exportable-to-onnx)
+  - [Reminders](#reminders)
+  - [FAQs](#faqs)
+
+<!-- TOC -->
+
+## How to convert models from Pytorch to ONNX
+
+### Prerequisite
+
+1. Please refer to [get_started.md](../get_started.md) for installation of MMCV and MMDetection.
+2. Install onnx and onnxruntime
+
+  ```shell
+  pip install onnx onnxruntime
+  ```
+
+### Usage
+
+```bash
+python tools/pytorch2onnx.py \
+    ${CONFIG_FILE} \
+    ${CHECKPOINT_FILE} \
+    --output-file ${OUTPUT_FILE} \
+    --input-img ${INPUT_IMAGE_PATH} \
+    --shape ${IMAGE_SHAPE} \
+    --mean ${IMAGE_MEAN} \
+    --std ${IMAGE_STD} \
+    --dataset ${DATASET_NAME} \
+    --test-img ${TEST_IMAGE_PATH} \
+    --opset-version ${OPSET_VERSION} \
+    --show \
+    --verify \
+```
+
+Description of all arguments:
+
+- `config` : The path of a model config file.
+- `checkpoint` : The path of a model checkpoint file.
+- `--output-file`: The path of output ONNX model. If not specified, it will be set to `tmp.onnx`.
+- `--input-img` : The path of an input image for tracing and conversion. By default, it will be set to `tests/data/color.jpg`.
+- `--shape`: The height and width of input tensor to the model. If not specified, it will be set to `800 1216`.
+- `--mean` : Three mean values for the input image. If not specified, it will be set to `123.675 116.28 103.53`.
+- `--std` : Three std values for the input image. If not specified, it will be set to `58.395 57.12 57.375`.
+- `--dataset` : The dataset name for the input model. If not specified, it will be set to `coco`.
+- `--test-img` : The path of an image to verify the exported ONNX model. By default, it will be set to `None`, meaning it will use `--input-img` for verification.
+- `--opset-version` : The opset version of ONNX. If not specified, it will be set to `11`.
+- `--show`: Determines whether to print the architecture of the exported model. If not specified, it will be set to `False`.
+- `--verify`: Determines whether to verify the correctness of an exported model. If not specified, it will be set to `False`.
+
+Example:
+
+```bash
+python tools/pytorch2onnx.py \
+    configs/yolo/yolov3_d53_mstrain-608_273e_coco.py \
+    checkpoints/yolo/yolov3_d53_mstrain-608_273e_coco.pth \
+    --output-file checkpoints/yolo/yolov3_d53_mstrain-608_273e_coco.onnx \
+    --input-img demo/demo.jpg \
+    --test-img tests/data/color.jpg \
+    --shape 608 608 \
+    --mean 0 0 0 \
+    --std 255 255 255 \
+    --show \
+    --verify \
+```
+
+## List of supported models exportable to ONNX
+
+The table below lists the models that are guaranteed to be exportable to ONNX and runnable in ONNX Runtime.
+
+|    Model    |                        Config                        | Note  |
+| :---------: | :--------------------------------------------------: | :---: |
+|     SSD     |             `configs/ssd/ssd300_coco.py`             |       |
+|   YOLOv3    |  `configs/yolo/yolov3_d53_mstrain-608_273e_coco.py`  |       |
+|    FSAF     |        `configs/fsaf/fsaf_r50_fpn_1x_coco.py`        |       |
+|  RetinaNet  |   `configs/retinanet/retinanet_r50_fpn_1x_coco.py`   |       |
+| Faster-RCNN | `configs/faster_rcnn/faster_rcnn_r50_fpn_1x_coco.py` |       |
+
+Notes:
+
+- *All models above are tested with Pytorch==1.6.0*
+
+## Reminders
+
+- If you meet any problem with the listed models above, please create an issue and it would be taken care of soon. For models not included in the list, please try to dig a little deeper and debug a little bit more and hopefully solve them by yourself.
+- Because this feature is experimental and may change fast, please always try with the latest `mmcv` and `mmdetecion`.
+
+## FAQs
+
+- None

docs/useful_tools.md

@@ -113,14 +113,13 @@ Params: 37.74 M
 
 ### MMDetection model to ONNX (experimental)
 
-We provide a script to convert model to [ONNX](https://github.com/onnx/onnx) format. We also support comparing the output results between Pytorch and
- ONNX model for verification.
+We provide a script to convert model to [ONNX](https://github.com/onnx/onnx) format. We also support comparing the output results between Pytorch and ONNX model for verification.
 
 ```shell
 python tools/pytorch2onnx.py ${CONFIG_FILE} ${CHECKPOINT_FILE} --output_file ${ONNX_FILE} [--shape ${INPUT_SHAPE} --verify]
 ```
 
-**Note**: This tool is still experimental. Some customized operators are not supported for now. We only support exporting RetinaNet model at this moment.
+**Note**: This tool is still experimental. Some customized operators are not supported for now. For a detailed description of the usage and the list of supported models, please refer to [pytorch2onnx](tutorials/pytorch2onnx.md).
 
 ### MMDetection 1.x model to MMDetection 2.x
 

tools/pytorch2onnx.py

@@ -140,8 +140,6 @@ def parse_args():
         '--test-img', type=str, default=None, help='Images for test')
     parser.add_argument(
         '--dataset', type=str, default='coco', help='Dataset name')
-    parser.add_argument(
-        '--view', action='store_true', help='Visualize results')
     parser.add_argument(
         '--verify',
         action='store_true',
@@ -200,4 +198,5 @@ def parse_args():
         output_file=args.output_file,
         verify=args.verify,
         normalize_cfg=normalize_cfg,
-        dataset=args.dataset)
+        dataset=args.dataset,
+        test_img=args.test_img)