Merge pull request #1 from PaddlePaddle/develop

update-2020-7-17

doc/doc_ch/FAQ.md

+## FAQ
+
+1. **预测报错：got an unexpected keyword argument 'gradient_clip'**  
+安装的paddle版本不对，目前本项目仅支持paddle1.7，近期会适配到1.8。
+
+2. **转换attention识别模型时报错：KeyError: 'predict'**  
+问题已解决，请更新到最新代码。
+
+3. **关于推理速度**  
+图片中的文字较多时，预测时间会增，可以使用--rec_batch_num设置更小预测batch num，默认值为30，可以改为10或其他数值。
+
+4. **服务部署与移动端部署**  
+预计6月中下旬会先后发布基于Serving的服务部署方案和基于Paddle Lite的移动端部署方案，欢迎持续关注。
+
+5. **自研算法发布时间**  
+自研算法SAST、SRN、End2End-PSL都将在7-8月陆续发布，敬请期待。
+
+6. **如何在Windows或Mac系统上运行**  
+PaddleOCR已完成Windows和Mac系统适配，运行时注意两点：1、在[快速安装](./installation.md)时，如果不想安装docker，可跳过第一步，直接从第二步安装paddle开始。2、inference模型下载时，如果没有安装wget，可直接点击模型链接或将链接地址复制到浏览器进行下载，并解压放置到相应目录。
+
+7. **超轻量模型和通用OCR模型的区别**  
+目前PaddleOCR开源了2个中文模型，分别是8.6M超轻量中文模型和通用中文OCR模型。两者对比信息如下：
+    - 相同点：两者使用相同的**算法**和**训练数据**；  
+    - 不同点：不同之处在于**骨干网络**和**通道参数**，超轻量模型使用MobileNetV3作为骨干网络，通用模型使用Resnet50_vd作为检测模型backbone，Resnet34_vd作为识别模型backbone，具体参数差异可对比两种模型训练的配置文件.
+
+|模型|骨干网络|检测训练配置|识别训练配置|
+|-|-|-|-|
+|8.6M超轻量中文OCR模型|MobileNetV3+MobileNetV3|det_mv3_db.yml|rec_chinese_lite_train.yml|
+|通用中文OCR模型|Resnet50_vd+Resnet34_vd|det_r50_vd_db.yml|rec_chinese_common_train.yml|
+
+8. **是否有计划开源仅识别数字或仅识别英文+数字的模型**  
+暂不计划开源仅数字、仅数字+英文、或其他小垂类专用模型。PaddleOCR开源了多种检测、识别算法供用户自定义训练，两种中文模型也是基于开源的算法库训练产出，有小垂类需求的小伙伴，可以按照教程准备好数据，选择合适的配置文件，自行训练，相信能有不错的效果。训练有任何问题欢迎提issue或在交流群提问，我们会及时解答。
+
+9. **开源模型使用的训练数据是什么，能否开源**  
+目前开源的模型，数据集和量级如下：
+    - 检测：  
+    英文数据集，ICDAR2015  
+    中文数据集，LSVT街景数据集训练数据3w张图片
+    - 识别：  
+    英文数据集，MJSynth和SynthText合成数据，数据量上千万。  
+    中文数据集，LSVT街景数据集根据真值将图crop出来，并进行位置校准，总共30w张图像。此外基于LSVT的语料，合成数据500w。  
+    
+    其中，公开数据集都是开源的，用户可自行搜索下载，也可参考[中文数据集](./datasets.md)，合成数据暂不开源，用户可使用开源合成工具自行合成，可参考的合成工具包括[text_renderer](https://github.com/Sanster/text_renderer)、[SynthText](https://github.com/ankush-me/SynthText)、[TextRecognitionDataGenerator](https://github.com/Belval/TextRecognitionDataGenerator)等。
+
+10. **使用带TPS的识别模型预测报错**  
+报错信息：Input(X) dims[3] and Input(Grid) dims[2] should be equal, but received X dimension[3](320) != Grid dimension[2](100)  
+原因：TPS模块暂时无法支持变长的输入，请设置 --rec_image_shape='3,32,100' --rec_char_type='en' 固定输入shape
+
+11. **自定义字典训练的模型，识别结果出现字典里没出现的字**  
+预测时没有设置采用的自定义字典路径。设置方法是在预测时，通过增加输入参数rec_char_dict_path来设置。
+

doc/doc_ch/benchmark.md

+# Benchmark
+
+本文给出了PaddleOCR超轻量中文模型（8.6M）在各平台的预测耗时benchmark。
+
+## 测试数据  
+- 从中文公开数据集[ICDAR2017-RCTW](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/doc/doc_ch/datasets.md#ICDAR2017-RCTW-17)中随机采样**500**张图像。  
+该集合大部分图片是通过手机摄像头在野外采集的。有些是截图。这些图片展示了各种各样的场景，包括街景、海报、菜单、室内场景和手机应用程序的截图。
+
+## 评估指标  
+在四种平台上的预测耗时指标如下：  
+
+|长边尺寸(px)|T4(s)|V100(s)|Intel至强6148(s)|骁龙855(s)|
+|-|-|-|-|-|
+|960|0.092|0.057|0.319|0.354|
+|640|0.067|0.045|0.198|0.236|
+|480|0.057|0.043|0.151|0.175| 
+
+说明： 
+- 评估耗时阶段为图像输入到结果输出的完整阶段，包括了图像的预处理和后处理。  
+- `Intel至强6148`为服务器端CPU型号，测试中使用Intel MKL-DNN 加速CPU预测速度，使用该操作需要：  
+    - 更新到飞桨latest版本：https://www.paddlepaddle.org.cn/documentation/docs/zh/install/Tables.html#whl-dev ，请根据自己环境的CUDA版本和Python版本选择相应的mkl版wheel包，如，CUDA10、Python3.7环境，应操作：
+    ```shell
+    # 获取安装包
+    wget https://paddle-wheel.bj.bcebos.com/0.0.0-gpu-cuda10-cudnn7-mkl/paddlepaddle_gpu-0.0.0-cp37-cp37m-linux_x86_64.whl
+    # 安装
+    pip3.7 install paddlepaddle_gpu-0.0.0-cp37-cp37m-linux_x86_64.whl
+    ```
+    - 预测时使用参数打开加速开关： `--enable_mkldnn True`  
+- `骁龙855`为移动端处理平台型号。  

doc/config.md → doc/doc_ch/config.md

@@ -8,7 +8,7 @@
 |          -o              |      ALL       |  设置配置文件里的参数内容  |  None  |  使用-o配置相较于-c选择的配置文件具有更高的优先级。例如：`-o Global.use_gpu=false`  |  
 
 
-## 配置文件 Global 参数介绍 
+## 配置文件 Global 参数介绍
 
 以 `rec_chinese_lite_train.yml` 为例
 
@@ -22,7 +22,7 @@
 |      print_batch_step    |    设置打印log间隔         |       10          |                \                 |
 |      save_model_dir      |    设置模型保存路径        |  output/{算法名称}  |                \                 |
 |      save_epoch_step     |    设置模型保存间隔        |       3           |                \                 |
-|      eval_batch_step     |    设置模型评估间隔        |       2000        |                \                 |
+|      eval_batch_step     |    设置模型评估间隔        | 2000 或 [1000, 2000]        | 2000 表示每2000次迭代评估一次，[1000， 2000]表示从1000次迭代开始，每2000次评估一次   |
 |train_batch_size_per_card |  设置训练时单卡batch size    |         256         |                \                 |
 | test_batch_size_per_card |  设置评估时单卡batch size    |         256         |                \                 |
 |      image_shape         |    设置输入图片尺寸        |   [3, 32, 100]    |                \                 |
@@ -30,6 +30,8 @@
 |      character_type      |    设置字符类型            |       ch          |    en/ch, en时将使用默认dict，ch时使用自定义dict|
 |      character_dict_path |    设置字典路径            |  ./ppocr/utils/ic15_dict.txt  |    \                 |
 |      loss_type           |    设置 loss 类型              |       ctc         |    支持两种loss： ctc / attention |
+|       distort            |    设置是否使用数据增强          |       false       |  设置为true时，将在训练时随机进行扰动，支持的扰动操作可阅读[img_tools.py](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/ppocr/data/rec/img_tools.py)                 |
+|       use_space_char     |    设置是否识别空格             |        false      |          仅在 character_type=ch 时支持空格                 |
 |      reader_yml          |    设置reader配置文件          |  ./configs/rec/rec_icdar15_reader.yml  |  \          |
 |      pretrain_weights    |    加载预训练模型路径      |  ./pretrain_models/CRNN/best_accuracy  |  \          |
 |      checkpoints         |    加载模型参数路径            |       None        |    用于中断后加载参数继续训练 |
@@ -47,3 +49,17 @@
 |      label_file_path      |    数据标签路径           |       ./train_data/rec_gt_train.txt| \    |
 |      infer_img            |    预测图像文件夹路径     |       ./infer_img | \|
 
+## 配置文件 Optimizer 系列参数介绍
+
+以 `rec_icdar15_train.yml` 为例
+
+|         字段             |            用途            |      默认值        |            备注             |
+| :---------------------: |  :---------------------:   | :--------------:  |   :--------------------:   |
+|         function        |         选择优化器          |  pocr.optimizer,AdamDecay  |  目前只支持Adam方式  |
+|         base_lr         |      设置初始学习率          |       0.0005      |               \             |
+|         beta1           |    设置一阶矩估计的指数衰减率  |       0.9         |               \             |
+|         beta2           |    设置二阶矩估计的指数衰减率  |     0.999         |               \             |
+|         decay           |         是否使用decay       |    \              |               \             |
+|      function(decay)    |         设置decay方式       |   cosine_decay    |       目前只支持cosin_decay  |
+|      step_each_epoch    |      每个epoch包含多少次迭代  |         20       | 计算方式：total_image_num / (batch_size_per_card * card_size) |
+|        total_epoch      |    总共迭代多少个epoch        |       1000      | 与Global.epoch_num 一致        |

doc/doc_ch/customize.md

+# 如何生产自定义超轻量模型？
+
+生产自定义的超轻量模型可分为三步：训练文本检测模型、训练文本识别模型、模型串联预测。
+
+## step1：训练文本检测模型
+
+PaddleOCR提供了EAST、DB两种文本检测算法，均支持MobileNetV3、ResNet50_vd两种骨干网络，根据需要选择相应的配置文件，启动训练。例如，训练使用MobileNetV3作为骨干网络的DB检测模型（即超轻量模型使用的配置）：
+```
+python3 tools/train.py -c configs/det/det_mv3_db.yml
+```
+更详细的数据准备和训练教程参考文档教程中[文本检测模型训练/评估/预测](./detection.md)。
+
+## step2：训练文本识别模型
+
+PaddleOCR提供了CRNN、Rosetta、STAR-Net、RARE四种文本识别算法，均支持MobileNetV3、ResNet34_vd两种骨干网络，根据需要选择相应的配置文件，启动训练。例如，训练使用MobileNetV3作为骨干网络的CRNN识别模型（即超轻量模型使用的配置）：
+```
+python3 tools/train.py -c configs/rec/rec_chinese_lite_train.yml
+```
+更详细的数据准备和训练教程参考文档教程中[文本识别模型训练/评估/预测](./recognition.md)。
+
+## step3：模型串联预测
+
+PaddleOCR提供了检测和识别模型的串联工具，可以将训练好的任一检测模型和任一识别模型串联成两阶段的文本识别系统。输入图像经过文本检测、检测框矫正、文本识别、得分过滤四个主要阶段输出文本位置和识别结果，同时可选择对结果进行可视化。
+
+在执行预测时，需要通过参数image_dir指定单张图像或者图像集合的路径、参数det_model_dir指定检测inference模型的路径和参数rec_model_dir指定识别inference模型的路径。可视化识别结果默认保存到 ./inference_results 文件夹里面。
+
+```
+python3 tools/infer/predict_system.py --image_dir="./doc/imgs/11.jpg" --det_model_dir="./inference/det/"  --rec_model_dir="./inference/rec/"
+```
+更多的文本检测、识别串联推理使用方式请参考文档教程中的[基于预测引擎推理](./inference.md)。

doc/doc_ch/data_annotation.md

+## 数据标注工具
+这里整理了常用的数据标注工具，持续更新中，欢迎各位小伙伴贡献工具～
+
+
+### 1. labelImg
+- 工具描述：矩形标注
+- 工具地址：https://github.com/tzutalin/labelImg
+- 示意图：  
+    ![](../datasets/labelimg.jpg)  
+
+### 2. roLabelImg
+- 工具描述：基于labelImg重写的标注工具，支持旋转矩形标注
+- 工具地址：https://github.com/cgvict/roLabelImg
+- 示意图：  
+    ![](../datasets/roLabelImg.png)  
+
+### 3. labelme
+- 工具描述：支持四点、多边形、圆形等多种标注
+- 工具地址：https://github.com/wkentaro/labelme
+- 示意图：  
+    ![](../datasets/labelme.jpg)  

doc/doc_ch/data_synthesis.md

+## 数据合成工具
+除了开源数据，用户还可使用合成工具自行合成。这里整理了常用的数据合成工具，持续更新中，欢迎各位小伙伴贡献工具～
+- [text_renderer](https://github.com/Sanster/text_renderer)
+- [SynthText](https://github.com/ankush-me/SynthText)
+- [SynthText_Chinese_version](https://github.com/JarveeLee/SynthText_Chinese_version)
+- [TextRecognitionDataGenerator](https://github.com/Belval/TextRecognitionDataGenerator)
+- [SynthText3D](https://github.com/MhLiao/SynthText3D)
+- [UnrealText](https://github.com/Jyouhou/UnrealText/)

doc/doc_ch/datasets.md

+## 通用中英文OCR数据集
+这里整理了常用中文数据集，持续更新中，欢迎各位小伙伴贡献数据集～
+- [ICDAR2019-LSVT](#ICDAR2019-LSVT)
+- [ICDAR2017-RCTW-17](#ICDAR2017-RCTW-17)
+- [中文街景文字识别](#中文街景文字识别)
+- [中文文档文字识别](#中文文档文字识别)
+- [ICDAR2019-ArT](#ICDAR2019-ArT)
+
+除了开源数据，用户还可使用合成工具自行合成，可参考[数据合成工具](./data_synthesis.md)；
+
+如果需要标注自己的数据，可参考[数据标注工具](./data_annotation.md)。  
+
+<a name="ICDAR2019-LSVT"></a>
+#### 1、ICDAR2019-LSVT
+- **数据来源**：https://ai.baidu.com/broad/introduction?dataset=lsvt
+- **数据简介**： 共45w中文街景图像，包含5w（2w测试+3w训练）全标注数据（文本坐标+文本内容），40w弱标注数据（仅文本内容），如下图所示：  
+    ![](../datasets/LSVT_1.jpg)  
+    (a) 全标注数据  
+    ![](../datasets/LSVT_2.jpg)  
+    (b) 弱标注数据  
+- **下载地址**：https://ai.baidu.com/broad/download?dataset=lsvt
+- **说明**：其中，test数据集的label目前没有开源，如要评估结果，可以去官网提交：https://rrc.cvc.uab.es/?ch=16
+
+<a name="ICDAR2017-RCTW-17"></a>
+#### 2、ICDAR2017-RCTW-17
+- **数据来源**：https://rctw.vlrlab.net/
+- **数据简介**：共包含12,000+图像，大部分图片是通过手机摄像头在野外采集的。有些是截图。这些图片展示了各种各样的场景，包括街景、海报、菜单、室内场景和手机应用程序的截图。
+    ![](../datasets/rctw.jpg)
+- **下载地址**：https://rctw.vlrlab.net/dataset/
+
+<a name="中文街景文字识别"></a>
+#### 3、中文街景文字识别 
+- **数据来源**：https://aistudio.baidu.com/aistudio/competition/detail/8
+- **数据简介**：ICDAR2019-LSVT行识别任务，共包括29万张图片，其中21万张图片作为训练集（带标注），8万张作为测试集（无标注）。数据集采自中国街景，并由街景图片中的文字行区域（例如店铺标牌、地标等等）截取出来而形成。所有图像都经过一些预处理，将文字区域利用仿射变化，等比映射为一张高为48像素的图片，如图所示：  
+    ![](../datasets/ch_street_rec_1.png)  
+    (a) 标注：魅派集成吊顶  
+    ![](../datasets/ch_street_rec_2.png)  
+    (b) 标注：母婴用品连锁  
+- **下载地址**
+https://aistudio.baidu.com/aistudio/datasetdetail/8429
+
+<a name="中文文档文字识别"></a>
+#### 4、中文文档文字识别
+- **数据来源**：https://github.com/YCG09/chinese_ocr  
+- **数据简介**：  
+    - 共约364万张图片，按照99:1划分成训练集和验证集。
+    - 数据利用中文语料库（新闻 + 文言文），通过字体、大小、灰度、模糊、透视、拉伸等变化随机生成
+    - 包含汉字、英文字母、数字和标点共5990个字符（字符集合：https://github.com/YCG09/chinese_ocr/blob/master/train/char_std_5990.txt ）
+    - 每个样本固定10个字符，字符随机截取自语料库中的句子
+    - 图片分辨率统一为280x32  
+    ![](../datasets/ch_doc1.jpg)  
+    ![](../datasets/ch_doc2.jpg)  
+    ![](../datasets/ch_doc3.jpg)  
+- **下载地址**：https://pan.baidu.com/s/1QkI7kjah8SPHwOQ40rS1Pw (密码：lu7m)
+
+<a name="ICDAR2019-ArT"></a>
+#### 5、ICDAR2019-ArT
+- **数据来源**：https://ai.baidu.com/broad/introduction?dataset=art
+- **数据简介**：共包含10,166张图像，训练集5603图，测试集4563图。由Total-Text、SCUT-CTW1500、Baidu Curved Scene Text (ICDAR2019-LSVT部分弯曲数据) 三部分组成，包含水平、多方向和弯曲等多种形状的文本。
+    ![](../datasets/ArT.jpg)
+- **下载地址**：https://ai.baidu.com/broad/download?dataset=art
+
+## 参考文献
+**ICDAR 2019-LSVT Challenge**
+```
+@article{sun2019icdar,
+  title={ICDAR 2019 Competition on Large-scale Street View Text with Partial Labeling--RRC-LSVT},
+  author={Sun, Yipeng and Ni, Zihan and Chng, Chee-Kheng and Liu, Yuliang and Luo, Canjie and Ng, Chun Chet and Han, Junyu and Ding, Errui and Liu, Jingtuo and Karatzas, Dimosthenis and others},
+  journal={arXiv preprint arXiv:1909.07741},
+  year={2019}
+}
+```
+
+**ICDAR 2019-ArT Challenge**
+```
+@article{chng2019icdar2019,
+  title={ICDAR2019 Robust Reading Challenge on Arbitrary-Shaped Text (RRC-ArT)},
+  author={Chng, Chee-Kheng and Liu, Yuliang and Sun, Yipeng and Ng, Chun Chet and Luo, Canjie and Ni, Zihan and Fang, ChuanMing and Zhang, Shuaitao and Han, Junyu and Ding, Errui and others},
+  journal={arXiv preprint arXiv:1909.07145},
+  year={2019}
+}
+```