mindspore-lab / mindpose

an open-source toolbox for pose estimation based on MindSpore

MindPose

Introduction | Installation | Get Started | Tutorials | Model List | Supported Algorithms | Notes

Introduction

MindPose is an open-source toolbox for pose estimation based on MindSpore. It collects a series of classic and SoTA vision models, such as HRNet, along with their pre-trained weights and training strategies.

Major Features

• Easy-to-Use. MindPose decomposes the vision framework into various configurable components. It is easy to customize your data pipeline, models, and learning pipeline with MindPose:

>>> import mindpose
# create a model
>>> network = mindpose.create_network(backbone_name='resnet50', head_name="simple_baseline_head")

• State-of-The-Art. MindPose provides various CNN-based and Transformer-based vision models. Their pretrained weights and performance reports are provided to help users select and reuse the right model.

• Flexibility and efficiency. MindPose is built on MindSpore which is an efficent DL framework that can be run on different hardware platforms (GPU/CPU/Ascend). It supports both graph mode for high efficiency and pynative mode for flexibility.

Benchmark Results

Installation

Dependency

• mindspore >= 1.8.1
• numpy >= 1.21.6
• scipy >= 1.5.4
• pyyaml >= 5.4.1
• pycocotools >= 2.0.6
• opencv-python >=4.2.0.34, <= 4.5.4.60
• tqdm >= 4.6.1
• openmpi 4.1.2 (for distributed mode)

To install the dependency, please run

pip install -r requirements.txt

MindSpore can be easily installed by following the official instructions where you can select your hardware platform for the best fit. To run in distributed mode, openmpi is required to install.

The following instructions assume the desired dependency is fulfilled.

Install with PyPI

The released version of MindPose can be installed via PyPI as follows:

pip install mindpose

Install from Source

The latest version of MindPose can be installed as follows:

pip install git+https://github.com/mindspore-lab/mindpose.git

Notes: MindPose can be installed on Linux and Mac but not on Windows currently.

Get Started

Hands-on Tutorial

TODO

Training

It is easy to train your model on a standard or customized dataset using tools/train.py, where the training strategy is configured with a yaml config file.

• Config and Training Strategy

You can configure your model and other components by writing a yaml config file. Here is an example of training using a preset yaml file.

mpirun --allow-run-as-root -n 4 python tools/train.py --config configs/hrnet/hrnet_w32_ascend.yaml

• Train on OpenI Platform

To run training on the OpenI cloud platform:

1. Create a new training task on the cloud platform.
2. Use tools/train_on_openi.py as the starting file.
3. Add run parameter config and specify the path to the yaml config file on the website UI interface.
4. Fill in other blanks on the website and launch the training task.

Validation

To evalute the model performance, please run tools/eval.py

# validate a trained checkpoint
python tools/eval.py --config=configs/hrnet/hrnet_w32_ascend.yaml --ckpt=/path/to/model.ckpt 

Tutorials

TODO

Model List

Currently, MindPose supports the model families listed below. More models with pre-trained weights are under development and will be released soon.

Supported models

• SimpleBaseline - https://arxiv.org/abs/1804.06208
• HRNet - https://arxiv.org/abs/1908.07919
• UDP - https://arxiv.org/abs/1911.07524

Please see configs for the details about model performance and pretrained weights.

Notes

What is New

TODO

How to Contribute

We appreciate all kind of contributions including issues and PRs to make MindPose better.

Please refer to CONTRIBUTING.md for the contributing guideline. Please follow the Model Template and Guideline for contributing a model that fits the overall interface :)

License

This project follows the Apache License 2.0 open-source license.

Acknowledgement

MindPose is an open-source project jointly developed by the MindSpore team. Sincere thanks to all participating researchers and developers for their hard work on this project. We also acknowledge the computing resources provided by OpenI.

Citation

If you find this project useful in your research, please consider citing:

@misc{MindSpore Pose 2022,
    title={{MindSpore Pose}:MindSpore Pose Toolbox and Benchmark},
    author={MindSpore Vision Contributors},
    howpublished = {\url{https://github.com/mindspore-lab/mindpose/}},
    year={2022}
}