Fix the docs (#2621)

* fix the docs

* add docs for image demo

* add macOS in supported systems

* add mmcv into requirements of readthedocs

README.md

@@ -9,8 +9,8 @@ Documentation: https://mmdetection.readthedocs.io/
 The master branch works with **PyTorch 1.3 to 1.5**.
 The old v1.x branch works with PyTorch 1.1 to 1.4, but v2.0 is strongly recommended for faster speed, higher performance, better design and more friendly usage.
 
-mmdetection is an open source object detection toolbox based on PyTorch. It is
-a part of the open-mmlab project developed by [Multimedia Laboratory, CUHK](http://mmlab.ie.cuhk.edu.hk/).
+MMDetection is an open source object detection toolbox based on PyTorch. It is
+a part of the OpenMMLab project developed by [Multimedia Laboratory, CUHK](http://mmlab.ie.cuhk.edu.hk/).
 
 ![demo image](demo/coco_test_12510.jpg)
 
@@ -26,7 +26,7 @@ a part of the open-mmlab project developed by [Multimedia Laboratory, CUHK](http
 
 - **High efficiency**
 
-  All basic bbox and mask operations run on GPUs now. The training speed is faster than or comparable to other codebases, including [Detectron](https://github.com/facebookresearch/Detectron), [maskrcnn-benchmark](https://github.com/facebookresearch/maskrcnn-benchmark) and [SimpleDet](https://github.com/TuSimple/simpledet).
+  All basic bbox and mask operations run on GPUs. The training speed is faster than or comparable to other codebases, including [Detectron2](https://github.com/facebookresearch/detectron2), [maskrcnn-benchmark](https://github.com/facebookresearch/maskrcnn-benchmark) and [SimpleDet](https://github.com/TuSimple/simpledet).
 
 - **State of the art**
 

demo/image_demo.py

@@ -10,6 +10,8 @@ def main():
     parser.add_argument('checkpoint', help='Checkpoint file')
     parser.add_argument(
         '--device', default='cuda:0', help='Device used for inference')
+    parser.add_argument(
+        '--score-thr', type=float, default=0.3, help='bbox score threshold')
     args = parser.parse_args()
 
     # build the model from a config file and a checkpoint file
@@ -17,7 +19,7 @@ def main():
     # test a single image
     result = inference_detector(model, args.img)
     # show the results
-    show_result_pyplot(model, args.img, result)
+    show_result_pyplot(model, args.img, result, score_thr=args.score_thr)
 
 
 if __name__ == '__main__':

docs/conf.py

@@ -39,9 +39,9 @@ extensions = [
 ]
 
 autodoc_mock_imports = [
-    'cv2', 'mmcv', 'matplotlib', 'pycocotools', 'terminaltables',
-    'mmdet.version', 'mmdet.ops.dcn', 'mmdet.ops.dcn', 'mmdet.ops.masked_conv',
-    'mmdet.ops.nms', 'mmdet.ops.roi_align', 'mmdet.ops.roi_pool',
+    'matplotlib', 'pycocotools', 'terminaltables', 'mmdet.version',
+    'mmdet.ops.dcn', 'mmdet.ops.masked_conv', 'mmdet.ops.nms',
+    'mmdet.ops.roi_align', 'mmdet.ops.roi_pool',
     'mmdet.ops.sigmoid_focal_loss', 'mmdet.ops.carafe', 'mmdet.ops.utils'
 ]
 

docs/getting_started.md

@@ -70,7 +70,7 @@ Optional arguments:
 - `RESULT_FILE`: Filename of the output results in pickle format. If not specified, the results will not be saved to a file.
 - `EVAL_METRICS`: Items to be evaluated on the results. Allowed values depend on the dataset, e.g., `proposal_fast`, `proposal`, `bbox`, `segm` are available for COCO, `mAP`, `recall` for PASCAL VOC. Cityscapes could be evaluated by `cityscapes` as well as all COCO metrics.
 - `--show`: If specified, detection results will be plotted on the images and shown in a new window. It is only applicable to single GPU testing and used for debugging and visualization. Please make sure that GUI is available in your environment, otherwise you may encounter the error like `cannot connect to X server`.
-- `--show-dir`: If specified, detection results will be plotted on the images and saved to the specified directory. It is only applicable to single GPU testing and used for debugging and visualization. You **don't** need a GUI available in your environment for using this option.
+- `--show-dir`: If specified, detection results will be plotted on the images and saved to the specified directory. It is only applicable to single GPU testing and used for debugging and visualization. You do NOT need a GUI available in your environment for using this option.
 - `--show-score-thr`: If specified, detections with score below this threshold will be removed.
 
 
@@ -138,12 +138,27 @@ You will get two json files `mask_rcnn_test-dev_results.bbox.json` and `mask_rcn
 
 The generated png and txt would be under `./mask_rcnn_cityscapes_test_results` directory.
 
+### Image demo
+
+We provide a demo script to test a single image.
+
+```shell
+python demo/image_demo.py ${CONFIG_FILE} ${CHECKPOINT_FILE} [--device ${GPU_ID}] [--camera-id ${CAMERA-ID}] [--score-thr ${SCORE_THR}]
+```
+
+Examples:
+
+```shell
+python demo/image_demo.py demo/demo.jpg configs/faster_rcnn_r50_fpn_1x_coco.py \
+    checkpoints/faster_rcnn_r50_fpn_1x_20181010-3d1b3351.pth --device cpu
+```
+
 ### Webcam demo
 
 We provide a webcam demo to illustrate the results.
 
 ```shell
-python demo/webcam_demo.py ${CONFIG_FILE} ${CHECKPOINT_FILE} [--device ${GPU_ID}] [--camera-id ${CAMERA-ID}] [--score-thr ${SCORE_THR}]
+python demo/webcam_demo.py ${IMAGE_FILE} ${CONFIG_FILE} ${CHECKPOINT_FILE} [--device ${GPU_ID}] [--score-thr ${SCORE_THR}]
 ```
 
 Examples:

docs/install.md

@@ -2,7 +2,7 @@
 
 ### Requirements
 
-- Linux (Windows is not officially supported)
+- Linux or macOS (Windows is not currently officially supported)
 - Python 3.6+
 - PyTorch 1.3+
 - CUDA 9.2+ (If you build PyTorch from source, CUDA 9.0 is also compatible)
@@ -39,7 +39,7 @@ conda install pytorch cudatoolkit=10.1 torchvision -c pytorch
 PyTorch 1.3.1., you need to install the prebuilt PyTorch with CUDA 9.2.
 
 ```python
-conda install pytorch=1.3.1 cudatoolkit=10.1 torchvision=0.4.2 -c pytorch
+conda install pytorch=1.3.1 cudatoolkit=9.2 torchvision=0.4.2 -c pytorch
 ```
 
 If you build PyTorch from source instead of installing the prebuilt pacakge,
@@ -61,6 +61,12 @@ pip install "git+https://github.com/cocodataset/cocoapi.git#subdirectory=PythonA
 pip install -v -e .  # or "python setup.py develop"
 ```
 
+If you build mmdetection on macOS, replace the last command with
+
+```
+CC=clang CXX=clang++ CFLAGS='-stdlib=libc++' pip install -e .
+```
+
 Note:
 
 1. The git commit id will be written to the version number with step d, e.g. 0.6.0+2e7045c. The version will also be saved in trained models.

requirements/readthedocs.txt

+mmcv
 torch
 torchvision