• MindOCR
• • Introduction
  • Installation
  • • • Prerequisites
      • Dependency
      • Install from Source (recommend)
      • Install from PyPI
  • Quick Start
  • • Text Detection and Recognition Demo
    • Model Training and Evaluation - Quick Guideline
  • Tutorials
  • Model List
  • Dataset List
  • Notes
  • • What is New
    • How to Contribute
    • License
    • Citation

MindOCR

English | 中文

Introduction |
Installation |
Quick Start |
Tutorials |
Model List |
Dataset List |
Notes

Introduction

MindOCR is an open-source toolbox for OCR development and application based on MindSpore, which integrates series of mainstream text detection and recognition algorihtms and models and provides easy-to-use training and inference tools. It can accelerate the process of developing and deploying SoTA text detection and recognition models in real-world applications, such as DBNet/DBNet++ and CRNN/SVTR, and help fulfill the need of image-text understanding .

Major Features

• Modular design: We decoupled the OCR task into several configurable modules. Users can setup the training and evaluation pipelines, customize the data processing pipeline and model architectures easily by modifying just few lines of code.
• High-performance: MindOCR provides a series of pretrained weights trained with optimized configurations that reach competitive performance on OCR tasks.
• Low-cost-to-apply: Easy-to-use inference tools are provided in MindOCR to perform text detection and recognition tasks.

Installation

Prerequisites

MindOCR is built on MindSpore AI framework, which supports CPU/GPU/NPU devices.
MindOCR is compatible with the following framework versions. For details and installation guideline, please refer to the installation links shown below.

• mindspore >= 1.9 [install]
• python >= 3.7
• openmpi 4.0.3 (for distributed training/evaluation) [install]
• mindspore lite (for inference) [install]

Dependency

pip install -r requirements.txt

Tips:

• If scikit_image cannot be imported, please set environment variable $LD_PRELOAD
  as follows, (related opencv issue)

  export LD_PRELOAD=path/to/scikit_image.libs/libgomp-d22c30c5.so.1.0.0:$LD_PRELOAD
  

Install from Source (recommend)

git clone https://github.com/mindspore-lab/mindocr.git
cd mindocr
pip install -e .

Using -e for "editable" mode can help resolve potential module import issues.

Install from PyPI

pip install mindocr

As this project is under active development, the version installed from PyPI is out-of-date currently. (will update soon).

Quick Start

Text Detection and Recognition Demo

After installing MindOCR, we can run text detection and recognition on an arbitrary image easily as follows.

python tools/infer/text/predict_system.py --image_dir {path_to_img or dir_to_imgs} \
                                          --det_algorithm DB++  \
                                          --rec_algorithm CRNN

After running, the results will be saved in ./inference_results by default. Here is an example result.

Visualization of text detection and recognition result

We can see that all texts on the image are detected and recognized accurately. For more usage, please refer to the inference section in tutorials.

Model Training and Evaluation - Quick Guideline

It is easy to train your OCR model with the tools/train.py script, which supports both text detection and recognition model training.

python tools/train.py --config {path/to/model_config.yaml}

The --config arg specifies the path to a yaml file that defines the model to be trained and the training strategy including data process pipeline, optimizer, lr scheduler, etc.

MindOCR provides SoTA OCR models with their training strategies in configs folder.
You may adapt it to your task/dataset, for example, by running

# train text detection model DBNet++ on icdar15 dataset
python tools/train.py --config configs/det/dbnet/db++_r50_icdar15.yaml

# train text recognition model CRNN on icdar15 dataset
python tools/train.py --config configs/rec/crnn/crnn_icdar15.yaml

Similarly, it is simple to evaluate the trained model with the tools/eval.py script.

python tools/eval.py \
    --config {path/to/model_config.yaml} \
    --opt eval.dataset_root={path/to/your_dataset} eval.ckpt_load_path={path/to/ckpt_file}

For more illustration and usage, please refer to the model training section in Tutorials.

Tutorials

• Datasets
  • Dataset Preparation
  • Data Transformation Mechanism
• Model Training
  • Yaml Configuration
  • Text Detection (coming soon)
  • Text Recognition
  • Distributed Training
  • Advance: Gradient Accumulation, EMA, Resume Training, etc
• Inference and Deployment
  • Python/C++ Inference on Ascend 310
  • Python Online Inference
• Developer Guides
  • Customize Dataset
  • Customize Data Transformation
  • Customize a New Model
  • Customize Postprocessing Method

Model List

Text Detection

• DBNet (AAAI'2020)
• DBNet++ (TPAMI'2022)
• PSENet (CVPR'2019)
• EAST(CVPR'2017)
• FCENet (CVPR'2021) [coming soon]

Text Recognition

• CRNN (TPAMI'2016)
• CRNN-Seq2Seq/RARE (CVPR'2016)
• SVTR (IJCAI'2022)
• ABINet (CVPR'2021) [coming soon]

For the detailed performance of the trained models, please refer to configs.

For detailed support for MindSpore Lite and ACL inference models, please refer to MindOCR Models Support List and Third-Party Models Support List.

Dataset List

MindOCR provides a dataset conversion tool to OCR datasets with different formats and support customized dataset by users. We have validated the following public OCR datasets in model training/evaluation.

General OCR Datasets

• ICDAR2015 [paper] [download]

• Total-Text [paper] [download]

• Syntext150k [paper] [download]

• MLT2017 [paper] [download] (multi-language)

• MSRA-TD500 [paper] [download]

• SCUT-CTW1500 [paper] [download]

• Chinese-Text-Recognition-Benchmark [paper] [download]

We will include more datasets for training and evaluation. This list will be continuously updated.

Notes

What is New

• 2023/06/07

1. Add new trained models
   • PSENet for text detection
   • EAST for text detection
   • SVTR for text recognition
2. Add more benchmark datasets and their results
   • totaltext
   • mlt2017
   • chinese_text_recognition
3. Add resume training function, which can be used in case of unexpected interruption in training. Usage: add the resume parameter under the model field in the yaml config, e.g.,resume: True, load and resume training from {ckpt_save_dir}/train_resume.ckpt or resume: /path/to/train_resume.ckpt, load and resume training from the given path.
4. Improve postprocessing for detection: re-scale detected text polygons to original image space by default,
   which can be enabled by add "shape_list" to the eval.dataset.output_columns list.
5. Refactor online inference to support more models, see README.md for details.

• 2023/05/15

1. Add new trained models
   • DBNet++ for text detection
   • CRNN-Seq2Seq for text recognition
   • DBNet pretrained on SynthText is now available: checkpoint url
2. Add more benchmark datasets and their results
   • SynthText, MSRA-TD500, CTW1500
   • More benchmark results for DBNet are reported here.
3. Add checkpoint manager for saving top-k checkpoints and improve log.
4. Python inference code refactored.
5. Bug fix: use Meter to average loss for large datasets, disable pred_cast_fp32 for ctcloss in AMP training, fix error when invalid polygons exist.

• 2023/05/04

1. Support loading self-defined pretrained checkpoints via setting model-pretrained with checkpoint url or local path in yaml.
2. Support setting probability for executing augmentation including rotation and flip.
3. Add Exponential Moving Average(EMA) for model training, which can be enabled by setting train-ema (default: False) and train-ema_decay in the yaml config.
4. Arg parameter changed：num_columns_to_net -> net_input_column_index: change the column number feeding into the network to the column index.
5. Arg parameter changed：num_columns_of_labels -> label_column_index: change the column number corresponds to the label to the column index.

• 2023/04/21

1. Add parameter grouping to support flexible regularization in training. Usage: add grouping_strategy argument in yaml config to select a predefined grouping strategy, or use no_weight_decay_params argument to pick layers to exclude from weight decay (e.g., bias, norm). Example can be referred in configs/rec/crnn/crnn_icdar15.yaml
2. Add gradient accumulation to support large batch size training. Usage: add gradient_accumulation_steps in yaml config, the global batch size = batch_size * devices * gradient_accumulation_steps. Example can be referred in configs/rec/crnn/crnn_icdar15.yaml
3. Add gradient clip to support training stablization. Enable it by setting grad_clip as True in yaml config.

• 2023/03/23

1. Add dynamic loss scaler support, compatible with drop overflow update. To enable dynamic loss scaler, please set type of loss_scale as dynamic. A YAML example can be viewed in configs/rec/crnn/crnn_icdar15.yaml

• 2023/03/20

1. Arg names changed: output_keys -> output_columns, num_keys_to_net -> num_columns_to_net
2. Data pipeline updated

• 2023/03/13

1. Add system test and CI workflow.
2. Add modelarts adapter to allow training on OpenI platform. To train on OpenI:

  i)   Create a new training task on the openi cloud platform.
  ii)  Link the dataset (e.g., ic15_mindocr) on the webpage.
  iii) Add run parameter `config` and write the yaml file path on the website UI interface, e.g., '/home/work/user-job-dir/V0001/configs/rec/test.yaml'
  iv)  Add run parameter `enable_modelarts` and set True on the website UI interface.
  v)   Fill in other blanks and launch.

How to Contribute

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

Citation

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

@misc{MindSpore OCR 2023,
    title={{MindSpore OCR }:MindSpore OCR Toolbox},
    author={MindSpore Team},
    howpublished = {\url{https://github.com/mindspore-lab/mindocr/}},
    year={2023}
}