mirror of https://github.com/open-mmlab/mmpose
191 lines
6.4 KiB
Markdown
191 lines
6.4 KiB
Markdown
# Quick Run
|
||
|
||
This page provides a basic tutorial about the usage of MMPose.
|
||
|
||
We will walk you through the 7 key steps of a typical MMPose workflow by training a top-down residual log-likelihood algorithm based on resnet50 on COCO dataset:
|
||
|
||
1. Inference with a pretrained model
|
||
2. Prepare the dataset
|
||
3. Prepare a config
|
||
4. Browse the transformed images
|
||
5. Training
|
||
6. Testing
|
||
7. Visualization
|
||
|
||
## Installation
|
||
|
||
For installation instructions, please refer to [Installation](./installation.md).
|
||
|
||
## Get Started
|
||
|
||
### Inference with a pretrained model
|
||
|
||
We provide a useful script to perform pose estimation with a pretrained model:
|
||
|
||
```Bash
|
||
python demo/image_demo.py \
|
||
tests/data/coco/000000000785.jpg \
|
||
configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py \
|
||
https://download.openmmlab.com/mmpose/top_down/deeppose/deeppose_res50_coco_256x192_rle-2ea9bb4a_20220616.pth
|
||
```
|
||
|
||
If MMPose is properly installed, you will get the visualized result as follows:
|
||
|
||
|
||
|
||
```{note}
|
||
More demo and full instructions can be found in [Inference](./user_guides/inference.md).
|
||
```
|
||
|
||
### Prepare the dataset
|
||
|
||
MMPose supports multiple tasks. We provide the corresponding guidelines for data preparation.
|
||
|
||
- [2D Body Keypoint Detection](./dataset_zoo/2d_body_keypoint.md)
|
||
|
||
- [3D Body Keypoint Detection](./dataset_zoo/3d_body_keypoint.md)
|
||
|
||
- [2D Hand Keypoint Detection](./dataset_zoo/2d_hand_keypoint.md)
|
||
|
||
- [3D Hand Keypoint Detection](./dataset_zoo/3d_hand_keypoint.md)
|
||
|
||
- [2D Face Keypoint Detection](./dataset_zoo/2d_face_keypoint.md)
|
||
|
||
- [2D WholeBody Keypoint Detection](./dataset_zoo/2d_wholebody_keypoint.md)
|
||
|
||
- [2D Fashion Landmark Detection](./dataset_zoo/2d_fashion_landmark.md)
|
||
|
||
- [2D Animal Keypoint Detection](./dataset_zoo/2d_animal_keypoint.md)
|
||
|
||
You can refer to \[2D Body Keypoint Detection\] > \[COCO\] for COCO dataset preparation.
|
||
|
||
```{note}
|
||
In MMPose, we suggest placing the data under `$MMPOSE/data`.
|
||
```
|
||
|
||
### Prepare a config
|
||
|
||
MMPose is equipped with a powerful config system to conduct various experiments conveniently. A config file organizes the settings of:
|
||
|
||
- **General**: basic configurations non-related to training or testing, such as Timer, Logger, Visualizer and other Hooks, as well as distributed-related environment settings
|
||
|
||
- **Data**: dataset, dataloader and data augmentation
|
||
|
||
- **Training**: resume, weights loading, optimizer, learning rate scheduling, epochs and valid interval etc.
|
||
|
||
- **Model**: structure, module and loss function etc.
|
||
|
||
- **Evaluation**: metrics
|
||
|
||
We provide a bunch of well-prepared configs under `$MMPOSE/configs` so that you can directly use or modify.
|
||
|
||
Going back to our example, we will use the prepared config:
|
||
|
||
```Bash
|
||
$MMPOSE/configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py
|
||
```
|
||
|
||
You can set the path of the COCO dataset by modifying `data_root` in the config：
|
||
|
||
```Python
|
||
data_root = 'data/coco'
|
||
```
|
||
|
||
```{note}
|
||
If you wish to learn more about our config system, please refer to [Configs](./user_guides/configs.md).
|
||
```
|
||
|
||
### Browse the transformed images
|
||
|
||
Before training, we can browse the transformed training data to check if the images are augmented properly:
|
||
|
||
```Bash
|
||
python tools/misc/browse_dastaset.py \
|
||
configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py \
|
||
--mode transformed
|
||
```
|
||
|
||
|
||
|
||
### Training
|
||
|
||
Use the following command to train with a single GPU:
|
||
|
||
```Bash
|
||
python tools/train.py configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py
|
||
```
|
||
|
||
```{note}
|
||
MMPose automates many useful training tricks and functions including:
|
||
|
||
- Learning rate warmup and scheduling
|
||
|
||
- ImageNet pretrained models
|
||
|
||
- Automatic learning rate scaling
|
||
|
||
- Multi-GPU and Multi-Node training support
|
||
|
||
- Various Data backend support, e.g. HardDisk, LMDB, Petrel, HTTP etc.
|
||
|
||
- Mixed precision training support
|
||
|
||
- TensorBoard
|
||
```
|
||
|
||
### Testing
|
||
|
||
Checkpoints and logs will be saved under `$MMPOSE/work_dirs` by default. The best model is under `$MMPOSE/work_dir/best_coco`.
|
||
|
||
Use the following command to evaluate the model on COCO dataset:
|
||
|
||
```Bash
|
||
python tools/test.py \
|
||
configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py \
|
||
work_dir/best_coco/AP_epoch_20.pth
|
||
```
|
||
|
||
Here is an example of evaluation results：
|
||
|
||
```Bash
|
||
Average Precision (AP) @[ IoU=0.50:0.95 | area= all | maxDets= 20 ] = 0.704
|
||
Average Precision (AP) @[ IoU=0.50 | area= all | maxDets= 20 ] = 0.883
|
||
Average Precision (AP) @[ IoU=0.75 | area= all | maxDets= 20 ] = 0.777
|
||
Average Precision (AP) @[ IoU=0.50:0.95 | area=medium | maxDets= 20 ] = 0.667
|
||
Average Precision (AP) @[ IoU=0.50:0.95 | area= large | maxDets= 20 ] = 0.769
|
||
Average Recall (AR) @[ IoU=0.50:0.95 | area= all | maxDets= 20 ] = 0.751
|
||
Average Recall (AR) @[ IoU=0.50 | area= all | maxDets= 20 ] = 0.920
|
||
Average Recall (AR) @[ IoU=0.75 | area= all | maxDets= 20 ] = 0.815
|
||
Average Recall (AR) @[ IoU=0.50:0.95 | area=medium | maxDets= 20 ] = 0.709
|
||
Average Recall (AR) @[ IoU=0.50:0.95 | area= large | maxDets= 20 ] = 0.811
|
||
08/23 12:04:42 - mmengine - INFO - Epoch(test) [3254/3254] coco/AP: 0.704168 coco/AP .5: 0.883134 coco/AP .75: 0.777015 coco/AP (M): 0.667207 coco/AP (L): 0.768644 coco/AR: 0.750913 coco/AR .5: 0.919710 coco/AR .75: 0.815334 coco/AR (M): 0.709232 coco/AR (L): 0.811334
|
||
```
|
||
|
||
```{note}
|
||
If you want to perform evaluation on other datasets, please refer to [Train & Test](./user_guides/train_and_test.md).
|
||
```
|
||
|
||
### Visualization
|
||
|
||
In addition to the visualization of the keypoint skeleton, MMPose also supports the visualization of Heatmaps by setting `output_heatmap=True` in confg:
|
||
|
||
```Python
|
||
model = dict(
|
||
## omitted
|
||
test_cfg = dict(
|
||
## omitted
|
||
output_heatmaps=True
|
||
)
|
||
)
|
||
```
|
||
|
||
or add `--cfg-options='model.test_cfg.output_heatmaps=True'` at the end of your command.
|
||
|
||
Visualization result (top: decoded keypoints; bottom: predicted heatmap):
|
||
|
||
|
||
|
||
```{note}
|
||
If you wish to apply MMPose to your own projects, we have prepared a detailed [Migration guide](./migration.md).
|
||
```
|