[Doc] Refine some docs (#1620)

liqikai9 · ly015 · web-flow · commit 6c0ccc0567bb · 2022-09-01T14:51:24.000+08:00
* fix typo

* minor modification to changlog.md

* fix lint

* remove legacy files

* remove .gitkeep

* remove legacy files

Co-authored-by: ly015 &lt;liyining0712@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -93,7 +93,7 @@ cd mmpose
 mim install -e .
 ```
 
-Please refer to [install.md](https://mmpose.readthedocs.io/en/1.x/installation.html) for more detailed installation and dataset preparation.
+Please refer to [installation.md](https://mmpose.readthedocs.io/en/1.x/installation.html) for more detailed installation and dataset preparation.
 
 ## Getting Started
 
@@ -147,7 +147,6 @@ A summary can be found in the [Model Zoo](https://mmpose.readthedocs.io/en/1.x/m
 - [x] [UDP](https://mmpose.readthedocs.io/en/1.x/model_zoo_papers/techniques.html#udp-cvpr-2020) (CVPR'2020)
 - [x] [Albumentations](https://mmpose.readthedocs.io/en/1.x/model_zoo_papers/techniques.html#albumentations-information-2020) (Information'2020)
 - [x] [SoftWingloss](https://mmpose.readthedocs.io/en/1.x/model_zoo_papers/techniques.html#softwingloss-tip-2021) (TIP'2021)
-- [x] [SmoothNet](/configs/_base_/filters/smoothnet_h36m.md) (arXiv'2021)
 - [x] [RLE](https://mmpose.readthedocs.io/en/1.x/model_zoo_papers/techniques.html#rle-iccv-2021) (ICCV'2021)
 
 </details>
diff --git a/demo/docs/2d_face_demo.md b/demo/docs/2d_face_demo.md
@@ -16,7 +16,7 @@ python demo/topdown_face_demo.py \
     [--kpt-thr ${KPT_SCORE_THR}]
 ```
 
-The pre-trained face keypoint estimation model can be found from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/face.html).
+The pre-trained face keypoint estimation model can be found from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/face_2d_keypoint.html).
 Take [aflw model](https://download.openmmlab.com/mmpose/face/hrnetv2/hrnetv2_w18_aflw_256x256-f2bbc62b_20210125.pth) as an example:
 
 ```shell
diff --git a/demo/docs/2d_hand_demo.md b/demo/docs/2d_hand_demo.md
@@ -19,7 +19,7 @@ python demo/topdown_demo_with_mmdet.py \
 
 ```
 
-The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/hand.html).
+The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/hand_2d_keypoint.html).
 Take [onehand10k model](https://download.openmmlab.com/mmpose/hand/hrnetv2/hrnetv2_w18_onehand10k_256x256-30bc9c6b_20210330.pth) as an example:
 
 ```shell
diff --git a/demo/docs/2d_human_pose_demo.md b/demo/docs/2d_human_pose_demo.md
@@ -16,7 +16,9 @@ python demo/image_demo.py \
     [--draw_heatmap]
 ```
 
-The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/body.html).
+If you use a heatmap-based model and set argument `--draw-heatmap`, the predicted heatmap will be visualized together with the keypoints.
+
+The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/body_2d_keypoint.html).
 Take [coco model](https://download.openmmlab.com/mmpose/top_down/hrnet/hrnet_w48_coco_256x192-b9e0b3ab_20200708.pth) as an example:
 
 ```shell
@@ -41,17 +43,21 @@ python demo/image_demo.py \
     --device=cpu
 ```
 
+Visualization result:
+
+<img src="https://user-images.githubusercontent.com/87690686/187824033-2cce0f55-034a-4127-82e2-52744178bc32.jpg" height="500px" alt><br>
+
 #### Use mmdet for human bounding box detection
 
 We provide a demo script to run mmdet for human detection, and mmpose for pose estimation.
 
-Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection).
+Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection) with version >= 3.0.
 
 ```shell
 python demo/topdown_demo_with_mmdet.py \
     ${MMDET_CONFIG_FILE} ${MMDET_CHECKPOINT_FILE} \
     ${MMPOSE_CONFIG_FILE} ${MMPOSE_CHECKPOINT_FILE} \
-    --input ${IMG_OR_VIDEO_FILE} \
+    --input ${INPUT_PATH} \
     --output-root ${OUTPUT_DIR} \
     [--show --draw-heatmap --device ${GPU_ID or CPU}] \
     [--bbox-thr ${BBOX_SCORE_THR} --kpt-thr ${KPT_SCORE_THR}]
@@ -69,11 +75,15 @@ python demo/topdown_demo_with_mmdet.py \
     --output-root vis_results/
 ```
 
+Visualization result:
+
+<img src="https://user-images.githubusercontent.com/87690686/187824368-1f1631c3-52bf-4b45-bf9a-a70cd6551e1a.jpg" height="500px" alt><br>
+
 ### 2D Human Pose Top-Down Video Demo
 
-The above demo script can also take video as input, and run mmdet for human detection, and mmpose for pose estimation.
+The above demo script can also take video as input, and run mmdet for human detection, and mmpose for pose estimation. The difference is, the `${INPUT_PATH}` for videos can be the local path or **URL** link to video file.
 
-Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection).
+Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection) with version >= 3.0.
 
 Examples:
 
@@ -93,5 +103,5 @@ Some tips to speed up MMPose inference:
 
 For top-down models, try to edit the config file. For example,
 
-1. set `flip_test=False` in [topdown-res50](/configs/body_2d_keypoint/topdown_heatmap/coco/td-hm_res50_8xb64-210e_coco-256x192.py#L56).
+1. set `model.test_cfg.flip_test=False` in [topdown-res50](/configs/body_2d_keypoint/topdown_heatmap/coco/td-hm_res50_8xb64-210e_coco-256x192.py#L56).
 2. use faster human bounding box detector, see [MMDetection](https://mmdetection.readthedocs.io/en/latest/model_zoo.html).
diff --git a/demo/docs/2d_wholebody_pose_demo.md b/demo/docs/2d_wholebody_pose_demo.md
@@ -16,7 +16,7 @@ python demo/image_demo.py \
     [--draw_heatmap]
 ```
 
-The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/wholebody.html).
+The pre-trained hand pose estimation model can be downloaded from [model zoo](https://mmpose.readthedocs.io/en/1.x/model_zoo/2d_wholebody_keypoint.html).
 Take [coco-wholebody_vipnas_res50_dark](https://download.openmmlab.com/mmpose/top_down/vipnas/vipnas_res50_wholebody_256x192_dark-67c0ce35_20211112.pth) model as an example:
 
 ```shell
@@ -43,13 +43,13 @@ python demo/image_demo.py \
 
 We provide a demo script to run mmdet for human detection, and mmpose for pose estimation.
 
-Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection).
+Assume that you have already installed [mmdet](https://github.com/open-mmlab/mmdetection) with version >= 3.0.
 
 ```shell
 python demo/topdown_demo_with_mmdet.py \
     ${MMDET_CONFIG_FILE} ${MMDET_CHECKPOINT_FILE} \
     ${MMPOSE_CONFIG_FILE} ${MMPOSE_CHECKPOINT_FILE} \
-    --input ${IMG_OR_VIDEO_FILE} \
+    --input ${INPUT_PATH} \
     --output-root ${OUTPUT_DIR} \
     [--show --draw-heatmap --device ${GPU_ID or CPU}] \
     [--bbox-thr ${BBOX_SCORE_THR} --kpt-thr ${KPT_SCORE_THR}]
@@ -91,5 +91,5 @@ Some tips to speed up MMPose inference:
 
 For top-down models, try to edit the config file. For example,
 
-1. set `flip_test=False` in [pose_hrnet_w48_dark+](/configs/wholebody_2d_keypoint/topdown_heatmap/coco-wholebody/td-hm_hrnet-w48_dark-8xb32-210e_coco-wholebody-384x288.py#L90).
+1. set `model.test_cfg.flip_test=False` in [pose_hrnet_w48_dark+](/configs/wholebody_2d_keypoint/topdown_heatmap/coco-wholebody/td-hm_hrnet-w48_dark-8xb32-210e_coco-wholebody-384x288.py#L90).
 2. use faster human bounding box detector, see [MMDetection](https://mmdetection.readthedocs.io/en/latest/model_zoo.html).
diff --git a/demo/topdown_demo_with_mmdet.py b/demo/topdown_demo_with_mmdet.py
@@ -161,6 +161,7 @@ def main():
     elif input_type == 'video':
         tmp_folder = tempfile.TemporaryDirectory()
         video = mmcv.VideoReader(args.input)
+        progressbar = mmengine.ProgressBar(len(video))
         video.cvt2frames(tmp_folder.name, show_progress=False)
         output_root = args.output_root
         args.output_root = tmp_folder.name
@@ -172,6 +173,7 @@ def main():
                 pose_estimator,
                 visualizer,
                 show_interval=1)
+            progressbar.update()
         if output_root:
             mmcv.frames2video(
                 tmp_folder.name,
diff --git a/docs/en/installation.md b/docs/en/installation.md
@@ -3,6 +3,7 @@
 - [Prerequisites](#prerequisites)
 - [Installation](#installation)
   - [Best Practices](#best-practices)
+  - [Verify the installation](#verify-the-installation)
   - [Customize Installation](#customize-installation)
     - [CUDA versions](#cuda-versions)
     - [Install MMEngine without MIM](#install-mmengine-without-mim)
@@ -60,15 +61,15 @@ We recommend that users follow our best practices to install MMPose. However, th
 ```shell
 pip install -U openmim
 mim install mmengine
-mim install mmcv>=2.0.0rc1
+mim install "mmcv>=2.0.0rc1"
 ```
 
 **Step 1.** Install MMPose.
 
 Case a: If you develop and run mmpose directly, install it from source:
 
 ```shell
-git clone https://github.com/open-mmlab/mmpose.git -d dev-1.x
+git clone https://github.com/open-mmlab/mmpose.git -b dev-1.x
 # "-b dev-1.x" means checkout to the `dev-1.x` branch.
 cd mmpose
 pip install -r requirements.txt
@@ -81,9 +82,13 @@ pip install -v -e .
 Case b: If you use mmpose as a dependency or third-party package, install it with pip:
 
 ```shell
-mim install mmpose>=1.0.0rc0
+mim install "mmpose>=1.0.0b0"
 ```
 
+### Verify the installation
+
+To verify that MMPose is installed correctly, you can run an inference demo according to this [guide](/demo/docs/2d_human_pose_demo.md).
+
 ### Customize Installation
 
 #### CUDA versions
@@ -135,7 +140,7 @@ thus we only need to install MMEngine, MMCV and MMPose with the following comman
 ```shell
 !pip3 install openmim
 !mim install mmengine
-!mim install mmcv>=2.0.0rc1
+!mim install "mmcv>=2.0.0rc1"
 ```
 
 **Step 2.** Install MMPose from the source.
diff --git a/docs/en/migration.md b/docs/en/migration.md
@@ -261,10 +261,8 @@ Commonly used transforms are defined in `$MMPOSE/mmpose/datasets/transforms/comm
 
 For top-down methods, `Shift`, `Rotate`and `Resize` are implemented by `RandomBBoxTransform`**.** For bottom-up methods, `BottomupRandomAffine` is used.
 
-Most data transforms depend on `bbox_center` and `bbox_scale`, which can be obtained by `GetBBoxCenterScale`.
-
 ```{note}
-All transforms in this part will only generate the **transformation matrix** and **will not** perform the actual transformation on the input data.
+Most data transforms depend on `bbox_center` and `bbox_scale`, which can be obtained by `GetBBoxCenterScale`.
 ```
 
 #### ii. Transformation
@@ -579,6 +577,8 @@ def loss(self,
 
 MMPose 1.0 has been refactored extensively and addressed many legacy issues. Most of the code in MMPose 1.0 will not be compatible with 0.x version.
 
+To try our best to help you migrate your code and model, here are some major changes:
+
 ### Data Transformation
 
 #### Translation, Rotation and Scaling
diff --git a/docs/en/notes/benchmark.md b/docs/en/notes/benchmark.md
@@ -0,0 +1,46 @@
+# Benchmark
+
+We compare our results with some popular frameworks and official releases in terms of speed and accuracy.
+
+## Comparison Rules
+
+Here we compare our MMPose repo with other pose estimation toolboxes in the same data and model settings.
+
+To ensure the fairness of the comparison, the comparison experiments were conducted under the same hardware environment and using the same dataset.
+For each model setting, we kept the same data pre-processing methods to make sure the same feature input.
+In addition, we also used Memcached, a distributed memory-caching system, to load the data in all the compared toolboxes.
+This minimizes the IO time during benchmark.
+
+The time we measured is the average training time for an iteration, including data processing and model training.
+The training speed is measure with s/iter. The lower, the better.
+
+### Results on COCO val2017 with detector having human AP of 56.4 on COCO val2017 dataset
+
+We demonstrate the superiority of our MMPose framework in terms of speed and accuracy on the standard COCO keypoint detection benchmark.
+The mAP (the mean average precision) is used as the evaluation metric.
+
+| Model      | Input size | MMPose (s/iter) | HRNet (s/iter) | MMPose (mAP) | HRNet (mAP) |
+| :--------- | :--------: | :-------------: | :------------: | :----------: | :---------: |
+| resnet_50  |  256x192   |    **0.28**     |      0.64      |  **0.718**   |    0.704    |
+| resnet_50  |  384x288   |    **0.81**     |      1.24      |  **0.731**   |    0.722    |
+| resnet_101 |  256x192   |    **0.36**     |      0.84      |  **0.726**   |    0.714    |
+| resnet_101 |  384x288   |    **0.79**     |      1.53      |  **0.748**   |    0.736    |
+| resnet_152 |  256x192   |    **0.49**     |      1.00      |  **0.735**   |    0.720    |
+| resnet_152 |  384x288   |    **0.96**     |      1.65      |  **0.750**   |    0.743    |
+| hrnet_w32  |  256x192   |    **0.54**     |      1.31      |  **0.746**   |    0.744    |
+| hrnet_w32  |  384x288   |    **0.76**     |      2.00      |  **0.760**   |    0.758    |
+| hrnet_w48  |  256x192   |    **0.66**     |      1.55      |  **0.756**   |    0.751    |
+| hrnet_w48  |  384x288   |    **1.23**     |      2.20      |  **0.767**   |    0.763    |
+
+## Hardware
+
+- 8 NVIDIA Tesla V100 (32G) GPUs
+- Intel(R) Xeon(R) Gold 6148 CPU @ 2.40GHz
+
+## Software Environment
+
+- Python 3.7
+- PyTorch 1.4
+- CUDA 10.1
+- CUDNN 7.6.03
+- NCCL 2.4.08
diff --git a/docs/en/notes/changelog.md b/docs/en/notes/changelog.md
@@ -4,9 +4,7 @@
 
 We are excited to announce the release of MMPose 1.0.0beta.
 MMPose 1.0.0beta is the first version of MMPose 1.x, a part of the OpenMMLab 2.x projects.
-Built upon the new [training engine](https://github.com/open-mmlab/mmengine),
-MMPose 1.x unifies the interfaces of dataset, models, evaluation, and visualization with faster training and testing speed.
-It also provide a general semi-supervised object detection framework, and more strong baselines.
+Built upon the new [training engine](https://github.com/open-mmlab/mmengine).
 
 **Highlights**
 
diff --git a/docs/zh_cn/faq.md b/docs/zh_cn/faq.md
@@ -0,0 +1,3 @@
+# 常见问题
+
+内容建设中……
diff --git a/docs/zh_cn/getting_started.md b/docs/zh_cn/getting_started.md
diff --git a/docs/zh_cn/stats.py b/docs/zh_cn/stats.py
diff --git a/docs/zh_cn/useful_tools.md b/docs/zh_cn/useful_tools.md
