5 Star 37 Fork 12

MindSpore Lab/mindcv

Create your Gitee Account
Explore and code with more than 13.5 million developers,Free private repositories !:)
Sign up
Clone or Download
contribute
Sync branch
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README
Apache-2.0

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.

mindcv mindspore
main master
0.5 2.5.0
0.4 2.3.0/2.3.1
0.3 2.2.10
0.2 2.0
0.1 1.8

Major Features

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

    >>> import mindcv
    # create a dataset
    >>> dataset = mindcv.create_dataset('cifar10', download=True)
    # create a model
    >>> network = mindcv.create_model('resnet50', pretrained=True)
    

    Users can customize and launch their transfer learning or training task in one command line.

    # transfer learning in one command line
    python train.py --model=swin_tiny --pretrained --opt=adamw --lr=0.001 --data_dir=/path/to/data
    
  • State-of-The-Art. MindCV provides various CNN-based and Transformer-based vision models including SwinTransformer. Their pretrained weights and performance reports are provided to help users select and reuse the right model:

  • Flexibility and efficiency. MindCV is built on MindSpore which is an efficient 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.

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.

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.

  • Standalone Training

    # standalone training
    python train.py --model=resnet50 --dataset=cifar10 --dataset_download
    

    Above is an example for training ResNet50 on CIFAR10 dataset on a CPU/GPU/Ascend device

  • Distributed Training

    For large datasets like ImageNet, it is necessary to do training in distributed mode on multiple devices. This can be achieved with msrun and parallel features supported by MindSpore.

    # distributed training
    # assume you have 4 NPUs
    msrun --bind_core=True --worker_num 4 python train.py --distribute \
        --model=densenet121 --dataset=imagenet --data_dir=/path/to/imagenet
    

    Notice that if you are using msrun startup with 2 devices, please add --bind_core=True to improve performance. For example:

    msrun --bind_core=True --worker_num=2--local_worker_num=2 --master_port=8118 \
    --log_dir=msrun_log --join=True --cluster_time_out=300 \
    python train.py --distribute --model=densenet121 --dataset=imagenet --data_dir=/path/to/imagenet
    

    For more information, please refer to https://www.mindspore.cn/docs/en/r2.5.0/model_train/parallel/startup_method.html

    Detailed parameter definitions can be seen in config.py and checked by running `python train.py --help'.

    To resume training, please set the --ckpt_path and --ckpt_save_dir arguments. The optimizer state including the learning rate of the last stopped epoch will also be recovered.

  • Config and Training Strategy

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

    msrun --bind_core=True --worker_num 4 python train.py -c configs/squeezenet/squeezenet_1.0_ascend.yaml
    

    Pre-defined Training Strategies: We provide more than 20 training recipes that achieve SoTA results on ImageNet currently. Please look into the configs folder for details. Please feel free to adapt these training strategies to your own model for performance improvement, which can be easily done by modifying the yaml file.

  • Train on ModelArts/OpenI Platform

    To run training on the ModelArts or OpenI cloud platform:

    1. Create a new training task on the cloud platform.
    2. Add run parameter `config` and specify the path to the yaml config file on the website UI interface.
    3. Add run parameter `enable_modelarts` and set True on the website UI interface.
    4. Fill in other blanks on the website and launch the training task.
    

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.

Supported models

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

Supported Algorithms

Supported algorithms
  • Augmentation
  • Optimizer
    • Adam
    • AdamW
    • Lion
    • Adan (experimental)
    • AdaGrad
    • LAMB
    • Momentum
    • RMSProp
    • SGD
    • NAdam
  • LR Scheduler
    • Warmup Cosine Decay
    • Step LR
    • Polynomial Decay
    • Exponential Decay
  • Regularization
    • Weight Decay
    • Label Smoothing
    • Stochastic Depth (depends on networks)
    • Dropout (depends on networks)
  • Loss
    • Cross Entropy (w/ class weight and auxiliary logit support)
    • Binary Cross Entropy (w/ class weight and auxiliary logit support)
    • Soft Cross Entropy Loss (automatically enabled if mixup or label smoothing is used)
    • Soft Binary Cross Entropy Loss (automatically enabled if mixup or label smoothing is used)
  • Ensemble
    • Warmup EMA (Exponential Moving Average)

What is New

  • 2024/1/17

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}
}
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About

MindSpore Computer Vision is an open source computer vision research toolbox based on MindSpore in computer vision direction. expand collapse
README
Apache-2.0
Cancel

Releases

No release

Contributors

All

Language(Optional)

Activities

can not load any more
马建仓 AI 助手
尝试更多
代码解读
代码找茬
代码优化
1
https://gitee.com/mindspore-lab/mindcv.git
git@gitee.com:mindspore-lab/mindcv.git
mindspore-lab
mindcv
mindcv
main

Search