update docs

cnocr/cli.py

@@ -177,6 +177,13 @@ def visualize_example(example, fp_prefix):
     default=DEFAULT_MODEL_NAME,
     help='模型名称。默认值为 %s' % DEFAULT_MODEL_NAME,
 )
+@click.option(
+    '-b',
+    '--model-backend',
+    type=click.Choice(['pytorch', 'onnx']),
+    default='onnx',
+    help='模型类型。默认值为 `onnx`',
+)
 @click.option(
     '-p',
     '--pretrained-model-fp',
@@ -198,9 +205,21 @@ def visualize_example(example, fp_prefix):
     is_flag=True,
     help="是否输入图片只包含单行文字。对包含单行文字的图片，不做按行切分；否则会先对图片按行分割后再进行识别",
 )
-def predict(model_name, pretrained_model_fp, context, img_file_or_dir, single_line):
+def predict(
+    model_name,
+    model_backend,
+    pretrained_model_fp,
+    context,
+    img_file_or_dir,
+    single_line,
+):
     """模型预测"""
-    ocr = CnOcr(model_name=model_name, model_fp=pretrained_model_fp, context=context)
+    ocr = CnOcr(
+        model_name=model_name,
+        model_backend=model_backend,
+        model_fp=pretrained_model_fp,
+        context=context,
+    )
     ocr_func = ocr.ocr_for_single_line if single_line else ocr.ocr
     fp_list = []
     if os.path.isfile(img_file_or_dir):
@@ -230,6 +249,13 @@ def predict(model_name, pretrained_model_fp, context, img_file_or_dir, single_li
     default=DEFAULT_MODEL_NAME,
     help='模型名称。默认值为 %s' % DEFAULT_MODEL_NAME,
 )
+@click.option(
+    '-b',
+    '--model-backend',
+    type=click.Choice(['pytorch', 'onnx']),
+    default='onnx',
+    help='模型类型。默认值为 `onnx`',
+)
 @click.option(
     '-p',
     '--pretrained-model-fp',
@@ -265,6 +291,7 @@ def predict(model_name, pretrained_model_fp, context, img_file_or_dir, single_li
 )
 def evaluate(
     model_name,
+    model_backend,
     pretrained_model_fp,
     context,
     eval_index_fp,
@@ -278,9 +305,16 @@ def evaluate(
         import Levenshtein
     except Exception as e:
         logger.error(e)
-        logger.error('try to install the package by using `pip install python-Levenshtein`')
+        logger.error(
+            'try to install the package by using `pip install python-Levenshtein`'
+        )
         return
-    ocr = CnOcr(model_name=model_name, model_fp=pretrained_model_fp, context=context)
+    ocr = CnOcr(
+        model_name=model_name,
+        model_backend=model_backend,
+        model_fp=pretrained_model_fp,
+        context=context,
+    )
 
     fn_labels_list = read_input_file(eval_index_fp)
 

docs/command.md

@@ -2,7 +2,7 @@
 
 **cnocr** 包含了几个命令行工具，安装 **cnocr** 后即可使用。
 
-## 预测单个文件或文件夹中所有图片
+## 图片预测
 
 使用命令 **`cnocr predict`** 预测单个文件或文件夹中所有图片，以下是使用说明：
 
@@ -14,6 +14,8 @@ Usage: cnocr predict [OPTIONS]
 
 Options:
   -m, --model-name TEXT           模型名称。默认值为 densenet_lite_136-fc
+  -b, --model-backend [pytorch|onnx]
+                                  模型类型。默认值为 `onnx`
   -p, --pretrained-model-fp TEXT  使用训练好的模型。默认为 `None`，表示使用系统自带的预训练模型
   -c, --context TEXT              使用cpu还是 `gpu` 运行代码，也可指定为特定gpu，如`cuda:0`。默认为
                                   `cpu`
@@ -45,6 +47,8 @@ Usage: cnocr evaluate [OPTIONS]
 
 Options:
   -m, --model-name TEXT           模型名称。默认值为 densenet_lite_136-fc
+  -b, --model-backend [pytorch|onnx]
+                                  模型类型。默认值为 `onnx`
   -p, --pretrained-model-fp TEXT  使用训练好的模型。默认为 `None`，表示使用系统自带的预训练模型
   -c, --context TEXT              使用cpu还是 `gpu` 运行代码，也可指定为特定gpu，如`cuda:0`。默认为
                                   `cpu`

docs/index.md

 # CnOcr
 
-**[CnOcr](https://github.com/breezedeus/cnocr)** 是 **Python 3** 下的**文字识别**（**Optical Character Recognition**，简称**OCR**）工具包，
-支持**中文**、**英文**的常见字符识别，自带了多个[训练好的识别模型](models.md)，安装后即可直接使用。
-欢迎扫码加入[QQ交流群](contact.md)。
+[**CnOcr**](https://github.com/breezedeus/cnocr) 是 **Python 3** 下的**文字识别**（**Optical Character Recognition**，简称**OCR**）工具包，支持**简体中文**、**繁体中文**（部分模型）、**英文**和**数字**的常见字符识别，支持竖排文字的识别。自带了**10+个** [训练好的识别模型](models.md)，安装后即可直接使用。欢迎扫码加入[QQ交流群](contact.md)。
 
 作者也维护 **知识星球** [**CnOCR/CnSTD私享群**](https://t.zsxq.com/FEYZRJQ) ，欢迎加入。**知识星球私享群**会陆续发布一些CnOCR/CnSTD相关的私有资料，包括**更详细的训练教程**，**未公开的模型**，使用过程中遇到的难题解答等。本群也会发布OCR/STD相关的最新研究资料。此外，**私享群中作者每月提供两次免费特有数据的训练服务**。
 
 CnOcr的目标是**使用简单**。
 
-可以使用 [在线 Demo](demo.md) 查看效果。
+可以使用 [**在线 Demo**](demo.md) 查看效果。
 
 ## 安装简单
 
@@ -49,6 +47,19 @@ res = ocr.ocr(img)
 print("Predicted Chars:", res)
 ```
 
+返回结果如下：
+
+```bash
+Predicted Chars: [
+    ('网络支付并无本质的区别，因为', 0.996096134185791), 
+    ('每一个手机号码和邮件地址背后', 0.9903925061225891), 
+    ('都会对应着一个账户一一这个账', 0.6401291489601135), 
+    ('户可以是信用卡账户、借记卡账', 0.9446338415145874), 
+    ('户，也包括邮局汇款、手机代', 0.9997618794441223), 
+    ('收、电话代收、预付费卡和点卡', 0.7029080390930176), 
+    ('等多种形式。', 0.8814011812210083)]
+```
+
 更多说明可见 [使用方法](usage.md)。
 
 ## 命令行工具
@@ -95,4 +106,11 @@ print("Predicted Chars:", res)
 * [x] 优化训练集，去掉不合理的样本；在此基础上，重新训练各个模型
 * [x] 由 MXNet 改为 PyTorch 架构（since `V2.0.0`）
 * [x] 基于 PyTorch 训练更高效的模型
-* [ ] 支持列格式的文字识别
+* [x] 支持列格式的文字识别
+- [ ] 支持与 [CnStd](https://github.com/breezedeus/cnstd) 的无缝衔接
+
+
+
+---
+
+官方代码库：[https://github.com/breezedeus/cnocr](https://github.com/breezedeus/cnocr)。

docs/models.md

 ## 可直接使用的模型
 
-cnocr的ocr模型可以分为两阶段：第一阶段是获得ocr图片的局部编码向量，第二部分是对局部编码向量进行序列学习，获得序列编码向量。目前的PyTorch版本的两个阶段分别包含以下模型：
+cnocr 自 **V2.1.2** 之后，可直接使用的模型包含两类：1）cnocr 自己训练的模型，通常会包含 PyTorch 和 ONNX 版本；2）从其他ocr引擎搬运过来的训练好的外部模型，ONNX化后用于 cnocr 中。
 
-1. 局部编码模型（emb model）
-   * **`densenet_lite_<numbers>`**：一个微型的`densenet`网络；其中的`<number>`表示模型中每个block包含的层数。
-   * **`densenet`**：一个小型的`densenet`网络；
-2. 序列编码模型（seq model）
-   * **`fc`**：两层的全连接网络；
-   * **`gru`**：一层的GRU网络；
-   * **`lstm`**：一层的LSTM网络。
+直接使用的模型都放在 [**cnstd-cnocr-models**](https://huggingface.co/breezedeus/cnstd-cnocr-models) 项目中，可免费下载使用。具体方法可参考 [使用方法](usage.md) 。
+
+## 1) cnocr 自己训练的模型
 
-cnocr **V2.1** 目前包含以下可直接使用的模型，训练好的模型都放在 **[cnstd-cnocr-models](https://github.com/breezedeus/cnstd-cnocr-models)** 项目中，可免费下载使用：
+cnocr 自己训练的模型都支持**常见简体中文、英文和数字**的识别，大家也可以基于这些模型在自己的领域数据上继续精调模型。模型列表如下：
 
-| Name                    | PyTorch 版本 | ONNX 版本 | 参数规模  | 模型文件大小 | 准确度    | 平均推断耗时（毫秒/图） |
+| `model_name`            | PyTorch 版本 | ONNX 版本 | 参数规模  | 模型文件大小 | 准确度    | 平均推断耗时（毫秒/图） |
 | ----------------------- | ---------- | ------- | ----- | ------ | ------ | ------------ |
 | densenet\_lite\_114-fc  | √          | √       | 1.3 M | 4.9 M  | 0.9274 | 9.229        |
 | densenet\_lite\_124-fc  | √          | √       | 1.3 M | 5.1 M  | 0.9429 | 10.112       |
@@ -26,3 +22,27 @@ cnocr **V2.1** 目前包含以下可直接使用的模型，训练好的模型
 1. 模型名称是由**局部编码**模型和**序列编码**模型名称拼接而成，以符合"-"分割。
 2. 列 **`PyTorch 版本`** 为 `√` 表示此模型支持 `model_backend=='pytorch'`；列 **`ONNX 版本`** 为 `√` 表示此模型支持 `model_backend=='onnx'`；取值为 `X` 则表示不支持对应的取值。
 3. `平均耗时` 是针对 `PyTorch 版本` 获得的，**`ONNX 版本` 耗时大致是 `PyTorch 版本` 的一半。**
+
+cnocr的自有模型从结构上可以分为两阶段：第一阶段是获得ocr图片的局部编码向量，第二部分是对局部编码向量进行序列学习，获得序列编码向量。目前的PyTorch版本的两个阶段分别包含以下模型：
+
+1. 局部编码模型（emb model）
+   - **`densenet_lite_<numbers>`**：一个微型的`densenet`网络；其中的`<number>`表示模型中每个block包含的层数。
+   - **`densenet`**：一个小型的`densenet`网络；
+2. 序列编码模型（seq model）
+   - **`fc`**：两层的全连接网络；
+   - **`gru`**：一层的GRU网络；
+   - **`lstm`**：一层的LSTM网络。
+
+## 2) 外部模型
+
+以下模型是 [**PaddleOCR**](https://github.com/PaddlePaddle/PaddleOCR) 中模型的 **ONNX** 版本，所以不会依赖 **PaddlePaddle** 相关工具包，故而也不支持基于这些模型在自己的领域数据上继续精调模型。这些模型应该都支持**竖排文字**。
+
+| `model_name`          | PyTorch 版本 | ONNX 版本 | 支持语言           | 模型文件大小 |
+| --------------------- | ---------- | ------- | -------------- | ------ |
+| ch_PP-OCRv3           | X          | √       | 简体中问、英文、数字     | 10 M   |
+| ch_ppocr_mobile_v2.0  | X          | √       | 简体中问、英文、数字     | 4.2 M  |
+| en_PP-OCRv3           | X          | √       | **英文**、数字      | 8.5 M  |
+| en_number_mobile_v2.0 | X          | √       | **英文**、数字      | 1.8M   |
+| chinese_cht_PP-OCRv3  | X          | √       | **繁体中文**、英文、数字 | 11 M   |
+
+更多模型可参考 [PaddleOCR/models_list.md](https://github.com/PaddlePaddle/PaddleOCR/blob/release%2F2.5/doc/doc_ch/models_list.md) 。如有其他外语（如日、韩等）识别需求，可在 **知识星球** [**CnOCR/CnSTD私享群**](https://t.zsxq.com/FEYZRJQ) 中向作者提出建议。

docs/usage.md

@@ -110,7 +110,7 @@ class CnOcr(object):
 
 其中的几个参数含义如下：
 
-* `model_name`: 模型名称，即上面表格第一列中的值。默认为 `densenet_lite_136-fc`。
+* `model_name`: 模型名称，即上面表格第一列中的值。默认为 `densenet_lite_136-fc`。更多可选模型见 [可直接使用的模型](models.md) 。
 
 * `cand_alphabet`: 待识别字符所在的候选集合。默认为 `None`，表示不限定识别字符范围。取值可以是字符串，如 `"0123456789"`，或者字符列表，如 `["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]`。
   
@@ -118,7 +118,7 @@ class CnOcr(object):
 
 * `context`：预测使用的机器资源，可取值为字符串`cpu`、`gpu`、`cuda:0`等。默认为 `cpu`。此参数仅在 `model_backend=='pytorch'` 时有效。
 
-* `model_fp`:  如果不使用系统自带的模型，可以通过此参数直接指定所使用的模型文件（`.ckpt` 文件）。
+* `model_fp`:  如果不使用系统自带的模型，可以通过此参数直接指定所使用的模型文件（`.ckpt` 或 `.onnx` 文件）。
 
 * `model_backend`：'pytorch', or 'onnx'。表明预测时是使用 `PyTorch` 版本模型，还是使用 `ONNX` 版本模型。 **同样的模型，ONNX 版本的预测速度一般是 PyTorch 版本的 2倍左右。** 默认为 'onnx'。
 
@@ -142,7 +142,7 @@ class CnOcr(object):
 **函数说明**：
 
 - 输入参数 `img_fp`: 可以是需要识别的图片文件路径（如下例）；或者是已经从图片文件中读入的数组，类型可以为 `torch.Tensor` 或  `np.ndarray`，取值应该是`[0，255]`的整数，维数应该是 `[height, width]` （灰度图片）或者 `[height, width, channel]`，`channel` 可以等于`1`（灰度图片）或者`3`（`RGB`格式的彩色图片）。
-- 返回值：为一个嵌套的`list`，其中的每个元素存储了对一行文字的识别结果，其中也包含了识别概率值。类似这样`[(['第', '一', '行'], 0.80), (['第', '二', '行'], 0.75), (['第', '三', '行'], 0.9)]`，其中的数字为对应的识别概率值。
+- 返回值：为一个嵌套的`list`，其中的每个元素存储了对一行文字的识别结果，其中也包含了识别概率值。类似这样`[('第一行', 0.80), ('第二行', 0.75), ('第三行', 0.9)]`，其中的数字为对应的识别概率值。
 
 **调用示例**：
 
@@ -175,13 +175,13 @@ print("Predicted Chars:", res)
 
 ```bash
 Predicted Chars: [
-        (['网', '络', '支', '付', '并', '无', '本', '质', '的', '区', '别', '，', '因', '为'], 0.8677546381950378), 
-        (['每', '一', '个', '手', '机', '号', '码', '和', '邮', '件', '地', '址', '背', '后'], 0.6706454157829285), 
-        (['都', '会', '对', '应', '着', '一', '个', '账', '户', '一', '一', '这', '个', '账'], 0.5052655935287476), 
-        (['户', '可', '以', '是', '信', '用', '卡', '账', '户', '、', '借', '记', '卡', '账'], 0.7785991430282593), 
-        (['户', '，', '也', '包', '括', '邮', '局', '汇', '款', '、', '手', '机', '代'], 0.37458470463752747), 
-        (['收', '、', '电', '话', '代', '收', '、', '预', '付', '费', '卡', '和', '点', '卡'], 0.7326119542121887), 
-        (['等', '多', '种', '形', '式', '。'], 0.14462216198444366)]
+    ('网络支付并无本质的区别，因为', 0.996096134185791), 
+    ('每一个手机号码和邮件地址背后', 0.9903925061225891), 
+    ('都会对应着一个账户一一这个账', 0.6401291489601135), 
+    ('户可以是信用卡账户、借记卡账', 0.9446338415145874), 
+    ('户，也包括邮局汇款、手机代', 0.9997618794441223), 
+    ('收、电话代收、预付费卡和点卡', 0.7029080390930176), 
+    ('等多种形式。', 0.8814011812210083)]
 ```
 
 ### 2. 函数`CnOcr.ocr_for_single_line(img_fp)`
@@ -191,7 +191,7 @@ Predicted Chars: [
 **函数说明**：
 
 - 输入参数 `img_fp`: 可以是需要识别的图片文件路径（如下例）；或者是已经从图片文件中读入的数组，类型可以为 `torch.Tensor` 或  `np.ndarray`，取值应该是`[0，255]`的整数，维数应该是 `[height, width]` （灰度图片）或者 `[height, width, channel]`，`channel` 可以等于`1`（灰度图片）或者`3`（`RGB`格式的彩色图片）。
-- 返回值：为一个`tuple`，其中存储了对一行文字的识别结果，也包含了识别概率值。类似这样`(['第', '一', '行'], 0.80)`，其中的数字为对应的识别概率值。
+- 返回值：为一个`tuple`，其中存储了对一行文字的识别结果，也包含了识别概率值。类似这样`('第一行', 0.80)`，其中的数字为对应的识别概率值。
 
 **调用示例**：
 
@@ -223,7 +223,7 @@ print("Predicted Chars:", res)
 的预测结果如下：
 
 ```bash
-Predicted Chars: (['笠', '淡', '嘿', '骅', '谧', '鼎', '皋', '姚', '歼', '蠢', '驼', '耳', '胬', '挝', '涯', '狗', '蒽', '了', '狞'], 0.7832438349723816)
+Predicted Chars: ('笠淡嘿骅谧鼎皋姚歼蠢驼耳窝挝涯狗蒽子犷', 0.34973764419555664)
 ```
 
 ### 3. 函数`CnOcr.ocr_for_single_lines(img_list, batch_size=1)`
@@ -234,7 +234,7 @@ Predicted Chars: (['笠', '淡', '嘿', '骅', '谧', '鼎', '皋', '姚', '歼'
 
 - 输入参数` img_list`: 为一个`list`；其中每个元素可以是需要识别的图片文件路径（如下例）；或者是已经从图片文件中读入的数组，类型可以为 `torch.Tensor` 或  `np.ndarray`，取值应该是`[0，255]`的整数，维数应该是 `[height, width]` （灰度图片）或者 `[height, width, channel]`，`channel` 可以等于`1`（灰度图片）或者`3`（`RGB`格式的彩色图片）。
 - 输入参数 `batch_size`: 待处理图片很多时，需要分批处理，每批图片的数量由此参数指定。默认为 `1`。
-- 返回值：为一个嵌套的`list`，其中的每个元素存储了对一行文字的识别结果，其中也包含了识别概率值。类似这样`[(['第', '一', '行'], 0.80), (['第', '二', '行'], 0.75), (['第', '三', '行'], 0.9)]`，其中的数字为对应的识别概率值。
+- 返回值：为一个嵌套的`list`，其中的每个元素存储了对一行文字的识别结果，其中也包含了识别概率值。类似这样`[('第一行', 0.80), ('第二行', 0.75), ('第三行', 0.9)]`，其中的数字为对应的识别概率值。
 
 **调用示例**：