Merge pull request #2 from PaddlePaddle/develop

mergepaddleocr

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/android_demo.md

+# Android Demo 快速测试
+
+
+### 1. 安装最新版本的Android Studio
+
+可以从 https://developer.android.com/studio 下载。本Demo使用是4.0版本Android Studio编写。
+
+### 2. 创建新项目
+
+Demo测试的时候使用的是NDK 20b版本，20版本以上均可以支持编译成功。
+
+如果您是初学者，可以用以下方式安装和测试NDK编译环境。
+点击 File -> New ->New Project，  新建  "Native C++" project
+
+
+1. Start a new Android Studio project
+    在项目模版中选择 Native C++ 选择PaddleOCR/depoly/android_demo 路径
+    进入项目后会自动编译，第一次编译会花费较长的时间，建议添加代理加速下载。
+
+**代理添加：**
+
+选择 Android Studio -> Perferences -> Appearance & Behavior -> System Settings -> HTTP Proxy -> Manual proxy configuration
+
+![](../demo/proxy.png)
+
+2. 开始编译
+
+点击编译按钮，连接手机，跟着Android Studio的引导完成操作。
+
+在 Android Studio 里看到下图，表示编译完成：
+
+![](../demo/build.png)
+
+**提示:** 此时如果出现下列找不到OpenCV的报错信息，请重新点击编译，编译完成后退出项目，再次进入。
+
+![](../demo/error.png)
+
+### 3. 发送到手机端
+
+完成编译，点击运行，在手机端查看效果。
+
+### 4. 如何自定义demo图片
+
+1. 图片存放路径:android_demo/app/src/main/assets/images
+
+   将自定义图片放置在该路径下
+
+2. 配置文件: android_demo/app/src/main/res/values/strings.xml
+
+   修改 IMAGE_PATH_DEFAULT 为自定义图片名即可
+
+
+# 获得更多支持
+前往[端计算模型生成平台EasyEdge](https://ai.baidu.com/easyedge/app/open_source_demo?referrerUrl=paddlelite)，获得更多开发支持：
+
+- Demo APP：可使用手机扫码安装，方便手机端快速体验文字识别
+- SDK：模型被封装为适配不同芯片硬件和操作系统SDK，包括完善的接口，方便进行二次开发

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/doc_ch/config.md

+# 可选参数列表
+
+以下列表可以通过`--help`查看
+
+|         FLAG             |     支持脚本    |        用途        |      默认值       |         备注         |
+| :----------------------: | :------------: | :---------------: | :--------------: | :-----------------: |
+|          -c              |      ALL       |  指定配置文件  |  None  |  **配置模块说明请参考 参数介绍** |
+|          -o              |      ALL       |  设置配置文件里的参数内容  |  None  |  使用-o配置相较于-c选择的配置文件具有更高的优先级。例如：`-o Global.use_gpu=false`  |  
+
+
+## 配置文件 Global 参数介绍
+
+以 `rec_chinese_lite_train.yml` 为例
+
+
+|         字段             |            用途                |      默认值       |            备注            |
+| :----------------------: |  :---------------------:   | :--------------:  |   :--------------------:   |
+|      algorithm           |    设置算法                    |  与配置文件同步   |     选择模型，支持模型请参考[简介](https://github.com/PaddlePaddle/PaddleOCR/blob/develop/README.md) |
+|      use_gpu             |    设置代码运行场所            |       true        |                \                 |
+|      epoch_num           |    最大训练epoch数             |       3000        |                \                 |
+|      log_smooth_window   |    滑动窗口大小            |       20          |                \                 |
+|      print_batch_step    |    设置打印log间隔         |       10          |                \                 |
+|      save_model_dir      |    设置模型保存路径        |  output/{算法名称}  |                \                 |
+|      save_epoch_step     |    设置模型保存间隔        |       3           |                \                 |
+|      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]    |                \                 |
+|      max_text_length     |    设置文本最大长度        |       25          |                \                 |
+|      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        |    用于中断后加载参数继续训练 |
+|      save_inference_dir  |    inference model 保存路径 |          None        |    用于保存inference model |
+
+## 配置文件 Reader 系列参数介绍
+
+以 `rec_chinese_reader.yml` 为例
+
+|         字段             |            用途                |      默认值       |            备注            |
+| :----------------------: |  :---------------------:   | :--------------:  |   :--------------------:   |
+|      reader_function     |    选择数据读取方式        |  ppocr.data.rec.dataset_traversal,SimpleReader  | 支持SimpleReader / LMDBReader 两种数据读取方式 |
+|      num_workers             |    设置数据读取线程数            |       8        |                \                 |
+|      img_set_dir          |    数据集路径             |       ./train_data        |                \                 |
+|      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与piecewise_decay  |
+|      step_each_epoch    |      每个epoch包含多少次迭代, cosine_decay时有效   |         20       | 计算方式：total_image_num / (batch_size_per_card * card_size) |
+|        total_epoch      |    总共迭代多少个epoch, cosine_decay时有效        |       1000      | 与Global.epoch_num 一致        |
+|        boundaries      |    学习率下降时的迭代次数间隔, piecewise_decay时有效       |       -      | 参数为列表形式        |
+|        decay_rate      |    学习率衰减系数, piecewise_decay时有效       |       -      |  \        |

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/)