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:
Inference with a pretrained model
Prepare the dataset
Prepare a config
Browse the transformed images
Training
Testing
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:
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
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):
Note
If you wish to apply MMPose to your own projects, we have prepared a detailed Migration guide.