update doc for rec and training, ch

configs/rec/rec_icdar15_train.yml

@@ -14,8 +14,8 @@ Global:
   use_visualdl: False
   infer_img: doc/imgs_words_en/word_10.png
   # for data or label process
-  character_dict_path: ppocr/utils/ic15_dict.txt
-  character_type: ch
+  character_dict_path: ppocr/utils/en_dict.txt
+  character_type: EN
   max_text_length: 25
   infer_mode: False
   use_space_char: False

doc/doc_ch/config.md

@@ -128,4 +128,77 @@
 
 ## 3. 多语言配置文件生成
 
-【参考识别模型训练补充内容】
+PaddleOCR目前已支持80种（除中文外）语种识别，`configs/rec/multi_languages` 路径下提供了一个多语言的配置文件模版: [rec_multi_language_lite_train.yml](../../configs/rec/multi_language/rec_multi_language_lite_train.yml)。
+
+您有两种方式创建所需的配置文件：
+
+1. 通过脚本自动生成
+
+[generate_multi_language_configs.py](../../configs/rec/multi_language/generate_multi_language_configs.py) 可以帮助您生成多语言模型的配置文件
+
+- 以意大利语为例，如果您的数据是按如下格式准备的：
+    ```
+    |-train_data
+        |- it_train.txt # 训练集标签
+        |- it_val.txt # 验证集标签
+        |- data
+            |- word_001.jpg
+            |- word_002.jpg
+            |- word_003.jpg
+            | ...
+    ```
+
+    可以使用默认参数，生成配置文件：
+
+    ```bash
+    # 该代码需要在指定目录运行
+    cd PaddleOCR/configs/rec/multi_language/
+    # 通过-l或者--language参数设置需要生成的语种的配置文件，该命令会将默认参数写入配置文件
+    python3 generate_multi_language_configs.py -l it
+    ```
+
+- 如果您的数据放置在其他位置，或希望使用自己的字典，可以通过指定相关参数来生成配置文件:
+
+    ```bash
+    # -l或者--language字段是必须的
+    # --train修改训练集，--val修改验证集，--data_dir修改数据集目录，--dict修改字典路径， -o修改对应默认参数
+    cd PaddleOCR/configs/rec/multi_language/
+    python3 generate_multi_language_configs.py -l it \  # 语种
+    --train {path/of/train_label.txt} \ # 训练标签文件的路径
+    --val {path/of/val_label.txt} \     # 验证集标签文件的路径
+    --data_dir {train_data/path} \      # 训练数据的根目录
+    --dict {path/of/dict} \             # 字典文件路径
+    -o Global.use_gpu=False             # 是否使用gpu
+    ...
+
+    ```
+
+意大利文由拉丁字母组成，因此执行完命令后会得到名为 rec_latin_lite_train.yml 的配置文件。
+
+2. 手动修改配置文件
+
+   您也可以手动修改模版中的以下几个字段得到配置文件:
+
+   ```
+    Global:
+      use_gpu: True
+      epoch_num: 500
+      ...
+      character_type: it  # 需要识别的语种
+      character_dict_path:  {path/of/dict} # 字典文件所在路径
+
+   Train:
+      dataset:
+        name: SimpleDataSet
+        data_dir: train_data/ # 数据存放根目录
+        label_file_list: ["./train_data/train_list.txt"] # 训练集label路径
+      ...
+
+   Eval:
+      dataset:
+        name: SimpleDataSet
+        data_dir: train_data/ # 数据存放根目录
+        label_file_list: ["./train_data/val_list.txt"] # 验证集label路径
+      ...
+
+   ```

doc/doc_ch/recognition.md

 ## 文字识别
 
+本文提供了PaddleOCR文本识别任务的全流程指南，包括数据准备、模型训练、调优、评估、预测，各个阶段的详细说明：
 
 - [1 数据准备](#数据准备)
     - [1.1 自定义数据集](#自定义数据集)
@@ -9,13 +10,12 @@
 
 - [2 启动训练](#启动训练)
     - [2.1 数据增强](#数据增强)
-    - [2.2 训练](#训练)
-    - [2.3 小语种](#小语种)
+    - [2.2 通用模型训练](#通用模型训练)
+    - [2.3 多语言模型训练](#多语言模型训练)
 
 - [3 评估](#评估)
 
 - [4 预测](#预测)
-    - [4.1 训练引擎预测](#训练引擎预测)
 
 
 <a name="数据准备"></a>
@@ -23,8 +23,8 @@
 
 
 PaddleOCR 支持两种数据格式:
- - `lmdb` 用于训练以lmdb格式存储的数据集;
- - `通用数据` 用于训练以文本文件存储的数据集:
+ - `lmdb` 用于训练以lmdb格式存储的数据集(LMDBDataSet);
+ - `通用数据` 用于训练以文本文件存储的数据集(SimpleDataSet);
 
 训练数据的默认存储路径是 `PaddleOCR/train_data`,如果您的磁盘上已有数据集，只需创建软链接至数据集目录：
 
@@ -82,14 +82,13 @@ train_data/rec/train/word_002.jpg   用科技让复杂的世界更简单
 
 <a name="数据下载"></a>
 
-1.2 数据下载
+#### 1.2 数据下载
 
-若您本地没有数据集，可以在官网下载 [icdar2015](http://rrc.cvc.uab.es/?ch=4&com=downloads) 数据，用于快速验证。也可以参考[DTRB](https://github.com/clovaai/deep-text-recognition-benchmark#download-lmdb-dataset-for-traininig-and-evaluation-from-here) ，下载 benchmark 所需的lmdb格式数据集。
+- ICDAR2015
 
-如果你使用的是icdar2015的公开数据集，PaddleOCR 提供了一份用于训练 icdar2015 数据集的标签文件，通过以下方式下载：
-
-如果希望复现SRN的论文指标，需要下载离线[增广数据](https://pan.baidu.com/s/1-HSZ-ZVdqBF2HaBZ5pRAKA),提取码: y3ry。增广数据是由MJSynth和SynthText做旋转和扰动得到的。数据下载完成后请解压到 {your_path}/PaddleOCR/train_data/data_lmdb_release/training/ 路径下。
+若您本地没有数据集，可以在官网下载 [ICDAR2015](http://rrc.cvc.uab.es/?ch=4&com=downloads) 数据，用于快速验证。也可以参考[DTRB](https://github.com/clovaai/deep-text-recognition-benchmark#download-lmdb-dataset-for-traininig-and-evaluation-from-here) ，下载 benchmark 所需的lmdb格式数据集。
 
+如果你使用的是icdar2015的公开数据集，PaddleOCR 提供了一份用于训练 ICDAR2015 数据集的标签文件，通过以下方式下载：
 ```
 # 训练集标签
 wget -P ./train_data/ic15_data  https://paddleocr.bj.bcebos.com/dataset/rec_gt_train.txt
@@ -97,15 +96,25 @@ wget -P ./train_data/ic15_data  https://paddleocr.bj.bcebos.com/dataset/rec_gt_t
 wget -P ./train_data/ic15_data  https://paddleocr.bj.bcebos.com/dataset/rec_gt_test.txt
 ```
 
-PaddleOCR 也提供了数据格式转换脚本，可以将官网 label 转换支持的数据格式。 数据转换工具在 `ppocr/utils/gen_label.py`, 这里以训练集为例：
+PaddleOCR 也提供了数据格式转换脚本，可以将ICDAR官网 label 转换为PaddleOCR支持的数据格式。 数据转换工具在 `ppocr/utils/gen_label.py`, 这里以训练集为例：
 
 ```
 # 将官网下载的标签文件转换为 rec_gt_label.txt
 python gen_label.py --mode="rec" --input_path="{path/of/origin/label}" --output_label="rec_gt_label.txt"
 ```
 
+数据样式格式如下，(a)为原始图片,(b)为每张图片对应的 Ground Truth 文本文件：
+![](../datasets/icdar_rec.png)
+
+- 多语言数据集
+
+多语言模型的训练数据集均为100w的合成数据，使用了开源合成工具 [text_renderer](https://github.com/Sanster/text_renderer) ，少量的字体可以通过下面两种方式下载。
+* [百度网盘](https://pan.baidu.com/s/1bS_u207Rm7YbY33wOECKDA) 提取码：frgi
+* [google drive](https://drive.google.com/file/d/18cSWX7wXSy4G0tbKJ0d9PuIaiwRLHpjA/view)
+
+
 <a name="字典"></a>
-1.3 字典
+#### 1.3 字典
 
 最后需要提供一个字典（{word_dict_name}.txt），使模型在训练时，可以将所有出现的字符映射为字典的索引。
 
@@ -152,7 +161,7 @@ PaddleOCR内置了一部分字典，可以按需使用。
 并将 `character_type` 设置为 `ch`。
 
 <a name="支持空格"></a>
-1.4 添加空格类别
+#### 1.4 添加空格类别
 
 如果希望支持识别"空格"类别, 请将yml文件中的 `use_space_char` 字段设置为 `True`。
 
@@ -160,6 +169,20 @@ PaddleOCR内置了一部分字典，可以按需使用。
 <a name="启动训练"></a>
 ### 2. 启动训练
 
+<a name="数据增强"></a>
+#### 2.1 数据增强
+
+PaddleOCR提供了多种数据增强方式，默认配置文件中已经添加了数据增广。
+
+默认的扰动方式有：颜色空间转换(cvtColor)、模糊(blur)、抖动(jitter)、噪声(Gasuss noise)、随机切割(random crop)、透视(perspective)、颜色反转(reverse)、TIA数据增广。
+
+训练过程中每种扰动方式以40%的概率被选择，具体代码实现请参考：[rec_img_aug.py](../../ppocr/data/imaug/rec_img_aug.py)
+
+*由于OpenCV的兼容性问题，扰动操作暂时只支持Linux*
+
+<a name="通用模型训练"></a>
+#### 2.2 通用模型训练
+
 PaddleOCR提供了训练脚本、评估脚本和预测脚本，本节将以 CRNN 识别模型为例：
 
 首先下载pretrain model，您可以下载训练好的模型在 icdar2015 数据上进行finetune
@@ -178,23 +201,16 @@ tar -xf rec_mv3_none_bilstm_ctc_v2.0_train.tar && rm -rf rec_mv3_none_bilstm_ctc
 *如果您安装的是cpu版本，请将配置文件中的 `use_gpu` 字段修改为false*
 
 ```
-# GPU训练 支持单卡，多卡训练，通过--gpus参数指定卡号
+# GPU训练 支持单卡，多卡训练
 # 训练icdar15英文数据 训练日志会自动保存为 "{save_model_dir}" 下的train.log
-python3 -m paddle.distributed.launch --gpus '0,1,2,3'  tools/train.py -c configs/rec/rec_icdar15_train.yml
-```
-<a name="数据增强"></a>
-#### 2.1 数据增强
 
-PaddleOCR提供了多种数据增强方式，默认配置文件中已经添加了数据增广。
-
-默认的扰动方式有：颜色空间转换(cvtColor)、模糊(blur)、抖动(jitter)、噪声(Gasuss noise)、随机切割(random crop)、透视(perspective)、颜色反转(reverse)、TIA数据增广。
+#单卡训练（训练周期长，不建议）
+python3 tools/train.py -c configs/rec/rec_icdar15_train.yml
 
-训练过程中每种扰动方式以40%的概率被选择，具体代码实现请参考：[rec_img_aug.py](../../ppocr/data/imaug/rec_img_aug.py)
-
-*由于OpenCV的兼容性问题，扰动操作暂时只支持Linux*
+#多卡训练，通过--gpus参数指定卡号
+python3 -m paddle.distributed.launch --gpus '0,1,2,3'  tools/train.py -c configs/rec/rec_icdar15_train.yml
+```
 
-<a name="训练"></a>
-#### 2.2 训练
 
 PaddleOCR支持训练和评估交替进行, 可以在 `configs/rec/rec_icdar15_train.yml` 中修改 `eval_batch_step` 设置评估频率，默认每500个iter评估一次。评估过程中默认将最佳acc模型，保存为 `output/rec_CRNN/best_accuracy` 。
 
@@ -283,85 +299,12 @@ Eval:
 ```
 **注意，预测/评估时的配置文件请务必与训练一致。**
 
-<a name="小语种"></a>
-#### 2.3 小语种
+<a name="多语言模型训练"></a>
+#### 2.3 多语言模型训练
 
 PaddleOCR目前已支持80种（除中文外）语种识别，`configs/rec/multi_languages` 路径下提供了一个多语言的配置文件模版: [rec_multi_language_lite_train.yml](../../configs/rec/multi_language/rec_multi_language_lite_train.yml)。
 
-您有两种方式创建所需的配置文件：
-
-1. 通过脚本自动生成
-
-[generate_multi_language_configs.py](../../configs/rec/multi_language/generate_multi_language_configs.py) 可以帮助您生成多语言模型的配置文件
-
-- 以意大利语为例，如果您的数据是按如下格式准备的：
-    ```
-    |-train_data
-        |- it_train.txt # 训练集标签
-        |- it_val.txt # 验证集标签
-        |- data
-            |- word_001.jpg
-            |- word_002.jpg
-            |- word_003.jpg
-            | ...
-    ```
-
-    可以使用默认参数，生成配置文件：
-
-    ```bash
-    # 该代码需要在指定目录运行
-    cd PaddleOCR/configs/rec/multi_language/
-    # 通过-l或者--language参数设置需要生成的语种的配置文件，该命令会将默认参数写入配置文件
-    python3 generate_multi_language_configs.py -l it
-    ```
-
-- 如果您的数据放置在其他位置，或希望使用自己的字典，可以通过指定相关参数来生成配置文件:
-
-    ```bash
-    # -l或者--language字段是必须的
-    # --train修改训练集，--val修改验证集，--data_dir修改数据集目录，--dict修改字典路径， -o修改对应默认参数
-    cd PaddleOCR/configs/rec/multi_language/
-    python3 generate_multi_language_configs.py -l it \  # 语种
-    --train {path/of/train_label.txt} \ # 训练标签文件的路径
-    --val {path/of/val_label.txt} \     # 验证集标签文件的路径
-    --data_dir {train_data/path} \      # 训练数据的根目录
-    --dict {path/of/dict} \             # 字典文件路径
-    -o Global.use_gpu=False             # 是否使用gpu
-    ...
-
-    ```
-
-意大利文由拉丁字母组成，因此执行完命令后会得到名为 rec_latin_lite_train.yml 的配置文件。
-
-2. 手动修改配置文件
-
-   您也可以手动修改模版中的以下几个字段:
-
-   ```
-    Global:
-      use_gpu: True
-      epoch_num: 500
-      ...
-      character_type: it  # 需要识别的语种
-      character_dict_path:  {path/of/dict} # 字典文件所在路径
-
-   Train:
-      dataset:
-        name: SimpleDataSet
-        data_dir: train_data/ # 数据存放根目录
-        label_file_list: ["./train_data/train_list.txt"] # 训练集label路径
-      ...
-
-   Eval:
-      dataset:
-        name: SimpleDataSet
-        data_dir: train_data/ # 数据存放根目录
-        label_file_list: ["./train_data/val_list.txt"] # 验证集label路径
-      ...
-
-   ```
-
-目前PaddleOCR支持的多语言算法有：
+按语系划分，目前PaddleOCR支持的语种有：
 
 | 配置文件 |  算法名称 |   backbone |   trans   |   seq      |     pred     |  language | character_type |
 | :--------: |  :-------:   | :-------:  |   :-------:   |   :-----:   |  :-----:   | :-----:  | :-----:  |
@@ -378,10 +321,6 @@ PaddleOCR目前已支持80种（除中文外）语种识别，`configs/rec/multi
 
 更多支持语种请参考: [多语言模型](https://github.com/PaddlePaddle/PaddleOCR/blob/release/2.1/doc/doc_ch/multi_languages.md#%E8%AF%AD%E7%A7%8D%E7%BC%A9%E5%86%99)
 
-多语言模型训练方式与中文模型一致，训练数据集均为100w的合成数据，少量的字体可以通过下面两种方式下载。
-* [百度网盘](https://pan.baidu.com/s/1bS_u207Rm7YbY33wOECKDA)。提取码：frgi。
-* [google drive](https://drive.google.com/file/d/18cSWX7wXSy4G0tbKJ0d9PuIaiwRLHpjA/view)
-
 如您希望在现有模型效果的基础上调优，请参考下列说明修改配置文件：
 
 以 `rec_french_lite_train` 为例：
@@ -429,12 +368,27 @@ python3 -m paddle.distributed.launch --gpus '0' tools/eval.py -c configs/rec/rec
 <a name="预测"></a>
 ### 4 预测
 
-<a name="训练引擎预测"></a>
-#### 4.1 训练引擎的预测
-
 使用 PaddleOCR 训练好的模型，可以通过以下脚本进行快速预测。
 
-默认预测图片存储在 `infer_img` 里，通过 `-o Global.checkpoints` 指定权重：
+默认预测图片存储在 `infer_img` 里，通过 `-o Global.checkpoints` 加载训练好的参数文件：
+
+根据配置文件中设置的的 `save_model_dir` 和 `save_epoch_step` 字段，会有以下几种参数被保存下来：
+
+```
+seed_ch/  
+├── best_accuracy.pdopt  
+├── best_accuracy.pdparams  
+├── best_accuracy.states  
+├── config.yml  
+├── iter_epoch_3.pdopt  
+├── iter_epoch_3.pdparams  
+├── iter_epoch_3.states  
+├── latest.pdopt  
+├── latest.pdparams  
+├── latest.states  
+└── train.log
+```
+其中 best_accuracy.* 是评估集上的最优模型；iter_epoch_x.* 是以 `save_epoch_step` 为间隔保存下来的模型；latest.* 是最后一个epoch的模型。
 
 ```
 # 预测英文结果

doc/doc_ch/training.md

+## 模型训练
+
+本文将介绍模型训练时需掌握的基本概念，和训练时的调优方法。
+
+同时会简单介绍PaddleOCR模型训练数据的组成部分，以及如何在垂类场景中准备数据finetune模型。
+
+### 基本概念
+
+OCR(Optical Character Recognition,光学字符识别)是指对图像进行分析识别处理，获取文字和版面信息的过程，是典型的计算机视觉任务，
+通常由文本检测和文本识别两个子任务构成。
+
+模型调优时需要关注以下参数：
+
+- 学习率
+
+学习率是训练神经网络的重要超参数之一，它代表在每一次迭代中梯度向损失函数最优解移动的步长。
+在PaddleOCR中提供了多种学习率更新策略,可以通过配置文件修改，例如：
+
+```
+Optimizer:
+  ...
+  lr:
+    name: Piecewise
+    decay_epochs : [700, 800]
+    values : [0.001, 0.0001]
+    warmup_epoch: 5
+```
+
+Piecewise 代表分段常数衰减，在不同的学习阶段指定不同的学习率，在每段内学习率相同。
+warmup_epoch 代表在前5个epoch中，学习率将逐渐从0增加到base_lr。全部策略可以参考代码[learning_rate.py](../../ppocr/optimizer/learning_rate.py) 。
+
+
+- 正则化
+
+正则化可以有效的避免算法过拟合，PaddleOCR中提供了L1、L2正则方法，L1 和 L2 正则化是最常用的正则化方法。L1 正则化向目标函数添加正则化项，以减少参数的绝对值总和；而 L2 正则化中，添加正则化项的目的在于减少参数平方的总和。配置方法如下：
+
+```
+Optimizer:
+  ...
+  regularizer:
+    name: L2
+    factor: 2.0e-05
+```
+
+
+- 评估指标：
+
+（1）检测阶段：先按照检测框和标注框的IOU评估，IOU大于某个阈值判断为检测准确。这里检测框和标注框不同于一般的通用目标检测框，是采用多边形进行表示。检测准确率：正确的检测框个数在全部检测框的占比，主要是判断检测指标。检测召回率：正确的检测框个数在全部标注框的占比，主要是判断漏检的指标。
+
+（2）识别阶段： 字符识别准确率，即正确识别的文本行占标注的文本行数量的比例，只有整行文本识别对才算正确识别。
+
+（3）端到端统计： 端对端召回率：准确检测并正确识别文本行在全部标注文本行的占比； 端到端准确率：准确检测并正确识别文本行在 检测到的文本行数量 的占比； 准确检测的标准是检测框与标注框的IOU大于某个阈值，正确识别的的检测框中的文本与标注的文本相同。
+
+### 常见问题
+
+**Q**: 基于深度学习的文字检测方法有哪几种？各有什么优缺点？
+
+    A: 常用的基于深度学习的文字检测方法一般可以分为基于回归的、基于分割的两大类，当然还有一些将两者进行结合的方法。
+
+    （1）基于回归的方法分为box回归和像素值回归。a. 采用box回归的方法主要有CTPN、Textbox系列和EAST，这类算法对规则形状文本检测效果较好，但无法准确检测不规则形状文本。 b. 像素值回归的方法主要有CRAFT和SA-Text，这类算法能够检测弯曲文本且对小文本效果优秀但是实时性能不够。
+
+    （2）基于分割的算法，如PSENet，这类算法不受文本形状的限制，对各种形状的文本都能取得较好的效果，但是往往后处理比较复杂，导致耗时严重。目前也有一些算法专门针对这个问题进行改进，如DB，将二值化进行近似，使其可导，融入训练，从而获取更准确的边界，大大降低了后处理的耗时。
+
+**Q**:对于中文行文本识别，CTC和Attention哪种更优？
+
+    A:
+    （1）从效果上来看，通用OCR场景CTC的识别效果优于Attention，因为带识别的字典中的字符比较多，常用中文汉字三千字以上，如果训练样本不足的情况下，对于这些字符的序列关系挖掘比较困难。中文场景下Attention模型的优势无法体现。而且Attention适合短语句识别，对长句子识别比较差。
+
+    （2）从训练和预测速度上，Attention的串行解码结构限制了预测速度，而CTC网络结构更高效，预测速度上更有优势。
+
+**Q**：训练CRNN识别时，如何选择合适的网络输入shape？
+
+    A：一般高度采用32，最长宽度的选择，有两种方法：
+
+    （1）统计训练样本图像的宽高比分布。最大宽高比的选取考虑满足80%的训练样本。
+
+    （2）统计训练样本文字数目。最长字符数目的选取考虑满足80%的训练样本。然后中文字符长宽比近似认为是1，英文认为3：1，预估一个最长宽度。
+
+
+### 数据与垂类场景
+
+- 训练数据：
+目前开源的模型，数据集和量级如下：
+
+    - 检测：  
+        - 英文数据集，ICDAR2015  
+        - 中文数据集，LSVT街景数据集训练数据3w张图片
+
+    - 识别：  
+        - 英文数据集，MJSynth和SynthText合成数据，数据量上千万。  
+        - 中文数据集，LSVT街景数据集根据真值将图crop出来，并进行位置校准，总共30w张图像。此外基于LSVT的语料，合成数据500w。
+        - 小语种数据集，使用不同语料和字体，分别生成了100w合成数据集，并使用ICDAR-MLT作为验证集。
+
+其中，公开数据集都是开源的，用户可自行搜索下载，也可参考[中文数据集](./datasets.md)，合成数据暂不开源，用户可使用开源合成工具自行合成，可参考的合成工具包括[text_renderer](https://github.com/Sanster/text_renderer) 、[SynthText](https://github.com/ankush-me/SynthText) 、[TextRecognitionDataGenerator](https://github.com/Belval/TextRecognitionDataGenerator) 等。
+
+
+- 垂类场景
+
+PaddleOCR主要聚焦通用OCR，如果有垂类需求，您可以用PaddleOCR+垂类数据自己训练；
+如果缺少带标注的数据，或者不想投入研发成本，建议直接调用开放的API，开放的API覆盖了目前比较常见的一些垂类。
+
+- 自己构建数据集
+
+在构建数据集时有几个经验可供参考：
+
+（1） 训练集的数据量：
+
+    a. 检测需要的数据相对较少，在PaddleOCR模型的基础上进行Fine-tune，一般需要500张可达到不错的效果。
+    b. 识别分英文和中文，一般英文场景需要几十万数据可达到不错的效果，中文则需要几百万甚至更多。
+
+
+（2）当训练数据量少时，可以尝试以下三种方式获取更多的数据：
+
+    a. 人工采集更多的训练数据，最直接也是最有效的方式。
+    b. 基于PIL和opencv基本图像处理或者变换。例如PIL中ImageFont, Image, ImageDraw三个模块将文字写到背景中，opencv的旋转仿射变换，高斯滤波等。
+    c. 利用数据生成算法合成数据，例如pix2pix等算法。