MindOCR

简介

MindOCR是一个基于MindSpore 框架开发的OCR开源工具箱，集成系列主流文字检测识别的算法、模型，并提供易用的训练和推理工具，可以帮助用户快速开发和应用业界SoTA文本检测、文本识别模型，如DBNet/DBNet++和CRNN/SVTR，满足图像文档理解的需求。

安装教程

pip install -r requirements.txt

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

pip install mindocr

快速开始

1. 文字检测和识别示例

安装完MindOCR后，我们就很方便地进行任意图像的文本检测和识别，如下。

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

运行结束后，结果将被默认保存在./inference_results路径，可视化结果如下：

文本检测、识别结果可视化

可以看到图像中的文字块均被检测出来并正确识别。更详细的用法介绍，请参考推理教程。

2. 模型训练与评估-快速指南

使用tools/train.py脚本可以很容易地训练OCR模型，该脚本可支持文本检测和识别模型训练。

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

--config 参数用于指定yaml文件的路径，该文件定义要训练的模型和训练策略，包括数据处理流程、优化器、学习率调度器等。

MindOCR在configs文件夹中提供系列SoTA的OCR模型及其训练策略，用户可以快速将其适配到自己的任务或数据集上，参考例子如下

# 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

类似的，使用tools/eval.py 脚本可以很容易地评估已训练好的模型，如下所示：

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}

更多使用方法，请参考使用教程中的模型训练章节。

3. 模型推理-快速指南

你可以在MindOCR中对MindOCR自研模型或第三方模型（如PaddleOCR、MMOCR等）进行MindSpore Lite推理。 请见MindOCR自研模型推理-快速开始或第三方模型推理-快速开始。

使用教程

• 数据集
  • 数据集准备
  • 数据增强策略
• 模型训练
  • Yaml配置文件
  • 文本检测
  • 文本识别
  • 分布式训练
  • 进阶技巧：梯度累积，EMA，断点续训等
• 推理与部署
  • 基于Python/C++和昇腾310的OCR推理
  • 基于Python的OCR在线推理
• 开发者指南
  • 如何自定义数据集
  • 如何自定义数据增强方法
  • 如何创建新的OCR模型
  • 如何自定义后处理方法

模型列表

关于以上模型的具体训练方法和结果，请参见configs下各模型子目录的readme文档。

关于MindSpore Lite和ACL模型推理的支持列表， 请参见MindOCR自研模型推理支持列表 和 第三方模型推理支持列表（如PaddleOCR、MMOCR等）。

数据集列表

MindOCR提供了数据格式转换工具 ，以支持不同格式的OCR数据集，支持用户自定义的数据集。 当前已在模型训练评估中验证过的公开OCR数据集如下。

我们会在更多的数据集上进行模型训练和验证。该列表将持续更新。

重要信息

更新日志

• 2023/07/06

1. 增加新模型
   • 文本识别RobustScanner

• 2023/07/05

1. 增加新模型
   • 文本识别VISIONLAN

• 2023/06/29

1. 新增2个SoTA模型
   • 文本检测FCENet
   • 文本识别MASTER

• 2023/06/07

1. 增加新模型
   • 文本检测PSENet
   • 文本检测EAST
   • 文本识别SVTR
2. 添加更多基准数据集及其结果
   • totaltext
   • mlt2017
   • chinese_text_recognition
3. 增加断点续训(resume training)功能，可在训练意外中断时使用。如需使用，请在配置文件中model字段下增加resume参数，允许传入具体路径resume: /path/to/train_resume.ckpt或者通过设置resume: True来加载在ckpt_save_dir下保存的trian_resume.ckpt
4. 改进检测模块的后处理部分：默认情况下，将检测到的文本多边形重新缩放到原始图像空间，可以通过在eval.dataset.output_columns列表中增加"shape_list"实现。
5. 重构在线推理以支持更多模型，详情请参见README.md 。

• 2023/05/15

1. 增加新模型
   • 文本检测DBNet++
   • 文本识别CRNN-Seq2Seq
   • 在SynthText数据集上预训练的DBNet
2. 添加更多基准数据集及其结果
   • SynthText, MSRA-TD500, CTW1500
   • DBNet的更多基准结果可以在此找到.
3. 添加用于保存前k个checkpoint的checkpoint manager并改进日志。
4. Python推理代码重构。
5. Bug修复：对大型数据集使用平均损失meter，在AMP训练中对ctcloss禁用pred_cast_fp32，修复存在无效多边形的错误。

• 2023/05/04

1. 支持加载自定义的预训练checkpoint， 通过在yaml配置中将model-pretrained设置为checkpoint url或本地路径来使用。
2. 支持设置执行包括旋转和翻转在内的数据增强操作的概率。
3. 为模型训练添加EMA功能，可以通过在yaml配置中设置train-ema（默认值：False）和train-ema_decay来启用。
4. 参数修改：num_columns_to_net -> net_input_column_index: 输入网络的columns数量改为输入网络的columns索引
5. 参数修改：num_columns_of_labels -> label_column_index: 用索引替换数量，以表示label的位置。

• 2023/04/21

1. 添加参数分组以支持训练中的正则化。用法：在yaml config中添加grouping_strategy参数以选择预定义的分组策略，或使用no_weight_decay_params参数选择要从权重衰减中排除的层（例如，bias、norm）。示例可参考configs/rec/crn/crnn_icdar15.yaml
2. 添加梯度累积，支持大批量训练。用法：在yaml配置中添加gradient_accumulation_steps，全局批量大小=batch_size * devices * gradient_aaccumulation_steps。示例可参考configs/rec/crn/crnn_icdar15.yaml
3. 添加梯度裁剪，支持训练稳定。通过在yaml配置中将grad_clip设置为True来启用。

• 2023/03/23

1. 增加dynamic loss scaler支持, 且与drop overflow update兼容。如需使用, 请在配置文件中增加loss_scale字段并将type参数设为dynamic，参考例子请见configs/rec/crnn/crnn_icdar15.yaml

• 2023/03/20

1. 参数名修改：output_keys -> output_columns；num_keys_to_net -> num_columns_to_net；
2. 更新数据流程。

• 2023/03/13

1. 增加系统测试和CI工作流；
2. 增加modelarts平台适配器，使得支持在OpenI平台上训练，在OpenI平台上训练需要以下步骤：

  i)   在OpenI云平台上创建一个训练任务；
  ii)  在网页上关联数据集，如ic15_mindocr；
  iii) 增加 `config` 参数，在网页的UI界面配置yaml文件路径，如'/home/work/user-job-dir/V0001/configs/rec/test.yaml'；
  iv)  在网页的UI界面增加运行参数`enable_modelarts`并将其设置为True；
  v)   填写其他项并启动训练任务。

如何贡献

我们欢迎包括问题单和PR在内的所有贡献，来让MindOCR变得更好。

请参考CONTRIBUTING.md作为贡献指南，请按照Model Template and Guideline的指引贡献一个适配所有接口的模型，多谢合作。

许可

本项目遵从Apache License 2.0开源许可。

引用

如果本项目对您的研究有帮助，请考虑引用：

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