Home

Awesome

<div align="center" markdown>

MindCV

CI PyPI - Python Version PyPI docs license open issues PRs Code style: black Imports: isort pre-commit

📝Documentation | 🚀Installation | 🎁Model Zoo | 🎉Update News | 🐛Reporting Issues

English | 中文

</div>

Introduction

MindCV is an open-source toolbox for computer vision research and development based on MindSpore. It collects a series of classic and SoTA vision models, such as ResNet and SwinTransformer, along with their pre-trained weights and training strategies. SoTA methods such as auto augmentation are also provided for performance improvement. With the decoupled module design, it is easy to apply or adapt MindCV to your own CV tasks.

The following is the corresponding mindcv versions and supported mindspore versions.

mindcvmindspore
mainmaster
v0.4.02.3.0
0.3.02.2.10
0.22.0
0.11.8

Major Features

Model Zoo

The performance of the models trained with MindCV is summarized in here, where the training recipes and weights are both available.

Model introduction and training details can be viewed in each sub-folder under configs.

Installation

See Installation for details.

Getting Started

Hands-on Tutorial

To get started with MindCV, please see the Quick Start, which will give you a quick tour on each key component and the train/validate/predict pipelines.

Below are a few code snippets for your taste.

>>> import mindcv
# List and find a pretrained vision model
>>> mindcv.list_models("swin*", pretrained=True)
['swin_tiny']
# Create the model object
>>> network = mindcv.create_model('swin_tiny', pretrained=True)
# Validate its accuracy
python validate.py --model=swin_tiny --pretrained --dataset=imagenet --val_split=validation
# {'Top_1_Accuracy': 0.80824, 'Top_5_Accuracy': 0.94802, 'loss': 1.7331367141008378}

Image classification demo

Right click on the image below and save as dog.jpg.

<p align="left"> <img src="https://user-images.githubusercontent.com/8156835/210049681-89f68b9f-eb44-44e2-b689-4d30c93c6191.jpg" width=360 /> </p>

Classify the downloaded image with a pretrained SoTA model:

python infer.py --model=swin_tiny --image_path='./dog.jpg'
# {'Labrador retriever': 0.5700152, 'golden retriever': 0.034551315, 'kelpie': 0.010108651, 'Chesapeake Bay retriever': 0.008229004, 'Walker hound, Walker foxhound': 0.007791956}

The top-1 prediction result is labrador retriever, which is the breed of this cut dog.

Training

It is easy to train your model on a standard or customized dataset using train.py, where the training strategy (e.g., augmentation, LR scheduling) can be configured with external arguments or a yaml config file.

Graph Mode and PyNative Mode:

By default, the training pipeline train.py is run in graph mode on MindSpore, which is optimized for efficiency and parallel computing with a compiled static graph. In contrast, pynative mode is optimized for flexibility and easy debugging. You may alter the parameter --mode to switch to pure pynative mode for debugging purpose.

Mixed Mode:

PyNative mode with mindspore.jit is a mixed mode for comprising flexibility and efficiency in MindSpore. To apply pynative mode with mindspore.jit for training, please run train_with_func.py, e.g.,

python train_with_func.py --model=resnet50 --dataset=cifar10 --dataset_download  --epoch_size=10

Note: this is an experimental function under improvement. It is not stable on MindSpore 1.8.1 or earlier versions.

Validation

To evaluate the model performance, please run validate.py

# validate a trained checkpoint
python validate.py --model=resnet50 --dataset=imagenet --data_dir=/path/to/data --ckpt_path=/path/to/model.ckpt

Validation while Training

You can also track the validation accuracy during training by enabling the --val_while_train option.

python train.py --model=resnet50 --dataset=cifar10 \
    --val_while_train --val_split=test --val_interval=1

The training loss and validation accuracy for each epoch will be saved in {ckpt_save_dir}/results.log.

More examples about training and validation can be seen in examples.

Tutorials

We provide the following jupyter notebook tutorials to help users learn to use MindCV.

Model List

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

<details open markdown> <summary> Supported models </summary>

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

</details>

Supported Algorithms

<details open markdown> <summary> Supported algorithms </summary> </details>

What is New

Release 0.3.0 is published. We will drop MindSpore 1.x in the future release.

  1. New models:
  2. Features:
    • AsymmetricLoss & JSDCrossEntropy
    • Augmentations Split
    • Customized AMP
  3. Bug fixes:
    • Since the classifier weights are not fully deleted, you may encounter an error passing in the num_classes when creating a pre-trained model.
  4. Refactoring:
    • The names of many models have been refactored for better understanding.
    • Script of VisionTransformer.
    • Script of Mixed(PyNative+jit) mode training.
  5. Documentation:
    • A guide of how to extract multiscale features from backbone.
    • A guide of how to finetune the pre-trained model on a custom dataset.
  6. BREAKING CHANGES:
    • We are going to drop support of MindSpore 1.x for it's EOL.
    • Configuration filter_bias_and_bn will be removed and renamed as weight_decay_filter, due to a prolonged misunderstanding of the MindSpore optimizer. We will migrate the existing training recipes, but the signature change of function create_optimizer will be incompatible and the old version training recipes will also be incompatible. See PR/752 for details.

See RELEASE for detailed history.

How to Contribute

We appreciate all kinds of contributions including issues and PRs to make MindCV 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

MindCV is an open-source project jointly developed by the MindSpore team, Xidian University, and Xi'an Jiaotong University. 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 Computer Vision 2022,
    title={{MindSpore Computer Vision}:MindSpore Computer Vision Toolbox and Benchmark},
    author={MindSpore Vision Contributors},
    howpublished = {\url{https://github.com/mindspore-lab/mindcv/}},
    year={2022}
}