Shortcuts

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.

Get Started

Inference with a pretrained model

We provide a useful script to perform pose estimation with a pretrained model:

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:

inference_demo

Note

More demo and full instructions can be found in Inference.

Prepare the dataset

MMPose supports multiple tasks. We provide the corresponding guidelines for data preparation.

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:

$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:

data_root = 'data/coco'

Note

If you wish to learn more about our config system, please refer to Configs.

Browse the transformed images

Before training, we can browse the transformed training data to check if the images are augmented properly:

python tools/misc/browse_dastaset.py \
    configs/body_2d_keypoint/topdown_regression/coco/td-reg_res50_rle-8xb64-210e_coco-256x192.py \
    --mode transformed

transformed_training_img

Training

Use the following command to train with a single GPU:

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:

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:

 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.

Visualization

In addition to the visualization of the keypoint skeleton, MMPose also supports the visualization of Heatmaps by setting output_heatmap=True in confg:

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):

vis_pred

Note

If you wish to apply MMPose to your own projects, we have prepared a detailed Migration guide.

Read the Docs v: dev-1.x
Versions
latest
0.x
dev-1.x
Downloads
epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.